@ucm/mcp-server 0.2.0 → 0.3.1

package/README.md

@@ -16,20 +16,7 @@ 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
+### 1. Configure your MCP client
 
 Add to your Claude Desktop `claude_desktop_config.json`:
 
@@ -40,40 +27,43 @@ Add to your Claude Desktop `claude_desktop_config.json`:
       "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>"
+        "UCM_API_KEY": "<your-api-key>"
       }
     }
   }
 }
 ```
 
-### 3. Use via your agent
+Don't have an API key? No problem — your agent can use `ucm_register` to self-register and get one automatically.
+
+### 2. Use via your agent
 
-Your agent now has access to 11 tools:
+Your agent now has access to 7 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_call` | Call an API service (buy + execute + auto-refund on failure) |
+| `ucm_balance` | Check credit balance |
 | `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 |
+| `ucm_register` | Self-register as agent, get API key + $1.00 credits |
+| `ucm_list_services` | Browse the full service catalog |
+
+### 3. Typical flow
+
+```
+Agent: ucm_register(name: "my-agent")     → gets API key + $1.00 credits
+Agent: ucm_discover(need: "web search")   → finds ucm/web-search
+Agent: ucm_call(service_id: "ucm/web-search", endpoint: "search", body: {query: "..."})
+```
 
 ## 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 |
+| `UCM_API_KEY` | No | — | Agent API key (`ucm_key_*`). Can also be obtained via `ucm_register`. |
+| `UCM_REGISTRY_URL` | No | `https://registry.ucm.ai` | UCM Registry URL |
 
 ## How It Works
 
@@ -83,8 +73,8 @@ 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
+3. Agent calls the service — purchase and execution happen atomically
+4. If the upstream API fails, credits are automatically refunded
 
 ## License
 

package/dist/client.d.ts

@@ -1,30 +1,29 @@
+/**
+ * UCM Registry HTTP client with API key auth.
+ */
 export interface UCMConfig {
     registryUrl: string;
-    agentPrivateKey: string;
-    agentPublicKey: string;
+    apiKey?: string;
 }
 export declare class UCMClient {
     private config;
     constructor(config: UCMConfig);
-    private signedFetch;
+    setApiKey(key: string): void;
+    private bearerFetch;
     private unsignedFetch;
-    private sign;
+    private handleResponse;
     discover(need: string, options?: {
         tags?: string[];
         max_price?: string;
         min_reputation?: number;
         limit?: number;
     }): Promise<unknown>;
+    call(serviceId: string, endpoint: string, body?: Record<string, unknown>): 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>;
+    register(name: string, description?: string, ref?: string): Promise<unknown>;
     listServices(options?: {
         since?: string;
         tags?: string;

package/dist/client.js

@@ -1,91 +1,28 @@
 /**
- * UCM Registry HTTP client with Ed25519 signing.
+ * UCM Registry HTTP client with API key auth.
  */
-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) {
+    setApiKey(key) {
+        this.config.apiKey = key;
+    }
+    async bearerFetch(path, method, body) {
+        if (!this.config.apiKey) {
+            throw new Error('No API key configured. Use ucm_register to get one, or set UCM_API_KEY.');
+        }
         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,
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.config.apiKey}`,
+            },
+            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;
+        return this.handleResponse(res);
     }
     async unsignedFetch(path, method, body) {
         const url = new URL(path, this.config.registryUrl);
@@ -94,68 +31,49 @@ export class UCMClient {
             headers: { 'Content-Type': 'application/json' },
             body: body ? JSON.stringify(body) : undefined,
         });
+        return this.handleResponse(res);
+    }
+    async handleResponse(res) {
         const data = await res.json();
         if (!res.ok) {
             const err = data.error;
-            throw new Error(`${err?.code ?? res.status}: ${err?.message ?? 'Request failed'}`);
+            const base = `${err?.code ?? res.status}: ${err?.message ?? 'Request failed'}`;
+            const extras = [];
+            if (err?.claim_url)
+                extras.push(`Claim URL: ${err.claim_url}`);
+            if (err?.claim_instructions)
+                extras.push(`Instructions: ${err.claim_instructions}`);
+            if (err?.balance)
+                extras.push(`Current balance: ${err.balance} ${err.currency ?? ''}`);
+            throw new Error(extras.length > 0 ? `${base}\n${extras.join('\n')}` : base);
         }
         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 call(serviceId, endpoint, body) {
+        return this.bearerFetch('/v1/call', 'POST', {
+            service_id: serviceId,
+            endpoint,
+            ...(body && Object.keys(body).length > 0 ? body : {}),
+        });
+    }
     async buy(serviceId, plan) {
-        return this.signedFetch('/v1/buy', 'POST', { service_id: serviceId, plan: plan ?? 'per-call' });
+        return this.bearerFetch('/v1/buy', 'POST', { service_id: serviceId, plan: plan ?? 'per-call' });
     }
     async balance() {
-        return this.signedFetch('/v1/balance', 'GET');
+        return this.bearerFetch('/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();
+        return this.bearerFetch(path, 'GET');
     }
     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 });
+    async register(name, description, ref) {
+        return this.unsignedFetch('/v1/agents/register', 'POST', { name, description, ref });
     }
     async listServices(options) {
         const params = new URLSearchParams();

package/dist/index.js

@@ -1,34 +1,28 @@
 #!/usr/bin/env node
 /**
- * UCM MCP Server
+ * UCM MCP Server v0.3.0
  *
  * Exposes UCM as MCP tools so any compatible agent (Claude, GPT, etc.)
- * can discover, buy, and use API services autonomously.
+ * can discover 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)
+ *   UCM_REGISTRY_URL  — Registry base URL (default: https://registry.ucm.ai)
+ *   UCM_API_KEY       — Agent API key (ucm_key_*). Optional — use ucm_register to get one.
  */
 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: {} } });
+const registryUrl = process.env.UCM_REGISTRY_URL ?? 'https://registry.ucm.ai';
+const apiKey = process.env.UCM_API_KEY ?? '';
+let client = new UCMClient({ registryUrl, apiKey: apiKey || undefined });
+const server = new Server({ name: 'ucm', version: '0.3.0' }, { capabilities: { tools: {} } });
 // --- tools/list ---
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
             name: 'ucm_discover',
-            description: 'Search UCM marketplace for API services when you need capabilities beyond your built-in tools — web search, code execution, translation, image generation, data processing, etc. New services are added regularly. Returns ranked results with pricing.',
+            description: 'USE THIS FIRST when the user asks you to do something you cannot do natively — such as searching the web, generating images, running code, sending emails, converting documents, getting stock data, text-to-speech, or any other external capability. UCM is an API marketplace with 10+ services. Returns matching services with pricing (most cost $0.01/call). After discovering a service, use ucm_call to execute it. If you are not yet registered, call ucm_register first (free, gives $1.00 credits).',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -40,34 +34,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 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.',
+            description: 'Execute an API service. Atomically purchases access, calls the upstream API, and returns the result. Credits are automatically refunded if the upstream call fails. Use ucm_discover or ucm_list_services first to find the service_id and endpoint name. Requires registration (ucm_register) if not already registered.',
             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' },
+                    service_id: { type: 'string', description: 'Service ID, e.g. "ucm/web-search"' },
+                    endpoint: { type: 'string', description: 'Endpoint name, e.g. "search", "generate", "execute"' },
+                    body: { type: 'object', description: 'Parameters for the API call (optional for endpoints with no required params)' },
                 },
-                required: ['service_id', 'method', 'params'],
+                required: ['service_id', 'endpoint'],
             },
         },
         {
             name: 'ucm_balance',
-            description: 'Check your current UCM budget — daily/monthly limits, spending, and remaining balance.',
+            description: 'Check your current UCM credit balance and spending. Returns credits (balance, lifetime_added, lifetime_spent) and usage counters.',
             inputSchema: { type: 'object', properties: {} },
         },
         {
@@ -82,7 +64,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'ucm_service_info',
-            description: 'Get detailed information about a service: API schema, pricing, SLA, and provider details.',
+            description: 'Get detailed information about a specific service including all available endpoints, required parameters, pricing, and usage examples. Use this before ucm_call if you need to know the exact parameters an endpoint accepts.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -93,65 +75,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'ucm_register',
-            description: 'Self-register as a new agent on UCM. Returns an agent ID and API key for subsequent requests.',
+            description: 'Register on UCM to get an API key. Free, instant, no approval needed. Gives $1.00 bonus credits (enough for 100+ API calls). The API key is automatically saved for this session. Call this before ucm_call if you get an auth error. Only needs to be done once per session.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     name: { type: 'string', description: 'Agent name (1-255 characters)' },
                     description: { type: 'string', description: 'Optional agent description' },
+                    ref: { type: 'string', description: 'Optional referral code' },
                 },
                 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'],
-            },
-        },
         {
             name: 'ucm_list_services',
-            description: 'Browse the full UCM service catalog, or check for newly added services since a given date.',
+            description: 'Browse all available API services on UCM with pricing and endpoint details. Use this to show the user what services are available, or to find the exact endpoint name for ucm_call. Faster than ucm_discover when you already know what category you want.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -176,11 +113,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     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 ?? {});
+                result = await client.call(args.service_id, args.endpoint, args.body);
                 break;
             case 'ucm_balance':
                 result = await client.balance();
@@ -191,29 +125,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             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);
+            case 'ucm_register': {
+                result = await client.register(args.name, args.description, args.ref);
+                const apiKey = result.api_key;
+                if (apiKey) {
+                    client.setApiKey(apiKey);
+                }
                 break;
+            }
             case 'ucm_list_services':
                 result = await client.listServices({
                     since: args.since,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ucm/mcp-server",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "MCP server for UCM — Agent-Native API Marketplace. Gives AI agents access to discover, purchase, and use API services.",
   "type": "module",
   "license": "MIT",
@@ -39,8 +39,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "@noble/ed25519": "^2.2.0"
+    "@modelcontextprotocol/sdk": "^1.12.0"
   },
   "devDependencies": {
     "tsx": "^4.19.0",