Metadata-Version: 2.4
Name: second-opinion-mcp
Version: 0.3.2
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: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.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

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

If you don't have pipx, install it first: `pip install pipx && pipx ensurepath`

### 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.

### 3. Register

After setup, copy the registration command from the wizard output, e.g.:

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

That's it. Restart Claude Code and the tools are available.

## 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
```

## Configuration

### Changing Providers

After initial setup, reconfigure providers:

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

Or manually set the environment variable:

```bash
# Claude Code CLI
claude mcp add -s user second-opinion -e SECOND_OPINION_PROVIDERS="deepseek" -- second-opinion-mcp

# Only DeepSeek
export SECOND_OPINION_PROVIDERS="deepseek"

# Only Moonshot
export SECOND_OPINION_PROVIDERS="moonshot"

# All providers
export SECOND_OPINION_PROVIDERS="deepseek,moonshot,openrouter"
```

### API Key Management

Keys are stored in your system's credential manager (Windows Credential Manager, macOS Keychain, or Linux Secret Service).

To update keys:

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

Or manually:

```bash
python -c "import keyring; keyring.set_password('second-opinion', 'deepseek', 'sk-YOUR_NEW_KEY')"
```

### Claude Desktop Configuration

For Claude Desktop (the standalone app), add to `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"
      }
    }
  }
}
```

## Troubleshooting

### "No API key configured" Error

Run the setup wizard again:

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

### "Keyring access failed" (Linux)

Linux without a desktop environment needs a keyring backend configured:

```bash
pip install keyrings.alt
mkdir -p ~/.local/share/python_keyring
echo -e "[backend]\ndefault-keyring=keyrings.alt.file.EncryptedKeyring" > ~/.local/share/python_keyring/keyringrc.cfg
```

### 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

# Uninstall package
pipx uninstall second-opinion-mcp

# Optional: remove stored API keys
python -c "import keyring; keyring.delete_password('second-opinion', 'deepseek')"
python -c "import keyring; keyring.delete_password('second-opinion', 'moonshot')"
```

## 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)
