diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index f421c93..d43ef7c 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -33,6 +33,7 @@ export default defineConfig({ { text: 'DAST Scanning', link: '/features/dast' }, { text: 'AI Chat (RAG)', link: '/features/ai-chat' }, { text: 'Issue Tracker Integration', link: '/features/issues' }, + { text: 'MCP Server', link: '/features/mcp-server' }, ], }, { diff --git a/docs/deployment/environment.md b/docs/deployment/environment.md index 2df4c33..b6b782e 100644 --- a/docs/deployment/environment.md +++ b/docs/deployment/environment.md @@ -75,6 +75,15 @@ REDIRECT_URI=http://localhost:8080/auth/callback APP_URL=http://localhost:8080 ``` +## MCP Server + +```bash +MONGODB_URI=mongodb://root:example@localhost:27017/compliance_scanner?authSource=admin +MONGODB_DATABASE=compliance_scanner +# Set to enable HTTP transport (omit for stdio) +MCP_PORT=8090 +``` + ## Observability ```bash diff --git a/docs/features/mcp-server.md b/docs/features/mcp-server.md new file mode 100644 index 0000000..1eb65bf --- /dev/null +++ b/docs/features/mcp-server.md @@ -0,0 +1,155 @@ +# MCP Server + +The Model Context Protocol (MCP) server exposes compliance data to external LLMs and AI agents. Any MCP-compatible client — such as Claude, Cursor, or a custom agent — can connect and query findings, SBOM data, and DAST results without direct database access. + +## How It Works + +The `compliance-mcp` crate runs as a standalone service that connects to the same MongoDB database as the agent and dashboard. It registers a set of **tools** that LLM clients can discover and call through the MCP protocol. + +``` +LLM Client ──MCP──▶ compliance-mcp ──MongoDB──▶ compliance_scanner DB +``` + +The server supports two transport modes: + +| Transport | Use Case | How to Enable | +|-----------|----------|---------------| +| **Stdio** | Local development, piped to a CLI tool | Default (no `MCP_PORT` set) | +| **Streamable HTTP** | Remote deployment, multiple clients | Set `MCP_PORT=8090` | + +## Available Tools + +The MCP server exposes seven tools: + +### Findings + +| Tool | Description | +|------|-------------| +| `list_findings` | Query findings with optional filters for repository, severity, status, and scan type. Returns up to 200 results (default 50). | +| `get_finding` | Retrieve a single finding by its MongoDB ObjectId. | +| `findings_summary` | Get finding counts grouped by severity and status, optionally filtered by repository. | + +### SBOM + +| Tool | Description | +|------|-------------| +| `list_sbom_packages` | List SBOM packages with filters for repository, vulnerabilities, package manager, and license. | +| `sbom_vuln_report` | Generate a vulnerability report for a repository showing all packages with known CVEs. | + +### DAST + +| Tool | Description | +|------|-------------| +| `list_dast_findings` | Query DAST findings with filters for target, scan run, severity, exploitability, and vulnerability type. | +| `dast_scan_summary` | Get a summary of recent DAST scan runs and finding counts. | + +## Running Locally + +### Stdio Mode + +Run the MCP server directly — it reads from stdin and writes to stdout: + +```bash +cd compliance-mcp +cargo run +``` + +Configure your MCP client to launch it as a subprocess. For example, in a Claude Code `mcp.json`: + +```json +{ + "mcpServers": { + "compliance": { + "command": "cargo", + "args": ["run", "-p", "compliance-mcp"], + "cwd": "/path/to/compliance-scanner" + } + } +} +``` + +### HTTP Mode + +Set `MCP_PORT` to start the Streamable HTTP server: + +```bash +MCP_PORT=8090 cargo run -p compliance-mcp +``` + +The server listens on `http://0.0.0.0:8090/mcp`. Point your MCP client to this endpoint. + +## Configuration + +| Variable | Description | Default | +|----------|-------------|---------| +| `MONGODB_URI` | MongoDB connection string | `mongodb://localhost:27017` | +| `MONGODB_DATABASE` | Database name | `compliance_scanner` | +| `MCP_PORT` | Port for HTTP transport (omit for stdio) | — | +| `RUST_LOG` | Log level filter | `compliance_mcp=info` | + +Create a `.env` file in the project root or set these as environment variables. + +## Deploying with Docker + +The `Dockerfile.mcp` builds and runs the MCP server in HTTP mode on port 8090. + +```bash +docker build -f Dockerfile.mcp -t compliance-mcp . +docker run -p 8090:8090 \ + -e MONGODB_URI=mongodb://mongo:27017 \ + -e MONGODB_DATABASE=compliance_scanner \ + -e MCP_PORT=8090 \ + compliance-mcp +``` + +### Coolify Deployment + +1. Create a new service in your Coolify project +2. Set the **Dockerfile path** to `Dockerfile.mcp` +3. Set the **exposed port** to `8090` +4. Add environment variables: `MONGODB_URI`, `MONGODB_DATABASE`, `MCP_PORT=8090` +5. The MCP endpoint will be available at your configured domain under `/mcp` + +The CI pipeline automatically deploys on changes to `compliance-core/`, `compliance-mcp/`, `Dockerfile.mcp`, or `Cargo.toml`/`Cargo.lock`. Add the `COOLIFY_WEBHOOK_MCP` secret to your Gitea repository. + +## Managing MCP Servers in the Dashboard + +Navigate to **MCP Servers** in the dashboard sidebar to: + +- **Register** MCP server instances with their endpoint URL, transport type, port, and database connection +- **View** server configuration, enabled tools, and status +- **Manage access tokens** — reveal, copy, or regenerate bearer tokens for authentication +- **Delete** servers that are no longer needed + +Each registered server is assigned a random access token on creation. Use this token in your MCP client configuration for authenticated access. + +## Example: Querying Findings from an LLM + +Once connected, an LLM can call any of the registered tools. For example: + +**"Show me all critical findings"** triggers `list_findings` with `severity: "critical"`: + +```json +{ + "tool": "list_findings", + "arguments": { + "severity": "critical", + "limit": 10 + } +} +``` + +**"What vulnerable packages does repo X have?"** triggers `sbom_vuln_report`: + +```json +{ + "tool": "sbom_vuln_report", + "arguments": { + "repo_id": "683abc..." + } +} +``` + +::: tip +The MCP server is read-only — it only queries data from MongoDB. It cannot modify findings, trigger scans, or change configuration. This makes it safe to expose to external LLM clients. +::: diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index 17ef92c..fc322c9 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -97,6 +97,17 @@ NVD_API_KEY=your-nvd-api-key Get a free key at [https://nvd.nist.gov/developers/request-an-api-key](https://nvd.nist.gov/developers/request-an-api-key). +## MCP Server + +The MCP server exposes compliance data to external LLMs via the Model Context Protocol. See [MCP Server](/features/mcp-server) for full details. + +```bash +# Set MCP_PORT to enable HTTP transport (omit for stdio mode) +MCP_PORT=8090 +``` + +The MCP server shares the `MONGODB_URI` and `MONGODB_DATABASE` variables with the rest of the platform. + ## Clone Path Where the agent stores cloned repository files: @@ -139,3 +150,4 @@ GIT_CLONE_BASE_PATH=/tmp/compliance-scanner/repos | `APP_URL` | No | — | Application root URL | | `OTEL_EXPORTER_OTLP_ENDPOINT` | No | — | OTLP collector endpoint | | `OTEL_SERVICE_NAME` | No | — | OpenTelemetry service name | +| `MCP_PORT` | No | — | MCP HTTP transport port (omit for stdio) |