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

🛠️ 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 /health endpoints 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

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