MCP Tools - Multi-Server Architecture
A modular FastMCP server architecture providing development tools, analytics, and reporting for Claude Code integration.
🏗️ Architecture Overview
MCP Tools uses a multi-server composition architecture with three specialized servers:
- 🎯 Coordinator (
localhost:8002) - Main orchestration server that composes tools and reports - 🛠️ Tools (
localhost:8003) - Development workflow automation (PR analysis, code review, JIRA) - 📈 Reports (
localhost:8004) - Performance analytics and reporting (quarterly reports, metrics)
All servers can run independently or composed together through the coordinator using FastMCP's mount() pattern.
🚀 Quick Start
Container-First Deployment (Recommended)
# Start all services
./scripts/start.sh
# Check status
./scripts/status.sh
# Stop all services
./scripts/stop.sh
# Add to Claude Code (coordinator endpoint)
claude mcp add mcp-tools http://localhost:8002/mcp/ --transport http --scope user
Development Setup
# Install dependencies
poetry install
# Run coordinator (mounts all servers)
poetry run python coordinator/server.py
# Or run individual servers
poetry run python tools/server.py # Tools only (port 8003)
poetry run python reports/server.py # Reports only (port 8004)
📊 Service Endpoints
| Service | Port | Health Check | Purpose |
|---|---|---|---|
| Coordinator | 8002 | http://localhost:8002/health | Main composition server |
| Tools | 8003 | http://localhost:8003/health | Development workflows |
| Reports | 8004 | http://localhost:8004/health | Analytics & reporting |
🛠️ Available Tools (14 Core Tools)
Development Workflow Tools (Tools Server)
1. PR Health (pr_health)
Analyzes PR health including open review threads, CI status, and merge readiness.
- Input: GitHub PR URL, optional description
- Output: Comprehensive health analysis with actionable solutions
- Example:
"pr_health https://github.com/owner/repo/pull/123"
2. Code Review (code_review)
Performs comprehensive code quality review with security and performance analysis.
- Input: GitHub PR URL, optional focus area, max diff lines
- Output: Structured code quality assessment
- Example:
"code_review https://github.com/owner/repo/pull/123 security"
3. Tech Design Review (tech_design_review)
Reviews technical design documents with architecture and implementation analysis.
- Input: Document URL (Confluence/GitHub), optional focus area
- Output: Design review with architecture recommendations
- Example:
"tech_design_review https://company.atlassian.net/wiki/pages/123456"
4. JIRA Transition (jira_transition)
Automates JIRA workflow transitions with intelligent state management.
- Input: Ticket ID, target state (supports aliases: "dev", "review", "qa", "done")
- Output: JIRA transition instructions with Atlassian MCP integration
- Example:
"jt SI-1234 start"or"jira_transition SI-1234 development"
5. Get JIRA Transitions (get_jira_transitions)
Calculates optimal transition paths between JIRA statuses.
- Input: From status, optional to status
- Output: Step-by-step transition path with MCP commands
- Example:
"get_jira_transitions 'Open' 'In Development'"
6. Epic Status Report (epic_status_report)
Generates comprehensive epic status with sub-task analysis and progress tracking.
- Input: Epic ticket ID, optional focus area
- Output: Epic progress analysis with assignee action items
- Example:
"epic_status_report SI-9038"
Analytics & Reporting Tools (Reports Server)
7. Quarterly Team Report (quarterly_team_report)
Generates comprehensive quarterly team performance reports with anonymized metrics.
- Input: Team prefix, year, quarter, optional description
- Output: Team analysis using JIRA and GitHub data
- Example:
"quarterly_team_report SI 2025 2"
8. Quarter-over-Quarter Analysis (quarter_over_quarter_analysis)
Analyzes team performance trends and size changes across multiple quarters.
- Input: Team prefix, period (e.g., "2024", "2023-2025")
- Output: Multi-quarter trend analysis with team composition tracking
- Example:
"quarter_over_quarter_analysis SI 2024"
9. Personal Quarterly Report (personal_quarterly_report)
Generates individual contributor performance reports for personal development.
- Input: Team prefix, year, quarter
- Output: Personal performance analysis with growth recommendations
- Example:
"personal_quarterly_report SI 2025 2"
10. Personal Quarter-over-Quarter (personal_quarter_over_quarter)
Analyzes personal performance trends and growth across multiple time periods.
- Input: Team prefix, period
- Output: Personal growth analysis with development insights
- Example:
"personal_quarter_over_quarter SI 2024"
System & Utility Tools
11. Setup Prerequisites (setup_prerequisites)
Validates and sets up all prerequisites required by MCP Tools.
- Output: Comprehensive validation with setup instructions
- Features: GitHub CLI, JIRA access, tool availability checks
12. Check Tool Requirements (check_tool_requirements)
Checks specific prerequisites for individual MCP tools.
- Input: Tool name
- Output: Tool-specific validation results
13. Echo (echo)
Simple connectivity test for MCP communication validation.
14. Get System Info (get_system_info)
System diagnostics and server health monitoring.
🐳 Container Architecture
Multi-Stage Dockerfiles
- Builder Stage: Poetry dependency installation
- Production Stage: Minimal runtime with non-root user
- Multi-arch: Supports AMD64 and ARM64 architectures
Container Features
- Health Checks: Built-in
/healthendpoints for all services - Security: Non-root user execution
- Logging: Structured logging with configurable levels
- Networking: Isolated bridge network for service communication
Docker Compose Services
services:
mcp-coordinator: # Main orchestration (port 8002)
mcp-tools: # Development tools (port 8003)
mcp-reports: # Analytics server (port 8004)
🔧 Development & Deployment
Environment Variables
| Variable | Default | Description |
|---|---|---|
MCP_SERVER_PORT | 8002/8003/8004 | Server port |
LOG_LEVEL | INFO | Logging level |
MOUNT_TOOLS | true | Mount tools server (coordinator only) |
MOUNT_REPORTS | true | Mount reports server (coordinator only) |
Container Management
# Build all containers
podman-compose build
# Start with logs
podman-compose up
# Background mode
podman-compose up -d
# Check status
podman-compose ps
# View logs
podman-compose logs -f mcp-coordinator
🎯 Integration Patterns
Claude Code Integration
# Primary endpoint (coordinator with all tools)
claude mcp add mcp-tools http://localhost:8002/mcp/ --transport http --scope user
# Individual servers (if needed)
claude mcp add mcp-tools-dev http://localhost:8003/mcp/ --transport http --scope user
claude mcp add mcp-reports http://localhost:8004/mcp/ --transport http --scope user
Workflow Examples
# Complete development workflow
claude "jt SI-1234 start -> pr_health https://github.com/owner/repo/pull/123 -> code_review same_url"
# Quarterly reporting workflow
claude "quarterly_team_report SI 2025 2 -> personal_quarterly_report SI 2025 2"
# Epic management workflow
claude "epic_status_report SI-9038 -> jt SI-1234 start -> create implementation plan"
🚨 Alpha Development Status
MCP Tools is currently in alpha development:
- ⚠️ Not production ready - features and accuracy not guaranteed
- 🔬 Internal use only - data validation required
- 📊 Report outputs require manual verification
- 🔄 Format and structure may change without notice
🏗️ Architecture Benefits
Modularity
- Independent Deployment: Each server can run standalone
- Specialized Concerns: Development tools vs. reporting separated
- Scalable: Add new servers without modifying existing ones
FastMCP Composition
- Server Mounting: Coordinator mounts specialized servers
- Unified Interface: Single endpoint with all tools
- Service Discovery: Automatic tool registration and health monitoring
Container-First Design
- Production Ready: Multi-stage builds with security best practices
- Orchestration: Docker Compose with networking and health checks
- Portability: Runs consistently across development and production environments
Requirements: Python 3.11+, Poetry, Podman/Docker, Git, curl, jq