# Implementing MCP in the CQA Test App

This document outlines the implementation of Model Context Protocol (MCP) server in the CQA Test Application, including the challenges faced, architectural decisions, and final solution.

## Table of Contents

- [Overview](#overview)
- [Initial Approach: Integrated MCP Server](#initial-approach-integrated-mcp-server)
- [Challenges and Problems](#challenges-and-problems)
- [Final Solution: Standalone MCP Server](#final-solution-standalone-mcp-server)
- [Architecture](#architecture)
- [Adding New MCP Tools](#adding-new-mcp-tools)
- [Testing](#testing)
- [Deployment](#deployment)
- [Troubleshooting](#troubleshooting)

## Overview

The goal was to implement MCP (Model Context Protocol) server capabilities to provide Jira integration tools that can be consumed by MCP clients like Claude Code. The implementation went through several iterations before settling on the final architecture.

### Requirements

- Provide Jira operations through MCP protocol
- Maintain existing Flask application functionality
- Support easy addition of new MCP tools
- Ensure proper environment configuration
- Enable containerized deployment

## Initial Approach: Integrated MCP Server

Initially, we attempted to integrate the MCP server directly into the existing Flask application to minimize infrastructure complexity.

### Attempt 1: Using flask-mcp-server Package

We first tried using the `flask-mcp-server` package to embed MCP capabilities within the Flask app.

**Implementation:**
```python
from flask_mcp_server import mount_mcp
from flask import Flask

app = Flask(__name__)
mount_mcp(app, mcp_server_instance, path="/mcp")
```

**Problems Encountered:**
- The package didn't implement the standard MCP `initialize` method
- Limited documentation and examples
- Incompatibility with our existing Flask Blueprint structure
- Error: "Method not implemented" for basic MCP operations

### Attempt 2: Manual JSON-RPC Implementation

We then implemented manual JSON-RPC handling within Flask blueprints.

**Implementation:**
```python
@bp.route('/mcp', methods=['POST'])
def mcp_handler():
    data = request.get_json()
    method = data.get('method')
    
    if method == "initialize":
        # Manual implementation
    elif method == "tools/list":
        # Manual schema generation
    elif method == "tools/call":
        # Manual tool execution
```

**Problems:**
- Over 100 lines of boilerplate code for JSON-RPC handling
- Manual schema generation for each tool
- Complex error handling
- Difficult to maintain and extend

### Attempt 3: FastMCP Integration with Flask

We attempted to use FastMCP alongside Flask using Werkzeug's DispatcherMiddleware.

**Implementation:**
```python
from werkzeug.middleware.dispatcher import DispatcherMiddleware
from fastmcp import FastMCP

mcp = FastMCP("Service")
dispatcher = DispatcherMiddleware(flask_app, {'/mcp': mcp})
```

**Problems:**
- `AttributeError: 'dict' object has no attribute 'startswith'`
- Complex async/sync integration issues
- Middleware conflicts with existing Flask setup
- Difficult debugging and error tracing

## Challenges and Problems

### Technical Challenges

1. **Protocol Complexity**: MCP requires specific JSON-RPC 2.0 implementation with exact message formats
2. **Schema Generation**: Converting Python function signatures to MCP tool schemas
3. **Error Handling**: Proper MCP error codes and message formatting
4. **Session Management**: Handling MCP session initialization and state

### Integration Issues

1. **Flask Blueprint Conflicts**: MCP endpoints conflicted with existing Flask routes
2. **Middleware Complexity**: WSGI middleware caused unexpected behaviors
3. **Async/Sync Mismatch**: FastMCP's async nature didn't integrate well with Flask
4. **Dependency Conflicts**: Package version incompatibilities

### Architectural Concerns

1. **Single Point of Failure**: Embedding MCP in Flask meant both services fail together
2. **Resource Sharing**: Both services competing for the same resources
3. **Deployment Complexity**: Harder to scale and deploy independently
4. **Testing Difficulty**: Complex setup for testing individual components

## Final Solution: Standalone MCP Server

After multiple failed attempts at integration, we decided to implement a standalone MCP server that runs independently from the Flask application.

### Architecture Decision

**Separate Services Approach:**
- Flask App: Handles web UI, REST APIs, and core application logic
- MCP Server: Dedicated FastMCP server for MCP protocol operations
- Shared Libraries: Common code (Jira client, utilities) used by both services

### Implementation

**1. Standalone MCP Server (`mcp_server.py`):**
```python
import os
import logging
from dotenv import load_dotenv
from products.mcp.jira import get_jira_mcp_server

# Load environment variables
load_dotenv()

def main():
    # Get FastMCP server instance
    mcp_server = get_jira_mcp_server()
    
    # Run on port 8001
    mcp_server.run(transport="http", host="0.0.0.0", port=8001, path="/mcp")
```

**2. Jira MCP Tools (`products/mcp/jira.py`):**
```python
from fastmcp import FastMCP
from lib.jira_client import JiraClient

jira_mcp = FastMCP("CQA Jira MCP Server")
jira_client = JiraClient()

@jira_mcp.tool
def jira_list_projects():
    """List all accessible Jira projects"""
    return jira_client.list_projects()

@jira_mcp.tool
def jira_search_issues(jql, max_results=50):
    """Search Jira issues using JQL query"""
    return jira_client.search_issues(jql, max_results)

# ... more tools
```

**3. Jira Client (`lib/jira_client.py`):**
```python
class JiraClient:
    def __init__(self):
        # Initialize with environment variables
        # Support both Personal Token and Username/API Token
        
    def list_projects(self):
        # Implementation
        
    def search_issues(self, jql, max_results=50):
        # Implementation
```

### Benefits of Standalone Approach

1. **Simplicity**: FastMCP handles all MCP protocol complexity
2. **Independence**: Services can be deployed and scaled separately  
3. **Maintainability**: Clear separation of concerns
4. **Reliability**: Failure in one service doesn't affect the other
5. **Development**: Easier testing and debugging

## Architecture

### Standalone FastMCP Server Architecture

```
🔧 Independent FastMCP Server Architecture:

┌─────────────────┐    ┌─────────────────┐
│   Flask App     │    │  FastMCP Server │
│   Port 10345    │    │   Port 8001     │
│                 │    │                 │
│ /test           │    │ /mcp (JSON-RPC) │
│ /run_cmd        │    │ - initialize    │
│ /api/app_runner │    │ - tools/list    │
│ /api/jira/*     │    │ - tools/call    │
│ /monitor/*      │    │                 │
│ ...             │    │ Jira Tools:     │
│                 │    │ - list_projects │
│                 │    │ - search_issues │
│                 │    │ - get_issue     │
│                 │    │ - get_comments  │
│                 │    │ - create_issue  │
└─────────────────┘    └─────────────────┘
        │                       │
        └───────────────────────┘
           Same server instance
         Running on different ports
```

### Service Structure

```
CQA Test App Ecosystem
├── Flask App (Port 10345)
│   ├── Web UI
│   ├── REST APIs
│   ├── Health checks
│   └── Legacy functionality
│
├── MCP Server (Port 8001)
│   ├── FastMCP instance
│   ├── Jira tools
│   └── Future MCP modules
│
└── Shared Libraries
    ├── lib/jira_client.py
    ├── lib/auth.py
    └── common/context.py
```

### Communication Flow

```
MCP Client (Claude Code)
        │
        ▼ HTTP POST /mcp
┌─────────────────┐
│  FastMCP Server │ ──┐
│   (Port 8001)   │   │
└─────────────────┘   │
        │              │ Shared Libraries
        ▼              │ & Environment
┌─────────────────┐   │
│   Jira Client   │ ◄─┘
│  (lib/jira_*)   │
└─────────────────┘
        │
        ▼ HTTPS API
┌─────────────────┐
│   Jira Server   │
│ (External API)  │
└─────────────────┘
```

### Environment Variables

**Required for MCP Server:**
```bash
# Jira Configuration
JIRA_URL=https://your-domain.atlassian.net
JIRA_PERSONAL_TOKEN=your_personal_token

# Optional Server Configuration
MCP_PORT=8001
MCP_HOST=0.0.0.0
```

### Docker Configuration

**Flask App (`Dockerfile`):** Existing configuration
**MCP Server (`Dockerfile.mcp`):**
```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY lib/ ./lib/
COPY products/mcp/ ./products/mcp/
COPY mcp_server.py .

ENV MCP_PORT=8001
ENV PYTHONPATH=/app

EXPOSE 8001
HEALTHCHECK CMD curl -f http://localhost:8001/health || exit 1

CMD ["python", "mcp_server.py"]
```

## Adding New MCP Tools

The modular architecture makes it easy to add new MCP tools or integrate with other services.

### Current Jira Tools

The implemented Jira tools include:

1. **`jira_list_projects`**: List all accessible Jira projects
2. **`jira_search_issues`**: Search issues using JQL queries
3. **`jira_get_issue`**: Get detailed information about a specific issue
4. **`jira_get_comments`**: Retrieve comments for an issue
5. **`jira_create_issue`**: Create new Jira issues

### Adding New Jira Tools

To add a new Jira tool to the existing module:

**1. Add method to JiraClient (`lib/jira_client.py`):**
```python
def update_issue(self, issue_key, fields):
    """Update an existing Jira issue"""
    if not self.is_connected():
        return {"error": "Not connected to Jira"}
    
    try:
        issue = self.jira.issue(issue_key)
        issue.update(fields=fields)
        return {
            "key": issue_key,
            "status": "Updated successfully"
        }
    except Exception as e:
        logger.error(f"Error updating issue {issue_key}: {e}")
        return {"error": str(e)}
```

**2. Add MCP tool (`products/mcp/jira.py`):**
```python
@jira_mcp.tool
def jira_update_issue(issue_key, summary=None, description=None):
    """Update an existing Jira issue
    
    Args:
        issue_key: Jira issue key (e.g., PROJ-123)
        summary: New summary (optional)
        description: New description (optional)
    """
    logger.info(f"Updating Jira issue: {issue_key}")
    
    fields = {}
    if summary:
        fields['summary'] = summary
    if description:
        fields['description'] = description
        
    return jira_client.update_issue(issue_key, fields)
```

### Adding New Service Modules

To integrate with other services (e.g., GitHub, Slack), create a new module:

**1. Create service client (`lib/github_client.py`):**
```python
import os
import logging
from github import Github

class GitHubClient:
    def __init__(self):
        self.github = None
        self.connected = False
        self._initialize_client()
    
    def _initialize_client(self):
        token = os.getenv("GITHUB_TOKEN")
        if token:
            try:
                self.github = Github(token)
                # Test connection
                self.github.get_user().login
                self.connected = True
                logger.info("Connected to GitHub")
            except Exception as e:
                logger.error(f"Failed to connect to GitHub: {e}")
    
    def list_repositories(self):
        """List user repositories"""
        if not self.connected:
            return {"error": "Not connected to GitHub"}
        
        try:
            repos = []
            for repo in self.github.get_user().get_repos():
                repos.append({
                    "name": repo.name,
                    "full_name": repo.full_name,
                    "description": repo.description,
                    "private": repo.private,
                    "language": repo.language
                })
            return {"repositories": repos, "count": len(repos)}
        except Exception as e:
            return {"error": str(e)}
```

**2. Create MCP module (`products/mcp/github.py`):**
```python
import os
import logging
from fastmcp import FastMCP
from lib.github_client import GitHubClient

logger = logging.getLogger(__name__)

# Check required environment variables
required_env_vars = ["GITHUB_TOKEN"]
missing_vars = [var for var in required_env_vars if not os.getenv(var)]

if missing_vars:
    logger.warning(f"Missing required environment variables: {missing_vars}")

# Initialize GitHub client
github_client = GitHubClient()

# Create FastMCP instance
github_mcp = FastMCP("CQA GitHub MCP Server")

@github_mcp.tool
def github_list_repos():
    """List user repositories"""
    logger.info("Executing github_list_repos")
    return github_client.list_repositories()

@github_mcp.tool
def github_get_repo(repo_name):
    """Get repository information
    
    Args:
        repo_name: Repository name (e.g., owner/repo)
    """
    logger.info(f"Getting repository: {repo_name}")
    return github_client.get_repository(repo_name)

def get_github_mcp_server():
    """Get the configured GitHub MCP server instance"""
    return github_mcp

def get_mcp_info():
    """Get MCP server information"""
    return {
        "server_name": "cqa-github-mcp",
        "server_version": "1.0.0",
        "github_connected": github_client.connected,
    }
```

**3. Update package initialization (`products/mcp/__init__.py`):**
```python
from .jira import get_jira_mcp_server, get_mcp_info as get_jira_info
from .github import get_github_mcp_server, get_mcp_info as get_github_info

__all__ = ['get_jira_mcp_server', 'get_github_mcp_server']

def get_all_mcp_modules():
    """Get information about all available MCP modules"""
    return {
        "jira": {
            "description": "Jira issue management and project operations",
            "server_available": True,
            "info": get_jira_info()
        },
        "github": {
            "description": "GitHub repository and issue management",
            "server_available": True,
            "info": get_github_info()
        }
    }
```

**4. Create multi-service MCP server (optional):**
```python
# mcp_server_multi.py
from products.mcp.jira import get_jira_mcp_server
from products.mcp.github import get_github_mcp_server

# You could combine multiple FastMCP instances
# or run separate servers on different ports
```

### Module Template

Use `products/mcp/template.py` as a starting point for new services. It provides:

- Standard FastMCP setup
- Environment variable checking
- Logging configuration
- Error handling patterns
- Documentation structure

---

*Continue to the next section for testing...*