2a84cd2865
Updated README and metadata for job-hunting focus: - Lead with "Production-ready" (recruiter keyword) - Feature-focused opening (not metaphor-focused) - Organized sections: Security, Architecture, Support - Professional tone throughout - Technical depth emphasized - Clear use cases and statistics pyproject.toml description updated to match. Positioning: serious engineer, production mindset, comprehensive docs. LinkedIn/Medium will use different voice for different audiences. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
178 lines
4.9 KiB
Markdown
178 lines
4.9 KiB
Markdown
# MCP Multiagent Bridge
|
|
|
|
Production-ready Python MCP server for secure multi-agent coordination with comprehensive safeguards.
|
|
|
|
## Overview
|
|
|
|
Enables multiple LLM agents (Claude, Codex, GPT, etc.) to collaborate safely through the Model Context Protocol without sharing workspaces or credentials. Built with security-first architecture and production-grade safeguards.
|
|
|
|
**Use cases:**
|
|
- Backend agent coordinating with frontend agent on different codebases
|
|
- Security review agent validating changes from development agent
|
|
- Specialized agents collaborating on complex multi-step workflows
|
|
- Any scenario requiring isolated agents to communicate securely
|
|
|
|
---
|
|
|
|
## Key Features
|
|
|
|
### 🔒 Security Architecture
|
|
|
|
**Authentication & Authorization:**
|
|
- HMAC-SHA256 session token authentication
|
|
- Automatic secret redaction (API keys, passwords, tokens, private keys)
|
|
- 3-hour session expiration with automatic cleanup
|
|
- SQLite WAL mode for atomic, race-condition-free operations
|
|
|
|
**4-Stage YOLO Guard™:**
|
|
Command execution (optional) requires multiple confirmation layers:
|
|
1. Environment gate - explicit `YOLO_MODE=1` opt-in
|
|
2. Interactive typed confirmation phrase
|
|
3. One-time validation code (prevents automation)
|
|
4. Time-limited approval tokens (5-minute TTL, single-use)
|
|
|
|
**Rate Limiting:**
|
|
- Token bucket algorithm with configurable windows
|
|
- Default: 10 requests/minute, 100/hour, 500/day
|
|
- Per-session tracking with automatic reset
|
|
- Prevents abuse while allowing legitimate bursts
|
|
|
|
**Audit Trail:**
|
|
- Comprehensive JSONL logging of all operations
|
|
- Timestamps, session IDs, actions, results
|
|
- Tamper-evident sequential logging
|
|
- Supports compliance and forensic analysis
|
|
|
|
### 🏗️ Production-Ready Architecture
|
|
|
|
- **Message-only bridge** - No auto-execution, returns proposals only
|
|
- **Schema validation** - Strict JSON schemas for all MCP tools
|
|
- **Command validation** - Configurable whitelist/blacklist patterns
|
|
- **Comprehensive error handling** - Graceful degradation, informative errors
|
|
- **Extensible design** - Plugin architecture for future backends
|
|
|
|
### 📦 Platform Support
|
|
|
|
**Works with any MCP-compatible LLM:**
|
|
- Claude Code, Claude Desktop, Claude API
|
|
- OpenAI models (via MCP adapters)
|
|
- Anthropic API models
|
|
- Custom/future models (not tied to specific backend)
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone https://github.com/dannystocker/mcp-multiagent-bridge.git
|
|
cd mcp-multiagent-bridge
|
|
|
|
# Install dependencies
|
|
pip install mcp>=1.0.0
|
|
|
|
# Run tests
|
|
python test_security.py
|
|
```
|
|
|
|
Full setup: See [QUICKSTART.md](QUICKSTART.md)
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
**Getting Started:**
|
|
- [QUICKSTART.md](QUICKSTART.md) - 5-minute setup guide
|
|
- [EXAMPLE_WORKFLOW.md](EXAMPLE_WORKFLOW.md) - Real-world collaboration scenarios
|
|
|
|
**Security & Compliance:**
|
|
- [SECURITY.md](SECURITY.md) - Threat model, responsible disclosure policy
|
|
- [YOLO_MODE.md](YOLO_MODE.md) - Command execution safety guide
|
|
- Policy compliance: Anthropic AUP, OpenAI Usage Policies
|
|
|
|
**Contributing:**
|
|
- [CONTRIBUTING.md](CONTRIBUTING.md) - Development setup, PR workflow
|
|
- [LICENSE](LICENSE) - MIT License
|
|
|
|
---
|
|
|
|
## Technical Stack
|
|
|
|
- **Python 3.11+** - Modern Python with type hints
|
|
- **SQLite** - Atomic operations with WAL mode
|
|
- **MCP Protocol** - Model Context Protocol integration
|
|
- **pytest** - Comprehensive test suite
|
|
- **CI/CD** - GitHub Actions (tests, security scanning, linting)
|
|
|
|
---
|
|
|
|
## Project Statistics
|
|
|
|
- **Lines of Code:** ~5,200 (including tests + documentation)
|
|
- **Test Coverage:** Core security components verified
|
|
- **Documentation:** 2,000+ lines across 7 markdown files
|
|
- **Dependencies:** 1 (mcp, pinned for reproducibility)
|
|
- **License:** MIT
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dev dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Install pre-commit hooks
|
|
pip install pre-commit
|
|
pre-commit install
|
|
|
|
# Run test suite
|
|
pytest
|
|
|
|
# Run security tests
|
|
python test_security.py
|
|
```
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for complete development workflow.
|
|
|
|
---
|
|
|
|
## Security Notice
|
|
|
|
⚠️ **Beta Software**: Designed for development/testing environments with human supervision.
|
|
|
|
**Recommended for:**
|
|
- Development and testing workflows
|
|
- Isolated workspaces
|
|
- Human-supervised operations
|
|
- Prototype multi-agent systems
|
|
|
|
**Not recommended for:**
|
|
- Production systems without additional safeguards
|
|
- Unattended automation
|
|
- Critical infrastructure
|
|
- Environments with untrusted agents
|
|
|
|
See [SECURITY.md](SECURITY.md) for complete security considerations and threat model.
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
- **Issues:** [GitHub Issues](https://github.com/dannystocker/mcp-multiagent-bridge/issues)
|
|
- **Discussions:** [GitHub Discussions](https://github.com/dannystocker/mcp-multiagent-bridge/discussions)
|
|
- **Security:** See [SECURITY.md](SECURITY.md) for responsible disclosure
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT License - Copyright © 2025 Danny Stocker
|
|
|
|
See [LICENSE](LICENSE) for full terms.
|
|
|
|
---
|
|
|
|
## Acknowledgments
|
|
|
|
Built with [Claude Code](https://docs.claude.com/claude-code) and [Model Context Protocol](https://modelcontextprotocol.io/).
|