Recursive Companion MCP

🚀 Recursive Companion MCP

An MCP (Model Context Protocol) server that implements iterative refinement through self-critique cycles. It adds incremental processing to avoid timeouts and enable progress visibility.

🚀 Quick Start

The Recursive Companion MCP is an MCP server inspired by Hank Besser's recursive-companion. It implements iterative refinement through self - critique cycles and adds incremental processing to avoid timeouts and make progress visible.

✨ Features

• Incremental Refinement: Breaks refinement into discrete steps to avoid timeouts.
• Mathematical Convergence: Uses cosine similarity to measure the completion of refinement.
• Domain - Specific Optimization: Auto - detects and optimizes for technical, marketing, strategy, legal, and financial domains.
• Progress Visibility: Each step returns immediately, allowing UI updates.
• Parallel Sessions: Supports multiple concurrent refinement sessions.
• Auto Session Tracking: No need for manual session ID management.
• AI - Friendly Error Handling: Provides actionable diagnostics and recovery hints for AI assistants.

💻 Usage Examples

Basic Usage

The refinement process follows a Draft → Critique → Revise → Converge pattern:

1. **Draft**: Generate initial response
2. **Critique**: Create multiple parallel critiques (using faster models)
3. **Revise**: Synthesize critiques into improved version
4. **Converge**: Measure similarity and repeat until threshold reached

Advanced Usage

The tool provides several MCP endpoints:

- Use start_refinement to refine: "Explain the key principles of secure API design"
- Use continue_refinement with session_id "abc123..."
- Use get_final_result with session_id "abc123..."
- Use get_refinement_status to check progress without advancing
- Use list_refinement_sessions to see all active sessions

📦 Installation

Prerequisites

• Python 3.10+
• uv package manager
• AWS Account with Bedrock access
• Claude Desktop app

Setup

1. Clone the repository:

git clone https://github.com/yourusername/recursive-companion-mcp.git
cd recursive-companion-mcp

2. Install dependencies:

uv sync

3. Configure AWS credentials as environment variables or through AWS CLI.
4. Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "recursive-companion": {
      "command": "/path/to/recursive-companion-mcp/run_server.sh",
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "your-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret",
        "BEDROCK_MODEL_ID": "anthropic.claude-3-sonnet-20240229-v1:0",
        "CRITIQUE_MODEL_ID": "anthropic.claude-3-haiku-20240307-v1:0",
        "CONVERGENCE_THRESHOLD": "0.95",
        "PARALLEL_CRITIQUES": "2",
        "MAX_ITERATIONS": "5",
        "REQUEST_TIMEOUT": "600"
      }
    }
  }
}

📚 Documentation

Configuration

Performance

With optimized settings:

• Each iteration takes 60 - 90 seconds.
• Typical convergence occurs in 2 - 3 iterations.
• Total time is 2 - 4 minutes (distributed across multiple calls). Using Haiku for critiques reduces iteration time by ~50%.

AI - Friendly Features

This tool includes special features for AI assistants:

• Auto Session Tracking: The current_session_id is automatically maintained.
• Smart Error Messages: Errors include _ai_ prefixed fields with actionable diagnostics.
• Performance Hints: Responses include optimization tips and predictions.
• Progress Predictions: Convergence tracking includes estimates of remaining iterations.

Example AI - helpful error response:

{
  "success": false,
  "error": "No session_id provided and no current session",
  "_ai_context": {
    "current_session_id": null,
    "active_session_count": 2,
    "recent_sessions": [...]
  },
  "_ai_suggestion": "Use start_refinement to create a new session",
  "_human_action": "Start a new refinement session first"
}

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Claude    │────▶│  MCP Server  │────▶│   Bedrock   │
│  Desktop    │◀────│              │◀────│   Claude    │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │   Session    │
                    │   Manager    │
                    └──────────────┘

Development

Running tests

uv run pytest tests/

Local testing

uv run python test_incremental.py

Attribution

This project is inspired by recursive - companion by Hank Besser. The original implementation provided the conceptual Draft → Critique → Revise → Converge pattern. This MCP version adds:

• Session - based incremental processing to avoid timeouts.
• AWS Bedrock integration for Claude and Titan embeddings.
• Domain auto - detection and specialized prompts.
• Mathematical convergence measurement.
• Support for different models for critiques vs generation.

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

MIT License - see LICENSE file for details.

Acknowledgments

• Original concept: Hank Besser's recursive - companion
• Built for the Model Context Protocol
• Uses AWS Bedrock for LLM access
• Inspired by iterative refinement patterns in AI reasoning