converse-mcp-server 1.0.1

package/.env.example

@@ -0,0 +1,177 @@
+# Zen MCP Server Environment Configuration
+# Copy this file to .env and fill in your values
+
+# API Keys - At least one is required
+#
+# IMPORTANT: Choose ONE approach:
+# - Native APIs (Gemini/OpenAI/XAI) for direct access
+# - DIAL for unified enterprise access
+# - OpenRouter for unified cloud access
+# Having multiple unified providers creates ambiguity about which serves each model.
+#
+# Option 1: Use native APIs (recommended for direct access)
+# Get your Gemini API key from: https://makersuite.google.com/app/apikey
+GEMINI_API_KEY=your_gemini_api_key_here
+
+# Get your OpenAI API key from: https://platform.openai.com/api-keys
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Get your X.AI API key from: https://console.x.ai/
+XAI_API_KEY=your_xai_api_key_here
+
+# Get your DIAL API key and configure host URL
+# DIAL provides unified access to multiple AI models through a single API
+DIAL_API_KEY=your_dial_api_key_here
+# DIAL_API_HOST=https://core.dialx.ai        # Optional: Base URL without /openai suffix (auto-appended)
+# DIAL_API_VERSION=2025-01-01-preview        # Optional: API version header for DIAL requests
+
+# Option 2: Use OpenRouter for access to multiple models through one API
+# Get your OpenRouter API key from: https://openrouter.ai/
+# If using OpenRouter, comment out the native API keys above
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+
+# Option 3: Use custom API endpoints for local models (Ollama, vLLM, LM Studio, etc.)
+# CUSTOM_API_URL=http://localhost:11434/v1  # Ollama example
+# CUSTOM_API_KEY=                                      # Empty for Ollama (no auth needed)
+# CUSTOM_MODEL_NAME=llama3.2                          # Default model name
+
+# Optional: Default model to use
+# Options: 'auto' (Claude picks best model), 'pro', 'flash', 'o3', 'o3-mini', 'o4-mini', 'o4-mini-high',
+#          'grok', 'opus-4', 'sonnet-4', or any DIAL model if DIAL is configured
+# When set to 'auto', Claude will select the best model for each task
+# Defaults to 'auto' if not specified
+DEFAULT_MODEL=auto
+
+# Optional: Default thinking mode for ThinkDeep tool
+# NOTE: Only applies to models that support extended thinking (e.g., Gemini 2.5 Pro)
+#       Flash models (2.0) will use system prompt engineering instead
+# Token consumption per mode:
+#   minimal: 128 tokens   - Quick analysis, fastest response
+#   low:     2,048 tokens - Light reasoning tasks  
+#   medium:  8,192 tokens - Balanced reasoning (good for most cases)
+#   high:    16,384 tokens - Complex analysis (recommended for thinkdeep)
+#   max:     32,768 tokens - Maximum reasoning depth, slowest but most thorough
+# Defaults to 'high' if not specified
+DEFAULT_THINKING_MODE_THINKDEEP=high
+
+# Optional: Model usage restrictions
+# Limit which models can be used from each provider for cost control, compliance, or standardization
+# Format: Comma-separated list of allowed model names (case-insensitive, whitespace tolerant)
+# Empty or unset = all models allowed (default behavior)
+# If you want to disable a provider entirely, don't set its API key
+#
+# Supported OpenAI models:
+#   - o3               (200K context, high reasoning)
+#   - o3-mini          (200K context, balanced)
+#   - o4-mini          (200K context, latest balanced, temperature=1.0 only)
+#   - o4-mini-high     (200K context, enhanced reasoning, temperature=1.0 only)
+#   - mini             (shorthand for o4-mini)
+#
+# Supported Google/Gemini models:
+#   - gemini-2.5-flash   (1M context, fast, supports thinking)
+#   - gemini-2.5-pro     (1M context, powerful, supports thinking)
+#   - flash                             (shorthand for gemini-2.5-flash)
+#   - pro                               (shorthand for gemini-2.5-pro)
+#
+# Supported X.AI GROK models:
+#   - grok-3          (131K context, advanced reasoning)
+#   - grok-3-fast     (131K context, higher performance but more expensive)
+#   - grok            (shorthand for grok-3)
+#   - grok3           (shorthand for grok-3)
+#   - grokfast        (shorthand for grok-3-fast)
+#
+# Supported DIAL models (when available in your DIAL deployment):
+#   - o3-2025-04-16   (200K context, latest O3 release)
+#   - o4-mini-2025-04-16 (200K context, latest O4 mini)
+#   - o3              (shorthand for o3-2025-04-16)
+#   - o4-mini         (shorthand for o4-mini-2025-04-16)
+#   - anthropic.claude-sonnet-4-20250514-v1:0 (200K context, Claude 4 Sonnet)
+#   - anthropic.claude-sonnet-4-20250514-v1:0-with-thinking (200K context, Claude 4 Sonnet with thinking mode)
+#   - anthropic.claude-opus-4-20250514-v1:0 (200K context, Claude 4 Opus)
+#   - anthropic.claude-opus-4-20250514-v1:0-with-thinking (200K context, Claude 4 Opus with thinking mode)
+#   - sonnet-4        (shorthand for Claude 4 Sonnet)
+#   - sonnet-4-thinking (shorthand for Claude 4 Sonnet with thinking)
+#   - opus-4          (shorthand for Claude 4 Opus)
+#   - opus-4-thinking (shorthand for Claude 4 Opus with thinking)
+#   - gemini-2.5-pro-preview-03-25-google-search (1M context, with Google Search)
+#   - gemini-2.5-pro-preview-05-06 (1M context, latest preview)
+#   - gemini-2.5-flash-preview-05-20 (1M context, latest flash preview)
+#   - gemini-2.5-pro  (shorthand for gemini-2.5-pro-preview-05-06)
+#   - gemini-2.5-pro-search (shorthand for gemini-2.5-pro-preview-03-25-google-search)
+#   - gemini-2.5-flash (shorthand for gemini-2.5-flash-preview-05-20)
+#
+# Examples:
+#   OPENAI_ALLOWED_MODELS=o3-mini,o4-mini,mini  # Only allow mini models (cost control)
+#   GOOGLE_ALLOWED_MODELS=flash                  # Only allow Flash (fast responses)
+#   XAI_ALLOWED_MODELS=grok-3                    # Only allow standard GROK (not fast variant)
+#   OPENAI_ALLOWED_MODELS=o4-mini                # Single model standardization
+#   GOOGLE_ALLOWED_MODELS=flash,pro              # Allow both Gemini models
+#   XAI_ALLOWED_MODELS=grok,grok-3-fast          # Allow both GROK variants
+#   DIAL_ALLOWED_MODELS=o3,o4-mini                       # Only allow O3/O4 models via DIAL
+#   DIAL_ALLOWED_MODELS=opus-4,sonnet-4                  # Only Claude 4 models (without thinking)
+#   DIAL_ALLOWED_MODELS=opus-4-thinking,sonnet-4-thinking # Only Claude 4 with thinking mode
+#   DIAL_ALLOWED_MODELS=gemini-2.5-pro,gemini-2.5-flash  # Only Gemini 2.5 models via DIAL
+#
+# Note: These restrictions apply even in 'auto' mode - Claude will only pick from allowed models
+# OPENAI_ALLOWED_MODELS=
+# GOOGLE_ALLOWED_MODELS=
+# XAI_ALLOWED_MODELS=
+# DIAL_ALLOWED_MODELS=
+
+# Optional: Custom model configuration file path
+# Override the default location of custom_models.json
+# CUSTOM_MODELS_CONFIG_PATH=/path/to/your/custom_models.json
+
+# Note: Conversations are stored in memory during the session
+
+# Optional: Conversation timeout (hours)
+# How long AI-to-AI conversation threads persist before expiring
+# Longer timeouts use more memory but allow resuming conversations later
+# Defaults to 3 hours if not specified
+CONVERSATION_TIMEOUT_HOURS=3
+
+# Optional: Max conversation turns
+# Maximum number of turns allowed in an AI-to-AI conversation thread
+# Each exchange (Claude asks, Gemini responds) counts as 2 turns
+# So 20 turns = 10 exchanges. Defaults to 20 if not specified
+MAX_CONVERSATION_TURNS=20
+
+# Optional: Logging level (DEBUG, INFO, WARNING, ERROR)
+# DEBUG: Shows detailed operational messages for troubleshooting (default)
+# INFO: Shows general operational messages
+# WARNING: Shows only warnings and errors
+# ERROR: Shows only errors
+LOG_LEVEL=DEBUG
+
+# Optional: Tool Selection
+# Comma-separated list of tools to disable. If not set, all tools are enabled.
+# Essential tools (version, listmodels) cannot be disabled.
+# Available tools: chat, thinkdeep, planner, consensus, codereview, precommit,
+#                  debug, docgen, analyze, refactor, tracer, testgen
+# Examples:
+# DISABLED_TOOLS=                    # All tools enabled (default)
+# DISABLED_TOOLS=debug,tracer        # Disable debug and tracer tools
+# DISABLED_TOOLS=planner,consensus   # Disable planning tools
+
+# Optional: Language/Locale for AI responses
+# When set, all AI tools will respond in the specified language
+# while maintaining their analytical capabilities
+# Examples: "fr-FR", "en-US", "zh-CN", "zh-TW", "ja-JP", "ko-KR", "es-ES"
+# Leave empty for default language (English)
+# LOCALE=fr-FR
+
+# ===========================================
+# Docker Configuration
+# ===========================================
+
+# Container name for Docker Compose
+# Used when running with docker-compose.yml
+COMPOSE_PROJECT_NAME=zen-mcp
+
+# Timezone for Docker containers
+# Ensures consistent time handling in containerized environments
+TZ=UTC
+
+# Maximum log file size (default: 10MB)
+# Applicable when using file-based logging
+LOG_MAX_SIZE=10MB

package/README.md

@@ -0,0 +1,425 @@
+# Converse MCP Server
+
+A simplified, functional Node.js implementation of an MCP (Model Context Protocol) server with chat and consensus tools. Built with modern Node.js practices and official SDKs for seamless AI provider integration.
+
+## 🚀 Quick Start
+
+### Option 1: Direct from GitHub (Recommended)
+
+```bash
+# Using npx (recommended)
+npx FallDownTheSystem/converse
+
+# Using pnpm dlx (alternative)
+pnpm dlx FallDownTheSystem/converse
+
+# Using yarn dlx (alternative)  
+yarn dlx FallDownTheSystem/converse
+```
+
+### Option 2: Clone and Install
+
+```bash
+# Clone the repository
+git clone https://github.com/FallDownTheSystem/converse.git
+cd converse
+
+# Install dependencies
+npm install
+
+# Copy and configure environment
+cp .env.example .env
+# Edit .env with your API keys
+
+# Start the server
+npm start
+```
+
+## 📋 Requirements
+
+- **Node.js**: >= 20.0.0 (LTS recommended)
+- **Package Manager**: npm, pnpm, or yarn
+- **API Keys**: At least one of OpenAI, Google, or X.AI
+
+## 🔑 Configuration
+
+### 1. Environment Variables
+
+Create a `.env` file in your project root:
+
+```bash
+# Required: At least one API key
+OPENAI_API_KEY=sk-proj-your_openai_key_here
+GOOGLE_API_KEY=your_google_api_key_here  
+XAI_API_KEY=xai-your_xai_key_here
+
+# Optional: Server configuration
+PORT=3000
+LOG_LEVEL=info
+MAX_MCP_OUTPUT_TOKENS=200000
+
+# Optional: Provider-specific settings
+GOOGLE_LOCATION=us-central1
+XAI_BASE_URL=https://api.x.ai/v1
+```
+
+### 2. Get API Keys
+
+| Provider | Where to Get | Example Format |
+|----------|-------------|----------------|
+| **OpenAI** | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | `sk-proj-...` |
+| **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
+
+Add to your MCP client configuration (e.g., Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "converse": {
+      "command": "npx",
+      "args": ["FallDownTheSystem/converse"],
+      "env": {
+        "OPENAI_API_KEY": "your_key_here",
+        "GOOGLE_API_KEY": "your_key_here",
+        "XAI_API_KEY": "your_key_here"
+      }
+    }
+  }
+}
+```
+
+## 🛠️ Available Tools
+
+### 1. Chat Tool
+
+General conversational AI with context and continuation support.
+
+```javascript
+// Example usage
+{
+  "prompt": "How should I structure the authentication module for this Express.js API?",
+  "model": "gemini-2.5-flash",
+  "files": ["/path/to/src/auth.js", "/path/to/config.json"],
+  "images": ["/path/to/architecture.png"],
+  "temperature": 0.5,
+  "reasoning_effort": "medium",
+  "use_websearch": false
+}
+```
+
+### 2. Consensus Tool
+
+Multi-provider parallel execution with cross-model feedback.
+
+```javascript
+// Example usage
+{
+  "prompt": "Should we use microservices or monolith architecture for our e-commerce platform?",
+  "models": [
+    {"model": "o3"},
+    {"model": "gemini-2.5-flash"},
+    {"model": "grok-4-0709"}
+  ],
+  "relevant_files": ["/path/to/requirements.md"],
+  "enable_cross_feedback": true,
+  "temperature": 0.2
+}
+```
+
+## 📊 Supported Models
+
+### OpenAI Models
+- **o3**: Strong reasoning (200K context)
+- **o3-mini**: Fast O3 variant (200K context)  
+- **o4-mini**: Latest reasoning model (200K context)
+- **gpt-4o**: Multimodal flagship (128K context)
+- **gpt-4o-mini**: Fast multimodal (128K context)
+
+### Google/Gemini Models
+- **gemini-2.5-flash** (alias: `flash`): Ultra-fast (1M context)
+- **gemini-2.5-pro** (alias: `pro`): Deep reasoning (1M context)
+- **gemini-2.0-flash**: Latest with experimental thinking
+
+### X.AI/Grok Models  
+- **grok-4-0709** (alias: `grok`): Latest advanced model (256K context)
+- **grok-3**: Previous generation (131K context)
+- **grok-3-fast**: Higher performance variant
+
+## 🚀 Development
+
+### Install from Source
+
+```bash
+# Clone and setup
+git clone https://github.com/FallDownTheSystem/converse.git
+cd converse
+npm install
+
+# Development with hot reload
+npm run dev
+
+# Run tests
+npm test
+
+# Run with specific log level
+LOG_LEVEL=debug npm run dev
+```
+
+### Scripts Available
+
+```bash
+# Server management
+npm start              # Start server (auto-kills existing server on port 3000)
+npm run start:clean    # Start server without killing existing processes
+npm run start:port     # Start server on port 3001 (avoids port conflicts)
+npm run dev            # Development with hot reload (auto-kills existing server)
+npm run dev:clean      # Development without killing existing processes
+npm run dev:port       # Development on port 3001 (avoids port conflicts)
+npm run dev:quiet      # Development with minimal logging
+npm run kill-server    # Kill any server running on port 3000
+
+# Testing
+npm test               # Run all tests
+npm run test:unit      # Unit tests only
+npm run test:integration # Integration tests
+npm run test:real-api  # Real API tests (requires keys)
+npm run test:coverage  # Coverage report
+
+# Code quality
+npm run lint           # Check code style
+npm run lint:fix       # Fix code style issues
+npm run format         # Format code with Prettier
+npm run validate       # Full validation (lint + test)
+
+# Utilities
+npm run build          # Build for production
+npm run debug          # Start with debugger
+npm run check-deps     # Check for outdated dependencies
+npm run kill-server    # Kill any server running on port 3000
+```
+
+### 💡 Development Notes
+
+**Port Management**: The server runs on port 3000 by default for HTTP transport. If you encounter "EADDRINUSE" errors:
+
+1. **Automatic cleanup**: `npm start` and `npm run dev` will automatically attempt to kill existing processes on port 3000
+2. **Manual cleanup**: Run `npm run kill-server` to manually free up port 3000  
+3. **Clean start**: Use `:clean` variants (`npm run start:clean`, `npm run dev:clean`) to skip auto-cleanup
+4. **Persistent issues**: If port conflicts persist, manually kill Node.js processes or restart your terminal
+
+**Troubleshooting EADDRINUSE errors**:
+```bash
+# Try manual cleanup first
+npm run kill-server
+
+# Or use a different port
+PORT=3001 npm start
+
+# Or use stdio transport instead
+npm start -- --transport=stdio
+```
+
+**Transport Modes**: 
+- **HTTP Transport** (default): `http://localhost:3000/mcp` - Better for development and debugging
+- **Stdio Transport**: Use `--transport=stdio` or set `MCP_TRANSPORT=stdio` for traditional stdio communication
+
+### Testing with Real APIs
+
+```bash
+# Set up your API keys in .env first
+OPENAI_API_KEY=sk-proj-...
+GOOGLE_API_KEY=AIzaSy...
+XAI_API_KEY=xai-...
+
+# Run real API tests
+npm run test:real-api
+
+# Run comprehensive integration tests
+node final-integration-test.js
+
+# Validate server functionality
+npm run validate
+```
+
+### ✅ Validation Steps
+
+After installation, verify everything is working:
+
+```bash
+# 1. Quick server test (should show startup message)
+npm start
+
+# 2. Run basic functionality tests
+npm test
+
+# 3. Test real API connectivity (requires API keys)
+npm run test:real-api
+
+# 4. Comprehensive validation
+node final-integration-test.js
+```
+
+**Expected Results:**
+- Server starts without errors on port 3000
+- All unit tests pass
+- Real API tests connect successfully (if keys configured)
+- Integration tests achieve >70% success rate
+
+## 📁 Project Structure
+
+```
+converse/
+├── src/
+│   ├── index.js              # Main server entry point
+│   ├── config.js             # Configuration management
+│   ├── router.js             # Central request dispatcher
+│   ├── continuationStore.js  # State management
+│   ├── systemPrompts.js      # Tool system prompts
+│   ├── providers/            # AI provider implementations
+│   │   ├── index.js          # Provider registry
+│   │   ├── openai.js         # OpenAI provider
+│   │   ├── xai.js            # XAI provider
+│   │   └── google.js         # Google provider
+│   ├── tools/                # MCP tool implementations
+│   │   ├── index.js          # Tool registry
+│   │   ├── chat.js           # Chat tool
+│   │   └── consensus.js      # Consensus tool
+│   └── utils/                # Utility modules
+│       ├── contextProcessor.js # File/image processing
+│       ├── errorHandler.js   # Error handling
+│       └── logger.js         # Logging utilities
+├── tests/                    # Comprehensive test suite
+├── docs/                     # API and architecture docs
+└── package.json              # Dependencies and scripts
+```
+
+## 🔧 Configuration Options
+
+### Environment Variables
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `PORT` | Server port | `3000` | `3000` |
+| `LOG_LEVEL` | Logging level | `info` | `debug`, `info`, `error` |
+| `MAX_MCP_OUTPUT_TOKENS` | Token response limit | `25000` | `200000` |
+| `GOOGLE_LOCATION` | Google API region | `us-central1` | `us-central1` |
+| `XAI_BASE_URL` | XAI API endpoint | `https://api.x.ai/v1` | Custom endpoint |
+
+### Model Selection
+
+Use `"auto"` for automatic model selection, or specify exact models:
+
+```javascript
+// Auto-selection (recommended)
+{ "model": "auto" }
+
+// Specific models
+{ "model": "gemini-2.5-flash" }
+{ "model": "o3" }
+{ "model": "grok-4-0709" }
+
+// Using aliases
+{ "model": "flash" }    // -> gemini-2.5-flash
+{ "model": "pro" }      // -> gemini-2.5-pro
+{ "model": "grok" }     // -> grok-4-0709
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Server won't start:**
+```bash
+# Check Node.js version
+node --version  # Should be >= 20.0.0
+
+# Check for port conflicts
+PORT=3001 npm start
+```
+
+**API key errors:**
+```bash
+# Verify your .env file format
+cat .env
+
+# Test API keys
+npm run test:real-api
+```
+
+**Module import errors:**
+```bash
+# Clear cache and reinstall
+npm run clean
+```
+
+### Debug Mode
+
+```bash
+# Enable debug logging
+LOG_LEVEL=debug npm run dev
+
+# Start with debugger
+npm run debug
+
+# Trace all operations
+LOG_LEVEL=trace npm run dev
+```
+
+## 📚 Documentation
+
+- **API Reference**: [docs/API.md](docs/API.md)
+- **Architecture Guide**: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- **Integration Examples**: [docs/EXAMPLES.md](docs/EXAMPLES.md)
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes
+4. Run tests: `npm run validate`
+5. Commit changes: `git commit -m 'Add amazing feature'`
+6. Push to branch: `git push origin feature/amazing-feature`
+7. Open a Pull Request
+
+### Development Setup
+
+```bash
+# Fork and clone your fork
+git clone https://github.com/yourusername/converse.git
+cd converse
+
+# Install dependencies
+npm install
+
+# Create feature branch
+git checkout -b feature/your-feature
+
+# Make changes and test
+npm run validate
+
+# Commit and push
+git add .
+git commit -m "Description of changes"
+git push origin feature/your-feature
+```
+
+## 🙏 Acknowledgments
+
+This MCP Server was inspired by and builds upon the excellent work from [BeehiveInnovations/zen-mcp-server](https://github.com/BeehiveInnovations/zen-mcp-server). We're grateful for their pioneering implementation and innovative approach to MCP server development.
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- **GitHub**: https://github.com/FallDownTheSystem/converse
+- **Issues**: https://github.com/FallDownTheSystem/converse/issues
+- **NPM Package**: https://www.npmjs.com/package/converse-mcp-server
+
+---
+
+**Built with ❤️ using Node.js and modern AI APIs**

package/bin/converse.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+/**
+ * Converse MCP Server - CLI Entry Point
+ * 
+ * This script allows the MCP server to be run via npx/pnpm dlx for easy installation and execution.
+ */
+
+import { fileURLToPath, pathToFileURL } from 'url';
+import { dirname, join } from 'path';
+import { createRequire } from 'module';
+
+// Get the directory of this script
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Get the project root (parent of bin directory)
+const projectRoot = dirname(__dirname);
+
+// Import and start the server
+try {
+  const indexPath = join(projectRoot, 'src/index.js');
+  const { startServer } = await import(pathToFileURL(indexPath).href);
+  
+  console.log('🚀 Starting Converse MCP Server...');
+  console.log(`📁 Project root: ${projectRoot}`);
+  
+  await startServer();
+} 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');
+  }
+  
+  process.exit(1);
+}