# Polyagent

Multi-provider AI agent bridge for Claude Desktop. Connect Claude to external AI agents (GLM, OpenAI, Anthropic, Bedrock, Gemini) for specialized tasks like security scanning, code review, and more.

## Features

- **Multi-Provider Support**: Google Gemini and Ollama Cloud through an OpenAI-compatible endpoint
- **Dynamic Agent Registration**: Register agents at runtime via MCP tools
- **Flexible Pipeline Modes**: Sequential, Iterative, and Parallel execution
- **Loop Prevention**: Max iterations, confidence thresholds, human approval
- **Streaming Support**: Stream responses in real-time
- **Production Ready**: Comprehensive error handling, logging, and metrics

## Architecture

```
[Claude Desktop] ←→ [AI Agent MCP Server] ←→ [External AI Agents]
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
   Agent Registry    Pipeline Engine    Loop Prevention
   (dynamic reg)     (seq/iter/parallel) (max iter/confidence/approval)
```

## Installation

### Prerequisites

- Python 3.10 or higher
- `uv` package manager (recommended)

### Setup

```bash
# Clone or navigate to the project
cd ai-agent-mcp-server

# Install dependencies
uv sync

# Set up environment variables. The server also loads a local .env file.
export GOOGLE_API_KEY="your-key"          # For Gemini
export OLLAMA_API_KEY="your-key"          # For Ollama Cloud
export OLLAMA_BASE_URL="https://ollama.com/v1"
```

## Usage

### 1. Configure Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ai-agent-bridge": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/ai-agent-mcp-server",
        "run",
        "main.py"
      ],
      "env": {
        "GOOGLE_API_KEY": "your-key",
        "OLLAMA_API_KEY": "your-key",
        "OLLAMA_BASE_URL": "https://ollama.com/v1"
      }
    }
  }
}
```

**Config file locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

### 2. Restart Claude Desktop

Fully quit Claude Desktop (Cmd+Q on macOS) and restart.

### 3. Register an Agent

In Claude Desktop, use the `register_agent` tool:

```
Register a security scanner agent using GLM-4
```

Claude will call:
```json
{
  "name": "register_agent",
  "arguments": {
    "name": "security-scanner",
    "provider": "openai_compat",
    "model": "glm-4",
    "system_prompt": "You are an expert security auditor...",
    "description": "Scans code for security vulnerabilities",
    "api_key_env": "GLM_API_KEY",
    "base_url": "https://open.bigmodel.cn/api/paas/v4",
    "capabilities": ["security", "vulnerability-detection"]
  }
}
```

### 4. Execute an Agent

```
Scan this code for vulnerabilities: [paste code]
```

Claude will call:
```json
{
  "name": "execute_agent",
  "arguments": {
    "agent_name": "security-scanner",
    "input_content": "[your code]"
  }
}
```

## Available Tools

### Agent Management

- **`register_agent`**: Register a new AI agent
- **`list_agents`**: List all registered agents
- **`update_agent`**: Update agent configuration
- **`remove_agent`**: Remove an agent

### Pipeline Execution

- **`execute_agent`**: Execute a single agent
- **`execute_pipeline`**: Execute multi-agent pipeline

### Configuration

- **`set_safety_config`**: Configure loop prevention
- **`get_safety_config`**: Get current safety settings

## Example: Security Scanner Pipeline

### Step 1: Register Security Agent

```python
# In Claude Desktop
register_agent(
    name="security-scanner",
    provider="openai_compat",
    model="glm-4",
    system_prompt="You are an expert security auditor. Find vulnerabilities in the following code.",
    description="Scans code for security vulnerabilities using GLM-4",
    api_key_env="GLM_API_KEY",
    base_url="https://open.bigmodel.cn/api/paas/v4",
    capabilities=["security", "vulnerability-detection"],
    temperature=0.3
)
```

### Step 2: Execute Security Scan

```python
# In Claude Desktop
execute_agent(
    agent_name="security-scanner",
    input_content="def process_user_input(user_input):\n    eval(user_input)"
)
```

### Step 3: Claude Processes Results

Claude receives the security findings and can:
- Explain vulnerabilities to the user
- Suggest fixes
- Re-run scans on fixed code

## Pipeline Modes

### Sequential (Default)

Single pass: Claude → Agent → Claude

```python
execute_pipeline(
    agents=["security-scanner"],
    input_content="[code]",
    mode="sequential"
)
```

### Iterative

Multiple rounds: Claude ↔ Agent (with loop prevention)

```python
execute_pipeline(
    agents=["security-scanner"],
    input_content="[code]",
    mode="iterative",
    max_iterations=3,
    confidence_threshold=0.9
)
```

### Parallel

Multiple agents analyze simultaneously:

```python
execute_pipeline(
    agents=["security-scanner", "code-reviewer", "performance-analyzer"],
    input_content="[code]",
    mode="parallel"
)
```

## Supported Providers

### OpenAI-Compatible (GLM, DeepSeek, etc.)

```python
register_agent(
    name="glm-agent",
    provider="openai_compat",
    model="glm-4",
    base_url="https://open.bigmodel.cn/api/paas/v4",
    api_key_env="GLM_API_KEY"
)
```

### Anthropic Claude

```python
register_agent(
    name="claude-agent",
    provider="anthropic",
    model="claude-3-5-sonnet-20241022",
    api_key_env="ANTHROPIC_API_KEY"
)
```

### Google Gemini

```python
register_agent(
    name="gemini-agent",
    provider="gemini",
    model="gemini-1.5-pro",
    api_key_env="GOOGLE_API_KEY"
)
```

### AWS Bedrock

```python
register_agent(
    name="bedrock-agent",
    provider="bedrock",
    model="anthropic.claude-3-5-sonnet-20241022-v2:0",
    api_key_env="AWS_BEDROCK_API_KEY",
    region="us-east-1"
)
```

## Loop Prevention

Configure safety settings:

```python
set_safety_config(
    max_iterations=3,              # Stop after 3 iterations
    confidence_threshold=0.9,      # Stop when confidence > 90%
    require_approval_after=2,      # Ask for approval after 2 iterations
    timeout_seconds=300            # Global timeout
)
```

## Development

### Run in Development Mode

```bash
# Test with MCP Inspector
uv run mcp dev main.py
```

### Run Tests

```bash
uv run pytest tests/
```

### Project Structure

```
ai-agent-mcp-server/
├── src/
│   ├── server.py           # MCP server entry point
│   ├── providers/          # AI provider adapters
│   │   ├── base.py         # Abstract base provider
│   │   ├── openai_compat.py # OpenAI-compatible (GLM, DeepSeek)
│   │   ├── anthropic.py    # Anthropic Claude
│   │   ├── bedrock.py      # AWS Bedrock
│   │   └── gemini.py       # Google Gemini
│   ├── agents/             # Agent management
│   │   ├── profiles.py     # Agent profile definitions
│   │   └── registry.py     # Dynamic agent registry
│   ├── pipeline/           # Communication pipeline
│   │   └── engine.py       # Pipeline execution engine
│   ├── safety/             # Loop prevention
│   │   └── limits.py       # Safety mechanisms
│   └── config.py           # Configuration management
├── tests/
├── main.py                 # Entry point
├── pyproject.toml
└── README.md
```

## Troubleshooting

### Server not showing up in Claude

1. Check `claude_desktop_config.json` syntax
2. Use absolute paths
3. Fully quit and restart Claude Desktop

### Tool calls failing

1. Check Claude's logs: `~/Library/Logs/Claude/mcp*.log`
2. Verify API keys are set
3. Test with MCP Inspector: `uv run mcp dev main.py`

### API errors

1. Verify API keys are correct
2. Check rate limits
3. Ensure model names are valid

## License

MIT

## Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

## Support

- GitHub Issues: [Report bugs or request features]
- Documentation: [Full API documentation]
- MCP Discord: [#python-sdk-dev](https://discord.gg/6CSzBmMkjX)