converse-mcp-server 1.1.1 → 1.2.0

package/README.md

@@ -71,9 +71,11 @@ XAI_BASE_URL=https://api.x.ai/v1
 | **Google** | [makersuite.google.com/app/apikey](https://makersuite.google.com/app/apikey) | `AIzaSy...` |
 | **X.AI** | [console.x.ai](https://console.x.ai/) | `xai-...` |
 
-### 3. MCP Client Configuration
+### 3. Installing in Claude Code or Claude Desktop
 
-Add to your MCP client configuration (e.g., Claude Desktop):
+There are several ways to add the Converse MCP Server to Claude:
+
+#### Option A: Using NPX (Recommended)
 
 ```json
 {
@@ -84,13 +86,95 @@ Add to your MCP client configuration (e.g., Claude Desktop):
       "env": {
         "OPENAI_API_KEY": "your_key_here",
         "GOOGLE_API_KEY": "your_key_here",
-        "XAI_API_KEY": "your_key_here"
+        "XAI_API_KEY": "your_key_here",
+        "MAX_MCP_OUTPUT_TOKENS": "200000"
+      }
+    }
+  }
+}
+```
+
+#### Option B: Using NPX with stdio transport
+
+```json
+{
+  "mcpServers": {
+    "converse": {
+      "command": "npx",
+      "args": ["FallDownTheSystem/converse", "--transport", "stdio"],
+      "env": {
+        "OPENAI_API_KEY": "your_key_here",
+        "GOOGLE_API_KEY": "your_key_here",
+        "XAI_API_KEY": "your_key_here",
+        "MAX_MCP_OUTPUT_TOKENS": "200000"
       }
     }
   }
 }
 ```
 
+#### Option C: Direct Node.js execution
+
+```json
+{
+  "mcpServers": {
+    "converse": {
+      "command": "node",
+      "args": [
+        "C:\\Users\\YourUsername\\Documents\\Projects\\converse\\src\\index.js",
+        "--transport",
+        "stdio"
+      ],
+      "env": {
+        "OPENAI_API_KEY": "your_key_here",
+        "GOOGLE_API_KEY": "your_key_here",
+        "XAI_API_KEY": "your_key_here",
+        "MAX_MCP_OUTPUT_TOKENS": "200000"
+      }
+    }
+  }
+}
+```
+
+#### Option D: Using environment variable for transport
+
+```json
+{
+  "mcpServers": {
+    "converse": {
+      "command": "npx",
+      "args": ["FallDownTheSystem/converse"],
+      "env": {
+        "MCP_TRANSPORT": "stdio",
+        "OPENAI_API_KEY": "your_key_here",
+        "GOOGLE_API_KEY": "your_key_here",
+        "XAI_API_KEY": "your_key_here",
+        "MAX_MCP_OUTPUT_TOKENS": "200000"
+      }
+    }
+  }
+}
+```
+
+#### Installation Steps
+
+1. **For Claude Code**: 
+   - Open the command palette (Ctrl/Cmd + Shift + P)
+   - Run "Claude Code: Edit MCP Settings"
+   - Add one of the configurations above
+
+2. **For Claude Desktop**:
+   - Navigate to Settings → Developer → MCP Servers
+   - Click "Add Server" and paste one of the configurations above
+
+3. **Manual Configuration**:
+   - The configuration file is typically located at:
+     - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+     - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+     - Linux: `~/.config/Claude/claude_desktop_config.json`
+
+For more detailed instructions, see the [official MCP configuration guide](https://docs.anthropic.com/en/docs/claude-code/mcp#configure-mcp-servers).
+
 ## 🛠️ Available Tools
 
 ### 1. Chat Tool
@@ -129,6 +213,23 @@ Multi-provider parallel execution with cross-model feedback.
 }
 ```
 
+## 📚 Help & Documentation
+
+The Converse MCP Server provides built-in help through:
+
+### Help Prompt
+Access comprehensive documentation directly in Claude:
+- `/converse:help` - Full documentation
+- `/converse:help tools` - Tool-specific help
+- `/converse:help models` - Model information
+- `/converse:help parameters` - Configuration details
+- `/converse:help examples` - Usage examples
+
+### Help Resource
+Programmatic access to documentation:
+- Resource URI: `converse://help`
+- Includes all documentation plus current server version
+
 ## 📊 Supported Models
 
 ### OpenAI Models

package/bin/converse.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * Converse MCP Server - CLI Entry Point
@@ -20,26 +20,13 @@ const projectRoot = dirname(__dirname);
 // Import and start the server
 try {
   const indexPath = join(projectRoot, 'src/index.js');
-  const { startServer } = await import(pathToFileURL(indexPath).href);
+  const { main } = await import(pathToFileURL(indexPath).href);
   
-  console.log('🚀 Starting Converse MCP Server...');
-  console.log(`📁 Project root: ${projectRoot}`);
-  
-  await startServer();
+  // The main function will handle all logging appropriately based on transport type
+  await main();
 } catch (error) {
-  console.error('❌ Failed to start Converse MCP Server:', error.message);
-  
-  if (error.code === 'ERR_MODULE_NOT_FOUND') {
-    console.error('\n💡 Troubleshooting:');
-    console.error('   1. Ensure you have Node.js >= 20.0.0');
-    console.error('   2. Try: npm install (if running from source)');
-    console.error('   3. Check that all dependencies are installed');
-  } else if (error.message.includes('API key')) {
-    console.error('\n🔑 API Key Configuration:');
-    console.error('   1. Create a .env file with your API keys');
-    console.error('   2. Set environment variables in your MCP client');
-    console.error('   3. See README.md for detailed setup instructions');
-  }
-  
+  // For stdio transport, we must not output anything to stdout
+  // For http transport, this will be logged by the error handler in main
+  // Just exit with error code
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "converse-mcp-server",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Converse MCP Server - Converse with other LLMs with chat and consensus tools",
   "type": "module",
   "main": "src/index.js",

package/src/config.js

@@ -45,25 +45,25 @@ const CONFIG_SCHEMA = {
   // Transport configuration
   transport: {
     MCP_TRANSPORT: { type: 'string', default: 'http', description: 'MCP transport type (http or stdio)' },
-    
+
     // HTTP server settings
     HTTP_PORT: { type: 'number', default: 3157, description: 'HTTP server port' },
     HTTP_HOST: { type: 'string', default: 'localhost', description: 'HTTP server host' },
     HTTP_REQUEST_TIMEOUT: { type: 'number', default: 300000, description: 'HTTP request timeout in milliseconds (5 minutes)' },
     HTTP_MAX_REQUEST_SIZE: { type: 'string', default: '10mb', description: 'Maximum HTTP request body size' },
-    
+
     // Session management
     HTTP_SESSION_TIMEOUT: { type: 'number', default: 1800000, description: 'Session timeout in milliseconds (30 minutes)' },
     HTTP_SESSION_CLEANUP_INTERVAL: { type: 'number', default: 300000, description: 'Session cleanup interval in milliseconds (5 minutes)' },
     HTTP_MAX_CONCURRENT_SESSIONS: { type: 'number', default: 100, description: 'Maximum concurrent sessions' },
-    
+
     // CORS configuration
     HTTP_ENABLE_CORS: { type: 'boolean', default: true, description: 'Enable CORS for HTTP transport' },
     HTTP_CORS_ORIGINS: { type: 'string', default: '*', description: 'CORS allowed origins (comma-separated)' },
     HTTP_CORS_METHODS: { type: 'string', default: 'GET,POST,DELETE,OPTIONS', description: 'CORS allowed methods' },
     HTTP_CORS_HEADERS: { type: 'string', default: 'Content-Type,mcp-session-id,Authorization', description: 'CORS allowed headers' },
     HTTP_CORS_CREDENTIALS: { type: 'boolean', default: false, description: 'CORS allow credentials' },
-    
+
     // Security settings
     HTTP_DNS_REBINDING_PROTECTION: { type: 'boolean', default: false, description: 'Enable DNS rebinding protection' },
     HTTP_ALLOWED_HOSTS: { type: 'string', default: '127.0.0.1,localhost', description: 'Allowed hosts for DNS rebinding protection (comma-separated)' },
@@ -163,7 +163,7 @@ function validateApiKeyFormat(provider, apiKey) {
 export async function loadConfig() {
   const configLogger = logger.operation('loadConfig');
   configLogger.debug('Starting configuration loading');
-  
+
   const config = {
     server: {},
     transport: {},
@@ -193,7 +193,7 @@ export async function loadConfig() {
     for (const [key, schema] of Object.entries(CONFIG_SCHEMA.transport)) {
       try {
         const value = validateEnvVar(key, process.env[key], schema);
-        
+
         if (key === 'MCP_TRANSPORT') {
           config.transport.mcptransport = value;
         } else if (key.startsWith('HTTP_')) {
@@ -286,7 +286,7 @@ export async function loadConfig() {
  */
 export function getHttpTransportConfig(config) {
   const transport = config.transport;
-  
+
   // Parse comma-separated values
   const corsOrigins = transport.corsorigins === '*' ? '*' : transport.corsorigins?.split(',').map(o => o.trim()) || ['*'];
   const corsMethods = transport.corsmethods?.split(',').map(m => m.trim()) || ['GET', 'POST', 'DELETE', 'OPTIONS'];
@@ -299,12 +299,12 @@ export function getHttpTransportConfig(config) {
     host: transport.host || 'localhost',
     requestTimeout: transport.requesttimeout || 300000,
     maxRequestSize: transport.maxrequestsize || '10mb',
-    
+
     // Session management
     sessionTimeout: transport.sessiontimeout || 1800000,
     sessionCleanupInterval: transport.sessioncleanupinterval || 300000,
     maxConcurrentSessions: transport.maxconcurrentsessions || 100,
-    
+
     // CORS configuration
     enableCors: transport.enablecors !== false,
     corsOptions: {
@@ -314,10 +314,10 @@ export function getHttpTransportConfig(config) {
       credentials: transport.corscredentials || false,
       exposedHeaders: ['Mcp-Session-Id'],
     },
-    
+
     // Security settings
     enableDnsRebindingProtection: transport.dnsrebindingprotection || false,
-    allowedHosts: allowedHosts,
+    allowedHosts,
     rateLimitEnabled: transport.ratelimitenabled || false,
     rateLimitWindow: transport.ratelimitwindow || 900000,
     rateLimitMaxRequests: transport.ratelimitmaxrequests || 1000,
@@ -396,36 +396,36 @@ export async function validateRuntimeConfig(config) {
     // Validate HTTP transport configuration
     if (config.transport.mcptransport === 'http') {
       const httpConfig = getHttpTransportConfig(config);
-      
+
       // Validate HTTP port
       if (httpConfig.port < 1 || httpConfig.port > 65535) {
         throw new ConfigurationError(`Invalid HTTP_PORT: ${httpConfig.port}. Must be between 1 and 65535`);
       }
-      
+
       // Validate timeouts
       if (httpConfig.requestTimeout < 1000) {
         throw new ConfigurationError(`Invalid HTTP_REQUEST_TIMEOUT: ${httpConfig.requestTimeout}. Must be at least 1000ms`);
       }
-      
+
       if (httpConfig.sessionTimeout < 60000) {
         throw new ConfigurationError(`Invalid HTTP_SESSION_TIMEOUT: ${httpConfig.sessionTimeout}. Must be at least 60000ms (1 minute)`);
       }
-      
+
       if (httpConfig.sessionCleanupInterval < 10000) {
         throw new ConfigurationError(`Invalid HTTP_SESSION_CLEANUP_INTERVAL: ${httpConfig.sessionCleanupInterval}. Must be at least 10000ms (10 seconds)`);
       }
-      
+
       // Validate max concurrent sessions
       if (httpConfig.maxConcurrentSessions < 1 || httpConfig.maxConcurrentSessions > 10000) {
         throw new ConfigurationError(`Invalid HTTP_MAX_CONCURRENT_SESSIONS: ${httpConfig.maxConcurrentSessions}. Must be between 1 and 10000`);
       }
-      
+
       // Validate rate limiting
       if (httpConfig.rateLimitEnabled) {
         if (httpConfig.rateLimitWindow < 1000) {
           throw new ConfigurationError(`Invalid HTTP_RATE_LIMIT_WINDOW: ${httpConfig.rateLimitWindow}. Must be at least 1000ms`);
         }
-        
+
         if (httpConfig.rateLimitMaxRequests < 1) {
           throw new ConfigurationError(`Invalid HTTP_RATE_LIMIT_MAX_REQUESTS: ${httpConfig.rateLimitMaxRequests}. Must be at least 1`);
         }
@@ -461,7 +461,7 @@ function logConfigurationSummary(config) {
   if (process.stdin.isTTY === false || process.env.NODE_ENV === 'test') {
     return;
   }
-  
+
   const availableProviders = getAvailableProviders(config);
 
   // Log configuration summary
@@ -491,6 +491,8 @@ export function getMcpClientConfig(config) {
     version: config.mcp.version,
     capabilities: {
       tools: {},
+      prompts: {},
+      resources: {},
     },
     environment: config.environment.nodeEnv,
     providers: getAvailableProviders(config),

package/src/index.js

@@ -7,6 +7,7 @@
  * with chat and consensus tools using modern Node.js practices.
  */
 
+import { fileURLToPath } from 'url';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { loadConfig, validateRuntimeConfig, getMcpClientConfig, getHttpTransportConfig } from './config.js';
@@ -52,7 +53,7 @@ Examples:
 function getTransportType() {
   // Check command line arguments
   const args = process.argv.slice(2);
-  
+
   // Support --transport=value format
   const transportEqualArg = args.find(arg => arg.startsWith('--transport='));
   if (transportEqualArg) {
@@ -61,7 +62,7 @@ function getTransportType() {
       return transport;
     }
   }
-  
+
   // Support --transport value format
   const transportIndex = args.findIndex(arg => arg === '--transport');
   if (transportIndex >= 0 && transportIndex + 1 < args.length) {
@@ -93,7 +94,7 @@ async function main() {
 
   // Determine transport type first to configure logging appropriately
   const transportType = getTransportType();
-  
+
   // Set environment variable early for stdio transport to suppress console output
   if (transportType === 'stdio') {
     process.env.MCP_TRANSPORT = 'stdio';
@@ -106,7 +107,7 @@ async function main() {
   }
 
   const serverTimer = startTimer('server-startup', 'server');
-  
+
   try {
     logger.info('Starting Converse MCP Server');
 
@@ -116,11 +117,11 @@ async function main() {
 
     // Get MCP client configuration
     const mcpConfig = getMcpClientConfig(config);
-    
+
     logger.info('Using transport type', { data: { transport: transportType } });
 
-    logger.debug('Creating MCP server instance', { 
-      data: { name: mcpConfig.name, version: mcpConfig.version } 
+    logger.debug('Creating MCP server instance', {
+      data: { name: mcpConfig.name, version: mcpConfig.version }
     });
 
     // Create MCP server with configuration
@@ -143,15 +144,15 @@ async function main() {
 
       await httpTransport.start();
       const status = httpTransport.getStatus();
-      
+
       const startupTime = serverTimer('completed');
-      logger.info('Converse MCP Server started successfully with HTTP transport', { 
-        data: { 
+      logger.info('Converse MCP Server started successfully with HTTP transport', {
+        data: {
           startupTime: `${startupTime}ms`,
           endpoint: `http://${status.host}:${status.port}/mcp`,
           host: status.host,
           port: status.port
-        } 
+        }
       });
 
       // Store reference for shutdown
@@ -162,13 +163,13 @@ async function main() {
       await server.connect(transport);
 
       const startupTime = serverTimer('completed');
-      logger.info('Converse MCP Server started successfully with stdio transport', { 
-        data: { startupTime: `${startupTime}ms` } 
+      logger.info('Converse MCP Server started successfully with stdio transport', {
+        data: { startupTime: `${startupTime}ms` }
       });
     }
   } catch (error) {
     serverTimer('failed');
-    
+
     if (error instanceof ConfigurationError) {
       logger.error('Configuration error during startup', { error });
       debugError('Configuration Error:');
@@ -190,7 +191,7 @@ async function main() {
 async function gracefulShutdown(signal) {
   logger.info(`Received ${signal}, shutting down gracefully`);
   debugError('Shutting down Converse MCP Server...');
-  
+
   if (process.httpTransport) {
     try {
       await process.httpTransport.stop();
@@ -199,7 +200,7 @@ async function gracefulShutdown(signal) {
       logger.error('Error stopping HTTP transport', { error });
     }
   }
-  
+
   process.exit(0);
 }
 
@@ -213,16 +214,26 @@ process.on('uncaughtException', (error) => {
 });
 
 process.on('unhandledRejection', (reason, promise) => {
-  logger.error('Unhandled promise rejection', { 
-    error: reason, 
-    data: { promise: promise.toString() } 
+  logger.error('Unhandled promise rejection', {
+    error: reason,
+    data: { promise: promise.toString() }
   });
   debugError('Unhandled promise rejection:', reason);
   process.exit(1);
 });
 
-main().catch((error) => {
-  logger.error('Fatal error in main', { error });
-  debugError('Fatal error:', error);
-  process.exit(1);
-});
+// Export the main function for use in bin/converse.js
+export { main };
+
+// Check if this module is the main entry point
+// This works better across platforms and Node.js versions
+const isMainModule = import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` ||
+                     process.argv[1] === fileURLToPath(import.meta.url);
+
+if (isMainModule) {
+  main().catch((error) => {
+    logger.error('Fatal error in main', { error });
+    debugError('Fatal error:', error);
+    process.exit(1);
+  });
+}