# Council MCP Server

A Model Context Protocol (MCP) server that enables Claude to collaborate with multiple AI models via OpenRouter. Access 100+ models from Google, Anthropic, OpenAI, Meta, Mistral, and more.

## Features

- **Multi-Model Support**: Access 100+ models via OpenRouter (Gemini, GPT, Claude, Llama, Mistral, etc.)
- **Dynamic Model Discovery**: List and filter available models by provider, capability, or pricing
- **Per-Request Model Override**: Use different models for different tasks
- **Multiple Collaboration Tools**: Code review, brainstorming, test generation, explanations
- **Response Caching**: Automatic caching for repeated queries

## Quick Start

### 1. Prerequisites

- Python 3.9+
- [Claude Desktop](https://claude.ai/download) or [Claude Code](https://claude.ai/code)
- [OpenRouter API Key](https://openrouter.ai/keys)

### 2. Installation

```bash
# Clone the repository
git clone https://github.com/lbds137/council-mcp-server.git
cd council-mcp-server

# Install dependencies
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
# Edit .env and add your OPENROUTER_API_KEY
```

### 3. Configuration

Edit `.env` to configure:

```bash
# Your OpenRouter API key (required)
OPENROUTER_API_KEY=sk-or-...

# Model configuration (optional - defaults shown)
COUNCIL_DEFAULT_MODEL=google/gemini-3-pro-preview
COUNCIL_CACHE_TTL=3600
COUNCIL_TIMEOUT=600000
```

### 4. Register with Claude

```bash
# Install to MCP location
./scripts/install.sh

# Or manually register
claude mcp add council python3 ~/.claude-mcp-servers/council/launcher.py
```

## Available Tools

### Core Tools

| Tool | Description |
|------|-------------|
| `ask` | General questions and problem-solving assistance |
| `code_review` | Code review feedback (security, performance, best practices) |
| `brainstorm` | Collaborative brainstorming for architecture and design |
| `test_cases` | Generate comprehensive test scenarios |
| `explain` | Clear explanations of complex code or concepts |
| `synthesize_perspectives` | Combine multiple viewpoints into a coherent summary |

### Model Management

| Tool | Description |
|------|-------------|
| `server_info` | Check server status and current model |
| `list_models` | List available models with filtering |
| `set_model` | Change the active model for subsequent requests |

### Model Override

All tools support an optional `model` parameter to use a specific model:

```python
# Use Claude for code review
mcp__council__code_review(
    code="def hello(): print('world')",
    focus="security",
    model="anthropic/claude-3-opus"
)

# Use GPT-4 for brainstorming
mcp__council__brainstorm(
    topic="API design patterns",
    model="openai/gpt-4-turbo"
)
```

## Popular Model Configurations

### Google Gemini (Default)
```bash
COUNCIL_DEFAULT_MODEL=google/gemini-3-pro-preview
```

### Anthropic Claude
```bash
COUNCIL_DEFAULT_MODEL=anthropic/claude-3.5-sonnet
```

### OpenAI GPT-4
```bash
COUNCIL_DEFAULT_MODEL=openai/gpt-4-turbo
```

### Meta Llama (Free)
```bash
COUNCIL_DEFAULT_MODEL=meta-llama/llama-3.3-70b-instruct:free
```

## Development

### Project Structure
```
council-mcp-server/
├── src/council/           # Main source code
│   ├── main.py           # CouncilMCPServer entry point
│   ├── manager.py        # ModelManager (OpenRouter)
│   ├── providers/        # LLM provider implementations
│   ├── discovery/        # Model discovery and filtering
│   ├── tools/            # MCP tool implementations
│   ├── core/             # Registry and orchestrator
│   └── services/         # Cache and memory
├── tests/                # Test suite
├── scripts/              # Installation scripts
├── server.py             # Bundled single-file server
├── launcher.py           # Launcher with venv support
├── CLAUDE.md            # Claude Code instructions
└── README.md            # This file
```

### Running Tests
```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest tests/ -v
```

### Building the Bundle
```bash
# Generate single-file server.py
python scripts/bundler.py

# Deploy to MCP location
./scripts/install.sh
```

## Updating

To update your local MCP installation after making changes:

```bash
./scripts/install.sh
```

Then restart Claude Desktop/Code.

## Troubleshooting

### Server not found
```bash
# Check registration
claude mcp list

# Re-register if needed
./scripts/install.sh
```

### API Key Issues
```bash
# Verify environment variable
echo $OPENROUTER_API_KEY

# Test with list_models tool
mcp__council__list_models(limit=5)
```

### Model Not Available
Use `list_models` to find available models:
```python
mcp__council__list_models(provider="google")
```

## Version History

- **v4.0.0**: Council - Multi-model support via OpenRouter
- **v3.0.0**: Modular architecture with bundler
- **v2.0.0**: Dual-model support with fallback
- **v1.0.0**: Initial Gemini integration

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built for [Claude](https://claude.ai) using the Model Context Protocol
- Powered by [OpenRouter](https://openrouter.ai/) for multi-model access