Metadata-Version: 2.4
Name: gatekeeper-mcp-server
Version: 3.0.0b6
Summary: FastMCP-based server exposing CAST Dashboard REST API via Model Context Protocol
Author-email: CAST Software <contact@castsoftware.com>
Project-URL: Homepage, https://www.castsoftware.com
Project-URL: Repository, https://gitlab.com/castsoftware/dashboards/mcp-server
Keywords: mcp,cast,dashboard,ai,fastmcp,compliance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp<3.0,>=2.10.0
Requires-Dist: starlette<1.0,>=0.45.2
Requires-Dist: uvicorn<1.0,>=0.34.0
Requires-Dist: rich<14.0,>=13.5.0
Requires-Dist: anyio<5.0,>=4.0.0
Requires-Dist: pydantic<3.0,>=2.11.7
Requires-Dist: pydantic-settings<3.0,>=2.7.1
Requires-Dist: pydantic-core<3.0,>=2.14
Requires-Dist: httpx<1.0,>=0.28.1
Requires-Dist: requests<3.0,>=2.32.3
Requires-Dist: py-eureka-client<1.0,>=0.11.17
Requires-Dist: sniffio<2.0,>=1.3.0
Requires-Dist: typing-extensions<5.0,>=4.8.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Dynamic: license-file

# Gatekeeper MCP Server

A FastMCP-based server that exposes CAST Imaging REST API functionality through the Model Context Protocol (MCP), enabling AI agents like Claude, GitHub Copilot, and Cursor to interact with application quality, compliance, and security data via natural language.

[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.9.2%2B-green)](https://pypi.org/project/fastmcp/)
[![PyPI](https://img.shields.io/pypi/v/gatekeeper-mcp-server)](https://pypi.org/project/gatekeeper-mcp-server/)

## Requirements

- Python 3.12 or higher
- CAST Imaging 3.6.2-funcrel or higher (with `imaging-services` component)
- Valid CAST Imaging API key
- TCP port 8283 (default, configurable)
- 2 GB minimum free disk space
- MCP-aware client: GitHub Copilot, Claude Desktop, or Cursor

## Installation

### Option 1: PyPI (Recommended)

```bash
pip install gatekeeper-mcp-server
```

### Option 2: Docker

```bash
cd deploy/server
./run.sh
```

## Configuration

### Step 1 — Verify CAST Imaging connectivity

```bash
curl -H "x-api-key: <api-key>" http://<imaging-host>:8090/dashboards/rest/
```

### Step 2 — Create `app.config`

```ini
# Required
HOST_CONTROL_PANEL=<imaging-services-host>
PORT_CONTROL_PANEL=8098

# Authentication
DASHBOARD_API_KEY=your-api-key

# MCP Server
MCP_SERVER_PORT=8283
SERVICE_HOST=<mcp-server-ip-or-hostname>

# SSL (set true if imaging-services uses HTTPS)
CONTROL_PANEL_SSL_ENABLED=false
```

### Configuration Priority

1. Command-line `--config` argument
2. Environment variables (UPPER_CASE)
3. Config file values
4. Default values

### Authentication Methods

The server resolves credentials in this order (highest priority first):

| Method | Format |
|---|---|
| Request header | `x-api-key: your-api-key` |
| Request header | `Authorization: Bearer your-token` |
| Config file | `DASHBOARD_API_KEY=your-api-key` |
| Environment variable | `DASHBOARD_API_KEY=your-api-key` |

## Running the Server

**With config file:**
```bash
gatekeeper-mcp-server --config /path/to/app.config
```

**With environment variables:**
```bash
HOST_CONTROL_PANEL=your-host PORT_CONTROL_PANEL=8098 gatekeeper-mcp-server
```

**PowerShell:**
```powershell
$env:HOST_CONTROL_PANEL = "your-host"
$env:PORT_CONTROL_PANEL = "8098"
$env:DASHBOARD_API_KEY  = "your-api-key"
gatekeeper-mcp-server
```

### Verify the Server is Running

```bash
curl http://localhost:8090/mcp/gatekeeper/healthcheck
```

Expected response:
```json
{"status": "healthy", "service": "GatekeeperMCPServer"}
```

## Client Integration

The MCP server URL for direct (non-proxied) installation is `http://<host>:8283/mcp`.

### VS Code with GitHub Copilot

Create `.vscode/mcp.json`:
```json
{
  "inputs": [
    {
      "id": "dashboard-key",
      "type": "promptString",
      "description": "CAST Imaging API Key"
    }
  ],
  "servers": {
    "gatekeeper": {
      "type": "http",
      "url": "http://localhost:8283/mcp",
      "headers": {
        "x-api-key": "${input:dashboard-key}"
      }
    }
  }
}
```

### Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "gatekeeper": {
      "type": "http",
      "url": "http://localhost:8283/mcp",
      "headers": {
        "x-api-key": "your-api-key"
      }
    }
  }
}
```

### Cursor

Create `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "gatekeeper": {
      "type": "http",
      "url": "http://localhost:8283/mcp",
      "headers": {
        "x-api-key": "your-api-key"
      }
    }
  }
}
```

> The MCP server must be running before connecting clients.

### URL Formats

| Deployment | URL |
|---|---|
| Direct (PyPI / source) | `http://localhost:8283/mcp` |
| Behind nginx proxy (HTTP) | `http://<host>:8090/mcp/gatekeeper` |
| Behind nginx proxy (HTTPS) | `https://<host>/mcp/gatekeeper` |
| Custom HTTPS port | `https://<host>:8443/mcp/gatekeeper` |

## Available Tools

### `get_compliance_status`

Get compliance status for an application with quality indicators, violations, and technical debt.

**Parameters:**
- `application_name` (required): Application name
- `quality_indicators` (optional): Comma-separated quality-indicator IDs (e.g., `"60017,4672"`)
- `snapshot` (optional): Snapshot number, `"first_last"`, or `"all"`
- `standard` (optional): Filter by standard — `"ISO-5055"`, `"CISQ"`, `"OWASP"`
- `technologies` (optional): Technology filter (comma-separated or `"$all"`)
- `modules` (optional): Module filter (comma-separated or `"$all"`)

### `get_technical_debt`

Get technical debt metrics including remediation effort in minutes and days.

### `get_violations`

Get detailed violations with code-level diagnosis including file paths, line numbers, and execution paths. Supports filtering by rule pattern, criticality, status, technologies, and business criteria.

**Example natural language queries:**
```
Get compliance status for MyApp with ISO-5055 standard
Show security violations for MyApp
What is the technical debt for MyApp?
```

## Architecture

```
MCP Client (Claude / Copilot / Cursor)
    │ Streamable HTTP — port 8283/mcp
    ▼
Tool Layer          (quality_tools.py)
    ▼
Business Logic      (dashboard_service.py)   validation, caching, normalization
    ▼
Data Access         (dashboard_server.py)    HTTP client, connection pooling, auth
    ▼
CAST Imaging REST API
```

### Key Files

| File | Role |
|---|---|
| `server/run_server.py` | Entry point, health check routes |
| `server/config.py` | Multi-source configuration |
| `server/services/dashboard_api/tools/quality_tools.py` | MCP tool definitions |
| `server/services/dashboard_api/utils/dashboard_service.py` | Business logic |
| `server/services/dashboard_api/dashboard_server.py` | HTTP client |
| `server/shared/` | Validators, exceptions, logging, middleware |

## Security

- **Input validation**: path traversal, SQL injection, length overflow, header injection prevention
- **SSL/TLS**: terminated externally (nginx) or via `SSL_CERT_FILE` env var for corporate CAs
- **Credentials**: never logged; resolved from headers → config → environment
- **Rate limiting**: configured in nginx (`limit_req_zone` / `limit_req`)

### Corporate / Self-Signed CA Certificates

```powershell
# Windows
$Env:SSL_CERT_FILE = "C:\path\to\ca-chain.pem"
gatekeeper-mcp-server --config app.config
```

```bash
# Linux
SSL_CERT_FILE=/path/to/ca-chain.pem gatekeeper-mcp-server --config app.config
```

## Monitoring & Logging

**Health check:**
```bash
curl http://localhost:8090/mcp/gatekeeper/healthcheck
```

**Log location (PyPI install):**
```
logs/mcp_gatekeeper.log   (rotating: 30 files × 10MB, gzipped)
```

**Enable debug logging:**
```ini
DEBUG_MODE=true
```

## Troubleshooting

**"Dashboard API is not available"**
- Check `HOST_CONTROL_PANEL` and `PORT_CONTROL_PANEL` in config
- Test connectivity: `curl -H "x-api-key: <key>" http://<imaging-host>:8090/dashboards/rest/`

**"No applications will be authorized"**
- Verify API key is valid and has application permissions in CAST Imaging

**Port already in use**
- Change `MCP_SERVER_PORT` in config or stop the existing process

**SSL/TLS errors**
- Set `SSL_CERT_FILE` to your PEM chain file before starting

**Rate limit exceeded (HTTP 429)**
- Adjust `limit_req_zone` rate or `limit_req` burst in `deploy/server/nginx/nginx.conf`

## Docker Deployment

```bash
cd deploy/server
./run.sh
```

Or with Docker Compose:
```yaml
services:
  mcp-server:
    image: gatekeeper-mcp-server
    ports:
      - "8283:8283"
    environment:
      - HOST_CONTROL_PANEL=your-imaging-host
      - PORT_CONTROL_PANEL=8098
      - DASHBOARD_API_KEY=your-api-key
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped
```

## Development

See [CLAUDE.md](CLAUDE.md) for developer documentation on extending the server.

```bash
# Run tests
pytest

# Health check
curl http://localhost:8283/mcp/healthcheck
```
