Felipe Cardoso
6e3cdebbfb
- Added the following ADRs to `docs/adrs/` directory: - ADR-001: MCP Integration Architecture - ADR-002: Real-time Communication Architecture - ADR-003: Background Task Architecture - ADR-004: LLM Provider Abstraction - ADR-005: Technology Stack Selection - Each ADR details the context, decision drivers, considered options, final decisions, and implementation plans. - Documentation aligns technical choices with architecture principles and system requirements for Syndarix.
135 lines
3.7 KiB
Markdown
135 lines
3.7 KiB
Markdown
# ADR-001: MCP Integration Architecture
|
||
|
||
**Status:** Accepted
|
||
**Date:** 2025-12-29
|
||
**Deciders:** Architecture Team
|
||
**Related Spikes:** SPIKE-001
|
||
|
||
---
|
||
|
||
## Context
|
||
|
||
Syndarix requires integration with multiple external services (LLM providers, Git, issue trackers, file systems, CI/CD). The Model Context Protocol (MCP) was identified as the standard for tool integration in AI applications. We need to decide on:
|
||
|
||
1. The MCP framework to use
|
||
2. Server deployment pattern (singleton vs per-project)
|
||
3. Scoping mechanism for multi-project/multi-agent access
|
||
|
||
## Decision Drivers
|
||
|
||
- **Simplicity:** Minimize operational complexity
|
||
- **Resource Efficiency:** Avoid spawning redundant processes
|
||
- **Consistency:** Unified interface across all integrations
|
||
- **Scalability:** Support 10+ concurrent projects
|
||
- **Maintainability:** Easy to add new MCP servers
|
||
|
||
## Considered Options
|
||
|
||
### Option 1: Per-Project MCP Servers
|
||
Spawn dedicated MCP server instances for each project.
|
||
|
||
**Pros:**
|
||
- Complete isolation between projects
|
||
- Simple access control (project owns server)
|
||
|
||
**Cons:**
|
||
- Resource heavy (7 servers × N projects)
|
||
- Complex orchestration
|
||
- Difficult to share cross-project resources
|
||
|
||
### Option 2: Unified Singleton MCP Servers (Selected)
|
||
Single instance of each MCP server type, with explicit project/agent scoping.
|
||
|
||
**Pros:**
|
||
- Resource efficient (7 total servers)
|
||
- Simpler deployment
|
||
- Enables cross-project learning (if desired)
|
||
- Consistent management
|
||
|
||
**Cons:**
|
||
- Requires explicit scoping in all tools
|
||
- Shared state requires careful design
|
||
|
||
### Option 3: Hybrid (MCP Proxy)
|
||
Single proxy that routes to per-project backends.
|
||
|
||
**Pros:**
|
||
- Balance of isolation and efficiency
|
||
|
||
**Cons:**
|
||
- Added complexity
|
||
- Routing overhead
|
||
|
||
## Decision
|
||
|
||
**Adopt Option 2: Unified Singleton MCP Servers with explicit scoping.**
|
||
|
||
All MCP servers are deployed as singletons. Every tool accepts `project_id` and `agent_id` parameters for:
|
||
- Access control validation
|
||
- Audit logging
|
||
- Context filtering
|
||
|
||
## Implementation
|
||
|
||
### MCP Server Registry
|
||
|
||
| Server | Port | Purpose |
|
||
|--------|------|---------|
|
||
| LLM Gateway | 9001 | Route LLM requests with failover |
|
||
| Git MCP | 9002 | Git operations across providers |
|
||
| Knowledge Base MCP | 9003 | RAG and document search |
|
||
| Issues MCP | 9004 | Issue tracking operations |
|
||
| File System MCP | 9005 | Workspace file operations |
|
||
| Code Analysis MCP | 9006 | Static analysis, linting |
|
||
| CI/CD MCP | 9007 | Pipeline operations |
|
||
|
||
### Framework Selection
|
||
|
||
Use **FastMCP 2.0** for all MCP server implementations:
|
||
- Decorator-based tool registration
|
||
- Built-in async support
|
||
- Compatible with SSE transport
|
||
- Type-safe with Pydantic
|
||
|
||
### Tool Signature Pattern
|
||
|
||
```python
|
||
@mcp.tool()
|
||
def tool_name(
|
||
project_id: str, # Required: project scope
|
||
agent_id: str, # Required: calling agent
|
||
# ... tool-specific params
|
||
) -> Result:
|
||
validate_access(agent_id, project_id)
|
||
log_tool_usage(agent_id, project_id, "tool_name")
|
||
# ... implementation
|
||
```
|
||
|
||
## Consequences
|
||
|
||
### Positive
|
||
- Single deployment per MCP type simplifies operations
|
||
- Consistent interface across all tools
|
||
- Easy to add monitoring/logging centrally
|
||
- Cross-project analytics possible
|
||
|
||
### Negative
|
||
- All tools must include scoping parameters
|
||
- Shared state requires careful design
|
||
- Single point of failure per MCP type (mitigated by multiple instances)
|
||
|
||
### Neutral
|
||
- Requires MCP client manager in FastAPI backend
|
||
- Authentication handled internally (service tokens for v1)
|
||
|
||
## Compliance
|
||
|
||
This decision aligns with:
|
||
- FR-802: MCP-first architecture requirement
|
||
- NFR-201: Horizontal scalability requirement
|
||
- NFR-602: Centralized logging requirement
|
||
|
||
---
|
||
|
||
*This ADR supersedes any previous decisions regarding MCP architecture.*
|