# Architecture
This document describes the high-level architecture of the MCP GitHub & Jira integration.

## System Diagram

```mermaid
graph TD
    MCP["MCP Server<br/>(FastMCP Framework)"]
    
    MCP --> GHTools["GitHub Tools"]
    MCP --> JiraTools["Jira Tools"]
    
    GHTools --> GHT1["create_branch"]
    GHTools --> GHT2["commit_and_push"]
    GHTools --> GHT3["create_pr"]
    GHTools --> GHT4["merge_pr"]
    
    JiraTools --> JT1["get_issue"]
    JiraTools --> JT2["search_issues"]
    JiraTools --> JT3["get_my_issues"]
    JiraTools --> JT4["transition_issue"]
    
    GHT1 --> GHAPI["GitHub API<br/>(httpx.Async)"]
    GHT2 --> GHAPI
    GHT3 --> GHAPI
    GHT4 --> GHAPI
    
    JT1 --> JiraAPI["Jira API<br/>(httpx.Async)"]
    JT2 --> JiraAPI
    JT3 --> JiraAPI
    JT4 --> JiraAPI
    
    GHAPI --> GHREST["GitHub REST API<br/>(github.com)"]
    JiraAPI --> JiraREST["Jira REST API<br/>(atlassian.net)"]
```

## Component Flow

### 1. Tool Registration Layer
Each tool is registered with the MCP server via the `@mcp.tool()` decorator.

```
User Request
    ↓
MCP Server receives tool call
    ↓
Route to registered tool function
    ↓
Execute async tool function
    ↓
Return result to user
```

### 2. Tool Layer (src/tools/)
Tools orchestrate the workflow:
- Accept user parameters
- Validate inputs
- Call provider APIs
- Format and return results

Example: `github_create_branch`
```
Input: issue_key, branch_name (optional)
    ↓
Get repo config (extract owner/repo)
    ↓
Fetch base branch SHA (github_api_get)
    ↓
Create new branch (github_api_post)
    ↓
Return: branch ref + commit SHA
```

### 3. Provider Layer (src/providers/)
Low-level API clients for GitHub & Jira:

**GitHub Provider:**
- `github_api_get()` - GET requests with auth headers
- `github_api_post()` - POST requests with JSON body
- `github_api_put()` - PUT requests for merges
- Uses `httpx.AsyncClient` for async HTTP

**Jira Provider:**
- `jira_api_get()` - GET requests with Basic Auth
- `jira_api_post()` - POST requests (search, transitions)
- Uses `httpx.AsyncClient` for async HTTP

### 4. Config Layer (src/config/)
Load and validate environment variables:
- `github_config.py` - GITHUB_REPO_URL, GITHUB_TOKEN, GITHUB_DEFAULT_BRANCH
- `jira_config.py` - JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN
- Provide helper functions like `extract_repo_info()`

## Async Flow

All providers use async I/O with `httpx.AsyncClient`:

```
Tool calls: await github_api_get(...)
    ↓
Provider function awaits httpx response
    ↓
HTTP request sent (non-blocking)
    ↓
Response received
    ↓
Tool processes result
    ↓
Return to MCP Server
```

Benefits:
- Multiple concurrent requests don't block
- Better resource utilization
- Faster response times for parallel operations

## Testing Strategy

Tests use mocking to avoid real API calls:

```
Test calls: asyncio.run(tool(...))
    ↓
Tool code runs with mocked providers
    ↓
Mocks return predefined responses (AsyncMock)
    ↓
Assertions verify tool called API correctly
    ↓
No network traffic, fast & repeatable
```

Key mocking pattern:
```python
with patch('src.tools.jira_tools.jira_get_issue.jira_api_get', 
           new=AsyncMock(return_value={"key": "KAN-1"})):
    result = asyncio.run(tool("KAN-1"))
    # Assert mock was called with correct params
```

## Error Handling

Tools validate and provide clear error messages:

- **Config errors** → ValueError (missing env vars)
- **API errors** → ValueError (404, 422, etc.)
- **Merge conflicts** → ValueError (PR not mergeable)
- **Validation errors** → ValueError (invalid transitions, missing reviews)