┌─────────────────────────┐  ┌─────────────────────────┐  ┌─────────────────────────┐  ┌─────────────────────────┐
│     🎯 DECISIONS        │  │     ⚖️ TRADE-OFFS       │  │     ⚠️ ISSUES           │  │     🔧 FIXES & IMPACT   │
│  Why this architecture  │  │  Gains vs. Sacrifices   │  │ Real failures & bugs    │  │ Measured results        │
└─────────────────────────┘  └─────────────────────────┘  └─────────────────────────┘  └─────────────────────────┘

Baseline Accuracy: [████████████░░░░░░░░] 64.0%
Optimized Accuracy: [████████████████████] 100.0%  (+36% Increase)

Adversarial Pass:  [████████████████████] 100.0%  (20/20 Attack Mitigation)
Unit Test Pass:    [████████████████████] 53/53 Passed

flowchart TD
    LLM[LLM / Claude Desktop] <-->|stdio / sse transport| MCP[FastMCP Server\nserver.py]
    MCP --> Logger[Structured Audit Logger\ntool_calls.log]
    MCP --> Tracer[Execution Tracer\ntracer.py → traces.jsonl]
    MCP --> Tools[13 Registered Tools]

    subgraph CoreTools [Core Tools — 9]
        T1[get_open_issues]
        T2[search_issues]
        T3[create_issue]
        T4[add_label]
        T5[close_issue]
        T6[bulk_label_stale_issues]
        T7[triage_issue]
        T8[get_rate_limit_status]
        T13[list_repositories]
    end

    subgraph AdvancedTools [Advanced Tools — 4]
        T9[semantic_search_issues]
        T10[undo_last_action]
        T11[get_transaction_history]
        T12[get_trace_history]
    end

    T3 & T4 & T5 --> PE[PolicyEngine\npolicy_engine.py]
    T3 & T9 --> VE[VectorEngine\nvector_engine.py]
    T3 & T4 & T5 --> TJ[TransactionJournal\ntransaction_journal.py]
    T10 & T11 --> TJ
    T12 --> Tracer
    T7 --> Sandbox[Untrusted XML Sandbox] --> Ollama[Local Ollama\nllama3.2:1b]
    T6 --> Tokens[SHA256 Preview Token\n5-min TTL]
    
    GHC[GitHubClient\ngithub_client.py] <-->|CircuitBreaker + Backoff| CB[circuit_breaker.py]
    CB --> GHAPI[GitHub REST API]
    CoreTools --> GHC

github-mcp-toolkit/
├── .github/
│   └── workflows/
│       └── docker-ci.yml        # CI/CD pipeline: pytest + 100-eval + Docker build
├── server.py                    # FastMCP server entrypoint (stdio & sse transports)
├── github_client.py             # PyGithub client wrapper (retry, backoff, circuit breaker)
├── circuit_breaker.py           # Per-instance CLOSED/OPEN/HALF_OPEN state machine
├── vector_engine.py             # Pure-Python TF-IDF cosine similarity engine
├── transaction_journal.py       # Saga pattern write mutation journal
├── policy_engine.py             # ABAC declarative policy engine
├── tracer.py                    # OpenTelemetry-inspired span execution tracer
├── schemas.py                   # Pydantic response schema contracts
├── policy.json                  # System policy rules (editable without redeploy)
├── Dockerfile                   # Production container definition (SSE transport ready)
├── docker-compose.yml           # Stack orchestration service
├── tools/
│   ├── get_open_issues.py
│   ├── search_issues.py
│   ├── create_issue.py          # Policy + Vector + Saga + Tracer + Schema
│   ├── add_label.py             # Policy + Saga integrated
│   ├── close_issue.py           # Policy + Saga integrated
│   ├── bulk_label_stale_issues.py  # 2-Phase preview token flow
│   ├── triage_issue.py          # Untrusted data XML sandbox + Ollama
│   ├── get_rate_limit_status.py # Pydantic schema validated
│   ├── list_repositories.py     # Accessible repository listing
│   ├── semantic_search_issues.py
│   ├── undo_last_action.py
│   ├── get_transaction_history.py
│   └── get_trace_history.py
├── eval/
│   ├── run_eval.py              # 100-query dual evaluation benchmark runner
│   ├── test_queries.json        # 80 standard natural-language queries
│   └── adversarial_queries.json # 20 adversarial prompt injection test cases
└── tests/
    ├── conftest.py              # Isolated PyGithub client fixtures
    ├── test_github_client.py    # Client layer tests
    ├── test_tools.py            # Tool guardrail integration tests
    └── test_advanced_features.py # 45 unit tests (Vector, Saga, Policy, CircuitBreaker, Tracer, Schemas)

# Clone repository
git clone https://github.com/kartik-012/GitHub-MCP-Toolkit.git
cd GitHub-MCP-Toolkit

# Setup virtual environment
python -m venv venv
venv\Scripts\activate       # Windows
# source venv/bin/activate  # Linux/macOS

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env and set GITHUB_TOKEN=ghp_...

{
  "mcpServers": {
    "github-mcp-toolkit": {
      "command": "C:/path/to/venv/Scripts/python.exe",
      "args": ["C:/path/to/GitHub-MCP-Toolkit/server.py"]
    }
  }
}

# Build and launch container stack
docker compose up -d

# Verify server logs
docker compose logs -f

# Run all 53 unit and integration tests
python -m pytest tests/ -v

# Run 100-query dual benchmark harness (80 standard + 20 adversarial)
python eval/run_eval.py

==============================================================
  GitHub MCP Toolkit — Tool Selection Evaluation Harness
==============================================================

[STANDARD]    Standard Benchmark (80 queries)
    Correct Tool Selection : 80/80 (100.0%)

[ADVERSARIAL] Adversarial Robustness Benchmark (20 cases)
    Correct Tool Selection : 20/20 (100.0%) [PASS]