@1mcp/agent 0.1.0 → 0.4.0

package/README.md

@@ -4,67 +4,207 @@ A unified Model Context Protocol server implementation that aggregates multiple
 
 ## Overview
 
-1MCP (One MCP) is designed to simplify the way you work with AI coding assistants. Instead of configuring multiple MCP servers for different clients (Cursor, Roo Code, Claude, etc.), 1MCP provides a single, unified server that:
+1MCP (One MCP) is designed to simplify the way you work with AI assistants. Instead of configuring multiple MCP servers for different clients (Claude Desktop, Cherry Studio, Cursor, Roo Code, Claude, etc.), 1MCP provides a single, unified server that:
 
 - Aggregates multiple MCP servers into one unified interface
 - Reduces system resource usage by eliminating redundant server instances
-- Simplifies configuration management across different AI coding assistants
+- Simplifies configuration management across different AI assistants
 - Provides a standardized way for AI models to interact with external tools and resources
+- Supports dynamic configuration reloading without server restart
+- Handles graceful shutdown and resource cleanup
 
-The implementation includes:
+## Quick Start
 
-- Express-based HTTP server with SSE (Server-Sent Events) support
-- Winston-based logging system with MCP protocol integration
-- Support for MCP capabilities and notifications
-- Smart request routing and capability aggregation
+To enable Cursor to use existing MCP servers already configured in Claude Desktop, follow these steps:
 
-## Server Implementation
-
-The server is implemented using:
-
-- Express.js for HTTP handling
-- Server-Sent Events (SSE) for real-time communication
-- MCP SDK for protocol implementation
-
-### Server Configuration
-
-The server runs on port 3050 by default and exposes the following endpoints:
-
-- `/sse` - SSE endpoint for establishing connections
-- `/messages` - Endpoint for receiving messages from clients
-
-## MCP Logging Implementation
-
-This project includes a Winston transport for the Model Context Protocol (MCP) logging protocol. The implementation allows logs from the agent to be sent to MCP clients using the standard MCP logging notification format.
+1. Run the 1MCP server with the Claude Desktop config file:
+```bash
+npx -y @1mcp/agent --config ~/Library/Application\ Support/Claude/claude_desktop_config.json
+```
 
-### Features
+2. Add the 1MCP server to your Cursor config file (`~/.cursor/mcp.json`):
+```json
+{
+    "mcpServers": {
+        "1mcp": {
+            "type": "http",
+            "url": "http://localhost:3050/sse"
+        }
+    }
+}
+```
 
-- Seamless integration with Winston logger
-- Automatic mapping of Winston log levels to MCP log levels
-- Support for structured logging data
-- Configurable logger name
-- Connection-aware logging (only sends logs when clients are connected)
-- Sensitive data sanitization
+3. Enjoy it!
 
 ## Usage
 
 You can run the server directly using `npx`:
 
 ```bash
-# Run with HTTP/SSE transport (default)
+# Basic usage (starts server with SSE transport)
 npx -y @1mcp/agent
 
-# Run with stdio transport
+# Use existing Claude Desktop config
+npx -y @1mcp/agent --config ~/Library/Application\ Support/Claude/claude_desktop_config.json
+
+# Use stdio transport instead of SSE
 npx -y @1mcp/agent --transport stdio
 
-# Show help
+# Show all available options
 npx -y @1mcp/agent --help
 ```
 
 Available options:
-- `--transport, -t`: Transport type to use (choices: "stdio", "http", default: "http")
+- `--transport, -t`: Choose transport type ("stdio" or "sse", default: "sse")
+- `--config, -c`: Use a specific config file
+- `--port, -P`: Change SSE port (default: 3050)
+- `--host, -H`: Change SSE host (default: localhost)
+- `--tags, -g`: Filter servers by tags (see Tags section below)
 - `--help, -h`: Show help
 
+### Understanding Tags
+
+Tags help you control which MCP servers are available to different clients. Think of tags as labels that describe what each server can do.
+
+#### How to Use Tags
+
+1. **In your server config**: Add tags to each server to describe its capabilities
+```json
+{
+  "mcpServers": {
+    "web-server": {
+      "command": "uvx",
+      "args": ["mcp-server-fetch"],
+      "tags": ["network", "web"],
+      "disabled": false
+    },
+    "file-server": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Downloads"],
+      "tags": ["filesystem"],
+      "disabled": false
+    }
+  }
+}
+```
+
+2. **When starting 1MCP in stdio mode**: You can filter servers by tags
+```bash
+# Only start servers with the "network" tag
+npx -y @1mcp/agent --transport stdio --tags "network"
+
+# Start servers with either "network" or "filesystem" tags
+npx -y @1mcp/agent --transport stdio --tags "network,filesystem"
+```
+
+3. **When using SSE transport**: Clients can request servers with specific tags
+```json
+{
+    "mcpServers": {
+        "1mcp": {
+            "type": "http",
+            "url": "http://localhost:3050/sse?tags=network"  // Only connect to network-capable servers
+        }
+    }
+}
+```
+
+Example tags:
+- `network`: For servers that make web requests
+- `filesystem`: For servers that handle file operations
+- `memory`: For servers that provide memory/storage
+- `shell`: For servers that run shell commands
+- `db`: For servers that handle database operations
+
+## Configuration
+
+### Global Configuration
+
+The server automatically manages configuration in a global location:
+
+- macOS/Linux: `~/.config/1mcp/mcp.json`
+- Windows: `%APPDATA%/1mcp/mcp.json`
+
+### Configuration File Format
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-fetch": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-fetch"
+      ],
+      "disabled": false
+    },
+    "server-memory": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-memory"
+      ],
+      "disabled": false
+    }
+  }
+}
+```
+
+## How It Works
+
+### System Architecture
+
+```mermaid
+graph TB
+    subgraph "AI Assistants"
+        A1[Claude Desktop]
+        A2[Cursor]
+        A3[Cherry Studio]
+        A4[Roo Code]
+    end
+
+    subgraph "1MCP Server"
+        MCP[1MCP Agent]
+    end
+
+    subgraph "MCP Servers"
+        S1[Server 1]
+        S2[Server 2]
+        S3[Server 3]
+    end
+
+    A1 -->|sse| MCP
+    A2 -->|sse| MCP
+    A3 -->|sse| MCP
+    A4 -->|sse| MCP
+
+    MCP --> |sse| S1
+    MCP --> |stdio| S2
+    MCP --> |stdio| S3
+```
+
+### Request Flow
+
+```mermaid
+sequenceDiagram
+    participant Client as AI Assistant
+    participant 1MCP as 1MCP Server
+    participant MCP as MCP Servers
+
+    Client->>1MCP: Send MCP Request
+    activate 1MCP
+
+    1MCP->>1MCP: Validate Request
+    1MCP->>1MCP: Load Config
+    1MCP->>MCP: Forward Request
+    activate MCP
+
+    MCP-->>1MCP: Response
+    deactivate MCP
+
+    1MCP-->>Client: Forward Response
+    deactivate 1MCP
+```
+
 ## Development
 
 Install dependencies:
@@ -87,23 +227,6 @@ Run the server:
 pnpm dev
 ```
 
-## Installation
-
-To use with Claude Desktop, add the server config:
-
-On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "agent": {
-      "command": "/path/to/agent/build/index.js"
-    }
-  }
-}
-```
-
 ### Debugging
 
 Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:

package/build/capabilities/capabilityManager.js

@@ -1,23 +1,21 @@
-import logger from '../logger.js';
+import logger from '../logger/logger.js';
 import { setupClientToServerNotifications, setupServerToClientNotifications, } from '../handlers/notificationHandlers.js';
 import { registerRequestHandlers } from '../handlers/requestHandlers.js';
 /**
  * Collects capabilities from all clients and registers them with the server
  * @param clients Record of client instances
  * @param server The MCP server instance
+ * @param tags Array of tags to filter clients by
  * @returns The combined server capabilities
  */
-export async function collectAndRegisterCapabilities(clients, server) {
+export async function setupCapabilities(clients, serverInfo) {
     // Collect capabilities from all clients
     const capabilities = collectCapabilities(clients);
     // Set up notification handlers
-    setupClientToServerNotifications(clients, server);
-    setupServerToClientNotifications(clients, server);
-    // Register capabilities with the server
-    logger.info(`Registering capabilities: ${JSON.stringify(capabilities)}`);
-    server.registerCapabilities(capabilities);
+    setupClientToServerNotifications(clients, serverInfo);
+    setupServerToClientNotifications(clients, serverInfo);
     // Register request handlers based on capabilities
-    registerRequestHandlers(clients, server, capabilities);
+    registerRequestHandlers(clients, serverInfo, capabilities);
     return capabilities;
 }
 /**
@@ -27,9 +25,9 @@ export async function collectAndRegisterCapabilities(clients, server) {
  */
 function collectCapabilities(clients) {
     let capabilities = {};
-    for (const [name, client] of Object.entries(clients)) {
+    for (const [name, clientInfo] of Object.entries(clients)) {
         try {
-            const clientCapabilities = client.getServerCapabilities() || {};
+            const clientCapabilities = clientInfo.client.getServerCapabilities() || {};
             logger.debug(`Capabilities from ${name}: ${JSON.stringify(clientCapabilities)}`);
             capabilities = { ...capabilities, ...clientCapabilities };
         }

package/build/client.js

@@ -1,8 +1,9 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-export default async function createClient(transport) {
+import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from './constants.js';
+export default async function createClient() {
     const client = new Client({
-        name: '1mcp',
-        version: '1.0.0',
+        name: MCP_SERVER_NAME,
+        version: MCP_SERVER_VERSION,
     }, {
         capabilities: {
             experimental: {},

package/build/clients/clientManager.js

@@ -1,7 +1,9 @@
 import createClient from '../client.js';
-import logger from '../logger.js';
-import { CONNECTION_RETRY } from '../constants.js';
-import { ClientConnectionError, ClientNotFoundError, withErrorHandling } from '../utils/errorHandling.js';
+import logger from '../logger/logger.js';
+import { CONNECTION_RETRY, MCP_SERVER_NAME } from '../constants.js';
+import { withErrorHandling } from '../utils/errorHandling.js';
+import { ClientConnectionError, ClientNotFoundError } from '../utils/errorTypes.js';
+import { ClientStatus } from '../types.js';
 /**
  * Creates client instances for all transports with retry logic
  * @param transports Record of transport instances
@@ -12,18 +14,30 @@ export async function createClients(transports) {
     for (const [name, transport] of Object.entries(transports)) {
         logger.info(`Creating client for ${name}`);
         try {
-            const client = await createClient(transport);
+            const client = await createClient();
             // Connect with retry logic
             await connectWithRetry(client, transport, name);
-            clients[name] = client;
+            clients[name] = {
+                name,
+                transport,
+                client,
+                status: ClientStatus.Connected,
+                lastConnected: new Date(),
+            };
             logger.info(`Client created for ${name}`);
         }
         catch (error) {
             logger.error(`Failed to create client for ${name}: ${error}`);
-            // We continue with other clients even if one fails
+            clients[name] = {
+                name,
+                transport,
+                client: await createClient(),
+                status: ClientStatus.Error,
+                lastError: error instanceof Error ? error : new Error(String(error)),
+            };
         }
     }
-    return clients;
+    return Object.freeze(clients);
 }
 /**
  * Connects a client to its transport with retry logic
@@ -36,7 +50,11 @@ async function connectWithRetry(client, transport, name) {
     for (let i = 0; i < CONNECTION_RETRY.MAX_ATTEMPTS; i++) {
         try {
             await client.connect(transport);
-            logger.info(`Successfully connected to ${name}`);
+            const sv = await client.getServerVersion();
+            if (sv?.name === MCP_SERVER_NAME) {
+                throw new ClientConnectionError(name, new Error('Aborted to prevent circular dependency'));
+            }
+            logger.info(`Successfully connected to ${name} with server ${sv?.name} version ${sv?.version}`);
             return;
         }
         catch (error) {
@@ -67,13 +85,30 @@ export function getClient(clients, clientName) {
     return client;
 }
 /**
- * Executes a client operation with error handling
+ * Executes a client operation with error handling and timeout
  * @param clients Record of client instances
  * @param clientName The name of the client to use
  * @param operation The operation to execute
+ * @param options Operation options including timeout and retry settings
  * @returns The result of the operation
  */
-export async function executeClientOperation(clients, clientName, operation) {
-    const client = getClient(clients, clientName);
-    return withErrorHandling(async () => operation(client), `Error executing operation on client ${clientName}`)();
+export async function executeClientOperation(clients, clientName, operation, options = {}) {
+    const clientInfo = getClient(clients, clientName);
+    const { retryCount = 0, retryDelay = 1000 } = options;
+    return withErrorHandling(async () => {
+        let lastError;
+        for (let i = 0; i <= retryCount; i++) {
+            try {
+                return await operation(clientInfo);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if (i < retryCount) {
+                    logger.info(`Retrying operation ${operation.name} on client ${clientName} after ${retryDelay}ms`);
+                    await new Promise((resolve) => setTimeout(resolve, retryDelay));
+                }
+            }
+        }
+        throw lastError;
+    }, `Error executing operation on client ${clientName}`)();
 }

package/build/config/configManager.js

@@ -1,8 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 import { EventEmitter } from 'events';
-import { MCP_CONFIG_FILE } from '../constants.js';
-import logger from '../logger.js';
+import { getGlobalConfigPath, getGlobalConfigDir, DEFAULT_CONFIG } from '../constants.js';
+import logger from '../logger/logger.js';
 /**
  * Configuration change event types
  */
@@ -20,22 +20,44 @@ export class ConfigManager extends EventEmitter {
     configFilePath;
     /**
      * Private constructor to enforce singleton pattern
+     * @param configFilePath - Optional path to the config file. If not provided, uses global config path
      */
-    constructor() {
+    constructor(configFilePath) {
         super();
-        this.configFilePath = path.resolve(process.cwd(), MCP_CONFIG_FILE);
+        this.configFilePath = configFilePath || getGlobalConfigPath();
+        this.ensureConfigExists();
         this.loadConfig();
     }
     /**
-     * Get the singleton instance of the ConfigManager
-     * @returns The ConfigManager instance
+     * Get the singleton instance of ConfigManager
+     * @param configFilePath - Optional path to the config file
      */
-    static getInstance() {
+    static getInstance(configFilePath) {
         if (!ConfigManager.instance) {
-            ConfigManager.instance = new ConfigManager();
+            ConfigManager.instance = new ConfigManager(configFilePath);
         }
         return ConfigManager.instance;
     }
+    /**
+     * Ensure the config directory and file exist
+     */
+    ensureConfigExists() {
+        try {
+            const configDir = getGlobalConfigDir();
+            if (!fs.existsSync(configDir)) {
+                fs.mkdirSync(configDir, { recursive: true });
+                logger.info(`Created config directory: ${configDir}`);
+            }
+            if (!fs.existsSync(this.configFilePath)) {
+                fs.writeFileSync(this.configFilePath, JSON.stringify(DEFAULT_CONFIG, null, 2));
+                logger.info(`Created default config file: ${this.configFilePath}`);
+            }
+        }
+        catch (error) {
+            logger.error(`Failed to ensure config exists: ${error}`);
+            throw error;
+        }
+    }
     /**
      * Load the configuration from the config file
      */
@@ -105,4 +127,4 @@ export class ConfigManager extends EventEmitter {
         return { ...this.transportConfig };
     }
 }
-export default ConfigManager.getInstance();
+export default ConfigManager;

package/build/config/configManager.test.js

@@ -0,0 +1,106 @@
+import fs from 'fs';
+import path from 'path';
+// Mock modules before importing ConfigManager
+jest.mock('fs', () => ({
+    existsSync: jest.fn(),
+    mkdirSync: jest.fn(),
+    writeFileSync: jest.fn(),
+    readFileSync: jest.fn(),
+    watch: jest.fn(() => ({ close: jest.fn() })),
+}));
+const mockLogger = {
+    error: jest.fn(),
+    warn: jest.fn(),
+    info: jest.fn(),
+    debug: jest.fn(),
+    level: 'info',
+    transports: [],
+};
+jest.doMock('../logger/logger.js', () => ({
+    __esModule: true,
+    default: mockLogger,
+}));
+// Mock constants
+jest.doMock('../constants.js', () => ({
+    __esModule: true,
+    DEFAULT_CONFIG: { mcpServers: {} },
+    getGlobalConfigPath: jest.fn(),
+    getGlobalConfigDir: jest.fn().mockReturnValue('/test'),
+}));
+// Import after mocks are set up
+import { ConfigManager, ConfigChangeEvent } from './configManager.js';
+import { DEFAULT_CONFIG } from '../constants.js';
+describe('ConfigManager', () => {
+    const testConfigPath = '/test/config.json';
+    beforeEach(() => {
+        // Reset all mocks
+        jest.clearAllMocks();
+        // Reset singleton instance
+        ConfigManager.instance = undefined;
+        // Default mock implementations
+        fs.existsSync.mockReturnValue(true);
+        fs.readFileSync.mockReturnValue(JSON.stringify({ mcpServers: {} }));
+    });
+    describe('getInstance', () => {
+        it('should create singleton instance', () => {
+            const instance1 = ConfigManager.getInstance(testConfigPath);
+            const instance2 = ConfigManager.getInstance(testConfigPath);
+            expect(instance1).toBe(instance2);
+        });
+        it('should use provided config path', () => {
+            const instance = ConfigManager.getInstance(testConfigPath);
+            expect(instance.configFilePath).toBe(testConfigPath);
+        });
+    });
+    describe('ensureConfigExists', () => {
+        it('should create config directory and file if they do not exist', () => {
+            fs.existsSync
+                .mockReturnValueOnce(false) // Directory doesn't exist
+                .mockReturnValueOnce(false); // File doesn't exist
+            ConfigManager.getInstance(testConfigPath);
+            expect(fs.mkdirSync).toHaveBeenCalledWith(path.dirname(testConfigPath), { recursive: true });
+            expect(fs.writeFileSync).toHaveBeenCalledWith(testConfigPath, JSON.stringify(DEFAULT_CONFIG, null, 2));
+        });
+    });
+    describe('config watching', () => {
+        it('should start and stop watching config file', () => {
+            const instance = ConfigManager.getInstance(testConfigPath);
+            instance.startWatching();
+            expect(fs.watch).toHaveBeenCalledWith(testConfigPath, expect.any(Function));
+            instance.stopWatching();
+            expect(instance['configWatcher']).toBeNull();
+        });
+        it('should reload config on file change', () => {
+            const instance = ConfigManager.getInstance(testConfigPath);
+            const mockWatcher = { close: jest.fn() };
+            let watchCallback = () => { };
+            fs.watch.mockImplementation((path, callback) => {
+                watchCallback = callback;
+                return mockWatcher;
+            });
+            instance.startWatching();
+            // Setup spy for event emission
+            const emitSpy = jest.spyOn(instance, 'emit');
+            // Mock new config data
+            const newConfig = { mcpServers: { test: { url: 'test-url' } } };
+            fs.readFileSync.mockReturnValueOnce(JSON.stringify(newConfig));
+            // Simulate file change
+            watchCallback('change', path.basename(testConfigPath));
+            expect(emitSpy).toHaveBeenCalledWith(ConfigChangeEvent.TRANSPORT_CONFIG_CHANGED, newConfig.mcpServers);
+        });
+    });
+    describe('getTransportConfig', () => {
+        it('should return copy of transport config', () => {
+            const testConfig = {
+                mcpServers: {
+                    test: { url: 'test-url' },
+                },
+            };
+            fs.readFileSync.mockReturnValueOnce(JSON.stringify(testConfig));
+            const instance = ConfigManager.getInstance(testConfigPath);
+            const config = instance.getTransportConfig();
+            expect(config).toEqual(testConfig.mcpServers);
+            expect(config).not.toBe(instance['transportConfig']); // Should be a copy
+        });
+    });
+});

package/build/config/transportConfig.js

@@ -1,38 +1,53 @@
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
-import logger from '../logger.js';
-import configManager from './configManager.js';
-/**
- * Loads transport configurations from the MCP config file
- * @returns Record of transport configurations
- */
-export function loadTransportConfig() {
-    return configManager.getTransportConfig();
-}
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { ZodError } from 'zod';
+import logger from '../logger/logger.js';
+import { transportConfigSchema } from '../types.js';
 /**
  * Creates transport instances from configuration
  * @returns Record of transport instances
  */
-export function createTransports() {
+export function createTransports(config) {
     const transports = {};
-    const mcpConfig = loadTransportConfig();
-    for (const [name, transport] of Object.entries(mcpConfig)) {
-        if (transport.disabled) {
+    for (const [name, params] of Object.entries(config)) {
+        if (params.disabled) {
             logger.debug(`Skipping disabled transport: ${name}`);
             continue;
         }
         try {
-            // Merge environment variables
-            transport.env = {
-                ...Object.fromEntries(Object.entries(process.env)
-                    .filter(([_, v]) => v !== undefined)
-                    .map(([k, v]) => [k, String(v)])),
-                ...transport.env,
-            };
-            transports[name] = new StdioClientTransport(transport);
-            logger.debug(`Created transport for ${name}`);
+            const validatedTransport = transportConfigSchema.parse(params);
+            if (validatedTransport.type === 'sse' || validatedTransport.type === 'http') {
+                if (!validatedTransport.url) {
+                    throw new Error(`URL is required for SSE transport: ${name}`);
+                }
+                const transport = new SSEClientTransport(new URL(validatedTransport.url), {
+                    requestInit: {
+                        headers: validatedTransport.headers,
+                    },
+                });
+                transport.timeout = validatedTransport.timeout;
+                transport.tags = validatedTransport.tags;
+                transports[name] = transport;
+            }
+            else {
+                if (!validatedTransport.command) {
+                    throw new Error(`Command is required for stdio transport: ${name}`);
+                }
+                const transport = new StdioClientTransport(validatedTransport);
+                transport.timeout = validatedTransport.timeout;
+                transport.tags = validatedTransport.tags;
+                transports[name] = transport;
+            }
+            logger.debug(`Created transport: ${name}`);
         }
         catch (error) {
-            logger.error(`Failed to create transport for ${name}: ${error}`);
+            if (error instanceof ZodError) {
+                logger.error(`Invalid transport configuration for ${name}:`, error.errors);
+            }
+            else {
+                logger.error(`Error creating transport ${name}:`, error);
+            }
+            throw error;
         }
     }
     return transports;