# Model Context Protocol (MCP) Server — FastAPI

A FastAPI-based **MCP Server** that exposes automation and AI tools via both REST API and MCP protocol. Tools cover performance testing (JMeter), security scanning (OWASP ZAP), browser automation (Playwright, Selenium), code review (GitLab), AI code generation (unit tests, scenario tests, API specs), knowledge retrieval (RAG/Knowledge Base), and design collaboration (Miro).

---

## Table of Contents

1. [Prerequisites](#1-prerequisites)
2. [Project Structure](#2-project-structure)
3. [Environment Variables](#3-environment-variables)
4. [Start the Server](#4-start-the-server)
5. [API & MCP Access](#5-api--mcp-access)
6. [Architecture](#6-architecture)
7. [Available Tools (MCP)](#7-available-tools-mcp)
8. [Development](#8-development)

---

---

## 1. Prerequisites

- [Docker](https://docs.docker.com/get-docker/)
- Docker Compose (included with Docker Desktop)

---

## 2. Project Structure

```
├── functions/
│   └── main.py                  # FastAPI entry point; registers all routers; configures MCP
├── routers/                     # One file per domain (REST endpoints)
├── services/                    # Core business logic
├── batch_jobs/
│   ├── base/
│   │   └── subprocess_job_runner.py   # Spawns worker processes; tracks state
│   └── jobs/                    # One job file per async tool
├── schemas/                     # Pydantic request/response models
├── models/                      # DynamoDB models, job registry, OWASP ZAP state
├── constants/
│   └── config.py                # All env-var constants (source of truth)
├── jobs/
│   └── scheduler.py             # APScheduler: background sync jobs
├── prompts/                     # Jinja2 prompt templates (organized by feature)
├── skills/                      # Markdown skill definitions for agent workflows
├── subagents/                   # Agent role documentation for multi-step pipelines
├── ui_s3_manager/               # Sub-app mounted at /ui-s3-manager and /ui-s3
├── data/
│   └── DDL/                     # DynamoDB table creation scripts
├── public/                      # Static files (served at /public)
├── docker/                      # Dockerfiles for fastapi (ZAP uses zaproxy/zap-stable in compose)
├── docker-compose.yml
├── requirements.txt
├── .env.example
└── ruff-guide.md
```

---

## 3. Environment Variables

Copy `.env.example` to `.env` and fill in the required values:

```bash
cp .env.example .env
```

| Variable | Required | Description |
|---|---|---|
| `AWS_REGION` | Yes | AWS region for S3, DynamoDB, Bedrock, etc. |
| `AWS_ACCESS_KEY_ID` | Yes | AWS credentials |
| `AWS_SECRET_ACCESS_KEY` | Yes | AWS credentials |
| `S3_BUCKET_NAME` | Yes | S3 bucket for uploads and report storage |
| GitLab host allowlist | Code | Edit `constants/gitlab_hosts.py` (not `.env`) |
| `GITLAB_TOKEN` | Removed | Replaced by per-request `gitlab_token` field in tool inputs |
| `REDIS_HOST` | Yes* | Redis host for Miro OAuth state and per-user token storage |
| `REDIS_PORT` | Yes* | Redis port (default `6379` in Docker Compose) |
| `AUTH_JWT_SECRET` | Yes | JWT secret for `AuthMiddleware` |
| `AWS_BEDROCK_LLM_MODEL` | Yes | Bedrock model ID (e.g. `anthropic.claude-3-haiku-20240307-v1:0`) |
| `SLACK_HOOK` | No | Slack incoming webhook URL for job notifications |
| `SLACK_CHANNEL` | No | Slack channel for notifications |
| `BACKLOG_DOMAIN` | No | Backlog domain for backlog sync jobs |
| `BACKLOG_API_KEY` | No | Backlog API key |
| `BACKLOG_PROJECT_KEYS` | No | Comma-separated Backlog project keys |
| `LLM_LOCAL_BASE_URL` | No | Base URL for local LLM (e.g. Ollama: `http://localhost:11434`) |
| `LLM_LOCAL_MODEL` | No | Local LLM model name (e.g. `qwen2.5:3b`) |
| `BEDROCK_AGENT_ID` | No | AWS Bedrock Agent ID |
| `BEDROCK_AGENT_ALIAS_ID` | No | AWS Bedrock Agent Alias ID |
| `RAG_INIT_S3_FOLDER` | No | S3 folder to seed the RAG knowledge base on startup |

> `Yes*` = required only when using that specific tool group.

See `.env.example` for all RAG, Selenium, and Redis tuning options.

---

## 4. Start the Server

Use the OS-specific wrapper script instead of calling `docker compose` directly. Each script auto-detects the host architecture and sets the correct platform before delegating to Docker.

### macOS (Intel or Apple Silicon)

**One-time prerequisite for Apple Silicon (M1/M2/M3):**
> Docker Desktop → Settings → General → enable **"Use Rosetta for x86_64/amd64 emulation on Apple Silicon"** → Apply & Restart

**Step 1 — Build and start:**

```bash
# All services
./run.sh up --build

# Minimal setup (fastapi + redis only)
./run.sh up --build fastapi redis

# Run in background
./run.sh up -d fastapi redis
```

On Apple Silicon you will see:
```
[run.sh] Apple Silicon (arm64) detected — running linux/amd64 containers via Rosetta 2 emulation
```

### Windows

```powershell
# All services
.\run.ps1 up --build

# Minimal setup (fastapi + redis only)
.\run.ps1 up --build fastapi redis

# Run in background
.\run.ps1 up -d fastapi redis
```

### Common commands (both OSes)

```bash
# Stop all containers
./run.sh down          # macOS
.\run.ps1 down         # Windows

# View logs
./run.sh logs -f fastapi

# Open a shell inside the container
docker exec -it fastapi_app bash
```

**Step 2 — (One-time) Create DynamoDB tables:**

```bash
docker exec -it fastapi_app python ./data/DDL/create_dynamodb_tables.py
```

**Check container logs:**

```bash
docker logs fastapi_app
```

---

## 5. API & MCP Access

| Interface | URL |
|---|---|
| REST API docs (Swagger) | http://localhost:8000/docs |
| MCP endpoint | http://localhost:8000/mcp |
| S3 File Manager UI | http://localhost:8000/ui-s3-manager |

**Integrate into an LLM client (MCP config):**

```json
{
  "mcpServers": {
    "local-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

---

## 6. Architecture

### Request Flow

```
Client → Router → Service → (optional) Batch Job → DynamoDB / Redis
                                                          ↑
Client polls  GET /api/history/{operation_id}  ───────────┘
```

1. **Router** (`routers/`) — validates the request schema and calls the service.
2. **Service** (`services/`) — core business logic. Short operations (reading rules, file uploads, Miro API calls) return a result immediately. Long-running operations (test execution, security scans, LLM generation) spawn a batch job and return an `operation_id`.
3. **Batch Job** (`batch_jobs/jobs/`) — runs in a subprocess via `SubprocessJobRunner`; writes status to DynamoDB/Redis. Only used for async operations.
4. **Client** — polls `GET /api/history/{operation_id}` (exposed as the `get_result` MCP tool) until the job resolves. Only needed after async operations.

### Infrastructure

| Service | Description | Exposed Port |
|---|---|---|
| `fastapi` | Main app (`fastapi_app`) | `8000` |
| `owaspzap_1–5` | 5 parallel OWASP ZAP instances | `8080` (internal) |
| `redis` | Job state / caching | `6379` |

### LLM Integration

| Service | Description |
|---|---|
| `LLMService` (`services/llm_service.py`) | Direct AWS Bedrock invocations |
| `LLMLocalService` (`services/llm_local_service.py`) | Local LLM via `LLM_LOCAL_BASE_URL` / `LLM_LOCAL_MODEL` |

Model IDs are configured via `AWS_BEDROCK_LLM_MODEL` in `constants/config.py`.

### MCP Exposure

Only operations listed in `include_operations` inside `functions/main.py` are exposed as MCP tools. Endpoints tagged `"allure"` are additionally exposed via `include_tags`.

> When adding a new router endpoint intended for MCP, add its `operation_id` to `include_operations` in `functions/main.py`.

### Authentication

`AuthMiddleware` (`services/auth_service.py`) is applied globally to all routes. JWT secret is configured via `AUTH_JWT_SECRET`.

---

## 7. Available Tools (MCP)

| Domain | Operation IDs |
|---|---|
| **JMeter** | `run_jmeter` |
| **OWASP ZAP** | `scan_owasp_zap`, `scan_owasp_zap_scenario`, `scan_owasp_zap_website` |
| **Playwright** | `get_playwright_scenario_rules`, `run_playwright_e2e`, `run_playwright_converse` |
| **GitLab** | `gitlab_review_merge_request` |
| **Miro** | `create_miro_board`, `get_all_boards`, `get_miro_mermaid_rules`, `draw_miro_board` |
| **Spec Generator** | `get_template_design`, `publish_file`, `publish_file_ui`, `publish_file_via_s3`, `extract_archive`, `ai_generate_spec` |
| **Unit Test Generator** | `ai_generate_unit_test` |
| **Scenario Test Generator** | `generate_scenario_test` |
| **Knowledge Base** | `knowledge_ask` |
| **Allure** | all endpoints tagged `allure` |
| **History** | `get_result`, `stop_operation` |

---

## 8. Development

All linting and formatting commands run **inside the container**:

```bash
# Open a shell in the container
docker exec -it fastapi_app bash

# Lint
ruff check .
ruff check . --fix            # auto-fix
ruff check path/to/file.py

# Format
ruff format .
ruff format path/to/file.py
ruff format . --check         # dry run (no changes)
```