README.md•12.1 kB
# Recursive Companion MCP
[](https://github.com/thinkerz-ai/recursive-companion-mcp/actions)
[](https://codecov.io/gh/thinkerz-ai/recursive-companion-mcp)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)
An MCP (Model Context Protocol) server that implements iterative refinement through self-critique cycles. Inspired by [Hank Besser's recursive-companion](https://github.com/hankbesser/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:
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
For detailed architecture diagrams and system design documentation, see [ARCHITECTURE.md](ARCHITECTURE.md).
## Installation
### Prerequisites
- Python 3.10+
- [uv](https://github.com/astral-sh/uv) package manager
- AWS Account with Bedrock access
- Claude Desktop app
### Setup
1. Clone the repository:
```bash
git clone https://github.com/thinkerz-ai/recursive-companion-mcp.git
cd recursive-companion-mcp
```
2. Install dependencies:
```bash
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`):
**Basic Configuration:**
```json
{
"mcpServers": {
"recursive-companion": {
"command": "/path/to/recursive-companion-mcp/run.sh",
"env": {
"AWS_REGION": "us-east-1",
"AWS_ACCESS_KEY_ID": "your-access-key",
"AWS_SECRET_ACCESS_KEY": "your-secret-key"
}
}
}
}
```
**Optimized Configuration (Recommended):**
```json
{
"mcpServers": {
"recursive-companion": {
"command": "/path/to/recursive-companion-mcp/run.sh",
"env": {
"AWS_REGION": "us-east-1",
"AWS_ACCESS_KEY_ID": "your-access-key",
"AWS_SECRET_ACCESS_KEY": "your-secret-key",
"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"
}
}
}
}
```
**Performance Tips:**
- Use Haiku for `CRITIQUE_MODEL_ID` for 50% speed improvement
- Lower `CONVERGENCE_THRESHOLD` to 0.95 for faster convergence
- Reduce `PARALLEL_CRITIQUES` to 2 for better resource usage
- See [API_EXAMPLES.md](API_EXAMPLES.md) for more configuration examples
## Usage
The tool provides several MCP endpoints for iterative refinement:
### Quick Start Examples
**Simple refinement (auto-complete):**
```bash
quick_refine(prompt="Explain the key principles of secure API design", max_wait=60)
```
**Step-by-step refinement (full control):**
```bash
# Start session
start_refinement(prompt="Design a microservices architecture for e-commerce", domain="technical")
# Continue iteratively
continue_refinement() # Draft phase
continue_refinement() # Critique phase
continue_refinement() # Revision phase
# Get final result
get_final_result()
```
**Session management:**
```bash
current_session() # Check active session
list_refinement_sessions() # List all sessions
abort_refinement() # Stop and get best result so far
```
### Complete API Reference
For comprehensive examples with realistic scenarios, error handling patterns, and integration workflows, see **[API_EXAMPLES.md](API_EXAMPLES.md)**.
### Available Tools
- `start_refinement` - Begin new refinement session with domain detection
- `continue_refinement` - Advance session through draft→critique→revise cycles
- `get_final_result` - Retrieve completed refinement
- `get_refinement_status` - Check progress without advancing
- `current_session` - Get active session info (no ID needed)
- `list_refinement_sessions` - See all active sessions
- `abort_refinement` - Stop refinement, return best version so far
- `quick_refine` - Auto-complete simple refinements (under 60s)
## 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 |
## 🌐 Streamable HTTP Transport
The server supports a stateless Streamable HTTP transport for enterprise deployments requiring horizontal scalability and web-based integration.
### Enable Streamable HTTP Transport
```bash
# Set transport type to streamable_http
export MCP_TRANSPORT=streamable_http
export MCP_HTTP_HOST=127.0.0.1 # Optional, defaults to 127.0.0.1
export MCP_HTTP_PORT=8080 # Optional, defaults to 8080
# Run the server
uv run python -m recursive_companion_mcp
```
Or in a single command:
```bash
MCP_TRANSPORT=streamable_http MCP_HTTP_PORT=8080 uv run python -m recursive_companion_mcp
```
### Streamable HTTP Features
- ✅ **Stateless Request Handling**: New server instance per request for complete isolation
- ✅ **Session Persistence**: Sessions maintained across requests via session IDs
- ✅ **JSON-RPC 2.0 Compliant**: Full MCP protocol support over HTTP
- ✅ **Enterprise Scalability**: Horizontal scaling with load balancers
- ✅ **Web Integration**: Perfect for web-based AI assistants
- ✅ **Health Checks**: Built-in health check endpoints
### Example HTTP Request
```bash
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "start_refinement",
"arguments": {
"topic": "Improve this algorithm design",
"style": "analytical"
}
},
"id": 1
}'
```
### Transport Modes Comparison
| Feature | Stdio Transport | HTTP Transport | Streamable HTTP Transport |
|---------|----------------|----------------|--------------------------|
| **Use Case** | Claude Desktop | Network access | Enterprise scalability |
| **State Management** | In-memory | In-memory | Stateless per request |
| **Session Persistence** | No | No | Yes (via session IDs) |
| **Load Balancing** | No | No | Yes |
| **Web Integration** | No | Limited | Full support |
## 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:
```json
{
"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
```bash
uv run pytest tests/
```
### Local testing
```bash
uv run python test_incremental.py
```
### Automation Infrastructure
This project includes comprehensive automation for OSS readiness:
- **🤖 Dependabot**: Automated dependency updates with intelligent grouping
- **🚀 Semantic Release**: Automated versioning and releases based on conventional commits
- **🔒 Security Monitoring**: Multi-tool security scanning (Safety, Bandit, CodeQL, Trivy)
- **✅ Quality Gates**: Automated testing, coverage, linting, and type checking
- **📦 Dependency Management**: Advanced dependency health monitoring and updates
#### Automation Commands
```bash
# Verify automation setup
uv run python scripts/setup_check.py
# Validate workflow configurations
uv run python scripts/validate_workflows.py
# Manual release (if needed)
uv run semantic-release version --noop # dry run
uv run semantic-release version --minor # actual release
```
#### Development Workflow
1. **Feature Development**: Work on feature branches
2. **Pull Requests**: Quality gates run automatically
3. **Code Review**: Automated security and quality feedback
4. **Merge to develop**: Beta releases created automatically
5. **Merge to main**: Production releases created automatically
See [AUTOMATION.md](AUTOMATION.md) for complete automation documentation.
## Attribution
This project is inspired by [recursive-companion](https://github.com/hankbesser/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](CONTRIBUTING.md) for details.
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgments
- Original concept: [Hank Besser's recursive-companion](https://github.com/hankbesser/recursive-companion)
- Built for the [Model Context Protocol](https://github.com/anthropics/mcp)
- Uses AWS Bedrock for LLM access
- Inspired by iterative refinement patterns in AI reasoning