@coop-tech/mcp-sidecar 0.0.1

package/README.md

@@ -0,0 +1,74 @@
+# @coop-tech/mcp-sidecar
+
+Connect MCP servers to [coop.tech](https://coop.tech) as sidecars.
+
+## Install
+
+```bash
+npm install @coop-tech/mcp-sidecar
+```
+
+## Library usage
+
+Connect an in-process MCP server:
+
+```ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { connectSidecar } from '@coop-tech/mcp-sidecar'
+
+const server = new McpServer({ name: 'my-tools', version: '1.0.0' })
+server.tool('analyze', 'Analyze data', { query: z.string() }, async ({ query }) => {
+  return { content: [{ type: 'text', text: 'result' }] }
+})
+
+await connectSidecar({
+  server,
+  token: process.env.COOP_TECH_TOKEN!,
+  description: 'Analyzes data',
+})
+```
+
+## CLI usage
+
+Spawn an external MCP server and connect it:
+
+```bash
+# Using --command:
+coop-mcp-sidecar --token YOUR_TOKEN --description "My server" --command "python my_server.py"
+
+# Using -- separator:
+coop-mcp-sidecar --token YOUR_TOKEN --description "My server" -- python my_server.py
+
+# Using env var:
+COOP_TECH_TOKEN=YOUR_TOKEN coop-mcp-sidecar --description "My server" -- python my_server.py
+```
+
+### CLI options
+
+| Option | Description |
+|--------|-------------|
+| `--token <token>` | Personal access token (or `COOP_TECH_TOKEN` env var) |
+| `--url <url>` | Server URL (default: `wss://coop.tech/mcp-sidecar`) |
+| `--description <text>` | Description of the server (required) |
+| `--instructions <text>` | Additional instructions for the agent |
+| `--name <name>` | Override server name |
+| `--version <version>` | Override server version |
+| `--verbose` | Log full tool call arguments and results |
+| `--quiet` | Suppress all logs |
+
+## API
+
+### `connectSidecar(config): Promise<Sidecar>`
+
+Creates and connects a sidecar. Config options:
+
+- **`token`** (required) - coop.tech personal access token
+- **`description`** (required) - description of what the server does
+- **`server`** - in-process `McpServer` instance (library mode)
+- **`command`** / **`args`** / **`env`** / **`cwd`** - external MCP server (stdio mode)
+- **`url`** - coop.tech WebSocket URL (default: `wss://coop.tech/mcp-sidecar`)
+- **`name`** / **`version`** - override server name/version
+- **`instructions`** - additional agent instructions
+- **`logLevel`** - `'normal'` | `'verbose'` | `'quiet'`
+- **`reconnect`** - auto-reconnect on disconnect (default: `true`)
+- **`onConnect`** / **`onDisconnect`** / **`onError`** - lifecycle callbacks

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { connectSidecar } from './index.js';
+function printUsage() {
+    console.log(`Usage: coop-mcp-sidecar [options] [-- command [args...]]
+
+Options:
+  --token <token>             Personal access token (or set COOP_TECH_TOKEN env var)
+  --url <url>                 Server URL (default: wss://coop.tech/mcp-sidecar)
+  --command <cmd>             MCP server command to spawn
+  --description <description> Description of what this server does (required)
+  --instructions <text>       Additional instructions for the agent
+  --name <name>               Override the server name reported to coop.tech
+  --version <version>         Override the server version reported to coop.tech
+  --verbose                   Log full tool call arguments and results
+  --quiet                     Suppress all tool call and connection logs
+  --help                      Show this help message
+
+Examples:
+  # Spawn an MCP server via stdio:
+  coop-mcp-sidecar --token YOUR_TOKEN --description "Manages database queries" --command "python my_server.py"
+
+  # Using -- separator for command with arguments:
+  coop-mcp-sidecar --token YOUR_TOKEN --description "Code search agent" -- claude mcp serve
+
+  # Override the server name and version:
+  coop-mcp-sidecar --token YOUR_TOKEN --description "My server" --name my-server --version 2.0.0 -- python my_server.py
+
+  # Using environment variable:
+  COOP_TECH_TOKEN=YOUR_TOKEN coop-mcp-sidecar --description "My server" -- python my_server.py`);
+}
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            token: { type: 'string' },
+            url: { type: 'string' },
+            command: { type: 'string' },
+            description: { type: 'string' },
+            instructions: { type: 'string' },
+            name: { type: 'string' },
+            version: { type: 'string' },
+            verbose: { type: 'boolean' },
+            quiet: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    if (values.help) {
+        printUsage();
+        process.exit(0);
+    }
+    const token = values.token ?? process.env.COOP_TECH_TOKEN;
+    const url = values.url;
+    let command = values.command;
+    let commandArgs = [];
+    if (positionals.length > 0) {
+        command = positionals[0];
+        commandArgs = positionals.slice(1);
+    }
+    if (!token) {
+        console.error('Error: --token is required (or set COOP_TECH_TOKEN environment variable)');
+        process.exit(1);
+    }
+    if (!command) {
+        console.error('Error: --command is required (or use -- separator)');
+        printUsage();
+        process.exit(1);
+    }
+    const description = values.description;
+    if (!description) {
+        console.error('Error: --description is required');
+        printUsage();
+        process.exit(1);
+    }
+    const logLevel = values.quiet ? 'quiet' : values.verbose ? 'verbose' : 'normal';
+    if (logLevel !== 'quiet') {
+        console.log(`[coop-sidecar] Starting MCP server: ${command} ${commandArgs.join(' ')}`);
+    }
+    const sidecar = await connectSidecar({
+        token,
+        url,
+        command,
+        args: commandArgs,
+        description,
+        instructions: values.instructions,
+        name: values.name,
+        version: values.version,
+        logLevel,
+        reconnect: true,
+        onConnect: () => console.log('[coop-sidecar] Connected to coop.tech'),
+        onDisconnect: () => console.log('[coop-sidecar] Disconnected from coop.tech'),
+        onError: (err) => console.error('[coop-sidecar] Error:', err.message),
+    });
+    // Handle graceful shutdown
+    const shutdown = async () => {
+        console.log('\n[coop-sidecar] Shutting down...');
+        await sidecar.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', () => { void shutdown(); });
+    process.on('SIGTERM', () => { void shutdown(); });
+}
+main().catch((err) => {
+    console.error('[coop-sidecar] Fatal error:', err);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+export { Sidecar } from './sidecar.js';
+export type { SidecarConfig } from './sidecar.js';
+export type { ToolInfo } from './types.js';
+import type { SidecarConfig } from './sidecar.js';
+import { Sidecar } from './sidecar.js';
+/**
+ * Connect an MCP server to coop.tech as a sidecar.
+ *
+ * @example Library mode (in-process McpServer):
+ * ```ts
+ * import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+ * import { connectSidecar } from '@coop-tech/mcp-sidecar'
+ *
+ * const server = new McpServer({ name: 'my-tools', version: '1.0.0' })
+ * server.tool('analyze', 'Analyze data', { query: z.string() }, async ({ query }) => { ... })
+ *
+ * await connectSidecar({
+ *   server,
+ *   token: process.env.COOP_TECH_TOKEN!,
+ * })
+ * ```
+ *
+ * @example Stdio mode (spawn external process):
+ * ```ts
+ * await connectSidecar({
+ *   command: 'python',
+ *   args: ['my_mcp_server.py'],
+ *   token: process.env.COOP_TECH_TOKEN!,
+ * })
+ * ```
+ */
+export declare function connectSidecar(config: SidecarConfig): Promise<Sidecar>;

package/dist/index.js

@@ -0,0 +1,33 @@
+export { Sidecar } from './sidecar.js';
+import { Sidecar } from './sidecar.js';
+/**
+ * Connect an MCP server to coop.tech as a sidecar.
+ *
+ * @example Library mode (in-process McpServer):
+ * ```ts
+ * import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+ * import { connectSidecar } from '@coop-tech/mcp-sidecar'
+ *
+ * const server = new McpServer({ name: 'my-tools', version: '1.0.0' })
+ * server.tool('analyze', 'Analyze data', { query: z.string() }, async ({ query }) => { ... })
+ *
+ * await connectSidecar({
+ *   server,
+ *   token: process.env.COOP_TECH_TOKEN!,
+ * })
+ * ```
+ *
+ * @example Stdio mode (spawn external process):
+ * ```ts
+ * await connectSidecar({
+ *   command: 'python',
+ *   args: ['my_mcp_server.py'],
+ *   token: process.env.COOP_TECH_TOKEN!,
+ * })
+ * ```
+ */
+export async function connectSidecar(config) {
+    const sidecar = new Sidecar(config);
+    await sidecar.connect();
+    return sidecar;
+}

package/dist/sidecar.d.ts

@@ -0,0 +1,41 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface SidecarConfig {
+    token: string;
+    url?: string;
+    server?: McpServer;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    description: string;
+    name?: string;
+    version?: string;
+    instructions?: string;
+    logLevel?: 'normal' | 'verbose' | 'quiet';
+    reconnect?: boolean;
+    reconnectIntervalMs?: number;
+    heartbeatIntervalMs?: number;
+    onConnect?: () => void;
+    onDisconnect?: () => void;
+    onError?: (error: Error) => void;
+}
+export declare class Sidecar {
+    private config;
+    private logLevel;
+    private mcpClient;
+    private ws;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private tools;
+    private serverName;
+    private serverVersion;
+    private closed;
+    constructor(config: SidecarConfig);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private connectMcpServer;
+    private connectWebSocket;
+    private handleToolCall;
+    private startHeartbeat;
+    private stopHeartbeat;
+}

package/dist/sidecar.js

@@ -0,0 +1,229 @@
+import { createRequire } from 'node:module';
+import WebSocket from 'ws';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+const require = createRequire(import.meta.url);
+const { version: packageVersion } = require('../package.json');
+const DEFAULT_URL = 'wss://coop.tech/mcp-sidecar';
+const DEFAULT_RECONNECT_INTERVAL_MS = 5000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+function truncate(str, max) {
+    if (str.length <= max)
+        return str;
+    return str.slice(0, max) + '...';
+}
+export class Sidecar {
+    config;
+    logLevel;
+    mcpClient = null;
+    ws = null;
+    heartbeatTimer = null;
+    reconnectTimer = null;
+    tools = [];
+    serverName = '';
+    serverVersion = '';
+    closed = false;
+    constructor(config) {
+        if (!config.token)
+            throw new Error('token is required');
+        if (!config.server && !config.command)
+            throw new Error('Either server or command is required');
+        if (!config.description)
+            throw new Error('description is required');
+        this.config = {
+            ...config,
+            url: config.url ?? DEFAULT_URL,
+            reconnect: config.reconnect ?? true,
+            reconnectIntervalMs: config.reconnectIntervalMs ?? DEFAULT_RECONNECT_INTERVAL_MS,
+            heartbeatIntervalMs: config.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+        };
+        this.logLevel = config.logLevel ?? 'normal';
+    }
+    async connect() {
+        // Step 1: Connect to MCP server and discover tools
+        await this.connectMcpServer();
+        // Step 2: Connect to coop.tech WebSocket
+        await this.connectWebSocket();
+    }
+    async close() {
+        this.closed = true;
+        this.stopHeartbeat();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close(1000, 'Client closing');
+            this.ws = null;
+        }
+        if (this.mcpClient) {
+            await this.mcpClient.close().catch(() => { });
+            this.mcpClient = null;
+        }
+    }
+    async connectMcpServer() {
+        this.mcpClient = new Client({ name: 'coop-sidecar', version: packageVersion });
+        if (this.config.server) {
+            // Library mode: in-process McpServer
+            const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+            await this.config.server.connect(serverTransport);
+            await this.mcpClient.connect(clientTransport);
+        }
+        else if (this.config.command) {
+            // Stdio mode: spawn external process
+            const transport = new StdioClientTransport({
+                command: this.config.command,
+                args: this.config.args,
+                env: this.config.env ? { ...process.env, ...this.config.env } : undefined,
+                cwd: this.config.cwd,
+            });
+            await this.mcpClient.connect(transport);
+        }
+        const mcpServerVersion = this.mcpClient.getServerVersion();
+        // Use config overrides or fall back to MCP server values
+        this.serverName = this.config.name ?? mcpServerVersion?.name ?? '';
+        this.serverVersion = this.config.version ?? mcpServerVersion?.version ?? '';
+        if (!this.serverName) {
+            throw new Error('MCP server must return a name in its initialize response (serverInfo.name), or provide a name via config');
+        }
+        // Discover tools
+        const result = await this.mcpClient.listTools();
+        this.tools = result.tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        }));
+        if (this.logLevel !== 'quiet') {
+            console.log(`[coop-sidecar] Discovered ${this.tools.length} tool(s) from MCP server "${this.serverName}"`);
+        }
+    }
+    connectWebSocket() {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(this.config.url);
+            this.ws = ws;
+            let authenticated = false;
+            ws.on('open', () => {
+                // Send auth message
+                ws.send(JSON.stringify({
+                    type: 'auth',
+                    token: this.config.token,
+                    serverName: this.serverName,
+                    description: this.config.description,
+                    instructions: this.config.instructions,
+                    tools: this.tools,
+                    version: this.serverVersion,
+                    sdkVersion: packageVersion,
+                }));
+            });
+            ws.on('message', (rawData) => {
+                let msg;
+                try {
+                    const text = typeof rawData === 'string' ? rawData : Buffer.from(rawData).toString();
+                    msg = JSON.parse(text);
+                }
+                catch {
+                    return;
+                }
+                if (msg.type === 'auth_ok') {
+                    authenticated = true;
+                    this.startHeartbeat();
+                    if (this.logLevel !== 'quiet') {
+                        console.log(`[coop-sidecar] Connected as "${this.serverName}" (id: ${msg.serverId})`);
+                    }
+                    this.config.onConnect?.();
+                    resolve();
+                    return;
+                }
+                if (msg.type === 'auth_error') {
+                    const err = new Error(`Authentication failed: ${msg.message}`);
+                    this.config.onError?.(err);
+                    reject(err);
+                    return;
+                }
+                if (msg.type === 'tool_call') {
+                    void this.handleToolCall(msg);
+                    return;
+                }
+                if (msg.type === 'pong') {
+                    return;
+                }
+            });
+            ws.on('close', () => {
+                this.stopHeartbeat();
+                this.config.onDisconnect?.();
+                if (!this.closed && this.config.reconnect && authenticated) {
+                    if (this.logLevel !== 'quiet') {
+                        console.log(`[coop-sidecar] Disconnected. Reconnecting in ${this.config.reconnectIntervalMs}ms...`);
+                    }
+                    this.reconnectTimer = setTimeout(() => {
+                        this.connectWebSocket().catch((err) => {
+                            this.config.onError?.(err instanceof Error ? err : new Error(String(err)));
+                        });
+                    }, this.config.reconnectIntervalMs);
+                }
+            });
+            ws.on('error', (err) => {
+                this.config.onError?.(err);
+                if (!authenticated) {
+                    reject(err);
+                }
+            });
+        });
+    }
+    async handleToolCall(msg) {
+        if (!this.mcpClient || !this.ws)
+            return;
+        const maxLen = this.logLevel === 'verbose' ? Infinity : 100;
+        if (this.logLevel !== 'quiet') {
+            const argsStr = truncate(JSON.stringify(msg.arguments), maxLen);
+            console.log(`[coop-sidecar] Tool call: ${msg.name} args=${argsStr}`);
+        }
+        try {
+            const result = await this.mcpClient.callTool({
+                name: msg.name,
+                arguments: msg.arguments,
+            });
+            const content = Array.isArray(result.content)
+                ? result.content
+                : [{ type: 'text', text: String(result.content) }];
+            if (this.logLevel !== 'quiet') {
+                const contentStr = truncate(JSON.stringify(content), maxLen);
+                console.log(`[coop-sidecar] Tool result: ${msg.name} isError=${Boolean(result.isError)} content=${contentStr}`);
+            }
+            this.ws.send(JSON.stringify({
+                type: 'tool_result',
+                requestId: msg.requestId,
+                result: { content, isError: result.isError },
+            }));
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (this.logLevel !== 'quiet') {
+                console.log(`[coop-sidecar] Tool error: ${msg.name} ${errorMessage}`);
+            }
+            this.ws?.send(JSON.stringify({
+                type: 'tool_result',
+                requestId: msg.requestId,
+                result: {
+                    content: [{ type: 'text', text: `Error: ${errorMessage}` }],
+                    isError: true,
+                },
+            }));
+        }
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.send(JSON.stringify({ type: 'ping' }));
+            }
+        }, this.config.heartbeatIntervalMs);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export interface AuthMessage {
+    type: 'auth';
+    token: string;
+    serverName: string;
+    description: string;
+    instructions?: string;
+    tools: ToolInfo[];
+    version: string;
+    sdkVersion: string;
+}
+export interface ToolResultMessage {
+    type: 'tool_result';
+    requestId: string;
+    result: {
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError?: boolean;
+    };
+}
+export interface PingMessage {
+    type: 'ping';
+}
+export interface AuthOkMessage {
+    type: 'auth_ok';
+    serverId: string;
+}
+export interface AuthErrorMessage {
+    type: 'auth_error';
+    message: string;
+}
+export interface ToolCallMessage {
+    type: 'tool_call';
+    requestId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface PongMessage {
+    type: 'pong';
+}
+export interface ToolInfo {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+export type ServerMessage = AuthOkMessage | AuthErrorMessage | ToolCallMessage | PongMessage;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@coop-tech/mcp-sidecar",
+  "version": "0.0.1",
+  "description": "Connect MCP servers to coop.tech as sidecars",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "coop-mcp-sidecar": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "pnpm build"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.9.0"
+  },
+  "dependencies": {
+    "ws": "8.19.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "@types/ws": "8.18.1",
+    "typescript": "5.9.3"
+  },
+  "keywords": [
+    "mcp",
+    "sidecar",
+    "coop"
+  ],
+  "license": "MIT"
+}