converse-mcp-server 2.3.0 → 2.4.0

package/README.md

@@ -1,738 +1,771 @@
-# Converse MCP Server
-
-[![npm version](https://img.shields.io/npm/v/converse-mcp-server.svg)](https://www.npmjs.com/package/converse-mcp-server)
-
-An MCP (Model Context Protocol) server that lets Claude talk to other AI models. Use it to chat with models from OpenAI, Google, Anthropic, X.AI, Mistral, DeepSeek, or OpenRouter. You can either talk to one model at a time or get multiple models to weigh in on complex decisions.
-
-## 📋 Requirements
-
-- **Node.js**: Version 20 or higher
-- **Package Manager**: npm (or pnpm/yarn)
-- **API Keys**: At least one from any supported provider
-
-## 🚀 Quick Start
-
-### Step 1: Get Your API Keys
-
-You need at least one API key from these providers:
-
-| Provider | Where to Get | Example Format |
-|----------|-------------|----------------|
-| **OpenAI** | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) | `sk-proj-...` |
-| **Google/Gemini** | [makersuite.google.com/app/apikey](https://makersuite.google.com/app/apikey) | `AIzaSy...` |
-| **X.AI** | [console.x.ai](https://console.x.ai/) | `xai-...` |
-| **Anthropic** | [console.anthropic.com](https://console.anthropic.com/) | `sk-ant-...` |
-| **Mistral** | [console.mistral.ai](https://console.mistral.ai/) | `wfBMkWL0...` |
-| **DeepSeek** | [platform.deepseek.com](https://platform.deepseek.com/) | `sk-...` |
-| **OpenRouter** | [openrouter.ai/keys](https://openrouter.ai/keys) | `sk-or-...` |
-| **Codex** | ChatGPT login (system-wide) | Local agentic assistant |
-
-**Note:** Codex uses your ChatGPT login (not an API key). If you have an active ChatGPT session, Codex will work automatically. For headless/server deployments, set `CODEX_API_KEY` in your environment.
-
-### Step 2: Add to Claude Code or Claude Desktop
-
-#### For Claude Code (Recommended)
-```bash
-# Add the server with your API keys
-claude mcp add converse \
-  -e OPENAI_API_KEY=your_key_here \
-  -e GEMINI_API_KEY=your_key_here \
-  -e XAI_API_KEY=your_key_here \
-  -e ANTHROPIC_API_KEY=your_key_here \
-  -e MISTRAL_API_KEY=your_key_here \
-  -e DEEPSEEK_API_KEY=your_key_here \
-  -e OPENROUTER_API_KEY=your_key_here \
-  -e ENABLE_RESPONSE_SUMMARIZATION=true \
-  -e SUMMARIZATION_MODEL=gpt-5 \
-  -s user \
-  npx converse-mcp-server
-```
-
-#### For Claude Desktop
-
-Add this configuration to your Claude Desktop settings:
-
-```json
-{
-  "mcpServers": {
-    "converse": {
-      "command": "npx",
-      "args": ["converse-mcp-server"],
-      "env": {
-        "OPENAI_API_KEY": "your_key_here",
-        "GEMINI_API_KEY": "your_key_here",
-        "XAI_API_KEY": "your_key_here",
-        "ANTHROPIC_API_KEY": "your_key_here",
-        "MISTRAL_API_KEY": "your_key_here",
-        "DEEPSEEK_API_KEY": "your_key_here",
-        "OPENROUTER_API_KEY": "your_key_here",
-        "ENABLE_RESPONSE_SUMMARIZATION": "true",
-        "SUMMARIZATION_MODEL": "gpt-5"
-      }
-    }
-  }
-}
-```
-
-**Windows Troubleshooting**: If `npx converse-mcp-server` doesn't work on Windows, try:
-```json
-{
-  "command": "cmd",
-  "args": ["/c", "npx", "converse-mcp-server"],
-  "env": {
-    "ENABLE_RESPONSE_SUMMARIZATION": "true",
-    "SUMMARIZATION_MODEL": "gpt-5"
-    // ... add your API keys here
-  }
-}
-```
-
-### Step 3: Start Using Converse
-
-Once installed, you can:
-
-- **Chat with a specific model**: Ask Claude to use the chat tool with your preferred model
-- **Get consensus**: Ask Claude to use the consensus tool when you need multiple perspectives
-- **Run tasks in background**: Use `async: true` for long-running operations that you can check later
-- **Monitor progress**: Use the check_status tool to monitor async operations with AI-generated summaries
-- **Cancel jobs**: Use the cancel_job tool to stop running operations
-- **Smart summaries**: Get auto-generated titles and summaries for better context understanding
-- **Get help**: Type `/converse:help` in Claude
-
-## 🛠️ Available Tools
-
-### 1. Chat Tool
-
-Talk to any AI model with support for files, images, and conversation history. The tool automatically routes your request to the right provider based on the model name. When AI summarization is enabled, generates smart titles and summaries for better context understanding.
-
-```javascript
-// Synchronous execution (default)
-{
-  "prompt": "How should I structure the authentication module for this Express.js API?",
-  "model": "gemini-2.5-flash",         // Routes to Google
-  "files": ["/path/to/src/auth.js", "/path/to/config.json"],
-  "images": ["/path/to/architecture.png"],
-  "temperature": 0.5,
-  "reasoning_effort": "medium",
-  "use_websearch": false
-}
-
-// Asynchronous execution (for long-running tasks)
-{
-  "prompt": "Analyze this large codebase and provide optimization recommendations",
-  "model": "gpt-5",
-  "files": ["/path/to/large-project"],
-  "async": true,           // Enables background processing
-  "continuation_id": "my-analysis-task"  // Optional: custom ID for tracking
-}
-
-// Codex - Agentic coding assistant with local file access
-{
-  "prompt": "Analyze this codebase and suggest improvements",
-  "model": "codex",
-  "files": ["/path/to/your/project"],
-  "async": true  // Recommended for Codex (responses take 6-20+ seconds)
-}
-```
-
-**Codex Notes:**
-- Uses thread-based sessions (context persists with `continuation_id`)
-- Responses typically take 6-20 seconds (complex tasks may take minutes)
-- Accesses files directly from your working directory
-- Configure sandbox mode via `CODEX_SANDBOX_MODE` environment variable
-
-### 2. Consensus Tool
-
-Get multiple AI models to analyze the same question simultaneously. Each model can see and respond to the others' answers, creating a rich discussion.
-
-```javascript
-// Synchronous consensus (default)
-{
-  "prompt": "Should we use microservices or monolith architecture for our e-commerce platform?",
-  "models": ["gpt-5", "gemini-2.5-flash", "grok-4"],
-  "files": ["/path/to/requirements.md"],
-  "enable_cross_feedback": true,
-  "temperature": 0.2
-}
-
-// Asynchronous consensus (for complex analysis)
-{
-  "prompt": "Review our system architecture and provide comprehensive recommendations",
-  "models": ["gpt-5", "gemini-2.5-pro", "claude-sonnet-4"],
-  "files": ["/path/to/architecture-docs"],
-  "async": true,          // Run in background
-  "enable_cross_feedback": true
-}
-```
-
-### 3. Check Status Tool
-
-Monitor the progress and retrieve results from asynchronous operations. When AI summarization is enabled, provides intelligent summaries of ongoing and completed tasks.
-
-```javascript
-// Check status of a specific job
-{
-  "continuation_id": "my-analysis-task"
-}
-
-// List recent jobs (shows last 10)
-// With summarization enabled, displays titles and final summaries
-{}
-
-// Get full conversation history for completed job
-{
-  "continuation_id": "my-analysis-task",
-  "full_history": true
-}
-```
-
-### 4. Cancel Job Tool
-
-Cancel running asynchronous operations when needed.
-
-```javascript
-// Cancel a running job
-{
-  "continuation_id": "my-analysis-task"
-}
-```
-
-## 🤖 AI Summarization Feature
-
-When enabled, the server automatically generates intelligent titles and summaries for better context understanding:
-
-- **Automatic Title Generation**: Creates descriptive titles (up to 60 chars) for each request
-- **Streaming Summaries**: Status check returns an up-to-date summary of the progress based on the partially streamed response  
-- **Final Summaries**: Concise 1-2 sentence summaries of completed responses
-- **Smart Status Display**: Enhanced check_status tool shows titles and summaries in job listings
-- **Persistent Context**: Summaries are stored with async jobs for better progress tracking
-
-**Configuration**:
-```bash
-# Enable in your environment
-ENABLE_RESPONSE_SUMMARIZATION=true    # Default: false  
-SUMMARIZATION_MODEL=gpt-5-nano        # Default: gpt-5-nano
-```
-
-**Benefits**:
-- Quickly understand what each async job is doing without reading full responses
-- Better context when reviewing multiple ongoing operations
-- Improved job management with at-a-glance understanding of task progress
-- Graceful fallback to text snippets when summarization is disabled or fails
-
-## 📊 Supported Models
-
-### OpenAI Models
-- **gpt-5**: Latest flagship model (400K context, 128K output) - Superior reasoning, code generation, and analysis
-- **gpt-5-mini**: Faster, cost-efficient GPT-5 (400K context, 128K output) - Well-defined tasks, precise prompts
-- **gpt-5-nano**: Fastest, most cost-efficient GPT-5 (400K context, 128K output) - Summarization, classification
-- **gpt-5-pro**: Most advanced reasoning model (400K context, 272K output) - Hardest problems, extended compute time (EXPENSIVE)
-- **o3**: Strong reasoning (200K context)
-- **o3-mini**: Fast O3 variant (200K context)
-- **o3-pro**: Professional-grade reasoning (200K context) - EXTREMELY EXPENSIVE
-- **o3-deep-research**: Deep research model (200K context) - 30-90 min runtime
-- **o4-mini**: Latest reasoning model (200K context)
-- **o4-mini-deep-research**: Fast deep research model (200K context) - 15-60 min runtime
-- **gpt-4.1**: Advanced reasoning (1M context)
-- **gpt-4o**: Multimodal flagship (128K context)
-- **gpt-4o-mini**: Fast multimodal (128K context)
-
-### Google/Gemini Models
-
-**API Key Options**:
-- **GEMINI_API_KEY**: For Gemini Developer API (recommended)
-- **GOOGLE_API_KEY**: Alternative name (GEMINI_API_KEY takes priority)
-- **Vertex AI**: Use `GOOGLE_GENAI_USE_VERTEXAI=true` with project/location settings
-- **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
-- **gemini-2.0-flash-lite**: Lightweight fast model, text-only
-
-### X.AI/Grok Models  
-- **grok-4-0709** (aliases: `grok`, `grok-4`): Latest advanced model (256K context)
-- **grok-code-fast-1**: Speedy and economical reasoning model that excels at agentic coding (256K context)
-
-### Anthropic Models
-- **claude-opus-4.1**: Highest intelligence with extended thinking (200K context)
-- **claude-sonnet-4**: Balanced performance with extended thinking (200K context)
-- **claude-3.7-sonnet**: Enhanced 3.x generation with thinking (200K context)
-- **claude-3.5-sonnet**: Fast and intelligent (200K context)
-- **claude-3.5-haiku**: Fastest model for simple queries (200K context)
-
-### Mistral Models
-- **magistral-medium**: Frontier-class reasoning model (40K context)
-- **magistral-small**: Small reasoning model (40K context)
-- **mistral-medium-3**: Frontier-class multimodal model (128K context)
-
-### DeepSeek Models
-- **deepseek-chat**: Strong MoE model with 671B/37B parameters (64K context)
-- **deepseek-reasoner**: Advanced reasoning model with CoT (64K context)
-
-### OpenRouter Models
-- **qwen3-235b-thinking**: Qwen3 with enhanced reasoning (32K context)
-- **qwen3-coder**: Specialized for programming tasks (32K context)
-- **kimi-k2**: Moonshot AI Kimi K2 with extended context (200K context)
-
-### Codex Models
-- **codex**: OpenAI Codex agentic coding assistant
-  - Thread-based sessions with persistent context
-  - Direct filesystem access from working directory
-  - Typical response time: 6-20 seconds (longer for complex tasks)
-  - Requires ChatGPT login or CODEX_API_KEY
-  - See [Configuration](#configuration) for sandbox and approval settings
-
-## 📚 Help & Documentation
-
-### Built-in Help
-Type these commands directly in Claude:
-- `/converse:help` - Full documentation
-- `/converse:help tools` - Tool-specific help (includes async features)
-- `/converse:help models` - Model information
-- `/converse:help parameters` - Configuration details
-- `/converse:help examples` - Usage examples (sync and async)
-- `/converse:help async` - Async execution guide
-
-### Additional Resources
-- **API Reference**: [docs/API.md](docs/API.md)
-- **Architecture Guide**: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
-- **Integration Examples**: [docs/EXAMPLES.md](docs/EXAMPLES.md)
-
-## ⚙️ Configuration
-
-### 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
-GEMINI_API_KEY=your_gemini_api_key_here  # Or GOOGLE_API_KEY (GEMINI_API_KEY takes priority)  
-XAI_API_KEY=xai-your_xai_key_here
-ANTHROPIC_API_KEY=sk-ant-your_anthropic_key_here
-MISTRAL_API_KEY=your_mistral_key_here
-DEEPSEEK_API_KEY=your_deepseek_key_here
-OPENROUTER_API_KEY=sk-or-your_openrouter_key_here
-
-# Optional: Server configuration
-PORT=3157
-LOG_LEVEL=info
-
-# Optional: AI Summarization (Enhanced async status display)
-ENABLE_RESPONSE_SUMMARIZATION=true    # Enable AI-generated titles and summaries
-SUMMARIZATION_MODEL=gpt-5-nano        # Model to use for summarization (default: gpt-5-nano)
-
-# Optional: OpenRouter configuration
-OPENROUTER_REFERER=https://github.com/FallDownTheSystem/converse
-OPENROUTER_TITLE=Converse
-OPENROUTER_DYNAMIC_MODELS=true
-
-# Optional: Codex configuration
-CODEX_API_KEY=your_codex_api_key_here       # Optional if ChatGPT login available
-CODEX_SANDBOX_MODE=read-only                 # read-only (default), workspace-write, danger-full-access
-CODEX_SKIP_GIT_CHECK=true                    # true (default), false
-CODEX_APPROVAL_POLICY=never                  # never (default), untrusted, on-failure, on-request
-CODEX_DEFAULT_MODEL=gpt-5-codex              # Default: gpt-5-codex
-```
-
-### Configuration Options
-
-#### Server Environment Variables (.env file)
-| Variable | Description | Default | Example |
-|----------|-------------|---------|---------|
-| `PORT` | Server port | `3157` | `3157` |
-| `LOG_LEVEL` | Logging level | `info` | `debug`, `info`, `error` |
-
-#### Claude Code Environment Variables (System/Global)
-These must be set in your system environment or when launching Claude Code, NOT in the project .env file:
-
-| Variable | Description | Default | Example |
-|----------|-------------|---------|---------|
-| `MAX_MCP_OUTPUT_TOKENS` | Token response limit | `25000` | `200000` |
-| `MCP_TOOL_TIMEOUT` | Tool execution timeout (ms) | `120000` | `5400000` (90 min for deep research) |
-
-```bash
-# Example: Set globally before starting Claude Code
-export MAX_MCP_OUTPUT_TOKENS=200000
-export MCP_TOOL_TIMEOUT=5400000  # 90 minutes for deep research models
-claude  # Then start Claude Code
-```
-
-### Model Selection
-
-Use `"auto"` for automatic model selection, or specify exact models:
-
-```javascript
-// Auto-selection (recommended)
-"auto"
-
-// Specific models
-"gemini-2.5-flash"
-"gpt-5"
-"grok-4-0709"
-
-// Using aliases
-"flash"    // -> gemini-2.5-flash
-"pro"      // -> gemini-2.5-pro
-"grok"     // -> grok-4-0709
-"grok-4"   // -> grok-4-0709
-```
-
-**Auto Model Behavior:**
-- **Chat Tool**: Selects the first available provider and uses its default model
-- **Consensus Tool**: When using `["auto"]`, automatically expands to the first 3 available providers
-
-Provider priority order (requires corresponding API key):
-  1. OpenAI (`gpt-5`)
-  2. Google (`gemini-2.5-pro`)
-  3. XAI (`grok-4`)
-  4. Anthropic (`claude-sonnet-4-20250514`)
-  5. Mistral (`magistral-medium-2506`)
-  6. DeepSeek (`deepseek-reasoner`)
-  7. OpenRouter (`qwen/qwen3-coder`)
-  
-The system will use the first 3 providers that have valid API keys configured. This enables automatic multi-model consensus without manually specifying models.
-
-### Advanced Configuration
-
-#### Manual Installation Options
-
-##### Option A: Direct Node.js execution
-
-If you've cloned the repository locally:
-
-```json
-{
-  "mcpServers": {
-    "converse": {
-      "command": "node",
-      "args": [
-        "C:\\Users\\YourUsername\\Documents\\Projects\\converse\\src\\index.js"
-      ],
-      "env": {
-        "OPENAI_API_KEY": "your_key_here",
-        "GEMINI_API_KEY": "your_key_here",
-        "XAI_API_KEY": "your_key_here",
-        "ANTHROPIC_API_KEY": "your_key_here",
-        "MISTRAL_API_KEY": "your_key_here",
-        "DEEPSEEK_API_KEY": "your_key_here",
-        "OPENROUTER_API_KEY": "your_key_here"
-      }
-    }
-  }
-}
-```
-
-##### Option B: Local HTTP Development (Advanced)
-
-For local development with HTTP transport (optional, for debugging):
-
-1. **First, start the server manually with HTTP transport**:
-   ```bash
-   # In a terminal, navigate to the project directory
-   cd converse
-   MCP_TRANSPORT=http npm run dev  # Starts server on http://localhost:3157/mcp
-   ```
-
-2. **Then configure Claude to connect to it**:
-   ```json
-   {
-     "mcpServers": {
-       "converse-local": {
-         "url": "http://localhost:3157/mcp"
-       }
-     }
-   }
-   ```
-
-**Important**: HTTP transport requires the server to be running before Claude can connect to it. Keep the terminal with the server open while using Claude.
-
-### Configuration File Locations
-
-The Claude 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).
-
-## 💻 Running Standalone (Without Claude)
-
-You can run the server directly without Claude for testing or development:
-
-```bash
-# Quick run (no installation needed)
-npx converse-mcp-server
-
-# Alternative package managers
-pnpm dlx converse-mcp-server
-yarn dlx converse-mcp-server
-```
-
-For development setup, see the [Development](#-development) section below.
-
-## 🐛 Troubleshooting
-
-### Common Issues
-
-**Server won't start:**
-- Check Node.js version: `node --version` (needs v20+)
-- Try a different port: `PORT=3001 npm start`
-
-**API key errors:**
-- Verify your .env file has the correct format
-- Test with: `npm run test:real-api`
-
-**Module import errors:**
-- 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
-```
-
-## 🔧 Development
-
-### Getting Started
-
-```bash
-# Clone the repository
-git clone https://github.com/FallDownTheSystem/converse.git
-cd converse
-npm install
-
-# Copy environment file and add your API keys
-cp .env.example .env
-
-# Start development server
-npm run dev
-```
-
-### Scripts Available
-
-```bash
-# Server management
-npm start              # Start server (auto-kills existing server on port 3157)
-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 3157
-
-# Testing
-npm test               # Run all tests
-npm run test:unit      # Unit tests only
-npm run test:integration # Integration tests
-npm run test:e2e       # End-to-end tests (requires API keys)
-
-# Integration test subcategories
-npm run test:integration:mcp        # MCP protocol tests
-npm run test:integration:tools      # Tool integration tests
-npm run test:integration:providers  # Provider integration tests
-npm run test:integration:performance # Performance tests
-npm run test:integration:general    # General integration tests
-
-# Other test categories
-npm run test:mcp-client # MCP client tests (HTTP-based)
-npm run test:providers # Provider unit tests
-npm run test:tools     # Tool tests
-npm run test:coverage  # Coverage report
-npm run test:watch     # Run tests in watch mode
-
-# 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 3157
-```
-
-### Development Notes
-
-**Port conflicts**: The server uses port 3157 by default. If you get an "EADDRINUSE" error:
-- Run `npm run kill-server` to free the port
-- Or use a different port: `PORT=3001 npm start`
-
-**Transport Modes**: 
-- **Stdio** (default): Works automatically with Claude
-- **HTTP**: Better for debugging, requires manual start (`MCP_TRANSPORT=http npm run dev`)
-
-### Testing with Real APIs
-
-After setting up your API keys in `.env`:
-
-```bash
-# Run end-to-end tests
-npm run test:e2e
-
-# Test specific providers
-npm run test:integration:providers
-
-# Full validation
-npm run validate
-```
-
-### Validation Steps
-
-After installation, run these tests to verify everything works:
-
-```bash
-npm start           # Should show startup message
-npm test            # Should pass all unit tests
-npm run validate    # Full validation suite
-```
-
-### 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
-│   │   ├── interface.js      # Unified provider interface
-│   │   ├── openai.js         # OpenAI provider
-│   │   ├── xai.js            # XAI provider
-│   │   ├── google.js         # Google provider
-│   │   ├── anthropic.js      # Anthropic provider
-│   │   ├── mistral.js        # Mistral AI provider
-│   │   ├── deepseek.js       # DeepSeek provider
-│   │   ├── openrouter.js     # OpenRouter provider
-│   │   └── openai-compatible.js # Base for OpenAI-compatible APIs
-│   ├── 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
-```
-
-## 📦 Publishing to NPM
-
-> **Note**: This section is for maintainers. The package is already published as `converse-mcp-server`.
-
-### Quick Publishing Checklist
-
-```bash
-# 1. Ensure clean working directory
-git status
-
-# 2. Run full validation
-npm run validate
-
-# 3. Test package contents
-npm pack --dry-run
-
-# 4. Test bin script
-node bin/converse.js --help
-
-# 5. Bump version (choose one)
-npm version patch    # Bug fixes: 1.0.1 → 1.0.2
-npm version minor    # New features: 1.0.1 → 1.1.0
-npm version major    # Breaking changes: 1.0.1 → 2.0.0
-
-# 6. Test publish (dry run)
-npm publish --dry-run
-
-# 7. Publish to npm
-npm publish
-
-# 8. Verify publication
-npm view converse-mcp-server
-npx converse-mcp-server --help
-```
-
-### Version Guidelines
-
-- **Patch** (`npm version patch`): Bug fixes, documentation updates, minor improvements
-- **Minor** (`npm version minor`): New features, new model support, new tool capabilities
-- **Major** (`npm version major`): Breaking API changes, major architecture changes
-
-### Post-Publication
-
-After publishing, update installation instructions if needed and verify:
-
-```bash
-# Test direct execution
-npx converse-mcp-server
-npx converse
-
-# Test MCP client integration
-# Update Claude Desktop config to use: "npx converse-mcp-server"
-```
-
-### Troubleshooting Publication
-
-- **Git not clean**: Commit all changes first
-- **Tests failing**: Fix issues before publishing
-- **Version conflicts**: Check existing versions with `npm view converse-mcp-server versions`
-- **Permission issues**: Ensure you're logged in with `npm whoami`
-
-## 🤝 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).
-
-## 📄 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
+# Converse MCP Server
+
+[![npm version](https://img.shields.io/npm/v/converse-mcp-server.svg)](https://www.npmjs.com/package/converse-mcp-server)
+
+An MCP (Model Context Protocol) server that lets Claude talk to other AI models. Use it to chat with models from OpenAI, Google, Anthropic, X.AI, Mistral, DeepSeek, or OpenRouter. You can either talk to one model at a time or get multiple models to weigh in on complex decisions.
+
+## 📋 Requirements
+
+- **Node.js**: Version 20 or higher
+- **Package Manager**: npm (or pnpm/yarn)
+- **API Keys**: At least one from any supported provider
+
+## 🚀 Quick Start
+
+### Step 1: Get Your API Keys
+
+You need at least one API key from these providers:
+
+| Provider          | Where to Get                                                                 | Example Format          |
+| ----------------- | ---------------------------------------------------------------------------- | ----------------------- |
+| **OpenAI**        | [platform.openai.com/api-keys](https://platform.openai.com/api-keys)         | `sk-proj-...`           |
+| **Google/Gemini** | [makersuite.google.com/app/apikey](https://makersuite.google.com/app/apikey) | `AIzaSy...`             |
+| **X.AI**          | [console.x.ai](https://console.x.ai/)                                        | `xai-...`               |
+| **Anthropic**     | [console.anthropic.com](https://console.anthropic.com/)                      | `sk-ant-...`            |
+| **Mistral**       | [console.mistral.ai](https://console.mistral.ai/)                            | `wfBMkWL0...`           |
+| **DeepSeek**      | [platform.deepseek.com](https://platform.deepseek.com/)                      | `sk-...`                |
+| **OpenRouter**    | [openrouter.ai/keys](https://openrouter.ai/keys)                             | `sk-or-...`             |
+| **Codex**         | ChatGPT login (system-wide)                                                  | Local agentic assistant |
+
+**Note:** Codex uses your ChatGPT login (not an API key). If you have an active ChatGPT session, Codex will work automatically. For headless/server deployments, set `CODEX_API_KEY` in your environment.
+
+### Step 2: Add to Claude Code or Claude Desktop
+
+#### For Claude Code (Recommended)
+
+```bash
+# Add the server with your API keys
+claude mcp add converse \
+  -e OPENAI_API_KEY=your_key_here \
+  -e GEMINI_API_KEY=your_key_here \
+  -e XAI_API_KEY=your_key_here \
+  -e ANTHROPIC_API_KEY=your_key_here \
+  -e MISTRAL_API_KEY=your_key_here \
+  -e DEEPSEEK_API_KEY=your_key_here \
+  -e OPENROUTER_API_KEY=your_key_here \
+  -e ENABLE_RESPONSE_SUMMARIZATION=true \
+  -e SUMMARIZATION_MODEL=gpt-5 \
+  -s user \
+  npx converse-mcp-server
+```
+
+#### For Claude Desktop
+
+Add this configuration to your Claude Desktop settings:
+
+```json
+{
+  "mcpServers": {
+    "converse": {
+      "command": "npx",
+      "args": ["converse-mcp-server"],
+      "env": {
+        "OPENAI_API_KEY": "your_key_here",
+        "GEMINI_API_KEY": "your_key_here",
+        "XAI_API_KEY": "your_key_here",
+        "ANTHROPIC_API_KEY": "your_key_here",
+        "MISTRAL_API_KEY": "your_key_here",
+        "DEEPSEEK_API_KEY": "your_key_here",
+        "OPENROUTER_API_KEY": "your_key_here",
+        "ENABLE_RESPONSE_SUMMARIZATION": "true",
+        "SUMMARIZATION_MODEL": "gpt-5"
+      }
+    }
+  }
+}
+```
+
+**Windows Troubleshooting**: If `npx converse-mcp-server` doesn't work on Windows, try:
+
+```json
+{
+  "command": "cmd",
+  "args": ["/c", "npx", "converse-mcp-server"],
+  "env": {
+    "ENABLE_RESPONSE_SUMMARIZATION": "true",
+    "SUMMARIZATION_MODEL": "gpt-5"
+    // ... add your API keys here
+  }
+}
+```
+
+### Step 3: Start Using Converse
+
+Once installed, you can:
+
+- **Chat with a specific model**: Ask Claude to use the chat tool with your preferred model
+- **Get consensus**: Ask Claude to use the consensus tool when you need multiple perspectives
+- **Run tasks in background**: Use `async: true` for long-running operations that you can check later
+- **Monitor progress**: Use the check_status tool to monitor async operations with AI-generated summaries
+- **Cancel jobs**: Use the cancel_job tool to stop running operations
+- **Smart summaries**: Get auto-generated titles and summaries for better context understanding
+- **Get help**: Type `/converse:help` in Claude
+
+## 🛠️ Available Tools
+
+### 1. Chat Tool
+
+Talk to any AI model with support for files, images, and conversation history. The tool automatically routes your request to the right provider based on the model name. When AI summarization is enabled, generates smart titles and summaries for better context understanding.
+
+```javascript
+// Synchronous execution (default)
+{
+  "prompt": "How should I structure the authentication module for this Express.js API?",
+  "model": "gemini-2.5-flash",         // Routes to Google
+  "files": ["/path/to/src/auth.js", "/path/to/config.json"],
+  "images": ["/path/to/architecture.png"],
+  "temperature": 0.5,
+  "reasoning_effort": "medium",
+  "use_websearch": false
+}
+
+// Asynchronous execution (for long-running tasks)
+{
+  "prompt": "Analyze this large codebase and provide optimization recommendations",
+  "model": "gpt-5",
+  "files": ["/path/to/large-project"],
+  "async": true,           // Enables background processing
+  "continuation_id": "my-analysis-task"  // Optional: custom ID for tracking
+}
+
+// Codex - Agentic coding assistant with local file access
+{
+  "prompt": "Analyze this codebase and suggest improvements",
+  "model": "codex",
+  "files": ["/path/to/your/project"],
+  "async": true  // Recommended for Codex (responses take 6-20+ seconds)
+}
+```
+
+**Codex Notes:**
+
+- Uses thread-based sessions (context persists with `continuation_id`)
+- Responses typically take 6-20 seconds (complex tasks may take minutes)
+- Accesses files directly from your working directory
+- Configure sandbox mode via `CODEX_SANDBOX_MODE` environment variable
+
+### 2. Consensus Tool
+
+Get multiple AI models to analyze the same question simultaneously. Each model can see and respond to the others' answers, creating a rich discussion.
+
+```javascript
+// Synchronous consensus (default)
+{
+  "prompt": "Should we use microservices or monolith architecture for our e-commerce platform?",
+  "models": ["gpt-5", "gemini-2.5-flash", "grok-4"],
+  "files": ["/path/to/requirements.md"],
+  "enable_cross_feedback": true,
+  "temperature": 0.2
+}
+
+// Asynchronous consensus (for complex analysis)
+{
+  "prompt": "Review our system architecture and provide comprehensive recommendations",
+  "models": ["gpt-5", "gemini-2.5-pro", "claude-sonnet-4"],
+  "files": ["/path/to/architecture-docs"],
+  "async": true,          // Run in background
+  "enable_cross_feedback": true
+}
+```
+
+### 3. Check Status Tool
+
+Monitor the progress and retrieve results from asynchronous operations. When AI summarization is enabled, provides intelligent summaries of ongoing and completed tasks.
+
+```javascript
+// Check status of a specific job
+{
+  "continuation_id": "my-analysis-task"
+}
+
+// List recent jobs (shows last 10)
+// With summarization enabled, displays titles and final summaries
+{}
+
+// Get full conversation history for completed job
+{
+  "continuation_id": "my-analysis-task",
+  "full_history": true
+}
+```
+
+### 4. Cancel Job Tool
+
+Cancel running asynchronous operations when needed.
+
+```javascript
+// Cancel a running job
+{
+  "continuation_id": "my-analysis-task"
+}
+```
+
+## 🤖 AI Summarization Feature
+
+When enabled, the server automatically generates intelligent titles and summaries for better context understanding:
+
+- **Automatic Title Generation**: Creates descriptive titles (up to 60 chars) for each request
+- **Streaming Summaries**: Status check returns an up-to-date summary of the progress based on the partially streamed response
+- **Final Summaries**: Concise 1-2 sentence summaries of completed responses
+- **Smart Status Display**: Enhanced check_status tool shows titles and summaries in job listings
+- **Persistent Context**: Summaries are stored with async jobs for better progress tracking
+
+**Configuration**:
+
+```bash
+# Enable in your environment
+ENABLE_RESPONSE_SUMMARIZATION=true    # Default: false
+SUMMARIZATION_MODEL=gpt-5-nano        # Default: gpt-5-nano
+```
+
+**Benefits**:
+
+- Quickly understand what each async job is doing without reading full responses
+- Better context when reviewing multiple ongoing operations
+- Improved job management with at-a-glance understanding of task progress
+- Graceful fallback to text snippets when summarization is disabled or fails
+
+## 📊 Supported Models
+
+### OpenAI Models
+
+- **gpt-5**: Latest flagship model (400K context, 128K output) - Superior reasoning, code generation, and analysis
+- **gpt-5-mini**: Faster, cost-efficient GPT-5 (400K context, 128K output) - Well-defined tasks, precise prompts
+- **gpt-5-nano**: Fastest, most cost-efficient GPT-5 (400K context, 128K output) - Summarization, classification
+- **gpt-5-pro**: Most advanced reasoning model (400K context, 272K output) - Hardest problems, extended compute time (EXPENSIVE)
+- **o3**: Strong reasoning (200K context)
+- **o3-mini**: Fast O3 variant (200K context)
+- **o3-pro**: Professional-grade reasoning (200K context) - EXTREMELY EXPENSIVE
+- **o3-deep-research**: Deep research model (200K context) - 30-90 min runtime
+- **o4-mini**: Latest reasoning model (200K context)
+- **o4-mini-deep-research**: Fast deep research model (200K context) - 15-60 min runtime
+- **gpt-4.1**: Advanced reasoning (1M context)
+- **gpt-4o**: Multimodal flagship (128K context)
+- **gpt-4o-mini**: Fast multimodal (128K context)
+
+### Google/Gemini Models
+
+**API Key Options**:
+
+- **GEMINI_API_KEY**: For Gemini Developer API (recommended)
+- **GOOGLE_API_KEY**: Alternative name (GEMINI_API_KEY takes priority)
+- **Vertex AI**: Use `GOOGLE_GENAI_USE_VERTEXAI=true` with project/location settings
+
+**Supported Models**:
+
+- **gemini-3-pro-preview** (aliases: `pro`, `gemini`): Enhanced reasoning with thinking levels (1M context, 64K output)
+- **gemini-2.5-flash** (alias: `flash`): Ultra-fast (1M context, 65K output)
+- **gemini-2.5-pro** (alias: `pro 2.5`): Deep reasoning with thinking budget (1M context, 65K output)
+- **gemini-2.0-flash**: Latest with experimental thinking (1M context, 65K output)
+- **gemini-2.0-flash-lite**: Lightweight fast model, text-only (1M context, 65K output)
+
+**Note**: Default aliases (`gemini`, `pro`) now point to Gemini 3.0 Pro. Use `gemini-2.5-pro` explicitly if you need version 2.5.
+
+### X.AI/Grok Models
+
+- **grok-4-0709** (aliases: `grok`, `grok-4`): Latest advanced model (256K context)
+- **grok-code-fast-1**: Speedy and economical reasoning model that excels at agentic coding (256K context)
+
+### Anthropic Models
+
+- **claude-opus-4.1**: Highest intelligence with extended thinking (200K context)
+- **claude-sonnet-4**: Balanced performance with extended thinking (200K context)
+- **claude-3.7-sonnet**: Enhanced 3.x generation with thinking (200K context)
+- **claude-3.5-sonnet**: Fast and intelligent (200K context)
+- **claude-3.5-haiku**: Fastest model for simple queries (200K context)
+
+### Mistral Models
+
+- **magistral-medium**: Frontier-class reasoning model (40K context)
+- **magistral-small**: Small reasoning model (40K context)
+- **mistral-medium-3**: Frontier-class multimodal model (128K context)
+
+### DeepSeek Models
+
+- **deepseek-chat**: Strong MoE model with 671B/37B parameters (64K context)
+- **deepseek-reasoner**: Advanced reasoning model with CoT (64K context)
+
+### OpenRouter Models
+
+- **qwen3-235b-thinking**: Qwen3 with enhanced reasoning (32K context)
+- **qwen3-coder**: Specialized for programming tasks (32K context)
+- **kimi-k2**: Moonshot AI Kimi K2 with extended context (200K context)
+
+### Codex Models
+
+- **codex**: OpenAI Codex agentic coding assistant
+  - Thread-based sessions with persistent context
+  - Direct filesystem access from working directory
+  - Typical response time: 6-20 seconds (longer for complex tasks)
+  - Requires ChatGPT login or CODEX_API_KEY
+  - See [Configuration](#configuration) for sandbox and approval settings
+
+## 📚 Help & Documentation
+
+### Built-in Help
+
+Type these commands directly in Claude:
+
+- `/converse:help` - Full documentation
+- `/converse:help tools` - Tool-specific help (includes async features)
+- `/converse:help models` - Model information
+- `/converse:help parameters` - Configuration details
+- `/converse:help examples` - Usage examples (sync and async)
+- `/converse:help async` - Async execution guide
+
+### Additional Resources
+
+- **API Reference**: [docs/API.md](docs/API.md)
+- **Architecture Guide**: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- **Integration Examples**: [docs/EXAMPLES.md](docs/EXAMPLES.md)
+
+## ⚙️ Configuration
+
+### 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
+GEMINI_API_KEY=your_gemini_api_key_here  # Or GOOGLE_API_KEY (GEMINI_API_KEY takes priority)
+XAI_API_KEY=xai-your_xai_key_here
+ANTHROPIC_API_KEY=sk-ant-your_anthropic_key_here
+MISTRAL_API_KEY=your_mistral_key_here
+DEEPSEEK_API_KEY=your_deepseek_key_here
+OPENROUTER_API_KEY=sk-or-your_openrouter_key_here
+
+# Optional: Server configuration
+PORT=3157
+LOG_LEVEL=info
+
+# Optional: AI Summarization (Enhanced async status display)
+ENABLE_RESPONSE_SUMMARIZATION=true    # Enable AI-generated titles and summaries
+SUMMARIZATION_MODEL=gpt-5-nano        # Model to use for summarization (default: gpt-5-nano)
+
+# Optional: OpenRouter configuration
+OPENROUTER_REFERER=https://github.com/FallDownTheSystem/converse
+OPENROUTER_TITLE=Converse
+OPENROUTER_DYNAMIC_MODELS=true
+
+# Optional: Codex configuration
+CODEX_API_KEY=your_codex_api_key_here       # Optional if ChatGPT login available
+CODEX_SANDBOX_MODE=read-only                 # read-only (default), workspace-write, danger-full-access
+CODEX_SKIP_GIT_CHECK=true                    # true (default), false
+CODEX_APPROVAL_POLICY=never                  # never (default), untrusted, on-failure, on-request
+CODEX_DEFAULT_MODEL=gpt-5-codex              # Default: gpt-5-codex
+```
+
+### Configuration Options
+
+#### Server Environment Variables (.env file)
+
+| Variable    | Description   | Default | Example                  |
+| ----------- | ------------- | ------- | ------------------------ |
+| `PORT`      | Server port   | `3157`  | `3157`                   |
+| `LOG_LEVEL` | Logging level | `info`  | `debug`, `info`, `error` |
+
+#### Claude Code Environment Variables (System/Global)
+
+These must be set in your system environment or when launching Claude Code, NOT in the project .env file:
+
+| Variable                | Description                 | Default  | Example                              |
+| ----------------------- | --------------------------- | -------- | ------------------------------------ |
+| `MAX_MCP_OUTPUT_TOKENS` | Token response limit        | `25000`  | `200000`                             |
+| `MCP_TOOL_TIMEOUT`      | Tool execution timeout (ms) | `120000` | `5400000` (90 min for deep research) |
+
+```bash
+# Example: Set globally before starting Claude Code
+export MAX_MCP_OUTPUT_TOKENS=200000
+export MCP_TOOL_TIMEOUT=5400000  # 90 minutes for deep research models
+claude  # Then start Claude Code
+```
+
+### Model Selection
+
+Use `"auto"` for automatic model selection, or specify exact models:
+
+```javascript
+// Auto-selection (recommended)
+"auto";
+
+// Specific models
+"gemini-2.5-flash";
+"gpt-5";
+"grok-4-0709";
+
+// Using aliases
+"flash"; // -> gemini-2.5-flash
+"pro"; // -> gemini-2.5-pro
+"grok"; // -> grok-4-0709
+"grok-4"; // -> grok-4-0709
+```
+
+**Auto Model Behavior:**
+
+- **Chat Tool**: Selects the first available provider and uses its default model
+- **Consensus Tool**: When using `["auto"]`, automatically expands to the first 3 available providers
+
+Provider priority order (requires corresponding API key):
+
+1. OpenAI (`gpt-5`)
+2. Google (`gemini-2.5-pro`)
+3. XAI (`grok-4`)
+4. Anthropic (`claude-sonnet-4-20250514`)
+5. Mistral (`magistral-medium-2506`)
+6. DeepSeek (`deepseek-reasoner`)
+7. OpenRouter (`qwen/qwen3-coder`)
+
+The system will use the first 3 providers that have valid API keys configured. This enables automatic multi-model consensus without manually specifying models.
+
+### Advanced Configuration
+
+#### Manual Installation Options
+
+##### Option A: Direct Node.js execution
+
+If you've cloned the repository locally:
+
+```json
+{
+  "mcpServers": {
+    "converse": {
+      "command": "node",
+      "args": [
+        "C:\\Users\\YourUsername\\Documents\\Projects\\converse\\src\\index.js"
+      ],
+      "env": {
+        "OPENAI_API_KEY": "your_key_here",
+        "GEMINI_API_KEY": "your_key_here",
+        "XAI_API_KEY": "your_key_here",
+        "ANTHROPIC_API_KEY": "your_key_here",
+        "MISTRAL_API_KEY": "your_key_here",
+        "DEEPSEEK_API_KEY": "your_key_here",
+        "OPENROUTER_API_KEY": "your_key_here"
+      }
+    }
+  }
+}
+```
+
+##### Option B: Local HTTP Development (Advanced)
+
+For local development with HTTP transport (optional, for debugging):
+
+1. **First, start the server manually with HTTP transport**:
+
+   ```bash
+   # In a terminal, navigate to the project directory
+   cd converse
+   MCP_TRANSPORT=http npm run dev  # Starts server on http://localhost:3157/mcp
+   ```
+
+2. **Then configure Claude to connect to it**:
+   ```json
+   {
+     "mcpServers": {
+       "converse-local": {
+         "url": "http://localhost:3157/mcp"
+       }
+     }
+   }
+   ```
+
+**Important**: HTTP transport requires the server to be running before Claude can connect to it. Keep the terminal with the server open while using Claude.
+
+### Configuration File Locations
+
+The Claude 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).
+
+## 💻 Running Standalone (Without Claude)
+
+You can run the server directly without Claude for testing or development:
+
+```bash
+# Quick run (no installation needed)
+npx converse-mcp-server
+
+# Alternative package managers
+pnpm dlx converse-mcp-server
+yarn dlx converse-mcp-server
+```
+
+For development setup, see the [Development](#-development) section below.
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Server won't start:**
+
+- Check Node.js version: `node --version` (needs v20+)
+- Try a different port: `PORT=3001 npm start`
+
+**API key errors:**
+
+- Verify your .env file has the correct format
+- Test with: `npm run test:real-api`
+
+**Module import errors:**
+
+- 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
+```
+
+## 🔧 Development
+
+### Getting Started
+
+```bash
+# Clone the repository
+git clone https://github.com/FallDownTheSystem/converse.git
+cd converse
+npm install
+
+# Copy environment file and add your API keys
+cp .env.example .env
+
+# Start development server
+npm run dev
+```
+
+### Scripts Available
+
+```bash
+# Server management
+npm start              # Start server (auto-kills existing server on port 3157)
+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 3157
+
+# Testing
+npm test               # Run all tests
+npm run test:unit      # Unit tests only
+npm run test:integration # Integration tests
+npm run test:e2e       # End-to-end tests (requires API keys)
+
+# Integration test subcategories
+npm run test:integration:mcp        # MCP protocol tests
+npm run test:integration:tools      # Tool integration tests
+npm run test:integration:providers  # Provider integration tests
+npm run test:integration:performance # Performance tests
+npm run test:integration:general    # General integration tests
+
+# Other test categories
+npm run test:mcp-client # MCP client tests (HTTP-based)
+npm run test:providers # Provider unit tests
+npm run test:tools     # Tool tests
+npm run test:coverage  # Coverage report
+npm run test:watch     # Run tests in watch mode
+
+# 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 3157
+```
+
+### Development Notes
+
+**Port conflicts**: The server uses port 3157 by default. If you get an "EADDRINUSE" error:
+
+- Run `npm run kill-server` to free the port
+- Or use a different port: `PORT=3001 npm start`
+
+**Transport Modes**:
+
+- **Stdio** (default): Works automatically with Claude
+- **HTTP**: Better for debugging, requires manual start (`MCP_TRANSPORT=http npm run dev`)
+
+### Testing with Real APIs
+
+After setting up your API keys in `.env`:
+
+```bash
+# Run end-to-end tests
+npm run test:e2e
+
+# Test specific providers
+npm run test:integration:providers
+
+# Full validation
+npm run validate
+```
+
+### Validation Steps
+
+After installation, run these tests to verify everything works:
+
+```bash
+npm start           # Should show startup message
+npm test            # Should pass all unit tests
+npm run validate    # Full validation suite
+```
+
+### 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
+│   │   ├── interface.js      # Unified provider interface
+│   │   ├── openai.js         # OpenAI provider
+│   │   ├── xai.js            # XAI provider
+│   │   ├── google.js         # Google provider
+│   │   ├── anthropic.js      # Anthropic provider
+│   │   ├── mistral.js        # Mistral AI provider
+│   │   ├── deepseek.js       # DeepSeek provider
+│   │   ├── openrouter.js     # OpenRouter provider
+│   │   └── openai-compatible.js # Base for OpenAI-compatible APIs
+│   ├── 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
+```
+
+## 📦 Publishing to NPM
+
+> **Note**: This section is for maintainers. The package is already published as `converse-mcp-server`.
+
+### Quick Publishing Checklist
+
+```bash
+# 1. Ensure clean working directory
+git status
+
+# 2. Run full validation
+npm run validate
+
+# 3. Test package contents
+npm pack --dry-run
+
+# 4. Test bin script
+node bin/converse.js --help
+
+# 5. Bump version (choose one)
+npm version patch    # Bug fixes: 1.0.1 → 1.0.2
+npm version minor    # New features: 1.0.1 → 1.1.0
+npm version major    # Breaking changes: 1.0.1 → 2.0.0
+
+# 6. Test publish (dry run)
+npm publish --dry-run
+
+# 7. Publish to npm
+npm publish
+
+# 8. Verify publication
+npm view converse-mcp-server
+npx converse-mcp-server --help
+```
+
+### Version Guidelines
+
+- **Patch** (`npm version patch`): Bug fixes, documentation updates, minor improvements
+- **Minor** (`npm version minor`): New features, new model support, new tool capabilities
+- **Major** (`npm version major`): Breaking API changes, major architecture changes
+
+### Post-Publication
+
+After publishing, update installation instructions if needed and verify:
+
+```bash
+# Test direct execution
+npx converse-mcp-server
+npx converse
+
+# Test MCP client integration
+# Update Claude Desktop config to use: "npx converse-mcp-server"
+```
+
+### Troubleshooting Publication
+
+- **Git not clean**: Commit all changes first
+- **Tests failing**: Fix issues before publishing
+- **Version conflicts**: Check existing versions with `npm view converse-mcp-server versions`
+- **Permission issues**: Ensure you're logged in with `npm whoami`
+
+## 🤝 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).
+
+## 📄 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