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 提交問題和拉取請求。