Multi Agent Architecture System
Production-ready MCP server orchestrating 40+ specialized AI agents for automated software architecture design
Installation
npx multi-agent-architecture-systemAsk AI about Multi Agent Architecture System
Powered by Claude Β· Grounded in docs
I know everything about Multi Agent Architecture System. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Multi-Agent Software Architecture Design System
A production-ready MCP (Model Context Protocol) server that orchestrates 40+ specialized AI agents to automate complete software architecture design processes. Transform business requirements into comprehensive architecture documentation including C4 diagrams, Architecture Decision Records (ADRs), and detailed implementation plans.
Key Features
- 40+ Specialized Agents: Each agent focuses on specific architectural domains (security, data, infrastructure, AI/ML, etc.)
- Automated Architecture Design: From requirements analysis through implementation planning
- Production Documentation: Generates complete architecture blueprints with ADRs, diagrams, and implementation roadmaps
- MCP Server Integration: Works seamlessly with Claude Code and other MCP-compatible tools
- Parallel Orchestration: Executes agents in parallel where possible while respecting dependencies
- Conflict Resolution: Built-in mechanisms to detect and resolve conflicting architectural decisions
- Dynamic Agent Factory: Creates ephemeral agents for emerging technologies not covered by core agents
Architecture Overview
The system follows a multi-agent orchestration pattern with 11 sequential phases:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Server Layer β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Meta-Coordinator Agent β β
β β β’ Request routing & workflow planning β β
β β β’ Agent orchestration (sequential & parallel) β β
β β β’ Conflict detection & resolution β β
β β β’ Context management & state persistence β β
β ββββββββββ¬βββββββββββββββββββββββββββββββββββββββ¬ββββββββ β
β β β β
β ββββββββββΌβββββββββββ βββββββββββΌβββββββββ β
β β Phase 1-10 β β Implementation β β
β β Architecture β β Planning Agent β β
β β Agents (40) β β (Phase 11) β β
β βββββββββββββββββββββ ββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Architecture Phases
- Phase 1 - Strategic Design: Requirements β Domain Design β System Topology
- Phase 2 - Infrastructure: Cloud β Containers β Networking
- Phase 3 - Data & Integration: Data Architecture β Caching β Events β APIs
- Phase 4 - Application: Backend β Frontend
- Phase 5 - AI/ML: AI Orchestrator β LLM β ML Pipeline β Vector DB
- Phase 6 - Security: Security Architecture β IAM β Compliance
- Phase 7 - Resilience: Fault Tolerance β High Availability β Disaster Recovery
- Phase 8 - Performance: Optimization β Scalability β Load Balancing
- Phase 9 - DevOps: CI/CD β IaC β Testing β Release Management
- Phase 10 - Governance: Cost β Tech Debt β Documentation
- Phase 11 - Implementation: Task breakdown and execution planning
Technology Stack
- Language: TypeScript (Node.js 18+)
- Package Manager: npm
- MCP SDK:
@modelcontextprotocol/sdk - LLM Provider:
@anthropic-ai/sdk(configurable) - Validation:
zodfor schema validation - Storage: Postgres + pgvector (coordinator memory) + filesystem for large artifacts
- Testing: Vitest for unit/integration tests
- Code Quality: ESLint + Prettier
Prerequisites
- Node.js 18 or higher
- npm (comes with Node.js)
- Git
- An Anthropic API key (for Claude integration)
- Docker (for local Postgres + pgvector)
Quick Start
Installation
# Clone the repository
git clone https://github.com/chipster6/multi-agent-architecture-system.git
cd multi-agent-architecture-system
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY
Database (Postgres + pgvector)
# Start local Postgres with pgvector
docker compose up -d postgres
Development
# Start development mode with watch
npm run dev
# Type checking
npm run type-check
# Linting and formatting
npm run lint
npm run format
# Run tests
npm test
Production
# Build the project
npm run build
# Start the MCP server
npm start
Project Structure
βββ src/
β βββ index.ts # MCP server entry point
β βββ coordinator/ # Meta-coordinator and workflow engine
β β βββ meta-coordinator.ts # Main orchestration logic
β β βββ workflow-engine.ts # Phase execution engine
β β βββ conflict-resolver.ts # Conflict detection/resolution
β βββ agents/ # 40+ specialized agents organized by phase
β β βββ base-agent.ts # Abstract base class
β β βββ phase-1-strategic/ # Requirements, domain design, topology
β β βββ phase-2-infrastructure/ # Cloud, containers, networking
β β βββ phase-3-data/ # Data architecture, caching, events
β β βββ ... # Additional phases
β βββ tools/ # MCP tool implementations
β βββ shared/ # Common types and utilities
β βββ prompts/ # Agent prompt templates
βββ docs/ # Generated architecture documentation
βββ tests/ # Test suites
βββ scripts/ # Build and utility scripts
Configuration
Environment Variables
Create a .env file in the root directory:
# Required
ANTHROPIC_API_KEY=your_anthropic_api_key_here
# Optional - Server Configuration
LOG_LEVEL=info # Logging verbosity (debug, info, warn, error)
MCP_SERVER_PORT=3000 # Server port (if applicable)
NODE_ENV=development # Environment mode
# Optional - Tool Configuration
TOOL_TIMEOUT_MS=30000 # Default timeout for tool execution (30 seconds)
MAX_CONCURRENT_EXECUTIONS=10 # Maximum concurrent tool executions
MAX_PAYLOAD_BYTES=1048576 # Maximum payload size (1MB)
MAX_STATE_BYTES=1048576 # Maximum agent state size (1MB)
# Optional - Admin Configuration
ADMIN_REGISTRATION_ENABLED=false # Enable admin tool registration
DYNAMIC_REGISTRATION_ENABLED=false # Enable dynamic tool registration
ADMIN_POLICY=deny_all # Admin policy: deny_all | local_stdio_only | token
# Optional - Postgres (coordinator memory + logs)
MCP_DB_HOST=localhost
MCP_DB_PORT=5432
MCP_DB_NAME=mcp
MCP_DB_USER=mcp
MCP_DB_PASSWORD=mcp
# Optional - Embeddings (Gemini)
GEMINI_API_KEY=your_gemini_api_key_here
MCP_EMBEDDINGS_MODEL=gemini-embedding-001
MCP_EMBEDDINGS_DIMENSIONS=1536
Configuration File
Alternatively, create a config.json file in the root directory:
{
"server": {
"name": "multi-agent-architecture-system",
"version": "1.0.0"
},
"tools": {
"defaultTimeoutMs": 30000,
"maxConcurrentExecutions": 10,
"maxPayloadBytes": 1048576,
"adminRegistrationEnabled": false,
"adminPolicy": "deny_all"
},
"security": {
"dynamicRegistrationEnabled": false
},
"logging": {
"level": "info",
"redactKeys": ["password", "apiKey", "token", "secret"]
}
}
Agent Configuration
Agents can be configured per project type and complexity:
- Model Selection: Claude Opus for critical decisions, Sonnet for standard operations
- Orchestration Strategy: API-based for complex agents, prompt-based for simpler ones
- Timeout Settings: Per-agent timeout configuration (default: 30 seconds)
- Retry Policies: Configurable retry logic for LLM calls
- Dynamic Registration: Control whether agents can register new tools at runtime
Usage
As an MCP Server
The system runs as an MCP server that can be integrated with Claude Code or other MCP-compatible tools:
- Start the server:
npm start - Connect your MCP client to the server
- Use the available tools to generate architecture documentation
Available MCP Tools
analyze_requirements: Parse and analyze business requirementsgenerate_architecture: Create complete architecture documentationvalidate_decisions: Check for conflicts and validate architectural decisionscreate_implementation_plan: Generate detailed implementation roadmaphealth: Get server health status and resource telemetryagent/sendMessage: Send messages to specific agentsagent/list: List all registered agentsagent/getState: Get current state of an agent
Tool Registration API
The system provides a flexible tool registration API for extending functionality:
Basic Tool Registration
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import * as z from 'zod';
const server = new McpServer({
name: 'architecture-server',
version: '1.0.0'
});
// Register a tool with input/output schemas
server.registerTool(
'analyze-requirements',
{
title: 'Requirements Analyzer',
description: 'Analyze and structure business requirements',
inputSchema: {
description: z.string().describe('Business requirements description'),
constraints: z.array(z.string()).optional().describe('Technical constraints'),
technologies: z.array(z.string()).optional().describe('Preferred technologies')
},
outputSchema: {
structuredRequirements: z.object({
functional: z.array(z.string()),
nonFunctional: z.array(z.string()),
constraints: z.array(z.string())
}),
recommendations: z.array(z.string())
}
},
async ({ description, constraints = [], technologies = [] }, extra) => {
// Check for cancellation
if (extra.abortSignal?.aborted) {
throw new Error('Operation cancelled');
}
// Tool implementation here
const analysis = await analyzeRequirements(description, constraints, technologies);
// Check again before returning (cooperative cancellation)
if (extra.abortSignal?.aborted) {
throw new Error('Operation cancelled');
}
const output = {
structuredRequirements: analysis.requirements,
recommendations: analysis.recommendations
};
return {
content: [{ type: 'text', text: JSON.stringify(output, null, 2) }],
structuredContent: output
};
}
);
Tool with AbortSignal Handling
server.registerTool(
'long-running-analysis',
{
title: 'Long Running Analysis',
description: 'Perform comprehensive architecture analysis',
inputSchema: {
projectData: z.object({
requirements: z.string(),
scale: z.enum(['small', 'medium', 'large', 'enterprise'])
})
}
},
async ({ projectData }, extra) => {
const { abortSignal } = extra;
// Perform work in chunks, checking for cancellation
for (let phase = 1; phase <= 5; phase++) {
// Check if operation was cancelled
if (abortSignal?.aborted) {
throw new Error(`Analysis cancelled during phase ${phase}`);
}
// Simulate work
await performAnalysisPhase(phase, projectData);
// Log progress (optional)
console.log(`Completed analysis phase ${phase}/5`);
}
return {
content: [{ type: 'text', text: 'Analysis complete' }]
};
}
);
Timeout Semantics
Important: Understanding timeout behavior is crucial for tool authors.
How Timeouts Work
- Server Timeout: When a tool execution exceeds the configured timeout (default: 30 seconds), the server stops waiting and returns a
TIMEOUTerror to the client - Cooperative Cancellation: The server fires an
AbortSignalto notify the tool handler that it should stop work - Handler Continues: The tool handler may continue running after timeout until it checks the
AbortSignaland exits gracefully
Key Points
- Timeout β Termination: A timeout means the server stopped waiting, not that the work stopped
- Resource Slots: Concurrency slots are held until the handler actually returns, even after timeout
- Late Completion: If a handler completes after timeout, it's logged but no response is sent to the client
- Cooperative: Handlers should regularly check
abortSignal.abortedand exit promptly when cancelled
Best Practices for Tool Authors
async function longRunningTool({ data }, { abortSignal }) {
const results = [];
for (const item of data.items) {
// Check for cancellation before each iteration
if (abortSignal?.aborted) {
throw new Error('Operation cancelled');
}
// Perform work
const result = await processItem(item);
results.push(result);
// For very long operations, check periodically
if (results.length % 100 === 0 && abortSignal?.aborted) {
throw new Error('Operation cancelled');
}
}
return { content: [{ type: 'text', text: JSON.stringify(results) }] };
}
Timeout Configuration
# Environment variable
TOOL_TIMEOUT_MS=45000 # 45 seconds
# Or in config.json
{
"tools": {
"defaultTimeoutMs": 45000
}
}
Example Workflow
// 1. Analyze requirements
const requirements = await analyzeRequirements({
description: 'E-commerce platform with AI recommendations',
constraints: ['PCI compliance', '99.9% uptime', 'global scale'],
technologies: ['Node.js', 'React', 'AWS'],
});
// 2. Generate architecture
const architecture = await generateArchitecture({
requirements,
preferences: {
cloudProvider: 'AWS',
architectureStyle: 'microservices',
},
});
// 3. Get implementation plan
const plan = await createImplementationPlan({
architecture,
timeline: '6 months',
teamSize: 8,
});
Testing
# Run all tests
npm test
# Run specific test suites
npm run test:unit # Unit tests only
npm run test:integration # Integration tests
npm run test:e2e # End-to-end workflow tests
# Run tests with coverage
npm run test:coverage
Documentation
Target Users
- Software Architects: Designing new systems with comprehensive documentation
- Development Teams: Needing architecture guidance and standardization
- Organizations: Standardizing architecture practices across teams
- Consultants: Providing architecture services with automated documentation
System Scope
In Scope
- Requirements analysis and translation
- Architecture style selection and justification
- Technology stack recommendations
- Security and compliance architecture
- Performance and scalability design
- Implementation planning and task breakdown
Out of Scope
- Actual code implementation
- Project management beyond architecture tasks
- Business strategy or product decisions
- Detailed UI/UX design
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
- Create an issue for bug reports or feature requests
- Check the documentation for detailed guides
- Review existing discussions for common questions
Acknowledgments
- Built on the Model Context Protocol (MCP)
- Powered by Anthropic's Claude
- Inspired by the C4 model for software architecture documentation
