iac MCP

iac mcp

AI/LLM和本地应用程序之间的通用桥梁

iac-mcp是一个mcp（模型上下文协议）服务器，它使用实时发现（JITD）来动态发现和编排任何已安装的应用程序，而无需预先构建集成。

平台支持

当前（第1阶段）： macOS

• AppleScript/JXA自动化
• SDEF（脚本定义）解析
• 可编写脚本的应用程序（Finder、Mail、Safari等）

计划（第5+阶段）： 多平台

• 视窗：VBA、COM、Windows消息传递
• Linux：D-Bus，命令行工具
• 跨平台：电子应用程序、网络自动化

JITD架构旨在与任何平台的原生自动化功能协同工作。

特性

• 🔍 及时发现：自动发现已安装的应用程序及其功能
• 🛠️ 动态工具生成：从应用程序自动化界面生成MCP工具
• 🔐 权限系统：使用用户控制的权限安全执行
• 🚀 零配置：可立即与应用程序配合使用，无需预先构建集成
• 🌍 平台不可知设计：可扩展到任何具有本机自动化的平台

状态

当前阶段：第0阶段-技术验证（macOS）

该项目尚处于早期开发阶段。第0阶段的目标是通过以下方式证明JITD概念在macOS上有效：

1. 解析SDEF文件（从Finder开始）
2. 生成MCP工具定义
3. 通过JXA执行命令
4. 使用Claude Desktop进行测试

先决条件

对于macOS（第一阶段）：

• macOS蒙特利或更高版本
• Node.js 20.11+（LTS）-请参阅 节点版本管理
• 克劳德桌面（用于测试）

安装

快速开始

# Clone the repository
git clone https://github.com/jsavin/iac-mcp.git
cd iac-mcp

# Install dependencies (uses package-lock.json for exact versions)
npm ci

# Build the project
npm run build

# Verify installation
npm run verify

节点版本管理

该项目需要 Node.js 20+我们推荐Node.js 20.x LTS以提高稳定性，但任何20+版本（包括22.x LTS或25.x Current）都可以正常工作。

选项1：使用Homebrew（macOS）

# Install Node.js LTS
brew install node@20

# Or use the current release (25.x)
brew install node

选项2：使用nvm（建议用于多个版本）

# Install nvm if you don't have it
# See: https://github.com/nvm-sh/nvm

# Use the LTS version (reads .nvmrc automatically)
nvm use

# Or install if you don't have Node 20+
nvm install 20  # or 'nvm install --lts'

选项3：使用Volta

# Volta automatically detects .node-version
# See: https://volta.sh/

# Just cd into the directory and Volta handles it
cd iac-mcp

选项4：手动安装

• 下载自https://nodejs.org/
• 安装LTS（20.x、22.x）或Current（25.x）
• 验证： node --version 应该显示 v20+

依赖管理

我们使用 package-lock.json 确保 每个人都有相同的依赖关系:

• 对于新安装： npm ci （更快、更严格，使用锁文件）
• 发展： npm install （如果需要，更新锁文件）
• 永不删除 package-lock.json -它致力于git

这可以防止“在我的机器上工作”问题因依赖版本漂移而产生。

发展

# Watch mode (rebuilds on file changes)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint
npm run lint:fix

MCP检验员测试

MCP Inspector是一个基于浏览器的工具，用于在与Claude Desktop集成之前测试MCP服务器：

# Start the MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

这将打开一个浏览器窗口，您可以在其中：

• 查看可用工具
• 测试工具执行
• 检查请求/响应有效载荷
• 调试服务器行为

使用Claude Desktop进行测试

步骤1：配置Claude桌面

1. 找到您的Claude Desktop配置文件：

   ~/Library/Application Support/Claude/claude_desktop_config.json

1. 添加iac mcp服务器配置：

   {
     "mcpServers": {
       "iac-mcp": {
         "command": "node",
         "args": ["/absolute/path/to/iac-mcp/dist/index.js"],
         "env": {
           "NODE_ENV": "production"
         }
       }
     }
   }

1. 重要提示： 替换 /absolute/path/to/iac-mcp 带有iac-mcp目录的实际绝对路径。

获取绝对路径的快速方法：

cd /path/to/iac-mcp
pwd
# Copy the output and append /dist/index.js

配置示例：

{
  "mcpServers": {
    "iac-mcp": {
      "command": "node",
      "args": ["/Users/yourusername/dev/iac-mcp/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

配置模板： 现成的模板可在 claude_desktop_config.json 在存储库根目录下。

步骤2：重新启动克劳德桌面

1. 完全退出克劳德桌面（Cmd+Q）
2. 重新启动克劳德桌面
3. iac mcp服务器将自动启动

步骤3：验证连接

在新的Claude对话中，您可以通过要求Claude列出可用工具或使用示例工具来验证服务器是否正常工作：

Can you show me what tools are available from iac-mcp?

或

Use the example_tool to echo "Hello from Claude Desktop"

步骤4：监控服务器日志

服务器日志会写入stderr，可以在Claude Desktop的开发人员控制台（如果可用）中查看，也可以手动运行服务器：

node dist/index.js
# Then interact with Claude Desktop
# Logs will appear in this terminal

克劳德桌面集成故障排除

问题：服务器未出现在Claude Desktop中

1. 验证配置文件路径是否正确
2. 检查到的绝对路径 dist/index.js 是正确的
3. 确保项目建成： npm run build
4. 检查JSON配置文件中的语法错误
5. 完全重新启动克劳德桌面

问题：工具未显示

1. 首先使用MCP Inspector进行测试，以验证服务器是否正常工作
2. 检查Claude Desktop日志/控制台是否有错误
3. 验证Node.js版本： node --version （必须为20+）

问题：工具执行失败

1. 检查服务器日志中的错误消息
2. 验证工具是否使用正确的参数调用
3. 在MCP检查器中测试相同的工具调用，以隔离问题

有关全面的测试程序，请参阅 docs/MANUAL-TESTING.md.

项目结构

src/
├── index.ts              # MCP server entry point
├── jitd/                 # JITD engine
│   ├── discovery/        # App discovery and SDEF parsing
│   ├── tool-generator/   # MCP tool generation
│   └── cache/            # Capability caching
├── adapters/             # Platform adapters
│   └── macos/            # macOS JXA/AppleEvents
├── mcp/                  # MCP protocol implementation
│   ├── server.ts         # MCP server setup
│   └── tools.ts          # Tool handlers
├── permissions/          # Permission system
└── types/                # TypeScript type definitions

planning/                 # Technical planning
tests/                    # Unit and integration tests
tools/                    # Development helper scripts

文档

• 从这里开始 -快速入门指南
• 决策 -架构决策
• CLAUDE.md -开发工作流程和模式

哲学

首先是互操作性。 让一切与其他一切协同工作。

• 本地优先：您的应用程序、数据、控制
• 无供应商锁定：开放标准（MCP），开源核心
• 通用：适用于任何可编写脚本的应用程序，而不仅仅是流行的应用程序
• 零配置：自动发现功能

许可证

麻省理工学院-见 许可证 详情

贡献

该项目尚处于早期开发阶段。第0阶段完成后，欢迎投稿。

开源路线图

• 阶段0 （第1个月）：技术验证-证明JITD在macOS上工作
• 第一阶段 （第2-5个月）：开源MCP桥（macOS可脚本化应用程序）

看 规划/ROADMAP.md 了解详情。

______________________________________________________________________

状态：第0阶段（技术验证）-验证JITD概念