codify-mcp

🚀 Codify MCP

Codify MCP 是一个使用 Apify Agent 的自定义自动化工具的 MCP 服务器，它是 Project Codify 的一部分。该项目提供了一个完整的端到端浏览器自动化管道，可在浏览器（或本地）中运行，能够将浏览器操作编码并回放为健壮（确定性）且可重复使用的脚本，适用于从快速原型制作和快速自动化脚本到大规模复杂部署等各种场景。

🚀 快速开始

1. Apify Token

这一步是可选的，你也可以稍后将令牌放在 MCP 服务器的 JSON 中。

apify login

此命令会将你的令牌保存到 ~/.apify/auth.json 文件中。

或者，你也可以设置环境变量：

export APIFY_TOKEN="your_token_here"

2. 创建工具

Apify Coder 可以将日常的浏览器操作转换为可重复使用的 AI 工具。目前，此功能也集成在了 Apify Agent 中。

导出一个工具，并将结果作为 JSON 字符串附加到 MCP 服务器的 args 字段中，或者让你的 AI 帮你完成此操作。

{
  "name": "scrape_product",
  "description": "Scrape product info from a page",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "Product page URL"
      }
    },
    "required": ["url"]
  },
  "implementation": {
    "type": "apify-actor",
    "actorId": "cyberfly/apify-agent",
    "script": "await page.goto(inputs.url); const title = await page.textContent('h1'); return {title};"
  }
}

3. 运行服务器

npx codify-mcp '{"name":"scrape_product","description":"...","inputSchema":{...},"implementation":{...}}'

或者使用多个工具：

npx codify-mcp \
  '{"name":"tool1",...}' \
  '{"name":"tool2",...}' \
  '{"name":"tool3",...}'

4. 连接到 Claude Desktop（或 Cursor/VS Code）

编辑你的 Claude Desktop 配置文件：

• macOS/Linux：~/.config/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "codify-mcp": {
      "command": "npx",
      "args": [
        "codify-mcp",
        "{\"name\":\"scrape_product\",\"description\":\"...\",\"inputSchema\":{...},\"implementation\":{...}}"
      ],
      "env": {
        "APIFY_TOKEN": "your_token_or_leave_empty_to_use_auth_file"
      }
    }
  }
}

重启 Claude，你的工具现在就可以供 AI 助手使用了。

✨ 主要特性

• Project Codify：提供完整的端到端浏览器自动化管道，可在浏览器（或本地）中运行，能将浏览器操作编码并回放为健壮（确定性）且可重复使用的脚本，适用于不同规模的自动化场景。
• 多组件支持：包括 Login（可重复使用的认证会话，可重复使用的安全登录，待开发）、Agent（将脚本转换为浏览器操作，支持代码或文本脚本，未来功能）、Coder（将浏览器操作转换为脚本，目前已集成）、Robot（用于可扩展性的自动化引擎，目前已集成）、MCP（使自动化成为可通过 AI 重复使用的工具）。
• Model Context Protocol (MCP) 服务器：允许 AI 助手（如 Claude、Cursor、VS Code）通过 Apify Agent 执行浏览器自动化任务。工具以干净的 JSON 参数形式传递，每行一个，无需手动设置或创建文件。

📦 安装指南

直接使用 npx 运行

npx codify-mcp {{JSON_MCP_TOOL_1}} {{JSON_MCP_TOOL_2}} {{JSON_MCP_TOOL_3}}...

本地安装

npm install -g codify-mcp

💻 使用示例

基础用法

单工具（开发环境）

npx codify-mcp '{"name":"test","description":"Test tool","inputSchema":{"type":"object","properties":{}},"implementation":{"type":"apify-actor","script":"console.log('hello')"}}'

多工具（生产环境）

npx codify-mcp \
  "$(cat tools/scraper.json)" \
  "$(cat tools/logger.json)" \
  "$(cat tools/analyzer.json)"

使用环境变量

APIFY_TOKEN="apk_..." npx codify-mcp '{"name":"...","description":"...","inputSchema":{},"implementation":{"type":"apify-actor","script":"..."}}'

使用 npm link（本地测试）

cd /path/to/codify-mcp
npm link

# 现在可以在任何地方使用
codify-mcp '{"name":"...","description":"...","inputSchema":{},"implementation":{"type":"apify-actor","script":"..."}}'

📚 详细文档

工具定义参考

基本结构

{
  // 必需
  "name": "tool_name",                    // 字母数字 + 下划线/破折号
  "description": "What the tool does",    // 展示给 AI
  "inputSchema": {
    "type": "object",
    "properties": {
      "paramName": {
        "type": "string",
        "description": "Parameter description"
      }
    },
    "required": ["paramName"]
  },
  "implementation": {
    "type": "apify-actor",
    "actorId": "cyberfly/apify-agent",    // 要运行的 actor
    "script": "await page.goto(inputs.url); ..."  // Playwright 代码
  },
  
  // 可选
  "version": "1.0.0",
  "metadata": { "custom": "fields" }
}

实现细节

• script：Playwright 自动化代码。接收包含用户提供参数的 inputs 对象和用于浏览器自动化的 page 对象。
• actorId：要执行的 Apify actor，默认为 cyberfly/apify-agent。

输入模式示例

简单文本输入：

{
  "url": {
    "type": "string",
    "description": "Website URL"
  }
}

可选字段：

{
  "timeout": {
    "type": "integer",
    "description": "Timeout in seconds",
    "default": 30
  }
}

枚举（下拉列表）：

{
  "format": {
    "type": "string",
    "enum": ["json", "csv", "markdown"],
    "description": "Output format"
  }
}

认证

令牌解析顺序：

1. APIFY_TOKEN 环境变量（如果设置且不为空）
2. ~/.apify/auth.json（通过 apify login CLI 命令生成）
3. 错误：未找到令牌，工具执行将失败并显示明确的错误信息

故障排除

"No valid tools in arguments"

确保你传递的是有效的 JSON 字符串作为参数：

# ✓ 正确
npx codify-mcp '{"name":"test","description":"Test","inputSchema":{"type":"object","properties":{}},"implementation":{"type":"apify-actor","script":"return {ok:true}"}}'

# ✗ 错误（JSON 缺少引号）
npx codify-mcp {name:"test"...}

# ✗ 错误（在 Linux/Mac 上，JSON 周围的单引号可能需要转义）
npx codify-mcp '{name:"test"...}'  # 内部使用双引号

"Invalid or missing Apify token"

确保已设置认证：

# 选项 1：通过 CLI 登录
apify login

# 选项 2：设置环境变量
export APIFY_TOKEN="apk_your_token_here"
apify token

"Tool execution failed"

检查你的 Playwright 脚本语法。脚本必须是有效的 JavaScript，并且：

• 可以访问 inputs（用户提供的参数）
• 可以访问 page（Playwright 页面对象）
• 返回一个值或对象

// ✓ 有效
await page.goto(inputs.url);
const title = await page.textContent('h1');
return { title };

// ✗ 无效（缺少 await）
page.goto(inputs.url);

大型工具集（50 个以上工具）

如果你有很多工具，可以考虑将它们拆分为多个 MCP 服务器：

{
  "mcpServers": {
    "apify-scraper": {
      "command": "npx",
      "args": ["codify-mcp", "...tool1...", "...tool2..."]
    },
    "apify-analyzer": {
      "command": "npx",
      "args": ["codify-mcp", "...tool3...", "...tool4..."]
    }
  }
}

开发

本地运行

npm link
codify-mcp '{"name":"test",...}'

项目结构

lib/
  index.js              # 主入口：assembleWrapperCode(), start()
  mcp/
    resolver.js         # 模块路径引导
    auth.js             # 令牌解析
    actor_caller.js     # Apify actor 执行
    server_setup.js     # MCP 服务器 + 工具注册

bin/
  start.js    # 可执行入口点（package.json 中的 bin 字段）

🔧 技术细节

关键设计原则

• 无文件依赖：工具完全通过 argv 传递，无需配置文件或手动设置。
• 无 base64 编码：命令行干净、可读，无混淆。
• 自包含：所有依赖项都打包在一起，安装后可离线使用。
• 无状态：每次调用都是独立的，易于水平扩展。
• 令牌来自环境变量/CLI：无缝的认证体验，遵循 Apify 生态系统约定。

📄 许可证

本项目采用 Apache-2.0 许可证。

🤝 贡献

欢迎在 github.com/cybairfly/codify-mcp 提交问题和拉取请求。