mcp-tools

dlightyupgrade/mcp-tools

3.1

If you are the rightful owner of mcp-tools and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

MCP Tools is a server with new_ws workstream integration tools built on the official TypeScript SDK, featuring streaming HTTP transport.

Tools
1
Resources
0
Prompts
0

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

ServicePortHealth CheckPurpose
Coordinator8002http://localhost:8002/healthMain composition server
Tools8003http://localhost:8003/healthDevelopment workflows
Reports8004http://localhost:8004/healthAnalytics & 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 /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

VariableDefaultDescription
MCP_SERVER_PORT8002/8003/8004Server port
LOG_LEVELINFOLogging level
MOUNT_TOOLStrueMount tools server (coordinator only)
MOUNT_REPORTStrueMount 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