codify-mcp 0.2.0

package/README.md

@@ -0,0 +1,339 @@
+# Codify MCP
+
+**MCP server for custom automation tools using [Apify Agent](https://apify.com/cyberfly/apify-agent)**
+
+> Part of [Project Codify](https://codify.codey.eu.org)
+
+## Project Codify
+- [Login](https://apify.com/cyberfly) - reusable authentication sessions - TBD
+
+- [Agent](https://apify.com/cyberfly) - turn scripts into browser actions
+- [Coder](https://apify.com/cyberfly) - turn browser actions into scripts (TBD - currently integrated)
+- [Robot](https://apify.com/cyberfly) - automation engine for scalability (TBD - currently integrated)
+
+More is on the way... Give it a [shot](https://codify.codey.eu.org) 🎬 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`:
+
+```bash
+npx codify-mcp {{MCP_TOOL_JSON}}
+```
+
+Or install locally:
+
+```bash
+npm install -g codify-mcp
+```
+
+## Quick Start
+
+### 1. Apify Token
+
+Optional - you can also place the token inside the MCP server JSON later.
+
+```bash
+apify login
+```
+
+This saves your token to `~/.apify/auth.json`. 
+
+Alternatively, set the environment variable:
+
+```bash
+export APIFY_TOKEN="your_token_here"
+```
+
+### 2. Create a Tool
+
+[Apify Coder](https://apify.com/cyberfly) can turn casual browser actions into reusable AI tools. 
+Currently, this feature is also integrated in [Apify Agent](https://apify.com/cyberfly/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.
+
+```json
+{
+  "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
+
+```bash
+npx codify-mcp '{"name":"scrape_product","description":"...","inputSchema":{...},"implementation":{...}}'
+```
+
+Or with multiple tools:
+
+```bash
+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`
+
+```json
+{
+  "mcpServers": {
+    "apify-agent": {
+      "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
+
+```javascript
+{
+  // 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:**
+```json
+{
+  "url": {
+    "type": "string",
+    "description": "Website URL"
+  }
+}
+```
+
+**Optional field:**
+```json
+{
+  "timeout": {
+    "type": "integer",
+    "description": "Timeout in seconds",
+    "default": 30
+  }
+}
+```
+
+**Enum (dropdown):**
+```json
+{
+  "format": {
+    "type": "string",
+    "enum": ["json", "csv", "markdown"],
+    "description": "Output format"
+  }
+}
+```
+
+## Usage Patterns
+
+### Single Tool (Development)
+
+```bash
+npx codify-mcp '{"name":"test","description":"Test tool","inputSchema":{"type":"object","properties":{}},"implementation":{"type":"apify-actor","script":"console.log('hello')"}}'
+```
+
+### Multiple Tools (Production)
+
+```bash
+npx codify-mcp \
+  "$(cat tools/scraper.json)" \
+  "$(cat tools/logger.json)" \
+  "$(cat tools/analyzer.json)"
+```
+
+### With Environment Variable
+
+```bash
+APIFY_TOKEN="apk_..." npx codify-mcp '{"name":"...","description":"...","inputSchema":{},"implementation":{"type":"apify-actor","script":"..."}}'
+```
+
+### With npm link (Local Testing)
+
+```bash
+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:
+
+```bash
+# ✓ 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:
+
+```bash
+# 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
+
+```javascript
+// ✓ 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:
+
+```json
+{
+  "mcpServers": {
+    "apify-scraper": {
+      "command": "npx",
+      "args": ["codify-mcp", "...tool1...", "...tool2..."]
+    },
+    "apify-analyzer": {
+      "command": "npx",
+      "args": ["codify-mcp", "...tool3...", "...tool4..."]
+    }
+  }
+}
+```
+
+## Development
+
+### Running Locally
+
+```bash
+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/apify-agent](https://github.com/cybairfly/apify-agent)

package/bin/start.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+/**
+ * codify-mcp executable entry point
+ * Starts MCP server with tools provided as command-line arguments
+ * 
+ * Usage:
+ *   codify-mcp '{"name":"tool1",...}'
+ * 
+ * Environment:
+ *   APIFY_TOKEN - Apify API token (optional, falls back to ~/.apify/auth.json)
+ */
+
+const { start } = require('../lib/index.js');
+
+start().catch(err => {
+	console.error('[Startup Error]', err.message);
+	process.exit(1);
+});

package/lib/index.js

@@ -0,0 +1,70 @@
+/**
+ * codify-mcp
+ * Standalone MCP server library for executing Apify Agent tools
+ * 
+ * Usage:
+ *   npx codify-mcp '{"name":"tool1",...}' '{"name":"tool2",...}'
+ * 
+ * Requires:
+ *   - APIFY_TOKEN env var OR ~/.apify/auth.json
+ */
+
+const { getToken } = require('./mcp/auth');
+const { fixModulePaths } = require('./mcp/resolver');
+const { setupServer } = require('./mcp/server_setup');
+
+/**
+ * Parse tools from process.argv
+ * @returns {Array} Array of tool objects
+ */
+const parseToolsFromArgv = () => {
+	const tools = [];
+	const toolJsonArgs = process.argv.slice(2);
+
+	for (const arg of toolJsonArgs) {
+		try {
+			const tool = JSON.parse(arg);
+			tools.push(tool);
+			console.error('[MCP Parser] Loaded tool:', tool.name || 'unnamed');
+		} catch (e) {
+			console.error('[MCP Parser] Failed to parse tool arg:', e.message);
+		}
+	}
+
+	if (tools.length === 0) {
+		console.error('[MCP Error] No valid tools in arguments. Expected JSON strings.');
+		process.exit(1);
+	}
+
+	return tools;
+};
+
+/**
+ * Start the MCP server with tools from argv
+ * Initializes everything and connects to MCP client via stdio
+ */
+const start = async () => {
+	try {
+		// 1. Fix module paths for npx environments
+		fixModulePaths();
+
+		// 2. Get Apify token
+		const apifyToken = getToken();
+		if (!apifyToken) {
+			console.error('[Auth Error] No Apify token found.');
+			console.error('Set APIFY_TOKEN env var or run: apify login');
+			process.exit(1);
+		}
+
+		// 3. Parse tools from command-line arguments
+		const tools = parseToolsFromArgv();
+
+		// 4. Setup and start MCP server
+		await setupServer({ tools, apifyToken });
+	} catch (e) {
+		console.error('[MCP Fatal Error]', e);
+		process.exit(1);
+	}
+};
+
+module.exports = { start, parseToolsFromArgv };

package/lib/mcp/actor_caller.js

@@ -0,0 +1,55 @@
+/**
+ * Apify Actor Caller
+ * Executes actor and returns results
+ */
+
+const performActorCall = async ({ client, actorId, input, server }) => {
+	// Save original stderr.write
+	const originalStderrWrite = process.stderr.write;
+
+	// Override to intercept actor logs
+	process.stderr.write = (chunk, encoding, callback) => {
+		const str = chunk.toString();
+		
+		if (str.includes('apify-agent runId:')) {
+			// Extract log part after ' -> ' (preserves all original formatting)
+			const match = str.match(/apify-agent runId:[^>]+> (.+)/);
+			if (match) {
+				const logLine = match[1];
+				// Send as MCP logging message with original formatting intact
+				if (server && server.sendLoggingMessage) {
+					server.sendLoggingMessage('info', logLine);
+				}
+			}
+			
+			// Don't write to stderr
+			if (callback) callback();
+			return true;
+		} else {
+			// Normal stderr output
+			return originalStderrWrite.call(process.stderr, chunk, encoding, callback);
+		}
+	};
+
+	try {
+		// Start the run
+		const run = await client.actor(actorId).call(input);
+		
+		// Fetch results
+		const { items } = await client.dataset(run.defaultDatasetId).listItems();
+		
+		return {
+			content: [
+				{ 
+					type: 'text', 
+					text: JSON.stringify(items.length > 0 ? items : run, null, 2) 
+				}
+			]
+		};
+	} finally {
+		// Restore stderr
+		process.stderr.write = originalStderrWrite;
+	}
+};
+
+module.exports = { performActorCall };

package/lib/mcp/auth.js

@@ -0,0 +1,33 @@
+/**
+ * Authentication Helper
+ * Returns the Apify token from env or ~/.apify/auth.json
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const getToken = () => {
+	// 1. Priority: Valid environment variable (not the placeholder)
+	if (process.env.APIFY_TOKEN && 
+		process.env.APIFY_TOKEN !== '{{Authorization}}' && 
+		process.env.APIFY_TOKEN !== 'YOUR_APIFY_TOKEN_OR_USE_ENV_VAR' &&
+		process.env.APIFY_TOKEN.trim() !== '') {
+		return process.env.APIFY_TOKEN;
+	}
+	
+	// 2. Fallback: Apify CLI auth file
+	try {
+		const authPath = path.join(os.homedir(), '.apify', 'auth.json');
+		if (fs.existsSync(authPath)) {
+			const auth = JSON.parse(fs.readFileSync(authPath, 'utf8'));
+			if (auth.token) return auth.token;
+		}
+	} catch (e) {
+		// Silently ignore auth file read errors
+	}
+	
+	return null;
+};
+
+module.exports = { getToken };

package/lib/mcp/resolver.js

@@ -0,0 +1,19 @@
+/**
+ * Module Path Resolver
+ * Fixes NODE_PATH for npx environments
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const fixModulePaths = () => {
+	process.env.PATH.split(path.delimiter).forEach(d => {
+		const b = path.join(d, '../');
+		if (d.includes('node_modules') || (fs.existsSync(b) && fs.readdirSync(b).includes('node_modules'))) {
+			const nm = d.includes('node_modules') ? d.split('node_modules')[0] + 'node_modules' : path.join(d, '../node_modules');
+			if (!module.paths.includes(nm)) module.paths.push(nm);
+		}
+	});
+};
+
+module.exports = { fixModulePaths };

package/lib/mcp/server_setup.js

@@ -0,0 +1,162 @@
+/**
+ * MCP Server Setup and Connection
+ * Initializes the MCP server with tools and connects via stdio
+ */
+
+const { ActorsMcpServer } = require('@apify/actors-mcp-server');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { ApifyClient } = require('apify-client');
+const { randomUUID } = require('node:crypto');
+const Ajv = require('ajv');
+const { performActorCall } = require('./actor_caller');
+
+const setupServer = async ({ tools, apifyToken }) => {
+	// Configure logging to stderr to avoid protocol corruption
+	try {
+		const log = require('@apify/log');
+		if (log && log.setLevel) log.setLevel(log.LEVELS.ERROR);
+	} catch (e) {
+		// Ignore if @apify/log is not found
+	}
+	console.log = (...args) => console.error(...args);
+	console.info = (...args) => console.error(...args);
+
+	// Create AJV instance for JSON Schema validation
+	const ajv = new Ajv({ allErrors: true, strict: false });
+
+	// Create MCP server
+	const server = new ActorsMcpServer({
+		transportType: 'stdio',
+		token: apifyToken,
+		telemetry: { enabled: false }
+	});
+
+	// Register all tools
+	if (!Array.isArray(tools) || tools.length === 0) {
+		console.error('[Server Error] No tools provided to server');
+		process.exit(1);
+	}
+
+	// Reconstruct tools: Apify SDK expects tool objects with methods
+	const reconstructedTools = tools.map(toolData => {
+		const tool = {
+			name: toolData.name,
+			description: toolData.description,
+			inputSchema: toolData.inputSchema || { type: 'object', properties: {} },
+			type: 'internal',
+
+			// ajvValidate: required by Apify SDK for input validation
+			ajvValidate: (input) => {
+				if (!tool.inputSchema) {
+					// If no schema, accept any input
+					return { valid: true };
+				}
+				try {
+					const validate = ajv.compile(tool.inputSchema);
+					const valid = validate(input);
+					return {
+						valid,
+						errors: validate.errors
+					};
+				} catch (error) {
+					console.error('Schema compilation error:', error);
+					return {
+						valid: false,
+						errors: [{ message: `Schema compilation failed: ${error.message}` }]
+					};
+				}
+			},
+
+			// call: the actual tool handler
+			call: async (context) => {
+				// For tools with apify-actor implementation
+				if (toolData.implementation?.type === 'apify-actor') {
+					const client = new ApifyClient({ token: apifyToken });
+					const actorId = toolData.implementation.actorId || 'cyberfly/apify-agent';
+					const script = toolData.implementation.script;
+
+					if (!script) {
+						return {
+							content: [{
+								type: 'text',
+								text: 'Error: No script provided in tool implementation'
+							}],
+							isError: true
+						};
+					}
+
+					const input = {
+						...context.args,
+						script: script
+					};
+
+					try {
+						return await performActorCall({ client, actorId, input, server });
+					} catch (e) {
+						console.error('[Tool Error]', e.message);
+						if (e.statusCode === 401 || (e.message && e.message.includes('token'))) {
+							return {
+								content: [{
+									type: 'text',
+									text: '[Authentication Required] Invalid or missing Apify token.'
+								}],
+								isError: true
+							};
+						}
+						return {
+							content: [{
+								type: 'text',
+								text: `Error: ${e.message}`
+							}],
+							isError: true
+						};
+					}
+				}
+
+				// Unsupported implementation type
+				return {
+					content: [{
+						type: 'text',
+						text: `Unsupported implementation type: ${toolData.implementation?.type}`
+					}],
+					isError: true
+				};
+			},
+
+			// Preserve optional fields
+			...(toolData.metadata && { metadata: toolData.metadata }),
+			...(toolData.version && { version: toolData.version }),
+		};
+		return tool;
+	});
+	server.upsertTools(reconstructedTools);
+	console.error(`[Server Setup] Registered ${reconstructedTools.length} tool(s)`);
+
+	// Connect server via stdio
+	try {
+		const transport = new StdioServerTransport();
+		const mcpSessionId = randomUUID();
+		
+		// Wrap onmessage to inject mcpSessionId
+		const originalOnMessage = transport.onmessage;
+		transport.onmessage = (message) => {
+			if (message.method === 'initialize') {
+				server.options.initializeRequestData = message;
+			}
+			// Inject session ID into _meta
+			const params = message.params || {};
+			params._meta = params._meta || {};
+			params._meta.mcpSessionId = mcpSessionId;
+			message.params = params;
+			
+			if (originalOnMessage) originalOnMessage(message);
+		};
+
+		await server.connect(transport);
+	} catch (e) {
+		console.error('[MCP Error]', e);
+		process.exit(1);
+	}
+};
+
+module.exports = { setupServer };

package/manifest.json

@@ -0,0 +1,74 @@
+{
+    "manifest_version": "0.2",
+    "version": "0.1.0",
+    "name": "codify-mcp",
+    "icon": "media/icons/play.png",
+    "display_name": "Codify MCP Server",
+    "description": "MCP server for custom automation tools using Apify Agent. Easily create reusable automations from casual browser actions.",
+    "author": "Apify & Community",
+    "license": "Apache-2.0",
+    "resources": {
+        "readme": "README.md"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/cybairfly/apify-agent"
+    },
+    "homepage": "https://codify.codey.eu.org",
+    "support": "https://github.com/cybairfly/apify-agent/issues",
+    "keywords": [
+        "ai",
+        "mcp",
+        "apify",
+        "agent",
+        "automation",
+        "claude",
+        "cursor",
+        "vscode",
+        "tools",
+        "model-context-protocol"
+    ],
+    "server": {
+        "type": "node",
+        "entry_point": "bin/start.js",
+        "mcp_config": {
+            "command": "node",
+            "args": [
+                "${__dirname}/bin/start.js",
+                "${user_config.tools}"
+            ],
+            "env": {
+                "APIFY_TOKEN": "${user_config.apify_token}"
+            }
+        }
+    },
+    "compatibility": {
+        "platforms": [
+            "darwin",
+            "linux",
+            "win32"
+        ],
+        "node_version": ">=20.0.0",
+        "clients": [
+            "claude_desktop",
+            "cursor"
+        ]
+    },
+    "user_config": {
+        "properties": {
+            "APIFY_TOKEN": {
+                "type": "string",
+                "description": "Apify API token for authentication",
+                "required": false,
+                "sensitive": true,
+                "masked": true
+            },
+            "tools": {
+                "type": "string",
+                "title": "Custom tools",
+                "description": "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.",
+                "required": false
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "codify-mcp",
+  "version": "0.2.0",
+  "description": "MCP server for custom automation tools using Apify Agent. Easily create reusable automations from casual browser actions.",
+  "main": "lib/index.js",
+  "bin": {
+    "codify-mcp": "bin/start.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "media/",
+    "server.json",
+    "manifest.json",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/start.js"
+  },
+  "keywords": [
+    "ai",
+    "mcp",
+    "apify",
+    "agent",
+    "apify-agent",
+    "automation",
+    "claude",
+    "cursor",
+    "vscode",
+    "tools",
+    "model-context-protocol"
+  ],
+  "author": "Apify & Community",
+  "license": "Apache-2.0",
+  "homepage": "https://codify.codey.eu.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cybairfly/apify-agent.git",
+    "directory": "libraries/codify-mcp"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "compatibility": {
+    "claude_desktop": ">=0.2.16",
+    "platforms": [
+      "darwin",
+      "win32",
+      "linux"
+    ]
+  },
+  "dependencies": {
+    "@apify/actors-mcp-server": "^0.7.1",
+    "@modelcontextprotocol/sdk": "^0.7.0",
+    "apify-client": "^2.1.0",
+    "@apify/log": "^1.0.0",
+    "ajv": "^8.12.0"
+  }
+}

package/server.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://raw.githubusercontent.com/modelcontextprotocol/modelcontextprotocol/main/schema/2025-11-25/schema.json",
+  "name": "com.apify/codify-mcp",
+  "version": "0.1.0",
+  "description": "Easily create reusable automation tools from casual browser actions using Apify Agent",
+  "transport": {
+    "type": "stdio",
+    "command": "codify-mcp",
+    "args": []
+  },
+  "authentication": {
+    "type": "environment",
+    "env_var": "APIFY_TOKEN"
+  },
+  "capabilities": {
+    "tools": true,
+    "prompts": false,
+    "resources": false
+  },
+  "implementation": {
+    "name": "Codify MCP Server",
+    "version": "0.1.0"
+  }
+}