@agentled/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Agentled
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @agentled/mcp-server
+
+MCP server for [Agentled](https://www.agentled.app) — create, manage, and run automation workflows from Claude Code.
+
+## Quick Setup
+
+```bash
+claude mcp add agentled \
+  -e AGENTLED_API_KEY=wsk_... \
+  -e AGENTLED_URL=https://www.agentled.app \
+  -- agentled-mcp-server
+```
+
+### Getting your API key
+
+1. Go to your [Agentled workspace](https://www.agentled.app)
+2. Open **Workspace Settings > Developer**
+3. Generate a new API key (starts with `wsk_`)
+
+### Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AGENTLED_API_KEY` | Yes | Workspace API key (`wsk_...`) |
+| `AGENTLED_URL` | No | API base URL (default: `https://www.agentled.app`) |
+
+## Available Tools
+
+### Workflows
+
+| Tool | Description |
+|------|-------------|
+| `list_workflows` | List all workflows in the workspace |
+| `get_workflow` | Get full workflow definition by ID |
+| `create_workflow` | Create a new workflow from pipeline JSON |
+| `update_workflow` | Update an existing workflow |
+| `delete_workflow` | Permanently delete a workflow |
+| `validate_workflow` | Validate pipeline structure, returns errors per step |
+| `publish_workflow` | Change workflow status (draft, live, paused, archived) |
+| `export_workflow` | Export a workflow as portable JSON |
+| `import_workflow` | Import a workflow from exported JSON |
+
+### Drafts & Snapshots
+
+| Tool | Description |
+|------|-------------|
+| `get_draft` | Get the current draft version of a workflow |
+| `promote_draft` | Promote a draft to the live version |
+| `discard_draft` | Discard the current draft |
+| `list_snapshots` | List version snapshots for a workflow |
+| `restore_snapshot` | Restore a workflow to a previous snapshot |
+
+### Executions
+
+| Tool | Description |
+|------|-------------|
+| `start_workflow` | Start a workflow execution with input |
+| `list_executions` | List executions for a workflow |
+| `get_execution` | Get execution details with step results |
+| `stop_execution` | Stop a running execution |
+| `retry_execution` | Retry a failed execution |
+
+### Apps & Testing
+
+| Tool | Description |
+|------|-------------|
+| `list_apps` | List available apps and integrations |
+| `get_app_actions` | Get action schemas for an app |
+| `test_app_action` | Test an app action without creating a workflow |
+| `test_ai_action` | Test an AI prompt without creating a workflow |
+
+### Knowledge & Data
+
+| Tool | Description |
+|------|-------------|
+| `get_workspace` | Get workspace info and settings |
+| `list_knowledge_lists` | List knowledge lists in the workspace |
+| `get_knowledge_rows` | Get rows from a knowledge list |
+| `get_knowledge_text` | Get text content from a knowledge entry |
+| `query_kg_edges` | Query knowledge graph edges |
+| `get_scoring_history` | Get scoring history for an entity |
+
+### n8n Migration
+
+| Tool | Description |
+|------|-------------|
+| `preview_n8n_import` | Preview an n8n workflow import (dry run) |
+| `import_n8n_workflow` | Import an n8n workflow into Agentled |
+
+## Example Usage
+
+Once connected, you can ask Claude Code to:
+
+- "List my workflows"
+- "Create a workflow that scrapes a URL and summarizes the content"
+- "Show me the last 5 executions of my lead scoring workflow"
+- "Test the LinkedIn company enrichment action with this URL"
+
+## Building from Source
+
+```bash
+git clone https://github.com/agentled/mcp-server.git
+cd mcp-server
+npm install
+npm run build
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,67 @@
+/**
+ * AgentledClient — HTTP client wrapping the /api/external/* routes.
+ *
+ * Reads AGENTLED_API_KEY and AGENTLED_URL from environment variables.
+ */
+export declare class AgentledClient {
+    private baseUrl;
+    private apiKey;
+    constructor();
+    private request;
+    listWorkflows(params?: {
+        status?: string;
+        limit?: number;
+    }): Promise<any>;
+    getWorkflow(id: string): Promise<any>;
+    createWorkflow(pipeline: Record<string, any>, locale?: string): Promise<any>;
+    updateWorkflow(id: string, updates: Record<string, any>, locale?: string): Promise<any>;
+    deleteWorkflow(id: string): Promise<any>;
+    validateWorkflow(id: string, pipeline?: Record<string, any>): Promise<any>;
+    publishWorkflow(id: string, status: string): Promise<any>;
+    listSnapshots(workflowId: string): Promise<any>;
+    restoreSnapshot(workflowId: string, snapshotId: string): Promise<any>;
+    getDraft(workflowId: string): Promise<any>;
+    promoteDraft(workflowId: string): Promise<any>;
+    discardDraft(workflowId: string): Promise<any>;
+    startWorkflow(id: string, input?: Record<string, any>, metadata?: Record<string, any>): Promise<any>;
+    listExecutions(workflowId: string, params?: {
+        status?: string;
+        limit?: number;
+        nextToken?: string;
+        direction?: 'asc' | 'desc';
+    }): Promise<any>;
+    getExecution(workflowId: string, executionId: string): Promise<any>;
+    stopExecution(workflowId: string, executionId: string): Promise<any>;
+    retryExecution(workflowId: string, executionId: string, options?: {
+        timelineId?: string;
+        forceWithoutCache?: boolean;
+        rerunMode?: string;
+    }): Promise<any>;
+    listApps(): Promise<any>;
+    getAppActions(appId: string): Promise<any>;
+    testAppAction(appId: string, actionId: string, input?: Record<string, any>, bypassCache?: boolean): Promise<any>;
+    testAiAction(template: string, variables?: Record<string, any>, responseStructure?: Record<string, any>, options?: {
+        responseType?: string;
+        systemPrompt?: string;
+    }): Promise<any>;
+    exportWorkflow(id: string): Promise<any>;
+    importWorkflow(exportData: Record<string, any>, locale?: string): Promise<any>;
+    getWorkspace(): Promise<any>;
+    listKnowledgeLists(): Promise<any>;
+    getKnowledgeRows(listKey: string, limit?: number): Promise<any>;
+    getKnowledgeText(key: string): Promise<any>;
+    queryKgEdges(entityName?: string, relationshipType?: string, limit?: number): Promise<any>;
+    getScoringHistory(entityName?: string, limit?: number): Promise<any>;
+    previewN8nImport(n8nJson: string | Record<string, any>, options?: Record<string, any>, workflow?: {
+        name?: string;
+        goal?: string;
+        description?: string;
+        pathname?: string;
+    }): Promise<any>;
+    importN8nWorkflow(n8nJson: string | Record<string, any>, workflow?: {
+        name?: string;
+        goal?: string;
+        description?: string;
+        pathname?: string;
+    }, options?: Record<string, any>, locale?: string): Promise<any>;
+}

package/dist/client.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * AgentledClient — HTTP client wrapping the /api/external/* routes.
+ *
+ * Reads AGENTLED_API_KEY and AGENTLED_URL from environment variables.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentledClient = void 0;
+class AgentledClient {
+    baseUrl;
+    apiKey;
+    constructor() {
+        this.apiKey = process.env.AGENTLED_API_KEY || '';
+        this.baseUrl = (process.env.AGENTLED_URL || 'http://localhost:3000').replace(/\/$/, '');
+        if (!this.apiKey) {
+            throw new Error('AGENTLED_API_KEY is not set. Generate one in Workspace Settings > Developer.');
+        }
+    }
+    async request(path, options = {}) {
+        const url = `${this.baseUrl}/api/external${path}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                ...options.headers,
+            },
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            throw new Error(data.error || `HTTP ${response.status}: ${response.statusText}`);
+        }
+        return data;
+    }
+    // --- Workflows ---
+    async listWorkflows(params) {
+        const query = new URLSearchParams();
+        if (params?.status)
+            query.set('status', params.status);
+        if (params?.limit)
+            query.set('limit', String(params.limit));
+        const qs = query.toString();
+        return this.request(`/workflows${qs ? `?${qs}` : ''}`);
+    }
+    async getWorkflow(id) {
+        return this.request(`/workflows/${id}`);
+    }
+    async createWorkflow(pipeline, locale) {
+        return this.request('/workflows', {
+            method: 'POST',
+            body: JSON.stringify({ pipeline, locale }),
+        });
+    }
+    async updateWorkflow(id, updates, locale) {
+        return this.request(`/workflows/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify({ updates, locale }),
+        });
+    }
+    async deleteWorkflow(id) {
+        return this.request(`/workflows/${id}`, { method: 'DELETE' });
+    }
+    async validateWorkflow(id, pipeline) {
+        return this.request(`/workflows/${id}/validate`, {
+            method: 'POST',
+            body: JSON.stringify({ pipeline }),
+        });
+    }
+    async publishWorkflow(id, status) {
+        return this.request(`/workflows/${id}/status`, {
+            method: 'PATCH',
+            body: JSON.stringify({ status }),
+        });
+    }
+    async listSnapshots(workflowId) {
+        return this.request(`/workflows/${workflowId}/snapshots`);
+    }
+    async restoreSnapshot(workflowId, snapshotId) {
+        return this.request(`/workflows/${workflowId}/snapshots`, {
+            method: 'POST',
+            body: JSON.stringify({ snapshotId }),
+        });
+    }
+    // --- Draft Lifecycle ---
+    async getDraft(workflowId) {
+        return this.request(`/workflows/${workflowId}/draft`);
+    }
+    async promoteDraft(workflowId) {
+        return this.request(`/workflows/${workflowId}/draft`, {
+            method: 'POST',
+        });
+    }
+    async discardDraft(workflowId) {
+        return this.request(`/workflows/${workflowId}/draft`, {
+            method: 'DELETE',
+        });
+    }
+    // --- Executions ---
+    async startWorkflow(id, input, metadata) {
+        return this.request(`/workflows/${id}/start`, {
+            method: 'POST',
+            body: JSON.stringify({ input, metadata }),
+        });
+    }
+    async listExecutions(workflowId, params) {
+        const query = new URLSearchParams();
+        if (params?.status)
+            query.set('status', params.status);
+        if (params?.limit)
+            query.set('limit', String(params.limit));
+        if (params?.nextToken)
+            query.set('nextToken', params.nextToken);
+        if (params?.direction)
+            query.set('direction', params.direction);
+        const qs = query.toString();
+        return this.request(`/workflows/${workflowId}/executions${qs ? `?${qs}` : ''}`);
+    }
+    async getExecution(workflowId, executionId) {
+        return this.request(`/workflows/${workflowId}/executions/${executionId}`);
+    }
+    async stopExecution(workflowId, executionId) {
+        return this.request(`/workflows/${workflowId}/executions/${executionId}/stop`, {
+            method: 'POST',
+        });
+    }
+    async retryExecution(workflowId, executionId, options) {
+        return this.request(`/workflows/${workflowId}/executions/${executionId}/retry`, {
+            method: 'POST',
+            body: JSON.stringify({
+                timelineId: options?.timelineId,
+                forceWithoutCache: options?.forceWithoutCache,
+                rerunMode: options?.rerunMode,
+            }),
+        });
+    }
+    // --- Apps ---
+    async listApps() {
+        return this.request('/apps');
+    }
+    async getAppActions(appId) {
+        return this.request(`/apps/${appId}/actions`);
+    }
+    // --- Step Testing ---
+    async testAppAction(appId, actionId, input, bypassCache) {
+        return this.request('/step/test', {
+            method: 'POST',
+            body: JSON.stringify({ appId, actionId, input, bypassCache }),
+        });
+    }
+    async testAiAction(template, variables, responseStructure, options) {
+        return this.request('/step/test-ai', {
+            method: 'POST',
+            body: JSON.stringify({
+                template,
+                variables,
+                responseStructure,
+                responseType: options?.responseType,
+                systemPrompt: options?.systemPrompt,
+            }),
+        });
+    }
+    // --- Workflow Export/Import ---
+    async exportWorkflow(id) {
+        return this.request(`/workflows/${id}/export`);
+    }
+    async importWorkflow(exportData, locale) {
+        return this.request('/workflows/import', {
+            method: 'POST',
+            body: JSON.stringify({ export: exportData, locale }),
+        });
+    }
+    // --- Workspace ---
+    async getWorkspace() {
+        return this.request('/workspace');
+    }
+    // --- Knowledge ---
+    async listKnowledgeLists() {
+        return this.request('/knowledge/lists');
+    }
+    async getKnowledgeRows(listKey, limit) {
+        const query = new URLSearchParams({ listKey });
+        if (limit)
+            query.set('limit', String(limit));
+        return this.request(`/knowledge/rows?${query}`);
+    }
+    async getKnowledgeText(key) {
+        const query = new URLSearchParams({ key });
+        return this.request(`/knowledge/text?${query}`);
+    }
+    // --- Knowledge Graph ---
+    async queryKgEdges(entityName, relationshipType, limit) {
+        const query = new URLSearchParams();
+        if (entityName)
+            query.set('entityName', entityName);
+        if (relationshipType)
+            query.set('relationshipType', relationshipType);
+        if (limit)
+            query.set('limit', String(limit));
+        const qs = query.toString();
+        return this.request(`/knowledge/graph/edges${qs ? `?${qs}` : ''}`);
+    }
+    async getScoringHistory(entityName, limit) {
+        const query = new URLSearchParams();
+        if (entityName)
+            query.set('entityName', entityName);
+        if (limit)
+            query.set('limit', String(limit));
+        const qs = query.toString();
+        return this.request(`/knowledge/graph/scoring${qs ? `?${qs}` : ''}`);
+    }
+    // --- n8n Import ---
+    async previewN8nImport(n8nJson, options, workflow) {
+        return this.request('/workflows/import/n8n/preview', {
+            method: 'POST',
+            body: JSON.stringify({ n8nJson, options, workflow }),
+        });
+    }
+    async importN8nWorkflow(n8nJson, workflow, options, locale) {
+        return this.request('/workflows/import/n8n/create', {
+            method: 'POST',
+            body: JSON.stringify({ n8nJson, workflow, options, locale }),
+        });
+    }
+}
+exports.AgentledClient = AgentledClient;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Agentled MCP Server — Entry point
+ *
+ * Connects via stdio transport for use with Claude Code.
+ *
+ * Environment variables:
+ *   AGENTLED_API_KEY  — Workspace API key (wsk_*)
+ *   AGENTLED_URL      — Base URL (default: http://localhost:3000)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Agentled MCP Server — Entry point
+ *
+ * Connects via stdio transport for use with Claude Code.
+ *
+ * Environment variables:
+ *   AGENTLED_API_KEY  — Workspace API key (wsk_*)
+ *   AGENTLED_URL      — Base URL (default: http://localhost:3000)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const server_js_1 = require("./server.js");
+async function main() {
+    const server = (0, server_js_1.createServer)();
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Failed to start Agentled MCP server:', error);
+    process.exit(1);
+});

package/dist/resources/apps.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Resource — App Catalog
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AgentledClient } from '../client.js';
+export declare function registerAppResources(server: McpServer, client: AgentledClient): void;

package/dist/resources/apps.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * MCP Resource — App Catalog
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAppResources = registerAppResources;
+function registerAppResources(server, client) {
+    server.resource('app-catalog', 'agentled://apps', {
+        description: 'Browse all available Agentled apps and their actions. Use this to discover integrations for building workflows.',
+        mimeType: 'application/json',
+    }, async () => {
+        const result = await client.listApps();
+        return {
+            contents: [{
+                    uri: 'agentled://apps',
+                    mimeType: 'application/json',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+}

package/dist/resources/workflows.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Resource — Workspace Workflows
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AgentledClient } from '../client.js';
+export declare function registerWorkflowResources(server: McpServer, client: AgentledClient): void;

package/dist/resources/workflows.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * MCP Resource — Workspace Workflows
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWorkflowResources = registerWorkflowResources;
+function registerWorkflowResources(server, client) {
+    server.resource('workflow-catalog', 'agentled://workflows', {
+        description: 'Browse all workflows in the current workspace. Shows id, name, status, and goal for each workflow.',
+        mimeType: 'application/json',
+    }, async () => {
+        const result = await client.listWorkflows({ limit: 100 });
+        return {
+            contents: [{
+                    uri: 'agentled://workflows',
+                    mimeType: 'application/json',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Agentled MCP Server setup.
+ *
+ * Registers all tools and resources.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Agentled MCP Server setup.
+ *
+ * Registers all tools and resources.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createServer = createServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const client_js_1 = require("./client.js");
+const workflows_js_1 = require("./tools/workflows.js");
+const executions_js_1 = require("./tools/executions.js");
+const apps_js_1 = require("./tools/apps.js");
+const testing_js_1 = require("./tools/testing.js");
+const knowledge_js_1 = require("./tools/knowledge.js");
+const apps_js_2 = require("./resources/apps.js");
+const workflows_js_2 = require("./resources/workflows.js");
+function createServer() {
+    const server = new mcp_js_1.McpServer({
+        name: 'agentled',
+        version: '0.1.0',
+    });
+    const client = new client_js_1.AgentledClient();
+    // Register tools
+    (0, workflows_js_1.registerWorkflowTools)(server, client);
+    (0, executions_js_1.registerExecutionTools)(server, client);
+    (0, apps_js_1.registerAppTools)(server, client);
+    (0, testing_js_1.registerTestingTools)(server, client);
+    (0, knowledge_js_1.registerKnowledgeTools)(server, client);
+    // Register resources
+    (0, apps_js_2.registerAppResources)(server, client);
+    (0, workflows_js_2.registerWorkflowResources)(server, client);
+    return server;
+}

package/dist/tools/apps.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Tools — App Discovery
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AgentledClient } from '../client.js';
+export declare function registerAppTools(server: McpServer, client: AgentledClient): void;

package/dist/tools/apps.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * MCP Tools — App Discovery
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAppTools = registerAppTools;
+const zod_1 = require("zod");
+function registerAppTools(server, client) {
+    server.tool('list_apps', `List all available apps/integrations in Agentled. Returns app names, descriptions, and action summaries.
+Use this to discover what integrations are available before building a workflow.
+Common apps: agentled (LinkedIn enrichment, email finder), hunter (email), web-scraping, affinity-crm, specter, http-request.`, {}, async () => {
+        const result = await client.listApps();
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('get_app_actions', `Get detailed action schemas for a specific app. Returns input parameters, output fields, and credit costs.
+Use this to understand exactly what inputs an action needs when building workflow steps.`, {
+        appId: zod_1.z.string().describe('The app ID (e.g., "agentled", "hunter", "web-scraping", "affinity-crm")'),
+    }, async ({ appId }) => {
+        const result = await client.getAppActions(appId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+}

package/dist/tools/executions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Tools — Workflow Executions
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AgentledClient } from '../client.js';
+export declare function registerExecutionTools(server: McpServer, client: AgentledClient): void;

package/dist/tools/executions.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * MCP Tools — Workflow Executions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerExecutionTools = registerExecutionTools;
+const zod_1 = require("zod");
+function registerExecutionTools(server, client) {
+    server.tool('start_workflow', `Start a workflow execution. Optionally provide input data that maps to the workflow's input page fields.
+For example, if the workflow expects "company_url", pass: { input: { company_url: "https://..." } }`, {
+        workflowId: zod_1.z.string().describe('The workflow ID to start'),
+        input: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Input payload matching the workflow input page fields'),
+        metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Optional execution metadata'),
+    }, async ({ workflowId, input, metadata }) => {
+        const result = await client.startWorkflow(workflowId, input, metadata);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('list_executions', 'List recent executions for a workflow. Returns execution id, status, timestamps.', {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+        status: zod_1.z.string().optional().describe('Filter: running, completed, failed'),
+        limit: zod_1.z.number().optional().describe('Max results (default 50, max 500)'),
+        direction: zod_1.z.enum(['asc', 'desc']).optional().describe('Sort order (default: desc)'),
+    }, async ({ workflowId, status, limit, direction }) => {
+        const result = await client.listExecutions(workflowId, { status, limit, direction });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('get_execution', `Get full execution details including results from each completed step.
+The executionContent field maps stepId -> step output data.
+Use this to inspect what a workflow produced, debug failures, or check intermediate results.`, {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+        executionId: zod_1.z.string().describe('The execution ID'),
+    }, async ({ workflowId, executionId }) => {
+        const result = await client.getExecution(workflowId, executionId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('stop_execution', 'Stop a running or pending workflow execution. Only works on executions with status "running" or "pending".', {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+        executionId: zod_1.z.string().describe('The execution ID to stop'),
+    }, async ({ workflowId, executionId }) => {
+        const result = await client.stopExecution(workflowId, executionId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('retry_execution', `Retry a failed step in a workflow execution. If no timelineId is provided, the most recent failed timeline is automatically detected and retried. This re-runs the failed step and continues the workflow from that point.`, {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+        executionId: zod_1.z.string().describe('The execution ID containing the failed step'),
+        timelineId: zod_1.z.string().optional().describe('Specific timeline ID to retry. If omitted, the most recent failed timeline is auto-detected.'),
+        forceWithoutCache: zod_1.z.boolean().optional().describe('Bypass cache when retrying the step'),
+        rerunMode: zod_1.z.enum(['single-step', 'from-step', 'selected-steps']).optional().describe('Rerun mode: single-step (retry only this step), from-step (retry from this step onward), selected-steps'),
+    }, async ({ workflowId, executionId, timelineId, forceWithoutCache, rerunMode }) => {
+        const result = await client.retryExecution(workflowId, executionId, {
+            timelineId,
+            forceWithoutCache,
+            rerunMode,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+}

package/dist/tools/knowledge.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Tools — Knowledge, Workspace & Knowledge Graph
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AgentledClient } from '../client.js';
+export declare function registerKnowledgeTools(server: McpServer, client: AgentledClient): void;

package/dist/tools/knowledge.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * MCP Tools — Knowledge, Workspace & Knowledge Graph
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerKnowledgeTools = registerKnowledgeTools;
+const zod_1 = require("zod");
+function registerKnowledgeTools(server, client) {
+    // --- Workspace Context ---
+    server.tool('get_workspace', `Get workspace company info, offerings, and knowledge schema overview.
+Returns company details (name, industry, size, offerings) and a summary of all knowledge lists with their field definitions and row counts.
+Use this as a first call to understand what data the workspace has.`, {}, async () => {
+        const result = await client.getWorkspace();
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    // --- Knowledge Data ---
+    server.tool('list_knowledge_lists', `List all knowledge list schemas with field definitions, row counts, and metadata.
+Returns detailed information about each list including fields, source type, category, entity config, and KG sync status.
+Use this to discover what lists exist and understand their structure before querying rows.`, {}, async () => {
+        const result = await client.listKnowledgeLists();
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('get_knowledge_rows', `Fetch sample rows from a knowledge list. Use this to inspect actual data — see example payloads from investor/deal lists.
+Returns rows with their full rowData, plus count and totalCount for the list.`, {
+        listKey: zod_1.z.string().describe('The list key to fetch rows from (e.g., "investors", "deals")'),
+        limit: zod_1.z.number().min(1).max(50).optional().describe('Number of rows to return (default 5, max 50)'),
+    }, async ({ listKey, limit }) => {
+        const result = await client.getKnowledgeRows(listKey, limit);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('get_knowledge_text', `Fetch a text-type knowledge entry by key. Use this to access text-based knowledge like feedback files, notes, or configuration text stored in the workspace.`, {
+        key: zod_1.z.string().describe('The key of the text entry to fetch'),
+    }, async ({ key }) => {
+        const result = await client.getKnowledgeText(key);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    // --- Knowledge Graph ---
+    server.tool('query_kg_edges', `Traverse Knowledge Graph edges by entity name and/or relationship type.
+Returns edges with source/target node IDs, relations, scores, and metadata.
+Use this to explore deal relationships, investor-startup connections, and scoring edges.
+Gracefully returns empty results if the Knowledge Graph is not configured.`, {
+        entityName: zod_1.z.string().optional().describe('Filter edges by entity name'),
+        relationshipType: zod_1.z.string().optional().describe('Filter edges by relationship type (e.g., "INVESTED_IN", "SCORED")'),
+        limit: zod_1.z.number().min(1).max(500).optional().describe('Max edges to return (default 100, max 500)'),
+    }, async ({ entityName, relationshipType, limit }) => {
+        const result = await client.queryKgEdges(entityName, relationshipType, limit);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('get_scoring_history', `Fetch scoring history for entities from the Knowledge Graph.
+Returns past scoring decisions (PROCEED_TO_IC, HOLD_FOR_REVIEW, REPOSITION, SCORED) with DMF scores and dates.
+Use this to see how entities were previously scored and calibrate future scoring runs.
+Returns both structured records and a compact text format for prompt injection.`, {
+        entityName: zod_1.z.string().optional().describe('Filter scoring history by entity name'),
+        limit: zod_1.z.number().min(1).max(500).optional().describe('Max records to return (default 100, max 500)'),
+    }, async ({ entityName, limit }) => {
+        const result = await client.getScoringHistory(entityName, limit);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+}

package/dist/tools/testing.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Tools — Step Testing
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AgentledClient } from '../client.js';
+export declare function registerTestingTools(server: McpServer, client: AgentledClient): void;

package/dist/tools/testing.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * MCP Tools — Step Testing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTestingTools = registerTestingTools;
+const zod_1 = require("zod");
+function registerTestingTools(server, client) {
+    server.tool('test_app_action', `Test an app action in isolation without creating a workflow or execution.
+Pass the appId and actionId (from list_apps / get_app_actions) plus input data to run the action directly and see results immediately.
+Useful for verifying inputs before wiring a step into a workflow.
+Example: test_app_action("web-scraping", "scrape", { url: "https://example.com" })`, {
+        appId: zod_1.z.string().describe('App ID (e.g., "agentled", "web-scraping", "hunter")'),
+        actionId: zod_1.z.string().describe('Action ID (e.g., "scrape", "get-linkedin-company-from-url", "find-email-person-domain")'),
+        input: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Input data for the action (e.g., { url: "https://example.com" })'),
+        bypassCache: zod_1.z.boolean().optional().describe('Skip cache and run against the live API (default: false)'),
+    }, async ({ appId, actionId, input, bypassCache }) => {
+        const result = await client.testAppAction(appId, actionId, input, bypassCache);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('test_ai_action', `Test an AI prompt in isolation without creating a workflow or execution.
+Pass a prompt template with {{variable}} syntax and variable values to run the AI and see the response.
+Useful for tuning prompts and response structures before adding an AI step to a workflow.
+Example: test_ai_action("Analyze this company: {{company}}", { company: "Stripe" }, { score: "number 0-100", summary: "string" })`, {
+        template: zod_1.z.string().describe('Prompt template with {{variable}} placeholders'),
+        variables: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Variable values to substitute in the template'),
+        responseStructure: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Expected JSON output shape (e.g., { score: "number 0-100", summary: "string" })'),
+        responseType: zod_1.z.enum(['json', 'text']).optional().describe('Response format: "json" (default) or "text"'),
+        systemPrompt: zod_1.z.string().optional().describe('Optional system instructions for the AI'),
+    }, async ({ template, variables, responseStructure, responseType, systemPrompt }) => {
+        const result = await client.testAiAction(template, variables, responseStructure, {
+            responseType,
+            systemPrompt,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+}

package/dist/tools/workflows.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Tools — Workflow CRUD + Validation + Lifecycle
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AgentledClient } from '../client.js';
+export declare function registerWorkflowTools(server: McpServer, client: AgentledClient): void;

package/dist/tools/workflows.js

@@ -0,0 +1,268 @@
+"use strict";
+/**
+ * MCP Tools — Workflow CRUD + Validation + Lifecycle
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWorkflowTools = registerWorkflowTools;
+const zod_1 = require("zod");
+function registerWorkflowTools(server, client) {
+    server.tool('list_workflows', 'List all workflows in the workspace. Returns id, name, status, goal for each.', {
+        status: zod_1.z.string().optional().describe('Filter by status: draft, active, paused'),
+        limit: zod_1.z.number().optional().describe('Max results (default 50, max 200)'),
+    }, async ({ status, limit }) => {
+        const result = await client.listWorkflows({ status, limit });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('get_workflow', `Get full details of a workflow including all steps, context, metadata, and configuration.
+Also returns hasDraftSnapshot (boolean) and draftSnapshot summary if a draft exists for a live workflow.`, {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+    }, async ({ workflowId }) => {
+        const result = await client.getWorkflow(workflowId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('create_workflow', `Create a new workflow from a pipeline definition. The pipeline object should include:
+- name (required): Workflow name
+- goal: What the workflow does
+- description: Longer description
+- steps: Array of pipeline steps (trigger, aiAction, appAction, milestone, etc.)
+- context: Execution input config and input/output pages
+- metadata: Template info, notifications, ROI
+- style: UI styling (colors, icon)`, {
+        pipeline: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).describe('The pipeline definition object'),
+        locale: zod_1.z.string().optional().describe('Locale (default: en)'),
+    }, async ({ pipeline, locale }) => {
+        const result = await client.createWorkflow(pipeline, locale);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('update_workflow', `Update an existing workflow. Provide only the fields you want to change.
+
+IMPORTANT: If the workflow is live, config edits (steps, context, name, etc.) are automatically
+routed to a draft snapshot instead of modifying the live pipeline. The response will include
+editingDraft: true. Use get_draft to view the draft, promote_draft to make it live, or
+discard_draft to throw away the changes. Non-live workflows are updated directly with an
+automatic pre-edit snapshot for rollback.`, {
+        workflowId: zod_1.z.string().describe('The workflow ID to update'),
+        updates: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).describe('Partial pipeline updates (name, steps, context, etc.)'),
+        locale: zod_1.z.string().optional().describe('Locale (default: en)'),
+    }, async ({ workflowId, updates, locale }) => {
+        const result = await client.updateWorkflow(workflowId, updates, locale);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('delete_workflow', 'Permanently delete a workflow by ID. This cannot be undone.', {
+        workflowId: zod_1.z.string().describe('The workflow ID to delete'),
+    }, async ({ workflowId }) => {
+        const result = await client.deleteWorkflow(workflowId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('validate_workflow', `Validate a workflow's pipeline definition. Returns structured errors per step.
+Use this after creating or updating a workflow to check for:
+- Missing step connections (broken next.stepId references)
+- Missing required fields (app action without inputs, AI step without prompt)
+- Unreachable steps (not connected to the trigger chain)
+- Invalid app/action IDs (not in the app registry)
+- Missing trigger or milestone steps
+- List field misconfigurations (missing itemFields, defaultValue format mismatches)
+- Config page field validation (missing name/type on input page fields)
+
+Each error/warning may include a "suggestedFix" with a concrete remediation.
+
+You can also pass a pipeline object to validate a draft before saving.
+Returns: { valid: boolean, errors: [...], warnings: [...], stepCount: number }`, {
+        workflowId: zod_1.z.string().describe('The workflow ID to validate'),
+        pipeline: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Optional draft pipeline to validate before saving (merged with stored pipeline)'),
+    }, async ({ workflowId, pipeline }) => {
+        const result = await client.validateWorkflow(workflowId, pipeline);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('list_snapshots', `List available config snapshots for a workflow. Snapshots are automatically captured
+before every external API update, allowing you to restore a previous configuration.
+Returns snapshot ID, timestamp, and which fields were changed.`, {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+    }, async ({ workflowId }) => {
+        const result = await client.listSnapshots(workflowId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('restore_snapshot', `Restore a workflow to a previous config snapshot. Use list_snapshots first to find the
+snapshot ID. This will revert the workflow's steps, context, name, description, goal, and
+style to the state captured in the snapshot.`, {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+        snapshotId: zod_1.z.string().describe('The snapshot ID to restore (from list_snapshots)'),
+    }, async ({ workflowId, snapshotId }) => {
+        const result = await client.restoreSnapshot(workflowId, snapshotId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('get_draft', `Get the draft snapshot for a live workflow. When you update a live workflow, changes
+go to a draft instead of modifying the live pipeline. Use this to inspect the current draft
+state. Returns hasDraft: true/false and the draft config if it exists.`, {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+    }, async ({ workflowId }) => {
+        const result = await client.getDraft(workflowId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('promote_draft', `Promote the draft snapshot to live. This overwrites the live pipeline config with
+the draft contents, then deletes the draft snapshot. A pre-promote snapshot is saved
+automatically so the previous live config can be restored if needed.`, {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+    }, async ({ workflowId }) => {
+        const result = await client.promoteDraft(workflowId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('discard_draft', `Discard the draft snapshot for a live workflow. The live pipeline config stays
+unchanged. Use this to abandon draft changes and go back to the current live version.`, {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+    }, async ({ workflowId }) => {
+        const result = await client.discardDraft(workflowId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('publish_workflow', `Change the status of a workflow (publish, pause, or archive).
+Valid transitions: created/draft -> live, live -> paused, paused -> live, any -> archived.
+Use "live" to publish a draft workflow so it can be executed.`, {
+        workflowId: zod_1.z.string().describe('The workflow ID'),
+        status: zod_1.z.enum(['live', 'paused', 'archived']).describe('Target status'),
+    }, async ({ workflowId, status }) => {
+        const result = await client.publishWorkflow(workflowId, status);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('export_workflow', `Export a workflow as portable JSON for cross-environment transfer.
+Returns a self-contained WorkflowExport object with all steps, context, metadata, and pages.
+Workspace-specific identifiers (workspaceId, agentIds) are stripped so the export can be imported into any workspace.
+
+Use this together with import_workflow to move workflows between environments (e.g. sandbox → prod).`, {
+        workflowId: zod_1.z.string().describe('The workflow ID to export'),
+    }, async ({ workflowId }) => {
+        const result = await client.exportWorkflow(workflowId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('import_workflow', `Import a workflow from an export JSON into this workspace.
+Accepts the full WorkflowExport object (from export_workflow) and creates a new workflow with fresh IDs.
+Associated pages are recreated. Import provenance is recorded in the workflow metadata.
+
+Use this together with export_workflow to move workflows between environments.
+Tip: register separate MCP servers for sandbox and prod, export from one, import into the other.`, {
+        exportJson: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).describe('The WorkflowExport object (output from export_workflow)'),
+        locale: zod_1.z.string().optional().describe('Locale for the imported workflow (default: en)'),
+    }, async ({ exportJson, locale }) => {
+        const result = await client.importWorkflow(exportJson, locale);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('preview_n8n_import', `Preview a deterministic n8n import from JSON. Returns:
+- normalized import hash and IR
+- mapped step graph
+- unsupported nodes + remediation
+- warnings/risks
+- draft workflow build contract and compiler readiness summary
+
+This is a read-only preview and does not create any workflow.`, {
+        n8nJson: zod_1.z.any().describe('n8n workflow JSON object or string export'),
+        options: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Optional import options (e.g. maxNodes, allowPartial)'),
+        workflow: zod_1.z.object({
+            name: zod_1.z.string().optional(),
+            goal: zod_1.z.string().optional(),
+            description: zod_1.z.string().optional(),
+            pathname: zod_1.z.string().optional(),
+        }).optional().describe('Optional workflow metadata overrides for preview contract'),
+    }, async ({ n8nJson, options, workflow }) => {
+        const result = await client.previewN8nImport(n8nJson, options, workflow);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('import_n8n_workflow', `Create a new Agentled workflow from an n8n JSON import.
+
+Behavior:
+- runs deterministic import preview
+- creates workflow in preflight draft mode
+- stores imported contract for review/approval
+- does NOT auto-apply scaffold`, {
+        n8nJson: zod_1.z.any().describe('n8n workflow JSON object or string export'),
+        workflow: zod_1.z.object({
+            name: zod_1.z.string().optional(),
+            goal: zod_1.z.string().optional(),
+            description: zod_1.z.string().optional(),
+            pathname: zod_1.z.string().optional(),
+        }).optional().describe('Optional metadata overrides for the created workflow'),
+        options: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional().describe('Optional import options'),
+        locale: zod_1.z.string().optional().describe('Locale for workflow creation (default en)'),
+    }, async ({ n8nJson, workflow, options, locale }) => {
+        const result = await client.importN8nWorkflow(n8nJson, workflow, options, locale);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@agentled/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Agentled — create, manage, and run workflows from Claude Code",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "agentled-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "tsc"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "agentled",
+    "workflows",
+    "claude-code",
+    "automation",
+    "ai-agents"
+  ],
+  "author": "Agentled",
+  "homepage": "https://www.agentled.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentled/mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/agentled/mcp-server/issues"
+  },
+  "license": "MIT"
+}