project-synapse

Project Synapse is a production-oriented multi-agent system that demonstrates Model Context Protocol (MCP) capabilities alongside Agent Communication Protocol (ACP). The primary MCP server is a FastAPI-based service that coordinates tools and access to a secure filesystem within a controlled environment. The system exposes endpoints for agent coordination, tool execution, and secure data exchange, all backed by a RabbitMQ message bus for asynchronous communication. You can run the primary server to bootstrap the MCP environment and observe how agents interact to perform tasks, validate results, and persist output through the secure file operations agent.

To use the server, ensure the message bus and API service are accessible. The server coordinates agents such as the orchestrator, search, extraction, validation, synthesis, file storage, and logger agents. These agents collaborate to fulfill complex research workflows, e.g., discovery, content processing, and report generation, with security enforced by MCP roots and filesystem boundaries. Interact with the HTTP API to trigger tasks, monitor progress, and retrieve results. The monitoring components provide observability through logs and metrics, enabling performance assessment and troubleshooting.

Prerequisites:

• Python 3.9+ installed on your system
• Git installed
• Optional: Docker and Docker Compose for production deployments

Install and run locally:

1. Clone the repository: git clone https://github.com/YanCotta/project-synapse.git cd project-synapse

2. Install Python dependencies (in a virtual environment): python -m venv venv source venv/bin/activate pip install -r requirements.txt

3. Run the primary MCP server (development / local run): python -m src.mcp_servers.fastapi_primary_server

4. (Optional) Run with Docker Compose for a production-like setup: docker-compose up --build

5. Verify the API is responding (default port may be 8000): curl http://localhost:8000/health

Prerequisites for production deployment:

• A running RabbitMQ broker
• Docker and Docker Compose
• Configured environment (MCP_ROOT, RABBITMQ_URL, appropriate resource limits)

Notes:

• The repository includes Kubernetes manifests under k8s/ for deployment in a cluster.
• For development, you can run the Python module directly as shown above.

Tips and common considerations:

• MCP Roots enforce filesystem boundaries; ensure MCP_ROOT points to a permitted location and that your agents request only approved paths.
• The system relies on RabbitMQ; ensure the broker is reachable at the configured RABBITMQ_URL and that credentials are secured in production.
• Enable monitoring and logging to observe agent interactions and performance metrics; reference the monitoring directory for dashboards and configurations.
• If you switch to Docker/Kubernetes, use the provided manifests and adjust resource limits to fit your environment.
• When updating code, rebuild the container images or restart services to pick up changes in agents or MCP server logic.