@cloudstreamsoftware/knowledge-mcp-client 1.0.0

package/README.md

@@ -0,0 +1,86 @@
+# @cloudstream/knowledge-mcp-client
+
+MCP client bridge for CloudStream Knowledge Server. Translates Claude Code's stdio-based MCP protocol to HTTP requests against the Cloudflare Knowledge Server.
+
+## Architecture
+
+```
+Claude Code ──stdio──► MCP Client Bridge ──HTTPS──► Knowledge Server
+ (Parent)    JSON-RPC    (Child Process)   JSON-RPC   (Cloudflare)
+```
+
+## Installation
+
+This package is automatically configured when you run the CloudStream setup wizard:
+
+```bash
+npx @cloudstreamsoftware/claude-tools setup
+```
+
+## Manual Configuration
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "cloudstream-knowledge": {
+      "command": "npx",
+      "args": ["@cloudstream/knowledge-mcp-client"],
+      "env": {
+        "CLOUDSTREAM_LICENSE": "your-license-key",
+        "CLOUDSTREAM_API": "https://cloudstream-knowledge.broken-rain-0984.workers.dev"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CLOUDSTREAM_LICENSE` | Yes | Your CloudStream license key |
+| `CLOUDSTREAM_API` | Yes | Knowledge Server URL |
+| `CLOUDSTREAM_TIMEOUT` | No | Request timeout in ms (default: 30000) |
+| `CLOUDSTREAM_DEBUG` | No | Set to "true" for debug logging |
+
+## How It Works
+
+1. Claude Code spawns this package as a child process
+2. Claude Code sends JSON-RPC 2.0 requests via stdin
+3. This bridge forwards requests to the Knowledge Server via HTTPS
+4. Responses are returned to Claude Code via stdout
+
+### Offline Mode
+
+When the Knowledge Server is unavailable, the bridge returns helpful error messages instead of crashing:
+
+- `tools/list` returns an empty list
+- `tools/call` returns a friendly message with troubleshooting steps
+
+## Debugging
+
+Enable debug logging:
+
+```bash
+CLOUDSTREAM_DEBUG=true npx @cloudstream/knowledge-mcp-client
+```
+
+Debug output goes to stderr (doesn't interfere with JSON-RPC protocol on stdout).
+
+## Testing
+
+```bash
+# Test initialize (no network required)
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | \
+  CLOUDSTREAM_LICENSE=test CLOUDSTREAM_API=http://localhost \
+  npx @cloudstream/knowledge-mcp-client
+
+# Expected response:
+# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}
+```
+
+## License
+
+MIT - CloudStream Software LLC

package/bin/knowledge-mcp-client.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index.js');

package/dist/bridge.d.ts

@@ -0,0 +1,50 @@
+import { McpRequest, McpResponse, BridgeConfig, ConnectionState } from './types';
+/**
+ * HTTP Bridge to Knowledge Server
+ *
+ * Responsibilities:
+ * - Forward JSON-RPC requests to HTTP endpoint
+ * - Add authentication headers
+ * - Handle timeouts and retries
+ * - Graceful degradation when server unavailable
+ */
+export declare class HttpBridge {
+    private config;
+    private connectionState;
+    private lastError;
+    constructor(config: BridgeConfig);
+    /**
+     * Forward MCP request to Knowledge Server
+     */
+    forward(request: McpRequest): Promise<McpResponse>;
+    /**
+     * Handle initialize request locally
+     * This allows the bridge to respond immediately without network roundtrip
+     */
+    private handleInitialize;
+    /**
+     * Send HTTP request to Knowledge Server
+     */
+    private sendRequest;
+    /**
+     * Handle errors with graceful degradation
+     */
+    private handleError;
+    /**
+     * Generate offline mode response with helpful message
+     */
+    private offlineModeResponse;
+    /**
+     * Create JSON-RPC error response
+     */
+    private errorResponse;
+    /**
+     * Get current connection state
+     */
+    getConnectionState(): ConnectionState;
+    /**
+     * Get last error (for diagnostics)
+     */
+    getLastError(): Error | null;
+}
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAGjF;;;;;;;;GAQG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,eAAe,CAAiC;IACxD,OAAO,CAAC,SAAS,CAAsB;gBAE3B,MAAM,EAAE,YAAY;IAIhC;;OAEG;IACG,OAAO,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAgBxD;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;OAEG;YACW,WAAW;IAwDzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAoBnB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA0C3B;;OAEG;IACH,OAAO,CAAC,aAAa;IAYrB;;OAEG;IACH,kBAAkB,IAAI,eAAe;IAIrC;;OAEG;IACH,YAAY,IAAI,KAAK,GAAG,IAAI;CAG7B"}

package/dist/bridge.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpBridge = void 0;
+const errors_1 = require("./errors");
+/**
+ * HTTP Bridge to Knowledge Server
+ *
+ * Responsibilities:
+ * - Forward JSON-RPC requests to HTTP endpoint
+ * - Add authentication headers
+ * - Handle timeouts and retries
+ * - Graceful degradation when server unavailable
+ */
+class HttpBridge {
+    config;
+    connectionState = 'connecting';
+    lastError = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Forward MCP request to Knowledge Server
+     */
+    async forward(request) {
+        // Handle initialize locally for faster response
+        if (request.method === 'initialize') {
+            return this.handleInitialize(request);
+        }
+        try {
+            const response = await this.sendRequest(request);
+            this.connectionState = 'connected';
+            this.lastError = null;
+            return response;
+        }
+        catch (error) {
+            return this.handleError(request, error);
+        }
+    }
+    /**
+     * Handle initialize request locally
+     * This allows the bridge to respond immediately without network roundtrip
+     */
+    handleInitialize(request) {
+        return {
+            jsonrpc: '2.0',
+            id: request.id,
+            result: {
+                protocolVersion: '2024-11-05',
+                serverInfo: {
+                    name: 'cloudstream-knowledge',
+                    version: '1.0.0',
+                },
+                capabilities: {
+                    tools: {},
+                },
+            },
+        };
+    }
+    /**
+     * Send HTTP request to Knowledge Server
+     */
+    async sendRequest(request) {
+        const url = `${this.config.apiUrl}/api/v1/mcp`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.config.licenseKey}`,
+                    'User-Agent': 'cloudstream-knowledge-mcp-client/1.0.0',
+                },
+                body: JSON.stringify(request),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (response.status === 401) {
+                throw new errors_1.AuthenticationError();
+            }
+            if (response.status === 429) {
+                throw new errors_1.BridgeError('Rate limit exceeded', -32005, true);
+            }
+            if (!response.ok) {
+                throw new errors_1.ServerUnavailableError(`Server returned ${response.status}: ${response.statusText}`);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof errors_1.BridgeError) {
+                throw error;
+            }
+            // Network errors
+            if (error.name === 'AbortError') {
+                throw new errors_1.ServerUnavailableError('Request timed out');
+            }
+            throw new errors_1.ServerUnavailableError(`Network error: ${error.message}`);
+        }
+    }
+    /**
+     * Handle errors with graceful degradation
+     */
+    handleError(request, error) {
+        this.lastError = error;
+        if (error instanceof errors_1.AuthenticationError) {
+            this.connectionState = 'disconnected';
+            return this.errorResponse(request.id, error.code, error.message);
+        }
+        if (error instanceof errors_1.ServerUnavailableError) {
+            this.connectionState = 'offline';
+            return this.offlineModeResponse(request);
+        }
+        return this.errorResponse(request.id, -32603, // Internal error
+        `Bridge error: ${error.message}`);
+    }
+    /**
+     * Generate offline mode response with helpful message
+     */
+    offlineModeResponse(request) {
+        // For tools/list, return empty list with offline notice
+        if (request.method === 'tools/list') {
+            return {
+                jsonrpc: '2.0',
+                id: request.id,
+                result: {
+                    tools: [],
+                },
+            };
+        }
+        // For tool calls, return friendly error
+        if (request.method === 'tools/call') {
+            const toolName = request.params?.name || 'unknown tool';
+            return {
+                jsonrpc: '2.0',
+                id: request.id,
+                result: {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `[OFFLINE] The CloudStream Knowledge Server is currently unavailable.\n\n` +
+                                `Unable to process: ${toolName}\n\n` +
+                                `Please check:\n` +
+                                `1. Your internet connection\n` +
+                                `2. Knowledge Server status at ${this.config.apiUrl}/health\n` +
+                                `3. Your license key validity\n\n` +
+                                `Local skills and web search remain available.`,
+                        },
+                    ],
+                },
+            };
+        }
+        return this.errorResponse(request.id, -32003, 'Knowledge Server unavailable');
+    }
+    /**
+     * Create JSON-RPC error response
+     */
+    errorResponse(id, code, message) {
+        return {
+            jsonrpc: '2.0',
+            id,
+            error: { code, message },
+        };
+    }
+    /**
+     * Get current connection state
+     */
+    getConnectionState() {
+        return this.connectionState;
+    }
+    /**
+     * Get last error (for diagnostics)
+     */
+    getLastError() {
+        return this.lastError;
+    }
+}
+exports.HttpBridge = HttpBridge;

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Base error for bridge operations
+ */
+export declare class BridgeError extends Error {
+    readonly code: number;
+    readonly retryable: boolean;
+    constructor(message: string, code: number, retryable?: boolean);
+}
+/**
+ * Configuration error (missing env vars)
+ */
+export declare class ConfigurationError extends BridgeError {
+    constructor(message: string);
+}
+/**
+ * Network/server unavailable error
+ */
+export declare class ServerUnavailableError extends BridgeError {
+    constructor(message: string);
+}
+/**
+ * Authentication error
+ */
+export declare class AuthenticationError extends BridgeError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aAGlB,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,OAAO;gBAFlC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,OAAe;CAK7C;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,WAAW;gBACzC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;gBACtC,OAAO,GAAE,MAAyC;CAI/D"}

package/dist/errors.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthenticationError = exports.ServerUnavailableError = exports.ConfigurationError = exports.BridgeError = void 0;
+/**
+ * Base error for bridge operations
+ */
+class BridgeError extends Error {
+    code;
+    retryable;
+    constructor(message, code, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'BridgeError';
+    }
+}
+exports.BridgeError = BridgeError;
+/**
+ * Configuration error (missing env vars)
+ */
+class ConfigurationError extends BridgeError {
+    constructor(message) {
+        super(message, -32600, false); // Invalid Request
+        this.name = 'ConfigurationError';
+    }
+}
+exports.ConfigurationError = ConfigurationError;
+/**
+ * Network/server unavailable error
+ */
+class ServerUnavailableError extends BridgeError {
+    constructor(message) {
+        super(message, -32003, true); // Custom code for server unavailable
+        this.name = 'ServerUnavailableError';
+    }
+}
+exports.ServerUnavailableError = ServerUnavailableError;
+/**
+ * Authentication error
+ */
+class AuthenticationError extends BridgeError {
+    constructor(message = 'Invalid or expired license key') {
+        super(message, -32001, false); // Custom code for auth
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const bridge_1 = require("./bridge");
+const errors_1 = require("./errors");
+const readline = __importStar(require("readline"));
+/**
+ * CloudStream Knowledge MCP Client
+ *
+ * Bridges stdio (Claude Code) <-> HTTP (Knowledge Server)
+ *
+ * Protocol: JSON-RPC 2.0 over stdio
+ * - Reads JSON-RPC requests from stdin (one per line)
+ * - Writes JSON-RPC responses to stdout (one per line)
+ * - Logs debug info to stderr (doesn't interfere with protocol)
+ */
+/**
+ * Load configuration from environment variables
+ */
+function loadConfig() {
+    const licenseKey = process.env.CLOUDSTREAM_LICENSE;
+    const apiUrl = process.env.CLOUDSTREAM_API;
+    if (!licenseKey) {
+        throw new errors_1.ConfigurationError('CLOUDSTREAM_LICENSE environment variable is required. ' +
+            'Run "npx cloudstream-setup" to configure.');
+    }
+    if (!apiUrl) {
+        throw new errors_1.ConfigurationError('CLOUDSTREAM_API environment variable is required. ' +
+            'Run "npx cloudstream-setup" to configure.');
+    }
+    return {
+        licenseKey,
+        apiUrl,
+        timeout: parseInt(process.env.CLOUDSTREAM_TIMEOUT || '30000', 10),
+    };
+}
+/**
+ * Debug logging to stderr (doesn't interfere with JSON-RPC on stdout)
+ */
+function debug(message) {
+    if (process.env.CLOUDSTREAM_DEBUG === 'true') {
+        process.stderr.write(`[mcp-client] ${message}\n`);
+    }
+}
+/**
+ * Send JSON-RPC response to stdout
+ */
+function sendResponse(response) {
+    process.stdout.write(JSON.stringify(response) + '\n');
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    debug('Starting CloudStream Knowledge MCP Client');
+    // Load configuration
+    let config;
+    try {
+        config = loadConfig();
+        debug(`API URL: ${config.apiUrl}`);
+        debug(`Timeout: ${config.timeout}ms`);
+    }
+    catch (error) {
+        // Configuration error - send error response and exit
+        process.stderr.write(`Configuration error: ${error.message}\n`);
+        process.exit(1);
+    }
+    // Create HTTP bridge
+    const bridge = new bridge_1.HttpBridge(config);
+    // Set up readline interface for stdin
+    const rl = readline.createInterface({
+        input: process.stdin,
+        terminal: false,
+    });
+    // Process JSON-RPC requests line by line
+    rl.on('line', async (line) => {
+        debug(`Received: ${line.slice(0, 100)}...`);
+        if (!line.trim()) {
+            return; // Ignore empty lines
+        }
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            // Parse error
+            sendResponse({
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: -32700,
+                    message: 'Parse error: Invalid JSON',
+                },
+            });
+            return;
+        }
+        // Forward to bridge and send response
+        try {
+            const response = await bridge.forward(request);
+            debug(`Response for ${request.method}: ${bridge.getConnectionState()}`);
+            sendResponse(response);
+        }
+        catch (error) {
+            // Unexpected error - should be handled by bridge
+            debug(`Unexpected error: ${error.message}`);
+            sendResponse({
+                jsonrpc: '2.0',
+                id: request.id,
+                error: {
+                    code: -32603,
+                    message: `Internal error: ${error.message}`,
+                },
+            });
+        }
+    });
+    // Handle stdin close
+    rl.on('close', () => {
+        debug('stdin closed, exiting');
+        process.exit(0);
+    });
+    // Handle errors
+    process.on('uncaughtException', (error) => {
+        process.stderr.write(`Uncaught exception: ${error.message}\n`);
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        process.stderr.write(`Unhandled rejection: ${reason}\n`);
+        process.exit(1);
+    });
+    debug('Ready for requests');
+}
+// Run
+main().catch((error) => {
+    process.stderr.write(`Fatal error: ${error.message}\n`);
+    process.exit(1);
+});

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * JSON-RPC 2.0 Request
+ */
+export interface McpRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: {
+        name?: string;
+        arguments?: Record<string, unknown>;
+    };
+}
+/**
+ * JSON-RPC 2.0 Response
+ */
+export interface McpResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * Configuration from environment variables
+ */
+export interface BridgeConfig {
+    licenseKey: string;
+    apiUrl: string;
+    timeout: number;
+}
+/**
+ * Connection state for graceful degradation
+ */
+export type ConnectionState = 'connected' | 'connecting' | 'disconnected' | 'offline';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,WAAW,GACX,YAAY,GACZ,cAAc,GACd,SAAS,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cloudstreamsoftware/knowledge-mcp-client",
+  "version": "1.0.0",
+  "description": "MCP client bridge for CloudStream Knowledge Server - translates stdio to HTTP",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "knowledge-mcp-client": "./bin/knowledge-mcp-client.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cloudstream",
+    "zoho",
+    "deluge",
+    "claude-code"
+  ],
+  "author": "CloudStream Software LLC",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cloudstream-dev/flowstate.git",
+    "directory": "packages/knowledge-mcp-client"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/",
+    "bin/"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  }
+}