References the original recursive-companion repository as inspiration, with this implementation adding incremental processing capabilities
Recursive Companion MCP
An MCP (Model Context Protocol) server that implements iterative refinement through self-critique cycles. Inspired by Hank Besser's recursive-companion, this implementation adds incremental processing to avoid timeouts and enable progress visibility.
Features
- Incremental Refinement: Avoids timeouts by breaking refinement into discrete steps
- Mathematical Convergence: Uses cosine similarity to measure when refinement is complete
- 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: Support for multiple concurrent refinement sessions
- Auto Session Tracking: No manual session ID management needed
- AI-Friendly Error Handling: Actionable diagnostics and recovery hints for AI assistants
How It Works
The refinement process follows a Draft → Critique → Revise → Converge pattern:
- Draft: Generate initial response
- Critique: Create multiple parallel critiques (using faster models)
- Revise: Synthesize critiques into improved version
- Converge: Measure similarity and repeat until threshold reached
Installation
Prerequisites
- Python 3.10+
- uv package manager
- AWS Account with Bedrock access
- Claude Desktop app
Setup
- Clone the repository:
- Install dependencies:
- Configure AWS credentials as environment variables or through AWS CLI
- Add to Claude Desktop config (
~/Library/Application Support/Claude/claude_desktop_config.json
):
Usage
The tool provides several MCP endpoints:
Start a refinement session
Continue refinement step by step
Get final result
Other tools
get_refinement_status
- Check progress without advancinglist_refinement_sessions
- See all active sessions
Configuration
Environment Variable | Default | Description |
---|---|---|
BEDROCK_MODEL_ID | anthropic.claude-3-sonnet-20240229-v1:0 | Main generation model |
CRITIQUE_MODEL_ID | Same as BEDROCK_MODEL_ID | Model for critiques (use Haiku for speed) |
CONVERGENCE_THRESHOLD | 0.98 | Similarity threshold for convergence (0.90-0.99) |
PARALLEL_CRITIQUES | 3 | Number of parallel critiques per iteration |
MAX_ITERATIONS | 10 | Maximum refinement iterations |
REQUEST_TIMEOUT | 300 | Timeout in seconds |
Performance
With optimized settings:
- Each iteration: 60-90 seconds
- Typical convergence: 2-3 iterations
- Total time: 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 using it:
- 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:
Architecture
Development
Running tests
Local testing
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
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
An MCP server that implements iterative refinement of responses through self-critique cycles, breaking the process into discrete steps to avoid timeouts and show progress.
Related MCP Servers
- AsecurityAlicenseAqualityAn adaptation of the MCP Sequential Thinking Server designed to guide tool usage in problem-solving. This server helps break down complex problems into manageable steps and provides recommendations for which MCP tools would be most effective at each stage.Last updated -11,188304TypeScriptMIT License
- -securityAlicense-qualityAn MCP server that reviews code with the sarcastic and cynical tone of a grumpy senior developer, helping identify issues in PRs and providing feedback on code quality.Last updated -618JavaScriptMIT License
- -securityFlicense-qualityAn advanced MCP server that implements sophisticated sequential thinking using a coordinated team of specialized AI agents (Planner, Researcher, Analyzer, Critic, Synthesizer) to deeply analyze problems and provide high-quality, structured reasoning.Last updated -216Python
- AsecurityAlicenseAqualityAn advanced MCP server that provides interactive feedback mechanisms with support for various feedback types, multi-language capabilities, and team collaboration features for AI tools like Cursor, Cline, and Windsurf.Last updated -41PythonMIT License