io.github.cybairfly/codify-mcp

Codify MCP

MCP server for custom automation tools using Apify Agent

Part of Project Codify

Project Codify

Complete end-to-end browser automation pipeline running inside browser (or locally). Codify and replay browser actions as robust (deterministic) and reusable scripts. From rapid prototyping and quick automation scripts to sophisticated deployments at scale.

• Login - reusable authentication sessions - reusable secure login (TBD) ❎

• Agent - turn scripts into browser actions - code or text script (future) ✅

• Coder - turn browser actions into scripts (TBD - currently integrated) ✅

• Robot - automation engine for scalability (TBD - currently integrated) ✅

• MCP - automations become reusable tools you can reuse through AI ✅

More is on the way... Give it a shot 🎬 or join the list to follow the project! 🔔

What It Does

Model Context Protocol (MCP) server that lets AI assistants (e.g. Claude, Cursor, VS Code) execute browser automation tasks via Apify Agent. Tools are passed as clean JSON arguments — one per line. No manual setup or file creation.

Usage

Run directly using npx:

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

Or install locally:

npm install -g codify-mcp

Quick Start

1. Apify Token

Optional - you can also place the token inside the MCP server JSON later.

apify login

This saves your token to ~/.apify/auth.json.

Alternatively, set the environment variable:

export APIFY_TOKEN="your_token_here"

2. Create a Tool

Apify Coder can turn 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.

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. Receives inputs object with user-provided parameters and page object for browser automation.
• actorId: Apify actor to execute. Defaults to 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":"..."}}'

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 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 passed entirely via argv; no config files or manual setup.
• No base64: Clean, readable command lines; no obfuscation.
• Self-contained: All dependencies bundled; works offline once installed.
• Stateless: Each invocation is independent; easy horizontal scaling.
• Token from env/CLI: Seamless auth experience; respects Apify ecosystem conventions.

License

Apache-2.0

Contributing

Issues and PRs welcome at github.com/cybairfly/codify-mcp