cellium-mcp-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cellium Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# @cellium/mcp-client
+
+A Model Context Protocol (MCP) client for connecting to the remote Cellium processor server via Server-Sent Events (SSE).
+
+## Features
+
+- **SSE Transport**: Connects to remote Cellium server using Server-Sent Events
+- **Authentication**: Token-based authentication with format `user:username:hash`
+- **Robust Connection Management**: Automatic reconnection with configurable retry logic
+- **MCP Protocol Compliance**: Uses official `@modelcontextprotocol/sdk`
+- **CLI Interface**: Ready-to-use command-line interface
+- **TypeScript Support**: Full TypeScript types and definitions
+
+## Installation
+
+```bash
+npm install -g @cellium/mcp-client
+```
+
+Or use directly with npx:
+
+```bash
+npx @cellium/mcp-client
+```
+
+## Usage
+
+### Command Line Interface
+
+```bash
+# Using environment variable for token
+export CELLIUM_MCP_TOKEN="user:your-username:your-hash"
+cellium-mcp-client
+
+# Using command line option
+cellium-mcp-client --token "user:your-username:your-hash"
+
+# With custom endpoint and verbose logging
+cellium-mcp-client \
+  --token "user:your-username:your-hash" \
+  --endpoint "https://mcp.cellium.dev/sse" \
+  --verbose \
+  --retry-attempts 5 \
+  --retry-delay 2000
+```
+
+### Configuration with Cody/Other MCP Clients
+
+Add to your MCP client configuration:
+
+```toml
+[mcp_servers.cellium]
+command = "npx"
+args = ["-y", "@cellium/mcp-client"]
+env = { CELLIUM_MCP_TOKEN = "user:your-username:your-hash" }
+enabled = true
+```
+
+### Programmatic Usage
+
+```typescript
+import { CelliumMCPClient } from '@cellium/mcp-client';
+import pino from 'pino';
+
+const logger = pino();
+
+const client = new CelliumMCPClient({
+  token: 'user:your-username:your-hash',
+  endpoint: 'https://mcp.cellium.dev/sse',
+  logger,
+  retryAttempts: 3,
+  retryDelay: 1000
+});
+
+await client.connect();
+
+// The client will now proxy MCP requests to the remote server
+// Handle shutdown gracefully
+process.on('SIGINT', async () => {
+  await client.disconnect();
+  process.exit(0);
+});
+```
+
+## Configuration Options
+
+| Option | Environment Variable | Description | Default |
+|--------|---------------------|-------------|---------|
+| `--token` | `CELLIUM_MCP_TOKEN` | Authentication token (required) | - |
+| `--endpoint` | - | Server endpoint URL | `https://mcp.cellium.dev/sse` |
+| `--verbose` | - | Enable verbose logging | `false` |
+| `--retry-attempts` | - | Number of retry attempts | `3` |
+| `--retry-delay` | - | Delay between retries (ms) | `1000` |
+
+## Authentication Token Format
+
+The authentication token must follow the format: `user:username:hash`
+
+Where:
+- `user`: Literal string "user"
+- `username`: Your Cellium username
+- `hash`: Authentication hash provided by Cellium
+
+Example: `user:john-doe:a1b2c3d4e5f6...`
+
+## Architecture
+
+```
+┌─────────────────┐    SSE     ┌─────────────────┐
+│                 │◄──────────►│                 │
+│   MCP Client    │   HTTPS    │ Cellium Server  │
+│  (This Package) │            │   (Remote)      │
+│                 │            │                 │
+└─────────────────┘            └─────────────────┘
+         ▲                               │
+         │ stdio                        │
+         │ MCP Protocol                 │
+         ▼                               │
+┌─────────────────┐                     │
+│                 │                     │
+│  Code Editor /  │                     │
+│  AI Assistant   │                     │
+│   (Cody, etc.)  │                     │
+└─────────────────┘                     │
+```
+
+The client acts as a bridge between local MCP clients (like Cody) and the remote Cellium processor server, handling:
+- Authentication and connection management
+- Protocol translation between stdio MCP and SSE
+- Error handling and reconnection logic
+- Request/response proxying
+
+## Development
+
+```bash
+# Clone and install dependencies
+git clone <repo-url>
+cd cellium-mcp-client
+npm install
+
+# Build
+npm run build
+
+# Run in development mode
+npm run dev
+
+# Test locally
+./dist/cli.js --help
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+1. **Invalid token format**: Ensure your token follows the `user:username:hash` format
+2. **Network connectivity**: Check if `https://mcp.cellium.dev/sse` is accessible
+3. **Authentication failed**: Verify your token is valid and not expired
+
+### Verbose Logging
+
+Use `--verbose` flag to enable detailed logging for debugging:
+
+```bash
+cellium-mcp-client --verbose --token "your-token"
+```
+
+### Common Error Messages
+
+- `Authentication token required`: Set `CELLIUM_MCP_TOKEN` or use `--token`
+- `Invalid token format`: Check token follows `user:username:hash` pattern  
+- `Not connected to remote server`: Connection to SSE endpoint failed
+- `Request timeout`: Remote server didn't respond within 30 seconds
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, please open an issue on the GitHub repository.
+

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const client_1 = require("./client");
+const commander_1 = require("commander");
+const pino_1 = __importDefault(require("pino"));
+const program = new commander_1.Command();
+program
+    .name('cellium-mcp-client')
+    .description('MCP client for connecting to remote Cellium processor server')
+    .version('1.0.0')
+    .option('-t, --token <token>', 'Authentication token (format: user:username:hash)')
+    .option('-e, --endpoint <url>', 'Server endpoint URL', 'https://mcp.cellium.dev/sse')
+    .option('-v, --verbose', 'Enable verbose logging')
+    .option('-r, --retry-attempts <num>', 'Number of retry attempts on connection failure', '3')
+    .option('--retry-delay <ms>', 'Delay between retry attempts in milliseconds', '1000')
+    .parse(process.argv);
+const options = program.opts();
+// Configure logging
+const logger = (0, pino_1.default)({
+    level: options.verbose ? 'debug' : 'info',
+    transport: {
+        target: 'pino-pretty',
+        options: {
+            colorize: true,
+            translateTime: 'HH:MM:ss',
+            ignore: 'pid,hostname'
+        }
+    }
+});
+async function main() {
+    try {
+        // Get token from environment or command line
+        const token = options.token || process.env.CELLIUM_MCP_TOKEN;
+        if (!token) {
+            logger.error('Authentication token required. Use --token option or CELLIUM_MCP_TOKEN environment variable');
+            process.exit(1);
+        }
+        // Validate token format
+        if (!token.match(/^user:[^:]+:[a-f0-9]+$/)) {
+            logger.error('Invalid token format. Expected: user:username:hash');
+            process.exit(1);
+        }
+        logger.info('Starting Cellium MCP Client');
+        logger.debug({
+            endpoint: options.endpoint,
+            retryAttempts: parseInt(options.retryAttempts),
+            retryDelay: parseInt(options.retryDelay)
+        }, 'Configuration');
+        const client = new client_1.CelliumMCPClient({
+            token,
+            endpoint: options.endpoint,
+            logger,
+            retryAttempts: parseInt(options.retryAttempts),
+            retryDelay: parseInt(options.retryDelay)
+        });
+        // Handle graceful shutdown
+        process.on('SIGINT', async () => {
+            logger.info('Received SIGINT, shutting down gracefully');
+            await client.disconnect();
+            process.exit(0);
+        });
+        process.on('SIGTERM', async () => {
+            logger.info('Received SIGTERM, shutting down gracefully');
+            await client.disconnect();
+            process.exit(0);
+        });
+        await client.connect();
+        // Keep the process alive
+        process.stdin.resume();
+    }
+    catch (error) {
+        logger.error({ error }, 'Fatal error');
+        process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error('Unhandled error:', error);
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+import type { Logger } from 'pino';
+export interface CelliumMCPClientConfig {
+    token: string;
+    endpoint: string;
+    logger: Logger;
+    retryAttempts?: number;
+    retryDelay?: number;
+}
+export declare class CelliumMCPClient {
+    private config;
+    private localServer;
+    private isConnected;
+    private reconnectTimer?;
+    private currentRetryCount;
+    constructor(config: CelliumMCPClientConfig);
+    private setupServer;
+    private makeHttpRequest;
+    connect(): Promise<void>;
+    private testConnection;
+    private handleConnectionError;
+    private reconnect;
+    disconnect(): Promise<void>;
+}

package/dist/client.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CelliumMCPClient = void 0;
+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");
+// Define schemas for MCP requests
+const ToolsListSchema = zod_1.z.object({
+    method: zod_1.z.literal('tools/list'),
+    params: zod_1.z.object({}).optional()
+});
+const ToolsCallSchema = zod_1.z.object({
+    method: zod_1.z.literal('tools/call'),
+    params: zod_1.z.object({
+        name: zod_1.z.string(),
+        arguments: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional()
+    })
+});
+const ResourcesListSchema = zod_1.z.object({
+    method: zod_1.z.literal('resources/list'),
+    params: zod_1.z.object({}).optional()
+});
+const ResourcesReadSchema = zod_1.z.object({
+    method: zod_1.z.literal('resources/read'),
+    params: zod_1.z.object({
+        uri: zod_1.z.string()
+    })
+});
+const PingSchema = zod_1.z.object({
+    method: zod_1.z.literal('ping'),
+    params: zod_1.z.object({}).optional()
+});
+class CelliumMCPClient {
+    config;
+    localServer;
+    isConnected = false;
+    reconnectTimer;
+    currentRetryCount = 0;
+    constructor(config) {
+        this.config = {
+            retryAttempts: 3,
+            retryDelay: 1000,
+            ...config
+        };
+        // Local server that interfaces with AI assistants via stdio
+        this.localServer = new mcp_js_1.McpServer({
+            name: 'cellium-mcp-client',
+            version: '1.0.0'
+        }, {
+            capabilities: {
+                tools: {},
+                resources: {}
+            }
+        });
+        this.setupServer();
+    }
+    setupServer() {
+        // Register a dynamic tool handler that forwards all tool calls to remote server
+        this.localServer.registerTool('cellium-proxy-tool', {
+            description: 'Proxy tool for Cellium server - handles all tool calls dynamically'
+        }, async (_args) => {
+            // This won't actually be called since we override the request handlers directly
+            return { content: [{ type: 'text', text: 'Proxy tool' }] };
+        });
+        // Override the underlying server's tool request handlers to proxy to remote
+        this.localServer.server.setRequestHandler(ToolsListSchema, async () => {
+            this.config.logger.debug('Proxying tools/list to remote server');
+            if (!this.isConnected) {
+                throw new Error('Not connected to remote server');
+            }
+            const result = await this.makeHttpRequest('tools/list', {});
+            return result;
+        });
+        this.localServer.server.setRequestHandler(ToolsCallSchema, async (request) => {
+            this.config.logger.debug({ toolName: request.params?.name }, 'Proxying tool call to remote server');
+            if (!this.isConnected) {
+                throw new Error('Not connected to remote server');
+            }
+            const result = await this.makeHttpRequest('tools/call', request.params);
+            return result;
+        });
+        // Handle resources as well
+        this.localServer.server.setRequestHandler(ResourcesListSchema, async () => {
+            this.config.logger.debug('Proxying resources/list to remote server');
+            if (!this.isConnected) {
+                throw new Error('Not connected to remote server');
+            }
+            const result = await this.makeHttpRequest('resources/list', {});
+            return result;
+        });
+        this.localServer.server.setRequestHandler(ResourcesReadSchema, async (request) => {
+            this.config.logger.debug({ uri: request.params?.uri }, 'Proxying resources/read to remote server');
+            if (!this.isConnected) {
+                throw new Error('Not connected to remote server');
+            }
+            const result = await this.makeHttpRequest('resources/read', request.params);
+            return result;
+        });
+        // Handle ping
+        this.localServer.server.setRequestHandler(PingSchema, async () => {
+            if (!this.isConnected) {
+                throw new Error('Not connected to remote server');
+            }
+            const result = await this.makeHttpRequest('ping', {});
+            return result;
+        });
+    }
+    async makeHttpRequest(method, params) {
+        const mcpEndpoint = this.config.endpoint.replace('/sse', '/mcp');
+        const requestBody = {
+            jsonrpc: '2.0',
+            id: Math.random().toString(36).substring(2, 15),
+            method,
+            params
+        };
+        this.config.logger.debug({ method, endpoint: mcpEndpoint }, 'Making HTTP request to remote server');
+        try {
+            const response = await fetch(mcpEndpoint, {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.config.token}`,
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(requestBody)
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            const jsonResponse = await response.json();
+            if (jsonResponse.error) {
+                throw new Error(`Remote server error: ${jsonResponse.error.message}`);
+            }
+            return jsonResponse.result;
+        }
+        catch (error) {
+            this.config.logger.error({ error, method }, 'HTTP request to remote server failed');
+            throw error;
+        }
+    }
+    async connect() {
+        try {
+            this.config.logger.info({ endpoint: this.config.endpoint }, 'Connecting to Cellium MCP Server');
+            // Test connection with a ping
+            await this.testConnection();
+            this.isConnected = true;
+            this.currentRetryCount = 0;
+            if (this.reconnectTimer) {
+                clearTimeout(this.reconnectTimer);
+                this.reconnectTimer = undefined;
+            }
+            this.config.logger.info('Connected to remote Cellium server');
+            // Set up the stdio transport for local MCP server
+            const stdioTransport = new stdio_js_1.StdioServerTransport();
+            await this.localServer.connect(stdioTransport);
+            this.config.logger.info('MCP Client connected and ready');
+        }
+        catch (error) {
+            this.config.logger.error({ error }, 'Failed to connect');
+            this.isConnected = false;
+            this.handleConnectionError();
+            throw error;
+        }
+    }
+    async testConnection() {
+        const mcpEndpoint = this.config.endpoint.replace('/sse', '/mcp');
+        const response = await fetch(mcpEndpoint, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.config.token}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 'test-connection',
+                method: 'ping',
+                params: {}
+            })
+        });
+        if (!response.ok) {
+            throw new Error(`Connection test failed: HTTP ${response.status}`);
+        }
+        const result = await response.json();
+        if (result.error) {
+            throw new Error(`Connection test failed: ${result.error.message}`);
+        }
+        this.config.logger.debug('Connection test successful');
+    }
+    handleConnectionError() {
+        if (this.currentRetryCount < this.config.retryAttempts) {
+            this.currentRetryCount++;
+            this.config.logger.warn(`Connection failed, retrying in ${this.config.retryDelay}ms (attempt ${this.currentRetryCount}/${this.config.retryAttempts})`);
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnect();
+            }, this.config.retryDelay);
+        }
+        else {
+            this.config.logger.error('Max retry attempts reached, giving up');
+            process.exit(1);
+        }
+    }
+    async reconnect() {
+        try {
+            await this.connect();
+        }
+        catch (error) {
+            this.config.logger.error({ error }, 'Reconnection failed');
+            this.handleConnectionError();
+        }
+    }
+    async disconnect() {
+        this.config.logger.info('Disconnecting from Cellium MCP Server');
+        this.isConnected = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        await this.localServer.close();
+        this.config.logger.info('Disconnected successfully');
+    }
+}
+exports.CelliumMCPClient = CelliumMCPClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { CelliumMCPClient } from './client';
+export type { CelliumMCPClientConfig } from './client';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CelliumMCPClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "CelliumMCPClient", { enumerable: true, get: function () { return client_1.CelliumMCPClient; } });

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "cellium-mcp-client",
+  "version": "1.0.0",
+  "description": "MCP client for connecting to remote Cellium processor server",
+  "main": "dist/index.js",
+  "bin": {
+    "cellium-mcp-client": "dist/cli.js"
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "echo \"No tests yet\"",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cellium",
+    "client"
+  ],
+  "author": "Cellium Team",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "commander": "^12.1.0",
+    "eventsource": "^2.0.2",
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.1.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/eventsource": "^1.1.15",
+    "@types/node": "^20.17.10",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cellium/mcp-client.git"
+  }
+}