@anycast/mcp 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# @anycast/mcp
+
+MCP (Model Context Protocol) server for the [Anycast Platform](https://anycast.net). Enables AI assistants like Claude, Cursor, and Copilot to manage agents, webhooks, and P2P connectivity.
+
+## Installation
+
+```bash
+npm install -g @anycast/mcp
+```
+
+## Configuration
+
+Set your Anycast API key:
+
+```bash
+export ANYCAST_API_KEY=your-api-key-here
+export ANYCAST_API_URL=https://api.anycast.net  # optional, defaults to localhost:3002
+```
+
+## Usage with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "anycast": {
+      "command": "anycast-mcp",
+      "env": {
+        "ANYCAST_API_KEY": "your-api-key-here",
+        "ANYCAST_API_URL": "https://api.anycast.net"
+      }
+    }
+  }
+}
+```
+
+## Usage with Claude Code
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "anycast": {
+      "command": "npx",
+      "args": ["@anycast/mcp"],
+      "env": {
+        "ANYCAST_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Usage with Cursor
+
+Add to Cursor settings > MCP Servers:
+
+```json
+{
+  "anycast": {
+    "command": "anycast-mcp",
+    "env": {
+      "ANYCAST_API_KEY": "your-api-key-here"
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Agents
+| Tool | Description |
+|------|-------------|
+| `list_agents` | List all agents with status, IP, version |
+| `get_agent` | Get agent details by ID |
+| `update_agent` | Update agent name or labels |
+| `delete_agent` | Delete agent (disconnects connections) |
+| `get_agent_connections` | Get connection history for an agent |
+
+### Tokens
+| Tool | Description |
+|------|-------------|
+| `list_tokens` | List registration tokens (prefixes only) |
+| `create_token` | Create new registration token |
+| `revoke_token` | Revoke a token |
+
+### Groups
+| Tool | Description |
+|------|-------------|
+| `list_groups` | List agent groups |
+| `create_group` | Create a new group |
+| `add_agent_to_group` | Add agent to group |
+| `remove_agent_from_group` | Remove agent from group |
+
+### Connectivity
+| Tool | Description |
+|------|-------------|
+| `get_discovery` | Get rendezvous server URL |
+| `list_connections` | List P2P connections |
+| `get_connection_stats` | Bandwidth and connection counts |
+
+### Webhooks (Ramps)
+| Tool | Description |
+|------|-------------|
+| `list_destinations` | List webhook destinations |
+| `create_destination` | Create webhook destination |
+| `list_events` | List webhook events |
+
+### Resources
+
+| URI | Description |
+|-----|-------------|
+| `anycast://agents` | All registered agents |
+| `anycast://connections` | Recent connections (24h) |
+| `anycast://stats` | Platform statistics |
+
+## Examples
+
+Ask Claude:
+
+> "List all my online agents"
+
+> "Create a registration token called 'production' with a limit of 50 uses"
+
+> "Show me the connection stats for the last week"
+
+> "Create a webhook destination at https://api.example.com/webhooks"
+
+> "Which agents are in the 'production' group?"
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Anycast Platform API client for the MCP server.
+ */
+export interface AnycastConfig {
+    apiUrl: string;
+    apiKey: string;
+}
+export declare function loadConfig(): AnycastConfig;
+export declare class AnycastClient {
+    private config;
+    constructor(config: AnycastConfig);
+    private request;
+    listAgents(params?: {
+        status?: string;
+        search?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    getAgent(id: string): Promise<unknown>;
+    updateAgent(id: string, data: {
+        name?: string;
+        labels?: Record<string, string>;
+    }): Promise<unknown>;
+    deleteAgent(id: string): Promise<unknown>;
+    getAgentConnections(id: string, params?: {
+        status?: string;
+        page?: number;
+    }): Promise<unknown>;
+    listTokens(): Promise<unknown>;
+    createToken(data: {
+        name: string;
+        usageLimit?: number;
+        expiresAt?: string;
+    }): Promise<unknown>;
+    revokeToken(id: string): Promise<unknown>;
+    listGroups(): Promise<unknown>;
+    createGroup(data: {
+        name: string;
+        description?: string;
+    }): Promise<unknown>;
+    addAgentToGroup(groupId: string, agentId: string): Promise<unknown>;
+    removeAgentFromGroup(groupId: string, agentId: string): Promise<unknown>;
+    getDiscovery(): Promise<unknown>;
+    listConnections(params?: {
+        status?: string;
+        type?: string;
+        days?: number;
+        page?: number;
+    }): Promise<unknown>;
+    getStats(): Promise<unknown>;
+    listDestinations(): Promise<unknown>;
+    createDestination(data: {
+        name?: string;
+        url: string;
+        maxRetries?: number;
+    }): Promise<unknown>;
+    listEvents(params?: {
+        status?: string;
+        provider?: string;
+        page?: number;
+        limit?: number;
+    }): Promise<unknown>;
+}

package/dist/client.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Anycast Platform API client for the MCP server.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnycastClient = void 0;
+exports.loadConfig = loadConfig;
+function loadConfig() {
+    const apiKey = process.env.ANYCAST_API_KEY || '';
+    const apiUrl = process.env.ANYCAST_API_URL || 'http://localhost:3002';
+    if (!apiKey) {
+        console.error('Warning: ANYCAST_API_KEY not set');
+    }
+    return { apiUrl, apiKey };
+}
+class AnycastClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(path, opts) {
+        const url = `${this.config.apiUrl}${path}`;
+        const res = await fetch(url, {
+            ...opts,
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.config.apiKey,
+                ...opts?.headers,
+            },
+        });
+        const text = await res.text();
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = { raw: text };
+        }
+        if (!res.ok) {
+            const errMsg = data?.error || `HTTP ${res.status}`;
+            throw new Error(errMsg);
+        }
+        return data;
+    }
+    // Agents
+    async listAgents(params) {
+        const qs = new URLSearchParams();
+        if (params?.status)
+            qs.set('status', params.status);
+        if (params?.search)
+            qs.set('search', params.search);
+        if (params?.page)
+            qs.set('page', String(params.page));
+        if (params?.limit)
+            qs.set('limit', String(params.limit));
+        return this.request(`/api/agents?${qs}`);
+    }
+    async getAgent(id) {
+        return this.request(`/api/agents/${id}`);
+    }
+    async updateAgent(id, data) {
+        return this.request(`/api/agents/${id}`, { method: 'PATCH', body: JSON.stringify(data) });
+    }
+    async deleteAgent(id) {
+        return this.request(`/api/agents/${id}`, { method: 'DELETE' });
+    }
+    async getAgentConnections(id, params) {
+        const qs = new URLSearchParams();
+        if (params?.status)
+            qs.set('status', params.status);
+        if (params?.page)
+            qs.set('page', String(params.page));
+        return this.request(`/api/agents/${id}/connections?${qs}`);
+    }
+    // Tokens
+    async listTokens() {
+        return this.request('/api/agents/tokens');
+    }
+    async createToken(data) {
+        return this.request('/api/agents/tokens', { method: 'POST', body: JSON.stringify(data) });
+    }
+    async revokeToken(id) {
+        return this.request(`/api/agents/tokens/${id}`, { method: 'DELETE' });
+    }
+    // Groups
+    async listGroups() {
+        return this.request('/api/agents/groups');
+    }
+    async createGroup(data) {
+        return this.request('/api/agents/groups', { method: 'POST', body: JSON.stringify(data) });
+    }
+    async addAgentToGroup(groupId, agentId) {
+        return this.request(`/api/agents/groups/${groupId}/members`, {
+            method: 'POST',
+            body: JSON.stringify({ agentIds: [agentId] }),
+        });
+    }
+    async removeAgentFromGroup(groupId, agentId) {
+        return this.request(`/api/agents/groups/${groupId}/members`, {
+            method: 'DELETE',
+            body: JSON.stringify({ agentId }),
+        });
+    }
+    // Discovery
+    async getDiscovery() {
+        // Public endpoint, no auth needed
+        const url = `${this.config.apiUrl}/api/agents/discover`;
+        const res = await fetch(url);
+        return res.json();
+    }
+    // Connections
+    async listConnections(params) {
+        const qs = new URLSearchParams();
+        if (params?.status)
+            qs.set('status', params.status);
+        if (params?.type)
+            qs.set('type', params.type);
+        if (params?.days)
+            qs.set('days', String(params.days));
+        if (params?.page)
+            qs.set('page', String(params.page));
+        return this.request(`/api/agents/connections?${qs}`);
+    }
+    async getStats() {
+        return this.request('/api/agents/stats');
+    }
+    // Destinations (Ramps)
+    async listDestinations() {
+        return this.request('/api/destinations');
+    }
+    async createDestination(data) {
+        return this.request('/api/destinations', { method: 'POST', body: JSON.stringify(data) });
+    }
+    // Events
+    async listEvents(params) {
+        const qs = new URLSearchParams();
+        if (params?.status)
+            qs.set('status', params.status);
+        if (params?.provider)
+            qs.set('provider', params.provider);
+        if (params?.page)
+            qs.set('page', String(params.page));
+        if (params?.limit)
+            qs.set('limit', String(params.limit));
+        return this.request(`/api/events?${qs}`);
+    }
+}
+exports.AnycastClient = AnycastClient;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * @anycast/mcp — MCP server for the Anycast Platform
+ *
+ * Enables AI assistants (Claude, Cursor, etc.) to manage agents,
+ * webhooks, and connectivity on the Anycast Edge Platform.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * @anycast/mcp — MCP server for the Anycast Platform
+ *
+ * Enables AI assistants (Claude, Cursor, etc.) to manage agents,
+ * webhooks, and connectivity on the Anycast Edge Platform.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const client_js_1 = require("./client.js");
+const config = (0, client_js_1.loadConfig)();
+const client = new client_js_1.AnycastClient(config);
+const server = new mcp_js_1.McpServer({
+    name: 'anycast',
+    version: '0.1.0',
+});
+// ---------------------------------------------------------------------------
+// Tools — Agents
+// ---------------------------------------------------------------------------
+server.tool('list_agents', 'List all registered agents with their status, IP, and version', { status: zod_1.z.enum(['ONLINE', 'OFFLINE', 'CONNECTING']).optional().describe('Filter by agent status'), search: zod_1.z.string().optional().describe('Search by agent name'), limit: zod_1.z.number().optional().describe('Max results (default 20)') }, async ({ status, search, limit }) => {
+    const data = await client.listAgents({ status, search, limit });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('get_agent', 'Get details for a specific agent including groups, connections, and labels', { id: zod_1.z.string().describe('Agent ID') }, async ({ id }) => {
+    const data = await client.getAgent(id);
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('update_agent', 'Update an agent name or labels', { id: zod_1.z.string().describe('Agent ID'), name: zod_1.z.string().optional().describe('New name'), labels: zod_1.z.record(zod_1.z.string()).optional().describe('Key-value labels') }, async ({ id, name, labels }) => {
+    const data = await client.updateAgent(id, { name, labels });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('delete_agent', 'Delete an agent — disconnects active connections and removes from all groups', { id: zod_1.z.string().describe('Agent ID to delete') }, async ({ id }) => {
+    const data = await client.deleteAgent(id);
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('get_agent_connections', 'Get connection history for a specific agent', { id: zod_1.z.string().describe('Agent ID'), status: zod_1.z.enum(['PENDING', 'CONNECTED', 'DISCONNECTED', 'FAILED']).optional() }, async ({ id, status }) => {
+    const data = await client.getAgentConnections(id, { status });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+// ---------------------------------------------------------------------------
+// Tools — Tokens
+// ---------------------------------------------------------------------------
+server.tool('list_tokens', 'List all agent registration tokens (prefixes only, not full tokens)', {}, async () => {
+    const data = await client.listTokens();
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('create_token', 'Create a new agent registration token — the full token is shown only once', { name: zod_1.z.string().describe('Token name'), usageLimit: zod_1.z.number().optional().describe('Max number of agents that can register with this token'), expiresAt: zod_1.z.string().optional().describe('ISO 8601 expiry date') }, async ({ name, usageLimit, expiresAt }) => {
+    const data = await client.createToken({ name, usageLimit, expiresAt });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('revoke_token', 'Revoke an agent registration token — agents already registered are not affected', { id: zod_1.z.string().describe('Token ID to revoke') }, async ({ id }) => {
+    const data = await client.revokeToken(id);
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+// ---------------------------------------------------------------------------
+// Tools — Groups
+// ---------------------------------------------------------------------------
+server.tool('list_groups', 'List agent groups with member and policy counts', {}, async () => {
+    const data = await client.listGroups();
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('create_group', 'Create a new agent group for organizing agents and applying policies', { name: zod_1.z.string().describe('Group name'), description: zod_1.z.string().optional().describe('Group description') }, async ({ name, description }) => {
+    const data = await client.createGroup({ name, description });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('add_agent_to_group', 'Add an agent to a group', { groupId: zod_1.z.string().describe('Group ID'), agentId: zod_1.z.string().describe('Agent ID to add') }, async ({ groupId, agentId }) => {
+    const data = await client.addAgentToGroup(groupId, agentId);
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('remove_agent_from_group', 'Remove an agent from a group', { groupId: zod_1.z.string().describe('Group ID'), agentId: zod_1.z.string().describe('Agent ID to remove') }, async ({ groupId, agentId }) => {
+    const data = await client.removeAgentFromGroup(groupId, agentId);
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+// ---------------------------------------------------------------------------
+// Tools — Connectivity
+// ---------------------------------------------------------------------------
+server.tool('get_discovery', 'Get the rendezvous server URL for agent connections (public, no auth needed)', {}, async () => {
+    const data = await client.getDiscovery();
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('list_connections', 'List P2P connections between agents', { status: zod_1.z.enum(['PENDING', 'CONNECTED', 'DISCONNECTED', 'FAILED']).optional(), type: zod_1.z.enum(['DIRECT', 'RELAYED']).optional(), days: zod_1.z.number().optional().describe('Lookback window in days (default 7)') }, async ({ status, type, days }) => {
+    const data = await client.listConnections({ status, type, days });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('get_connection_stats', 'Get agent and connection statistics — online counts, bandwidth, totals', {}, async () => {
+    const data = await client.getStats();
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+// ---------------------------------------------------------------------------
+// Tools — Ramps (webhook delivery)
+// ---------------------------------------------------------------------------
+server.tool('list_destinations', 'List webhook delivery destinations with retry config and alert settings', {}, async () => {
+    const data = await client.listDestinations();
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('create_destination', 'Create a new webhook delivery destination', { url: zod_1.z.string().describe('Webhook endpoint URL'), name: zod_1.z.string().optional().describe('Display name'), maxRetries: zod_1.z.number().optional().describe('Max retry attempts (0-10)') }, async ({ url, name, maxRetries }) => {
+    const data = await client.createDestination({ url, name, maxRetries });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+server.tool('list_events', 'List webhook events with filtering by status, provider, and time', { status: zod_1.z.enum(['RECEIVED', 'PROCESSING', 'DELIVERED', 'FAILED', 'RETRYING', 'DEAD']).optional(), provider: zod_1.z.string().optional().describe('Filter by provider (moonpay, transak, etc.)'), limit: zod_1.z.number().optional().describe('Max results') }, async ({ status, provider, limit }) => {
+    const data = await client.listEvents({ status, provider, limit });
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+// ---------------------------------------------------------------------------
+// Resources
+// ---------------------------------------------------------------------------
+server.resource('agents', 'anycast://agents', async (uri) => {
+    const data = await client.listAgents({ limit: 100 });
+    return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(data, null, 2) }] };
+});
+server.resource('connections', 'anycast://connections', async (uri) => {
+    const data = await client.listConnections({ days: 1 });
+    return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(data, null, 2) }] };
+});
+server.resource('stats', 'anycast://stats', async (uri) => {
+    const data = await client.getStats();
+    return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(data, null, 2) }] };
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('MCP server error:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@anycast/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the Anycast Platform — enables AI assistants to manage agents, webhooks, and connectivity",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "anycast-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^4.0.18"
+  },
+  "files": ["dist"],
+  "keywords": ["mcp", "anycast", "ai", "agents", "claude", "cursor"],
+  "license": "MIT"
+}