Codify MCP

🚀 Codify MCP

Codify MCP is an MCP server designed for custom automation tools, leveraging the Apify Agent.

It's part of Project Codify.

📚 Project Codify

Project Codify offers a comprehensive end-to-end browser automation pipeline that can run either inside the browser or locally. It enables users to codify and replay browser actions as robust (deterministic) and reusable scripts, catering to a wide range of needs from rapid prototyping and quick automation scripts to large-scale sophisticated deployments.

• Login - Reusable authentication sessions and secure login (To Be Determined) ❎
• Agent - Convert scripts into browser actions, supporting both code and text scripts (Available in the future) ✅
• Coder - Transform browser actions into scripts (Currently integrated) ✅
• Robot - An automation engine for scalability (Currently integrated) ✅
• MCP - Turn automations into reusable tools that can be utilized through AI ✅

There's more to come! Give it a try here 🎬 or join the list to stay updated on the project! 🔔

✨ Features

The Model Context Protocol (MCP) server allows AI assistants (such as Claude, Cursor, and VS Code) to execute browser automation tasks via the Apify Agent. Tools are passed as clean JSON arguments, one per line, eliminating the need for manual setup or file creation.

📦 Installation

Run directly using npx

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

Install locally

npm install -g codify-mcp

💻 Usage Examples

Basic Usage

1. Apify Token (Optional)

You can also place the token inside the MCP server JSON later.

apify login

This command saves your token to ~/.apify/auth.json. Alternatively, you can set the environment variable:

export APIFY_TOKEN="your_token_here"

2. Create a Tool

Apify Coder can convert casual browser actions into reusable AI tools. Currently, this feature is also integrated in Apify Agent. Export a tool and append the result as a JSON string to the MCP server args field or ask your AI to do it for you.

{
  "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. Run the Server

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

Or with multiple tools:

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

4. Connect to Claude Desktop (or Cursor/VS Code)

Edit your Claude Desktop config:

• 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"
      }
    }
  }
}

Restart Claude. Your tools are now available to the AI assistant.

Advanced Usage

Tool Definition Reference

Basic Structure

{
  // Required
  "name": "tool_name",                    // alphanumeric + underscore/dash
  "description": "What the tool does",    // shown to AI
  "inputSchema": {
    "type": "object",
    "properties": {
      "paramName": {
        "type": "string",
        "description": "Parameter description"
      }
    },
    "required": ["paramName"]
  },
  "implementation": {
    "type": "apify-actor",
    "actorId": "cyberfly/apify-agent",    // actor to run
    "script": "await page.goto(inputs.url); ..."  // Playwright code
  },
  
  // Optional
  "version": "1.0.0",
  "metadata": { "custom": "fields" }
}

Implementation Details

• script: Playwright automation code. It receives an inputs object with user-provided parameters and a page object for browser automation.
• actorId: The Apify actor to execute. The default is cyberfly/apify-agent.

Input Schema Examples

Simple text input:

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

Optional field:

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

Enum (dropdown):

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

Usage Patterns

Single Tool (Development)

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

Multiple Tools (Production)

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

With Environment Variable

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

With npm link (Local Testing)

cd /path/to/codify-mcp
npm link

# Now use anywhere
codify-mcp '{"name":"...","description":"...","inputSchema":{},"implementation":{"type":"apify-actor","script":"..."}}'

🔧 Technical Details

Authentication

Token resolution order:

1. APIFY_TOKEN environment variable (if set and not empty)
2. ~/.apify/auth.json (from apify login CLI command)
3. Error: No token found, tool execution will fail with a clear message

Troubleshooting

"No valid tools in arguments"

Ensure you're passing valid JSON strings as arguments:

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

# ✗ Wrong (missing quotes around JSON)
npx codify-mcp {name:"test"...}

# ✗ Wrong (single quotes around JSON on Linux/Mac may need escaping)
npx codify-mcp '{name:"test"...}'  # Use double quotes inside

"Invalid or missing Apify token"

Ensure authentication is set up:

# Option 1: Login via CLI
apify login

# Option 2: Set environment variable
export APIFY_TOKEN="apk_your_token_here"
apify token

"Tool execution failed"

Check your Playwright script syntax. The script must be valid JavaScript that:

• Has access to inputs (user-provided parameters)
• Has access to page (Playwright page object)
• Returns a value or object

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

// ✗ Invalid (missing await)
page.goto(inputs.url);

Large Tool Sets (50+ tools)

If you have many tools, consider splitting into multiple MCP servers:

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

Development

Running Locally

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

Structure

lib/
  index.js              # Main entry: assembleWrapperCode(), start()
  mcp/
    resolver.js         # Module path bootstrapping
    auth.js             # Token resolution
    actor_caller.js     # Apify actor execution
    server_setup.js     # MCP server + tool registration

bin/
  start.js    # Executable entry point (bin field in package.json)

Key Design Principles

• No files: Tools are passed entirely via argv, eliminating the need for config files or manual setup.
• No base64: Clean, readable command lines without obfuscation.
• Self-contained: All dependencies are bundled, allowing it to work offline once installed.
• Stateless: Each invocation is independent, facilitating easy horizontal scaling.
• Token from env/CLI: Seamless authentication experience, respecting Apify ecosystem conventions.

📄 License

This project is licensed under the Apache-2.0 license.

🤝 Contributing

Issues and pull requests are welcome at github.com/cybairfly/codify-mcp.