@ucm/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @ucm/mcp-server
+
+MCP (Model Context Protocol) server for [UCM](https://ucm.ai) — the Agent-Native API Marketplace. Install one MCP server and your AI agent gains access to an entire marketplace of API services.
+
+## Installation
+
+```bash
+npm install -g @ucm/mcp-server
+```
+
+Or use directly with `npx`:
+
+```bash
+npx @ucm/mcp-server
+```
+
+## Quick Start
+
+### 1. Generate Ed25519 keys
+
+```bash
+node -e "
+import('@noble/ed25519').then(async ed => {
+  const priv = ed.utils.randomPrivateKey();
+  const pub = await ed.getPublicKeyAsync(priv);
+  console.log('UCM_PRIVATE_KEY=' + Buffer.from(priv).toString('hex'));
+  console.log('UCM_PUBLIC_KEY=' + Buffer.from(pub).toString('hex'));
+})
+"
+```
+
+### 2. Configure your MCP client
+
+Add to your Claude Desktop `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ucm": {
+      "command": "npx",
+      "args": ["@ucm/mcp-server"],
+      "env": {
+        "UCM_REGISTRY_URL": "https://registry.ucm.ai",
+        "UCM_PRIVATE_KEY": "<your-private-key-hex>",
+        "UCM_PUBLIC_KEY": "<your-public-key-hex>"
+      }
+    }
+  }
+}
+```
+
+### 3. Use via your agent
+
+Your agent now has access to 11 tools:
+
+| Tool | Description |
+|------|-------------|
+| `ucm_discover` | Search marketplace by natural language |
+| `ucm_buy` | Purchase service access token |
+| `ucm_call` | Buy + call provider API in one step |
+| `ucm_balance` | Check budget remaining |
+| `ucm_history` | View transaction history |
+| `ucm_service_info` | Get service details |
+| `ucm_register` | Self-register as agent, get API key |
+| `ucm_publish` | Publish a service on the marketplace |
+| `ucm_delete_service` | Remove a service |
+| `ucm_authorize` | Create budget authorization for an agent |
+| `ucm_verify_token` | Verify an ACP access token |
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `UCM_PRIVATE_KEY` | Yes | — | Ed25519 private key (hex) |
+| `UCM_PUBLIC_KEY` | Yes | — | Ed25519 public key (hex) |
+| `UCM_REGISTRY_URL` | No | `http://localhost:3000` | UCM Registry URL |
+
+## How It Works
+
+```
+Agent → MCP Client → UCM MCP Server → UCM Registry → Provider APIs
+```
+
+1. Your agent describes what it needs (e.g., "I need a web search API")
+2. The MCP server searches the UCM marketplace
+3. Agent selects a service and purchases access
+4. The access token is used to call the provider API directly
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+export interface UCMConfig {
+    registryUrl: string;
+    agentPrivateKey: string;
+    agentPublicKey: string;
+}
+export declare class UCMClient {
+    private config;
+    constructor(config: UCMConfig);
+    private signedFetch;
+    private unsignedFetch;
+    private sign;
+    discover(need: string, options?: {
+        tags?: string[];
+        max_price?: string;
+        min_reputation?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    buy(serviceId: string, plan?: string): Promise<unknown>;
+    balance(): Promise<unknown>;
+    history(limit?: number): Promise<unknown>;
+    call(serviceId: string, method: string, params: Record<string, unknown>): Promise<any>;
+    getService(serviceId: string): Promise<unknown>;
+    register(name: string, description?: string): Promise<unknown>;
+    publish(descriptor: Record<string, unknown>): Promise<unknown>;
+    deleteService(serviceId: string): Promise<unknown>;
+    authorize(authorization: Record<string, unknown>): Promise<unknown>;
+    verifyToken(token: string): Promise<unknown>;
+}

package/dist/client.js

@@ -0,0 +1,160 @@
+/**
+ * UCM Registry HTTP client with Ed25519 signing.
+ */
+import * as ed from '@noble/ed25519';
+import { createHash } from 'crypto';
+// Setup sha512 for noble/ed25519 v2
+ed.etc.sha512Sync = (...m) => {
+    const h = createHash('sha512');
+    for (const msg of m)
+        h.update(msg);
+    return new Uint8Array(h.digest());
+};
+function hexToBytes(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+    }
+    return bytes;
+}
+function isHex(value) {
+    return value.length % 2 === 0 && /^[0-9a-fA-F]+$/.test(value);
+}
+function decodeKey(key) {
+    if (isHex(key)) {
+        return hexToBytes(key);
+    }
+    return new Uint8Array(Buffer.from(key, 'base64url'));
+}
+function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (isPlainObject(value)) {
+        const sortedKeys = Object.keys(value).sort();
+        const result = {};
+        for (const key of sortedKeys) {
+            result[key] = canonicalize(value[key]);
+        }
+        return result;
+    }
+    return value;
+}
+function canonicalJson(obj) {
+    return JSON.stringify(canonicalize(obj));
+}
+export class UCMClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async signedFetch(path, method, body) {
+        const url = new URL(path, this.config.registryUrl);
+        const bodyStr = body ? JSON.stringify(body) : '';
+        const timestamp = Date.now();
+        const nonce = crypto.randomUUID();
+        const pathWithQuery = `${url.pathname}${url.search}`;
+        const payload = canonicalJson({
+            body_hash: sha256Hex(bodyStr || ''),
+            method,
+            nonce,
+            path: pathWithQuery,
+            timestamp,
+        });
+        const signature = await this.sign(sha256Hex(payload));
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-ACP-Pubkey': this.config.agentPublicKey,
+            'X-ACP-Timestamp': String(timestamp),
+            'X-ACP-Nonce': nonce,
+            'X-ACP-Signature': signature,
+        };
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: bodyStr || undefined,
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            const err = data.error;
+            throw new Error(`${err?.code ?? res.status}: ${err?.message ?? 'Request failed'}`);
+        }
+        return data;
+    }
+    async unsignedFetch(path, method, body) {
+        const url = new URL(path, this.config.registryUrl);
+        const res = await fetch(url, {
+            method,
+            headers: { 'Content-Type': 'application/json' },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            const err = data.error;
+            throw new Error(`${err?.code ?? res.status}: ${err?.message ?? 'Request failed'}`);
+        }
+        return data;
+    }
+    async sign(message) {
+        const msgBytes = new TextEncoder().encode(message);
+        const sig = await ed.signAsync(msgBytes, decodeKey(this.config.agentPrivateKey));
+        return Buffer.from(sig).toString('base64url');
+    }
+    async discover(need, options) {
+        return this.unsignedFetch('/v1/discover', 'POST', { need, ...options });
+    }
+    async buy(serviceId, plan) {
+        return this.signedFetch('/v1/buy', 'POST', { service_id: serviceId, plan: plan ?? 'per-call' });
+    }
+    async balance() {
+        return this.signedFetch('/v1/balance', 'GET');
+    }
+    async history(limit) {
+        const path = limit ? `/v1/history?limit=${limit}` : '/v1/history';
+        return this.signedFetch(path, 'GET');
+    }
+    async call(serviceId, method, params) {
+        // 1. Buy to get a token
+        const buyResult = await this.buy(serviceId);
+        const token = buyResult.access_token;
+        const endpoint = buyResult.service_endpoint;
+        // 2. Call the provider API
+        const res = await fetch(`${endpoint}${method}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${token}`,
+            },
+            body: JSON.stringify(params),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Provider API error ${res.status}: ${text}`);
+        }
+        return res.json();
+    }
+    async getService(serviceId) {
+        return this.unsignedFetch(`/v1/services/${serviceId}`, 'GET');
+    }
+    async register(name, description) {
+        return this.unsignedFetch('/v1/agents/register', 'POST', { name, description });
+    }
+    async publish(descriptor) {
+        return this.signedFetch('/v1/publish', 'POST', descriptor);
+    }
+    async deleteService(serviceId) {
+        return this.signedFetch(`/v1/publish/${serviceId}`, 'DELETE');
+    }
+    async authorize(authorization) {
+        return this.signedFetch('/v1/authorize', 'POST', authorization);
+    }
+    async verifyToken(token) {
+        return this.unsignedFetch('/v1/token/verify', 'POST', { token });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * UCM MCP Server
+ *
+ * Exposes UCM as MCP tools so any compatible agent (Claude, GPT, etc.)
+ * can discover, buy, and use API services autonomously.
+ *
+ * Config via env vars:
+ *   UCM_REGISTRY_URL  — Registry base URL (default: http://localhost:3000)
+ *   UCM_PRIVATE_KEY   — Agent Ed25519 private key (hex)
+ *   UCM_PUBLIC_KEY    — Agent Ed25519 public key (hex)
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { UCMClient } from './client.js';
+const registryUrl = process.env.UCM_REGISTRY_URL ?? 'http://localhost:3000';
+const privateKey = process.env.UCM_PRIVATE_KEY ?? '';
+const publicKey = process.env.UCM_PUBLIC_KEY ?? '';
+if (!privateKey || !publicKey) {
+    console.error('Error: UCM_PRIVATE_KEY and UCM_PUBLIC_KEY env vars are required.');
+    process.exit(1);
+}
+const client = new UCMClient({ registryUrl, agentPrivateKey: privateKey, agentPublicKey: publicKey });
+const server = new Server({ name: 'ucm', version: '0.1.0' }, { capabilities: { tools: {} } });
+// --- tools/list ---
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'ucm_discover',
+            description: 'Search UCM marketplace for API services that match your needs. Returns ranked results with pricing.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    need: { type: 'string', description: 'Natural language description of what capability you need' },
+                    max_price: { type: 'string', description: 'Maximum price per call, e.g. "0.10"' },
+                    tags: { type: 'array', items: { type: 'string' }, description: 'Filter by tags' },
+                    limit: { type: 'number', description: 'Max results (default 5, max 20)' },
+                },
+                required: ['need'],
+            },
+        },
+        {
+            name: 'ucm_buy',
+            description: 'Purchase access to an API service. Returns an access token and the service endpoint. Charges are deducted from your budget.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    service_id: { type: 'string', description: 'Service ID, e.g. "acme/web-search"' },
+                    plan: { type: 'string', description: 'Pricing plan: "per-call" (default) or "subscription"' },
+                },
+                required: ['service_id'],
+            },
+        },
+        {
+            name: 'ucm_call',
+            description: 'Buy and immediately call an API service in one step. Purchases a token, then calls the provider API with your parameters.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    service_id: { type: 'string', description: 'Service ID to call' },
+                    method: { type: 'string', description: 'API method/path, e.g. "/search"' },
+                    params: { type: 'object', description: 'Parameters for the API call' },
+                },
+                required: ['service_id', 'method', 'params'],
+            },
+        },
+        {
+            name: 'ucm_balance',
+            description: 'Check your current UCM budget — daily/monthly limits, spending, and remaining balance.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: 'ucm_history',
+            description: 'View your recent UCM transaction history.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    limit: { type: 'number', description: 'Number of recent transactions (default 20)' },
+                },
+            },
+        },
+        {
+            name: 'ucm_service_info',
+            description: 'Get detailed information about a service: API schema, pricing, SLA, and provider details.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    service_id: { type: 'string', description: 'Service ID' },
+                },
+                required: ['service_id'],
+            },
+        },
+        {
+            name: 'ucm_register',
+            description: 'Self-register as a new agent on UCM. Returns an agent ID and API key for subsequent requests.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Agent name (1-255 characters)' },
+                    description: { type: 'string', description: 'Optional agent description' },
+                },
+                required: ['name'],
+            },
+        },
+        {
+            name: 'ucm_publish',
+            description: 'Publish (list) a new API service on the UCM marketplace. Requires Ed25519 signing.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    descriptor: { type: 'object', description: 'Full ACP service descriptor object with acp_version, service_id, name, provider, endpoints, pricing, sla, etc.' },
+                },
+                required: ['descriptor'],
+            },
+        },
+        {
+            name: 'ucm_delete_service',
+            description: 'Remove (delist) a service from the UCM marketplace. Only the service provider can delete it.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    service_id: { type: 'string', description: 'Service ID to delete' },
+                },
+                required: ['service_id'],
+            },
+        },
+        {
+            name: 'ucm_authorize',
+            description: 'Create a budget authorization for an agent. Sets per-transaction, daily, and monthly spending limits.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    agent: { type: 'string', description: 'Agent identifier (e.g. "solana:<pubkey>")' },
+                    rules: { type: 'object', description: 'Budget rules: max_per_tx, max_daily, max_monthly, currency, expires_at, etc.' },
+                    operator: { type: 'string', description: 'Operator identifier (your pubkey)' },
+                },
+                required: ['agent', 'rules', 'operator'],
+            },
+        },
+        {
+            name: 'ucm_verify_token',
+            description: 'Verify an ACP access token. Returns token validity and payload details.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    token: { type: 'string', description: 'Access token starting with "acp_sk_"' },
+                },
+                required: ['token'],
+            },
+        },
+    ],
+}));
+// --- tools/call ---
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case 'ucm_discover':
+                result = await client.discover(args.need, {
+                    max_price: args.max_price,
+                    tags: args.tags,
+                    limit: args.limit,
+                });
+                break;
+            case 'ucm_buy':
+                result = await client.buy(args.service_id, args.plan);
+                break;
+            case 'ucm_call':
+                result = await client.call(args.service_id, args.method, args.params ?? {});
+                break;
+            case 'ucm_balance':
+                result = await client.balance();
+                break;
+            case 'ucm_history':
+                result = await client.history(args.limit);
+                break;
+            case 'ucm_service_info':
+                result = await client.getService(args.service_id);
+                break;
+            case 'ucm_register':
+                result = await client.register(args.name, args.description);
+                break;
+            case 'ucm_publish':
+                result = await client.publish(args.descriptor);
+                break;
+            case 'ucm_delete_service':
+                result = await client.deleteService(args.service_id);
+                break;
+            case 'ucm_authorize':
+                result = await client.authorize({
+                    agent: args.agent,
+                    rules: args.rules,
+                    operator: args.operator,
+                    acp_version: '0.1',
+                    type: 'budget_authorization',
+                    created_at: new Date().toISOString(),
+                    signature: 'mcp-tool',
+                });
+                break;
+            case 'ucm_verify_token':
+                result = await client.verifyToken(args.token);
+                break;
+            default:
+                return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
+    }
+});
+// Start
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    console.error('Fatal:', e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ucm/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for UCM — Agent-Native API Marketplace. Gives AI agents access to discover, purchase, and use API services.",
+  "type": "module",
+  "license": "MIT",
+  "author": "UCM <hello@ucm.ai>",
+  "homepage": "https://ucm.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ucmai/ucm.ai",
+    "directory": "packages/mcp-server"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "api-marketplace",
+    "ucm",
+    "acp",
+    "agent-commerce-protocol"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "ucm-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@noble/ed25519": "^2.2.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}