agentkit-mesh 1.0.0

package/README.md

@@ -0,0 +1,153 @@
+# agentkit-mesh
+
+Agent-to-agent discovery and delegation via [MCP](https://modelcontextprotocol.io) (Model Context Protocol).
+
+Agents register their capabilities, discover each other by semantic search, and delegate tasks — all through standard MCP tools.
+
+## Quick Start
+
+```bash
+npx agentkit-mesh
+```
+
+This starts an MCP server over stdio, ready to connect to Claude Desktop, OpenClaw, or any MCP client.
+
+## MCP Configuration
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentkit-mesh": {
+      "command": "npx",
+      "args": ["agentkit-mesh"]
+    }
+  }
+}
+```
+
+### OpenClaw
+
+Add to your OpenClaw config:
+
+```yaml
+mcp:
+  agentkit-mesh:
+    command: npx agentkit-mesh
+```
+
+## Architecture
+
+```
+┌─────────────┐     MCP      ┌──────────────────┐
+│  AI Agent A  │◄────────────►│                  │
+└─────────────┘              │  agentkit-mesh   │
+                             │                  │
+┌─────────────┐     MCP      │  ┌────────────┐  │
+│  AI Agent B  │◄────────────►│  │  Registry   │  │
+└─────────────┘              │  │  (SQLite)   │  │
+                             │  └────────────┘  │
+┌─────────────┐     MCP      │  ┌────────────┐  │
+│  AI Agent C  │◄────────────►│  │  Discovery  │  │
+└─────────────┘              │  └────────────┘  │
+                             │  ┌────────────┐  │
+                             │  │ Delegation  │  │
+                             │  └────────────┘  │
+                             └──────────────────┘
+```
+
+## MCP Tools
+
+### `mesh_register`
+
+Register an agent with its capabilities.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Unique agent name |
+| `description` | string | What this agent does |
+| `capabilities` | string[] | List of capabilities |
+| `endpoint` | string | Agent's MCP endpoint URL |
+
+### `mesh_discover`
+
+Discover agents matching a natural language query.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Search query (e.g. "budget management") |
+| `limit` | number? | Max results to return |
+
+Returns agents ranked by relevance score with matched capability terms.
+
+### `mesh_unregister`
+
+Remove an agent from the registry.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Agent name to remove |
+
+### `mesh_delegate`
+
+Delegate a task to another agent by name.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetName` | string | Name of the target agent |
+| `task` | string | Task description to delegate |
+| `context` | string? | Optional JSON context |
+
+Connects to the target agent's MCP endpoint and calls its `handle_task` tool.
+
+## Use Case: FormBridge
+
+An HR agent filling an expense form discovers the Finance agent:
+
+```typescript
+import { AgentRegistry, DiscoveryEngine } from 'agentkit-mesh';
+
+const registry = new AgentRegistry();
+
+// Agents register themselves
+registry.register({
+  name: 'finance-agent',
+  description: 'Budget management and expense approval',
+  capabilities: ['budget', 'cost_center', 'expense_approval'],
+  endpoint: 'http://localhost:4002/mcp',
+});
+
+// HR agent discovers who can help with budget fields
+const discovery = new DiscoveryEngine();
+const results = discovery.discover('budget cost center', registry);
+// → [{ agent: finance-agent, score: 0.67, matchedTerms: ['budget', 'cost', 'center'] }]
+```
+
+See [examples/](examples/) for a runnable demo.
+
+## Optional: Lore Integration
+
+For semantic search beyond keyword matching, connect to a [Lore](https://github.com/openclaw/lore) server:
+
+```typescript
+import { LoreDiscoveryEngine } from 'agentkit-mesh';
+
+const engine = new LoreDiscoveryEngine('http://lore:8080', registry, 'api-key');
+const results = await engine.discover('financial planning');
+// Falls back to text matching if Lore is unavailable
+```
+
+## Programmatic API
+
+```typescript
+import { AgentRegistry, DiscoveryEngine, DelegationClient, createServer } from 'agentkit-mesh';
+```
+
+All classes are exported for direct use without the MCP server layer.
+
+## License
+
+ISC

package/dist/delegation.d.ts

@@ -0,0 +1,11 @@
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+export interface DelegationResult {
+    success: boolean;
+    result?: string;
+    error?: string;
+    latencyMs: number;
+}
+export declare class DelegationClient {
+    delegateViaTransport(transport: Transport, task: string, context?: Record<string, any>, timeout?: number): Promise<DelegationResult>;
+    delegate(targetEndpoint: string, task: string, context?: Record<string, any>, timeout?: number): Promise<DelegationResult>;
+}

package/dist/delegation.js

@@ -0,0 +1,61 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+const MAX_DEPTH = 3;
+const DEFAULT_TIMEOUT = 60_000;
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`Delegation timed out after ${ms}ms`)), ms);
+        promise.then(resolve, reject).finally(() => clearTimeout(timer));
+    });
+}
+export class DelegationClient {
+    async delegateViaTransport(transport, task, context, timeout) {
+        const depth = context?.depth ?? 0;
+        if (depth > MAX_DEPTH) {
+            return { success: false, error: `Delegation depth ${depth} exceeds max ${MAX_DEPTH}`, latencyMs: 0 };
+        }
+        const start = Date.now();
+        const client = new Client({ name: 'delegation-client', version: '0.1.0' });
+        try {
+            await client.connect(transport);
+            const nextContext = { ...context, depth: depth + 1 };
+            const response = await withTimeout(client.callTool({ name: 'handle_task', arguments: { task, context: nextContext } }), timeout ?? DEFAULT_TIMEOUT);
+            const text = response.content?.[0]?.text ?? '';
+            return { success: true, result: text, latencyMs: Date.now() - start };
+        }
+        catch (err) {
+            return { success: false, error: err.message ?? String(err), latencyMs: Date.now() - start };
+        }
+        finally {
+            try {
+                await client.close();
+            }
+            catch { }
+        }
+    }
+    async delegate(targetEndpoint, task, context, timeout) {
+        const depth = context?.depth ?? 0;
+        if (depth > MAX_DEPTH) {
+            return { success: false, error: `Delegation depth ${depth} exceeds max ${MAX_DEPTH}`, latencyMs: 0 };
+        }
+        const start = Date.now();
+        const client = new Client({ name: 'delegation-client', version: '0.1.0' });
+        try {
+            const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
+            const transport = new SSEClientTransport(new URL(targetEndpoint));
+            await client.connect(transport);
+            const nextContext = { ...context, depth: depth + 1 };
+            const response = await withTimeout(client.callTool({ name: 'handle_task', arguments: { task, context: nextContext } }), timeout ?? DEFAULT_TIMEOUT);
+            const text = response.content?.[0]?.text ?? '';
+            return { success: true, result: text, latencyMs: Date.now() - start };
+        }
+        catch (err) {
+            return { success: false, error: err.message ?? String(err), latencyMs: Date.now() - start };
+        }
+        finally {
+            try {
+                await client.close();
+            }
+            catch { }
+        }
+    }
+}

package/dist/discovery.d.ts

@@ -0,0 +1,13 @@
+import { AgentRecord, AgentRegistry } from './registry.js';
+export interface DiscoveryResult {
+    agent: AgentRecord;
+    score: number;
+    matchedTerms: string[];
+}
+export interface DiscoveryProvider {
+    discover(query: string, limit?: number): Promise<DiscoveryResult[]>;
+}
+export declare class DiscoveryEngine {
+    discover(query: string, registry: AgentRegistry, limit?: number): DiscoveryResult[];
+    private tokenize;
+}

package/dist/discovery.js

@@ -0,0 +1,36 @@
+export class DiscoveryEngine {
+    discover(query, registry, limit) {
+        const tokens = this.tokenize(query);
+        if (tokens.length === 0)
+            return [];
+        const agents = registry.list();
+        const results = [];
+        for (const agent of agents) {
+            const searchText = [
+                agent.description.toLowerCase(),
+                ...agent.capabilities.map(c => c.toLowerCase()),
+            ].join(' ');
+            const matchedTerms = [];
+            for (const token of tokens) {
+                if (searchText.includes(token)) {
+                    matchedTerms.push(token);
+                }
+            }
+            if (matchedTerms.length > 0) {
+                results.push({
+                    agent,
+                    score: matchedTerms.length / tokens.length,
+                    matchedTerms,
+                });
+            }
+        }
+        results.sort((a, b) => b.score - a.score);
+        return limit ? results.slice(0, limit) : results;
+    }
+    tokenize(query) {
+        return query
+            .toLowerCase()
+            .split(/[\s\W]+/)
+            .filter(t => t.length > 0);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+export { AgentRegistry } from './registry.js';
+export type { AgentRecord, RegisterInput } from './registry.js';
+export { DiscoveryEngine } from './discovery.js';
+export type { DiscoveryResult, DiscoveryProvider } from './discovery.js';
+export { DelegationClient } from './delegation.js';
+export type { DelegationResult } from './delegation.js';
+export { createServer } from './server.js';
+export { LoreDiscoveryEngine } from './lore-discovery.js';

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+export { AgentRegistry } from './registry.js';
+export { DiscoveryEngine } from './discovery.js';
+export { DelegationClient } from './delegation.js';
+export { createServer } from './server.js';
+export { LoreDiscoveryEngine } from './lore-discovery.js';
+// CLI entry point: only start server when run directly via the bin script
+const scriptPath = process.argv[1] ?? '';
+const isDirectRun = scriptPath.endsWith('/agentkit-mesh') ||
+    scriptPath.endsWith('\\agentkit-mesh') ||
+    (scriptPath.endsWith('/index.js') && scriptPath.includes('agentkit-mesh'));
+if (isDirectRun) {
+    const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+    const { AgentRegistry: Registry } = await import('./registry.js');
+    const { createServer: create } = await import('./server.js');
+    const dbPath = process.argv[2] || undefined;
+    const registry = new Registry(dbPath);
+    const server = create(registry);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.on('SIGINT', () => { registry.close(); process.exit(0); });
+    process.on('SIGTERM', () => { registry.close(); process.exit(0); });
+}

package/dist/lore-discovery.d.ts

@@ -0,0 +1,12 @@
+import { AgentRecord, AgentRegistry } from './registry.js';
+import { DiscoveryResult, DiscoveryProvider } from './discovery.js';
+export declare class LoreDiscoveryEngine implements DiscoveryProvider {
+    private loreUrl;
+    private loreApiKey?;
+    private registry;
+    private fallback;
+    constructor(loreUrl: string, registry: AgentRegistry, loreApiKey?: string);
+    discover(query: string, limit?: number): Promise<DiscoveryResult[]>;
+    private discoverViaLore;
+    publishCapabilities(agent: AgentRecord): Promise<boolean>;
+}

package/dist/lore-discovery.js

@@ -0,0 +1,71 @@
+import { DiscoveryEngine } from './discovery.js';
+export class LoreDiscoveryEngine {
+    loreUrl;
+    loreApiKey;
+    registry;
+    fallback;
+    constructor(loreUrl, registry, loreApiKey) {
+        this.loreUrl = loreUrl.replace(/\/+$/, '');
+        this.loreApiKey = loreApiKey;
+        this.registry = registry;
+        this.fallback = new DiscoveryEngine();
+    }
+    async discover(query, limit) {
+        try {
+            return await this.discoverViaLore(query, limit);
+        }
+        catch {
+            // Fall back to text matching
+            return this.fallback.discover(query, this.registry, limit);
+        }
+    }
+    async discoverViaLore(query, limit) {
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.loreApiKey) {
+            headers['Authorization'] = `Bearer ${this.loreApiKey}`;
+        }
+        const response = await fetch(`${this.loreUrl}/v1/lessons/search`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ query, limit: limit ?? 10 }),
+        });
+        if (!response.ok) {
+            throw new Error(`Lore API returned ${response.status}`);
+        }
+        const data = await response.json();
+        return data.lessons.map((lesson) => ({
+            agent: {
+                name: lesson.title,
+                description: lesson.content,
+                capabilities: lesson.tags ?? [],
+                endpoint: '',
+                protocol: 'mcp',
+                registered_at: '',
+                last_seen: '',
+            },
+            score: lesson.score ?? 0.5,
+            matchedTerms: lesson.tags ?? [],
+        }));
+    }
+    async publishCapabilities(agent) {
+        try {
+            const headers = { 'Content-Type': 'application/json' };
+            if (this.loreApiKey) {
+                headers['Authorization'] = `Bearer ${this.loreApiKey}`;
+            }
+            const response = await fetch(`${this.loreUrl}/v1/lessons`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({
+                    title: agent.name,
+                    content: `${agent.description}. Capabilities: ${agent.capabilities.join(', ')}`,
+                    tags: agent.capabilities,
+                }),
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/registry.d.ts

@@ -0,0 +1,28 @@
+export interface AgentRecord {
+    name: string;
+    description: string;
+    capabilities: string[];
+    endpoint: string;
+    protocol: string;
+    registered_at: string;
+    last_seen: string;
+}
+export interface RegisterInput {
+    name: string;
+    description: string;
+    capabilities: string[];
+    endpoint: string;
+    protocol?: string;
+}
+export declare class AgentRegistry {
+    private db;
+    constructor(dbPath?: string);
+    private initSchema;
+    register(agent: RegisterInput): AgentRecord;
+    unregister(name: string): boolean;
+    list(): AgentRecord[];
+    get(name: string): AgentRecord | null;
+    heartbeat(name: string): boolean;
+    close(): void;
+    private rowToRecord;
+}

package/dist/registry.js

@@ -0,0 +1,80 @@
+import Database from 'better-sqlite3';
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+export class AgentRegistry {
+    db;
+    constructor(dbPath) {
+        if (!dbPath) {
+            const dir = path.join(os.homedir(), '.agentkit-mesh');
+            fs.mkdirSync(dir, { recursive: true });
+            dbPath = path.join(dir, 'registry.db');
+        }
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.initSchema();
+    }
+    initSchema() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS agents (
+        name TEXT PRIMARY KEY,
+        description TEXT NOT NULL,
+        capabilities TEXT NOT NULL,
+        endpoint TEXT NOT NULL,
+        protocol TEXT NOT NULL DEFAULT 'mcp',
+        registered_at TEXT NOT NULL,
+        last_seen TEXT NOT NULL
+      )
+    `);
+    }
+    register(agent) {
+        if (!agent.name || agent.name.trim().length === 0) {
+            throw new Error('Agent name is required');
+        }
+        if (!agent.endpoint || agent.endpoint.trim().length === 0) {
+            throw new Error('Agent endpoint is required');
+        }
+        const now = new Date().toISOString();
+        const capabilities = JSON.stringify(agent.capabilities);
+        const protocol = agent.protocol ?? 'mcp';
+        this.db.prepare(`
+      INSERT INTO agents (name, description, capabilities, endpoint, protocol, registered_at, last_seen)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(name) DO UPDATE SET
+        description = excluded.description,
+        capabilities = excluded.capabilities,
+        endpoint = excluded.endpoint,
+        protocol = excluded.protocol,
+        last_seen = excluded.last_seen
+    `).run(agent.name, agent.description, capabilities, agent.endpoint, protocol, now, now);
+        return this.get(agent.name);
+    }
+    unregister(name) {
+        const result = this.db.prepare('DELETE FROM agents WHERE name = ?').run(name);
+        return result.changes > 0;
+    }
+    list() {
+        const rows = this.db.prepare('SELECT * FROM agents ORDER BY name').all();
+        return rows.map(r => this.rowToRecord(r));
+    }
+    get(name) {
+        const row = this.db.prepare('SELECT * FROM agents WHERE name = ?').get(name);
+        if (!row)
+            return null;
+        return this.rowToRecord(row);
+    }
+    heartbeat(name) {
+        const now = new Date().toISOString();
+        const result = this.db.prepare('UPDATE agents SET last_seen = ? WHERE name = ?').run(now, name);
+        return result.changes > 0;
+    }
+    close() {
+        this.db.close();
+    }
+    rowToRecord(row) {
+        return {
+            ...row,
+            capabilities: JSON.parse(row.capabilities),
+        };
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AgentRegistry } from './registry.js';
+export declare function createServer(registry: AgentRegistry): McpServer;

package/dist/server.js

@@ -0,0 +1,58 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { DiscoveryEngine } from './discovery.js';
+import { DelegationClient } from './delegation.js';
+export function createServer(registry) {
+    const server = new McpServer({
+        name: 'agentkit-mesh',
+        version: '0.1.0',
+    });
+    const discovery = new DiscoveryEngine();
+    server.tool('mesh_register', 'Register an agent with its capabilities', {
+        name: z.string().describe('Unique agent name'),
+        description: z.string().describe('What this agent does'),
+        capabilities: z.array(z.string()).describe('List of capabilities'),
+        endpoint: z.string().describe('Agent endpoint URL'),
+    }, async ({ name, description, capabilities, endpoint }) => {
+        const agent = registry.register({ name, description, capabilities, endpoint });
+        return { content: [{ type: 'text', text: JSON.stringify(agent, null, 2) }] };
+    });
+    server.tool('mesh_discover', 'Discover agents matching a query', {
+        query: z.string().describe('Search query'),
+        limit: z.number().optional().describe('Max results'),
+    }, async ({ query, limit }) => {
+        const results = discovery.discover(query, registry, limit);
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+    });
+    server.tool('mesh_unregister', 'Unregister an agent', {
+        name: z.string().describe('Agent name to remove'),
+    }, async ({ name }) => {
+        const removed = registry.unregister(name);
+        return {
+            content: [{ type: 'text', text: removed ? `Unregistered ${name}` : `Agent ${name} not found` }],
+        };
+    });
+    const delegationClient = new DelegationClient();
+    server.tool('mesh_delegate', 'Delegate a task to another agent by name', {
+        targetName: z.string().describe('Name of the target agent'),
+        task: z.string().describe('Task to delegate'),
+        context: z.string().optional().describe('Optional JSON context'),
+    }, async ({ targetName, task, context }) => {
+        const agent = registry.get(targetName);
+        if (!agent) {
+            return { content: [{ type: 'text', text: `Agent "${targetName}" not found` }] };
+        }
+        let ctx = {};
+        if (context) {
+            try {
+                ctx = JSON.parse(context);
+            }
+            catch {
+                return { content: [{ type: 'text', text: `Invalid JSON in context` }] };
+            }
+        }
+        const result = await delegationClient.delegate(agent.endpoint, task, ctx);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "agentkit-mesh",
+  "version": "1.0.0",
+  "description": "Agent-to-agent discovery and delegation via MCP (Model Context Protocol)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/agentkit-mesh"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "bin": {
+    "agentkit-mesh": "./dist/index.js"
+  }
+}