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
2. Project Structure
3. Environment Variables
4. Start the Server
5. API & MCP Access
6. Architecture
7. Available Tools (MCP)
8. Development

---

---

1. Prerequisites

• 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:

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:

# 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

# 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)

# 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:

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

Check container logs:

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):

{
  "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:

# 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)