# Elrond MCP - Thinking Augmentation Server

A Model Context Protocol (MCP) server that provides hierarchical LLM critique and synthesis for enhanced decision-making and idea evaluation.

> [!WARNING]
> **Preview Software**: This is experimental software in active development and is not intended for production use. Features may change, break, or be removed without notice. Use at your own risk.

## Overview

Elrond MCP implements a multi-agent thinking augmentation system that analyzes proposals through three specialized critique perspectives (positive, neutral, negative) and synthesizes them into comprehensive, actionable insights. This approach helps overcome single-model biases and provides more thorough analysis of complex ideas.

## Features

- **Parallel Critique Analysis**: Three specialized agents analyze proposals simultaneously from different perspectives
- **Structured Responses**: Uses Pydantic models and `instructor` library for reliable, structured outputs
- **Google AI Integration**: Leverages Gemini 2.5 Flash for critiques and Gemini 2.5 Pro for synthesis
- **MCP Compliance**: Full Model Context Protocol support for seamless integration with AI assistants
- **Comprehensive Analysis**: Covers feasibility, risks, benefits, implementation, stakeholder impact, and resource requirements
- **Consensus Building**: Identifies areas of agreement and disagreement across perspectives

## Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Positive      │    │    Neutral      │    │   Negative      │
│   Critique      │    │   Critique      │    │   Critique      │
│   Agent         │    │    Agent        │    │    Agent        │
│                 │    │                 │    │                 │
│ Gemini 2.5      │    │ Gemini 2.5      │    │ Gemini 2.5      │
│ Flash           │    │ Flash           │    │ Flash           │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                                 ▼
                    ┌─────────────────────────┐
                    │    Synthesis Agent      │
                    │                         │
                    │  Gemini 2.5 Pro         │
                    │                         │
                    │                         │
                    │  Consensus + Summary    │
                    └─────────────────────────┘
```

## Installation

### Prerequisites

- Python 3.13 or higher
- Google AI API key (get one at [Google AI Studio](https://aistudio.google.com/))

### Setup

1. **Clone the repository:**

   ```bash
   git clone <repository-url>
   cd elrond-mcp
   ```

2. **Install dependencies:**

   ```bash
   # Using uv (recommended)
   uv sync --dev --all-extras

   # Or using pip
   pip install -e .[dev]
   ```

3. **Configure API key:**

   ```bash
   export GEMINI_API_KEY="your-gemini-api-key-here"

   # Or create a .env file
   echo "GEMINI_API_KEY=your-gemini-api-key-here" > .env
   ```

## Usage

### Running the Server

#### Development Mode

```bash
# Using uv
uv run python main.py

# Using MCP CLI (if installed)
mcp dev elrond_mcp/server.py
```

#### Production Mode

```bash
# Direct execution
python main.py

# Or via package entry point
elrond-mcp
```

### Integration with Claude Desktop

1. **Install for Claude Desktop:**

   ```bash
   mcp install elrond_mcp/server.py --name "Elrond Thinking Augmentation"
   ```

2. **Manual Configuration:**
   Add to your Claude Desktop MCP settings:
   ```json
   {
     "elrond-mcp": {
       "command": "python",
       "args": ["/path/to/elrond-mcp/main.py"],
       "env": {
         "GEMINI_API_KEY": "your-api-key-here"
       }
     }
   }
   ```

### Using the Tools

#### Augment Thinking Tool

Analyze any proposal through multi-perspective critique:

```
Use the "consult_the_council" tool with this proposal:

# Project Alpha: AI-Powered Customer Service

## Overview
Implement an AI chatbot to handle 80% of customer service inquiries, reducing response time from 2 hours to 30 seconds.

## Goals
- Reduce operational costs by 40%
- Improve customer satisfaction scores
- Free up human agents for complex issues

## Implementation
- Deploy GPT-4 based chatbot
- Integrate with existing CRM
- 3-month rollout plan
- $200K initial investment
```

#### Check System Status Tool

Monitor the health and configuration of the thinking augmentation system:

```
Use the "check_system_status" tool to verify:
- API key configuration
- Model availability
- System health
```

## Response Structure

### Critique Response

Each critique agent provides:

- **Executive Summary**: Brief overview of the perspective
- **Structured Analysis**:
  - Feasibility assessment
  - Risk identification
  - Benefit analysis
  - Implementation considerations
  - Stakeholder impact
  - Resource requirements
- **Key Insights**: 3-5 critical observations
- **Confidence Level**: Numerical confidence (0.0-1.0)

### Synthesis Response

The synthesis agent provides:

- **Executive Summary**: High-level recommendation
- **Consensus View**:
  - Areas of agreement
  - Areas of disagreement
  - Balanced assessment
  - Critical considerations
- **Recommendation**: Overall guidance
- **Next Steps**: Concrete action items
- **Uncertainty Flags**: Areas needing more information
- **Overall Confidence**: Synthesis confidence level

## Development

### Project Structure

```
elrond-mcp/
├── elrond_mcp/
│   ├── __init__.py
│   ├── server.py          # MCP server implementation
│   ├── agents.py          # Critique and synthesis agents
│   ├── client.py          # Centralized Google AI client management
│   └── models.py          # Pydantic data models
├── scripts/               # Development scripts
│   └── check.sh          # Quality check script
├── tests/                 # Test suite
├── main.py               # Entry point
├── pyproject.toml        # Project configuration
└── README.md
```

### Running Tests

```bash
# Using uv
uv run pytest

# Using pip
pytest
```

### Code Formatting

```bash
# Format and lint code
uv run ruff format .
uv run ruff check --fix .

# Type checking
uv run mypy elrond_mcp/
```

### Development Script

For convenience, use the provided script to run all quality checks:

```bash
# Run all quality checks (lint, format, test)
./scripts/check.sh
```

This script will:

- Sync dependencies
- Run Ruff linter with auto-fix
- Format code with Ruff
- Execute the full test suite
- Perform final lint check
- Provide a pre-commit checklist

## Configuration

### Environment Variables

- `GEMINI_API_KEY`: Required Google AI API key
- `LOG_LEVEL`: Logging level (default: INFO)

### Model Configuration

- **Critique Agents**: `gemini-2.5-flash`
- **Synthesis Agent**: `gemini-2.5-pro`

Models can be customized by modifying the agent initialization in `agents.py`.

## Troubleshooting

### Common Issues

1. **API Key Not Found**

   ```
   Error: Google AI API key is required
   ```

   **Solution**: Set the `GEMINI_API_KEY` environment variable

2. **Empty Proposal Error**

   ```
   Error: Proposal cannot be empty
   ```

   **Solution**: Ensure your proposal is at least 10 characters long

3. **Model Rate Limits**

   ```
   Error: Rate limit exceeded
   ```

   **Solution**: Wait a moment and retry, or check your Google AI quota

4. **Validation Errors**
   ```
   ValidationError: ...
   ```
   **Solution**: The LLM response didn't match expected structure. This is usually temporary - retry the request

### Debugging

Enable debug logging:

```bash
export LOG_LEVEL=DEBUG
export GEMINI_API_KEY=your-api-key-here
python main.py
```

Check system status:

```python
# Use the check_system_status tool to verify configuration
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

## License

See LICENSE

## Support

For issues and questions:

- Check the troubleshooting section above
- Review the logs for detailed error information
- Open an issue on the repository

## Roadmap

- [ ] Support for additional LLM providers (OpenAI, Anthropic)
- [ ] Custom critique perspectives and personas
- [ ] Performance optimization and caching
- [ ] Advanced synthesis algorithms