# ProjectBrain MCP
ProjectBrain MCP is a Model Context Protocol (MCP) server for project planning and execution workflows.
It exposes tools for tasks, decisions, facts, milestones, comments, and team messaging through a Streamable HTTP endpoint.

## What it does
- Serves MCP tools over HTTPS at `https://mcp.projectbrain.tools`
- Allows unauthenticated MCP discovery requests for `initialize`, `notifications/initialized`, `ping`, `tools/list`, `resources/list`, `resources/templates/list`, and `prompts/list`
- Authenticates bearer tokens (JWT or API key) for all tool execution and data access
- Provides MCP OAuth metadata endpoints
- Executes tool actions against the ProjectBrain API

## Service endpoints
- `GET /health`
- `GET /.well-known/oauth-protected-resource`
- `GET /.well-known/oauth-authorization-server`
- `POST /`

## Configuration
Set these environment variables:

- `SERVER_URL` (default: `http://localhost:8000`)  
  Base URL of the ProjectBrain API.
- `MCP_SERVER_URL` (default: same as `SERVER_URL`)  
  Public base URL used in OAuth resource metadata.
- `JWT_SECRET_KEY`  
  Secret used to validate JWT bearer tokens.
- `JWT_ALGORITHM` (default: `HS256`)
- `CORS_ORIGINS` (default: `["http://localhost:5173"]`)  
  Accepts either a JSON array or a comma-separated list.
- `MCP_REQUEST_TIMEOUT_SECONDS` (default: `30`)
- `MCP_UNAUTH_DISCOVERY_METHOD_SCAN_BYTES` (default: `8192`)  
  Max unauthenticated request bytes scanned to detect JSON-RPC `method` in lightweight middleware parsing.
- `SENTRY_DSN`  
  Sentry DSN for MCP service error/performance reporting.
- `SENTRY_TRACES_SAMPLE_RATE` (default: `0.2`)  
  Trace sample rate passed to `sentry_sdk.init`.
- `SENTRY_SEND_DEFAULT_PII` (default: `false`)  
  Set to `true` to include richer MCP request/response context with `MCPIntegration` (review data collection implications before enabling).
- `SENTRY_ENVIRONMENT` (optional)  
  Sentry environment tag (for example: `production`, `staging`).

## Local development
From repository root:

1. Install backend dependencies:
   - `cd api && uv sync --locked`
2. Start the MCP server:
   - `PYTHONPATH=mcp api/.venv/bin/uvicorn api_adapter:app --app-dir mcp --host 0.0.0.0 --port 8001`

## Directory structure
- `api_adapter.py` — FastAPI app entrypoint and auth middleware
- `server.py` — MCP tool definitions and HTTP client adapter
- `runtime.py` — runtime config and request-scoped auth context