Metadata-Version: 2.4
Name: second-opinion-mcp
Version: 0.4.0
Summary: Multi-model AI analysis for Claude - get second opinions from DeepSeek, Kimi, and OpenRouter
Project-URL: Homepage, https://github.com/MarvinFS/second-opinion-mcp
Project-URL: Repository, https://github.com/MarvinFS/second-opinion-mcp
Project-URL: Issues, https://github.com/MarvinFS/second-opinion-mcp/issues
Project-URL: Changelog, https://github.com/MarvinFS/second-opinion-mcp/blob/main/docs/CHANGELOG.md
Author: MarvinFS
License: MIT
License-File: LICENSE
Keywords: ai,claude,code-review,deepseek,mcp,moonshot,openrouter,second-opinion
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=25.6.0
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: openai>=1.68.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: tenacity>=8.2.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# Second Opinion MCP

Get second opinions from multiple AI models while using Claude. Break the single-model echo chamber by consulting DeepSeek Reasoner, Kimi K2.5 (Moonshot), and 300+ OpenRouter models.

## What It Does

When working with Claude Code or Claude Desktop, this MCP server lets you:

- Get alternative perspectives on code, architecture, and decisions
- Run systematic code reviews with severity-classified issues
- Stage multi-model debates where AI models argue opposing positions
- Challenge proposals with anti-sycophancy mode (finds weaknesses, not validation)

## Quickstart

### 1. Install

#### Windows

```powershell
# Install Python 3.10+ from python.org if not installed
# Then install pipx
pip install pipx
pipx ensurepath

# Restart your terminal, then install
pipx install second-opinion-mcp
```

#### macOS

```bash
# Install Python 3.10+ via Homebrew if not installed
brew install python@3.12

# Install pipx
pip3 install pipx
pipx ensurepath

# Restart your terminal, then install
pipx install second-opinion-mcp
```

#### Linux (Ubuntu/Debian)

```bash
# Install Python and pipx
sudo apt update
sudo apt install python3 python3-pip python3-venv
pip3 install pipx
pipx ensurepath

# Restart your terminal, then install
pipx install second-opinion-mcp
```

#### Linux (Fedora/RHEL)

```bash
sudo dnf install python3 python3-pip
pip3 install pipx
pipx ensurepath

# Restart your terminal, then install
pipx install second-opinion-mcp
```

### 2. Setup

Run the interactive setup wizard:

```bash
second-opinion-mcp setup
```

The wizard will guide you through selecting providers and entering API keys. Keys are stored securely in your system's credential manager.

After setup completes, see Client Integration below for instructions specific to your MCP client.

## Client Integration

After running the setup wizard, register the MCP server with your client.

### Claude Code CLI

Register the server:

```bash
claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="deepseek,moonshot" -- second-opinion-mcp
```

Restart Claude Code after registering.

Verify the server is registered:

```bash
claude mcp list | grep second-opinion
```

### Claude Desktop App

Add to your `claude_desktop_config.json`:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "second-opinion": {
      "command": "second-opinion-mcp",
      "env": {
        "SECOND_OPINION_PROVIDERS": "deepseek,moonshot"
      }
    }
  }
}
```

Restart Claude Desktop after saving. To verify, start a new conversation and check that the second-opinion tools appear in the available tools list.

### OpenClaw

[OpenClaw](https://github.com/AugustDev/openclaw) is an open-source desktop MCP client. Add the server with these settings:

- Server command: `second-opinion-mcp`
- Environment variable: `SECOND_OPINION_PROVIDERS=deepseek,moonshot`

See the [OpenClaw MCP documentation](https://github.com/AugustDev/openclaw#mcp-servers) for detailed configuration steps. Check the MCP server status in the app to verify the connection.

### Other MCP Clients

For any MCP-compatible client, configure it with:

- Server command: `second-opinion-mcp`
- Environment variable: `SECOND_OPINION_PROVIDERS=deepseek,moonshot`

Refer to your client's documentation for how to add MCP servers. The setup wizard (`second-opinion-mcp setup`) will show the server command you need.

## Supported Models

### DeepSeek V3.2 (Recommended)

Chain-of-thought reasoning model. Best for code reviews and complex analysis.

- Get your API key at https://platform.deepseek.com
- Pricing: ~$0.28/$0.42 per million tokens (input/output)

### Kimi K2.5 (Moonshot)

Chinese AI model with thinking mode. Good for alternative perspectives and debates.

- Get your API key at https://platform.moonshot.cn
- Supports 256K context window

### OpenRouter (Optional)

Access 300+ models through a single API. Enable for variety or specific model access.

- Get your API key at https://openrouter.ai/keys

## Available Tools

### second_opinion

Get a straightforward second opinion on any question, code, or decision.

```
Use second_opinion to review this database schema: [paste schema]
```

### challenge

Anti-sycophancy mode. The model is instructed to find weaknesses, not validate.

```
Use challenge to critique: "We should use a global singleton for database connections"
```

### code_review

Systematic directory-based code review with BLOCKER/CRITICAL/MAJOR/MINOR classifications.

```
Use code_review on directory="./src" with focus_areas=["security", "performance"]
```

### consensus

Multi-model debate where DeepSeek and Moonshot argue opposing positions, then synthesize.

```
Use consensus to debate: "GraphQL vs REST for internal microservices"
```

### review_synthesis

Full workflow: parallel reviews from both models, debate, then synthesis instructions.

```
Perform a comprehensive code review of ./myproject using review_synthesis
```

## Usage Examples

### Thorough Code Review Workflow

For comprehensive code reviews, use this prompt pattern with Claude Code:

```
MyProject: perform a comprehensive deep parallel code review with deepseek and kimi
using mcp server second-opinion - save resulting md files to the project folder
to the docs subfolder in md format.

After that perform Consensus debate + arbiter synthesis using same mcp server tools
with opus 4.5 compiling a final document for the final review.

First 2 tasks can be run in parallel.
```

This triggers parallel code_review calls to DeepSeek and Moonshot, then a consensus debate on findings, and finally Claude synthesizes the final review document.

### Quick Second Opinion

```
Use second_opinion to review this database schema:
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR(255),
  password VARCHAR(255)
);
```

### Critical Challenge

```
Use challenge to critique this proposal: "We should use a global singleton for
database connections because it's simpler"
```

### Consensus Debate

```
Use consensus to debate: "GraphQL vs REST for our internal microservices API"
```

### Code Review with Focus Areas

```
Use code_review on directory="./src" with focus_areas=["security", "error-handling"]
and save_to="./docs/reviews"
```

## Configuration

### Changing Providers

To reconfigure which providers are enabled, run the setup wizard again:

```bash
second-opinion-mcp setup
```

Or re-register the server with different providers:

```bash
# Only DeepSeek
claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="deepseek" -- second-opinion-mcp

# Only Moonshot
claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="moonshot" -- second-opinion-mcp

# All providers
claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="deepseek,moonshot,openrouter" -- second-opinion-mcp
```

### API Key Management

Credentials are stored using platform-appropriate storage:

| Platform | Storage Location |
|----------|-----------------|
| Windows | Windows Credential Manager |
| macOS (GUI) | macOS Keychain |
| macOS (headless/SSH) | `~/.second-opinion-config` |
| Linux | `~/.second-opinion-config` |

On Linux and headless macOS, credentials are stored in `~/.second-opinion-config` with SSH-style permissions (600). This is the same security model used by SSH private keys.

To update keys:

```bash
second-opinion-mcp setup
```

Or manually edit `~/.second-opinion-config` (Linux/macOS headless):

```json
{
  "credentials": {
    "deepseek": "sk-YOUR_DEEPSEEK_KEY",
    "moonshot": "YOUR_MOONSHOT_KEY",
    "openrouter": "sk-or-YOUR_OPENROUTER_KEY"
  }
}
```

Then set permissions: `chmod 600 ~/.second-opinion-config`

## Troubleshooting

### "No API key configured" Error

Run the setup wizard again:

```bash
second-opinion-mcp setup
```

### Connection Timeout

Check firewall, VPN, or proxy settings. Both DeepSeek (api.deepseek.com) and Moonshot (api.moonshot.ai) must be accessible.

### Rate Limit Exceeded

Moonshot has rate limits (3 concurrent, 20 RPM at Tier 0). Wait a minute and retry, or use fast mode for non-critical queries.

### Tool Not Found in Claude

Verify registration:

```bash
claude mcp list
```

If not listed, re-register:

```bash
claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="deepseek,moonshot" -- second-opinion-mcp
```

## Advanced Usage

### Fast Mode

Skip the thinking/reasoning phase for quicker responses:

```
Use second_opinion with fast=true to check: is this regex correct?
```

Note: Code reviews always use full thinking mode regardless of this setting.

### Include Reasoning

See the model's chain-of-thought:

```
Use second_opinion with include_reasoning=true to analyze this algorithm
```

### Focus Areas for Reviews

```
Use code_review with focus_areas=["security", "error-handling", "performance"]
```

### Save Review Output

```
Use code_review on directory="./src" with save_to="./docs/reviews"
```

## Updating

The server checks for updates on startup and notifies you if a new version is available.

To update manually:

```bash
pipx upgrade second-opinion-mcp
```

Or reinstall:

```bash
pipx uninstall second-opinion-mcp
pipx install second-opinion-mcp
```

Your API keys are preserved in the system keyring across updates.

## Uninstalling

```bash
# Remove from Claude
claude mcp remove second-opinion

# Optional: remove stored API keys BEFORE uninstalling (requires pipx venv Python)
SOPYTHON=~/.local/share/pipx/venvs/second-opinion-mcp/bin/python3
$SOPYTHON -c "import keyring; keyring.delete_password('second-opinion', 'deepseek')"
$SOPYTHON -c "import keyring; keyring.delete_password('second-opinion', 'moonshot')"
$SOPYTHON -c "import keyring; keyring.delete_password('second-opinion', 'openrouter')"

# Uninstall package
pipx uninstall second-opinion-mcp
```

## Security

API keys are stored in your OS keyring, not in environment variables or config files. The code review tool:

- Skips `.env` files, credentials, SSH keys, and certificates
- Validates directories against allowed roots
- Detects symlinks to prevent traversal attacks
- Limits content size to prevent memory exhaustion

## Cost Estimates

Per operation (typical usage):

| Tool | Approximate Cost |
|------|------------------|
| second_opinion / challenge | ~$0.001 |
| code_review | ~$0.01-0.05 |
| consensus (2 rounds) | ~$0.004-0.010 |
| review_synthesis | ~$0.02-0.10 |

## License

MIT License. See LICENSE file.

## Links

- [GitHub Repository](https://github.com/MarvinFS/second-opinion-mcp)
- [Issue Tracker](https://github.com/MarvinFS/second-opinion-mcp/issues)
- [Changelog](https://github.com/MarvinFS/second-opinion-mcp/blob/main/docs/CHANGELOG.md)
