gatekeeper-mcp-server 3.0.0b3__tar.gz

gatekeeper_mcp_server-3.0.0b3/PKG-INFO

@@ -0,0 +1,528 @@
+Metadata-Version: 2.4
+Name: gatekeeper-mcp-server
+Version: 3.0.0b3
+Summary: FastMCP-based server exposing CAST Dashboard REST API via Model Context Protocol
+Author-email: CAST Software <contact@castsoftware.com>
+License: Proprietary
+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
+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"
+
+# Gatekeeper MCP Server
+
+A FastMCP-based server that exposes CAST Gatekeeper REST API functionality through the Model Context Protocol (MCP), enabling AI agents like Claude and GitHub Copilot to interact with Gatekeeper domains, applications, snapshots, and compliance 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/)
+
+## 🚀 Features
+
+- **MCP Protocol Support**: Full implementation of Model Context Protocol for AI agent integration
+- **Compliance Monitoring**: Real-time access to application compliance status, quality indicators, and violation tracking
+- **ISO-5055 Standard Support**: Filter and analyze compliance data by industry standards
+- **Multi-Snapshot Comparison**: Compare quality metrics across multiple application snapshots
+- **Technology & Module Breakdown**: Detailed violation analysis by technology stack and modules
+- **Smart Caching**: TTL-based caching for improved performance and reduced API calls
+- **Service Discovery**: Optional Eureka integration for microservices architecture
+- **Streamable HTTP Transport**: MCP over HTTP (streamable-HTTP on port 8283)
+- **Security First**: SSL/TLS support, input validation, and secure credential handling
+
+## 📋 Requirements
+
+- Python 3.12 or higher
+- CAST Dashboard REST API access
+- API key or OAuth token for Dashboard authentication
+
+## 🔧 Installation
+
+### Option 1: Python Installation
+
+1. Clone the repository:
+```bash
+git clone https://gitlab.com/castsoftware/dashboards/mcp-server.git
+cd mcp-server
+```
+
+2. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+3. Configure the server (see [Configuration](#-configuration))
+
+4. Run the server:
+```bash
+python server/run_server.py
+```
+
+### Option 2: Docker Deployment
+
+1. Navigate to the Docker directory:
+```bash
+cd deploy/server
+```
+
+2. Configure `config/app.config` with your Dashboard credentials
+
+3. Run the container:
+```bash
+./run.sh
+```
+
+For HTTPS mode, place certificates in `deploy/server/certificates/` and see the [Docker Deployment](#-docker-deployment) section.
+
+## ⚙️ Configuration
+
+### Required Settings
+
+Create or edit `server/config/app.config`:
+
+```ini
+# Dashboard API Connection (Required)
+HOST_CONTROL_PANEL=your-controlpanel-host
+PORT_CONTROL_PANEL=8098
+
+# Authentication (Required)
+DASHBOARD_API_KEY=your-api-key
+```
+
+### Optional Settings
+
+```ini
+# MCP Server
+MCP_SERVER_PORT=8283
+
+# Control Panel SSL (set true if control panel uses HTTPS)
+CONTROL_PANEL_SSL_ENABLED=false
+
+# MCP Server SSL — marks the Eureka service registry entry as HTTPS
+MCP_SERVER_SSL_ENABLED=false
+
+# Logging and Debug
+DEBUG_MODE=false
+
+# Service Discovery
+SERVICE_NAME=GatekeeperMCPServer
+SERVICE_HOST=your-machine-ip-or-hostname
+```
+
+### Configuration Priority
+
+The server resolves configuration in the following order:
+1. Command-line arguments (`--config /path/to/app.config`)
+2. Environment variables (UPPER_CASE format)
+3. Config file values (snake_case or UPPER_CASE)
+4. Default values
+
+### Authentication Methods
+
+**API Key Authentication** (Recommended):
+```ini
+DASHBOARD_API_KEY=your-api-key
+```
+
+**OAuth Token Authentication**:
+```ini
+DASHBOARD_OAUTH_TOKEN=your-oauth-token
+```
+
+**Request Headers** (Highest Priority):
+```bash
+x-api-key: your-api-key
+# OR
+Authorization: Bearer your-oauth-token
+```
+
+## 🎯 Usage
+
+### Starting the Server
+
+**Default mode (streamable-HTTP on port 8283):**
+```bash
+python server/run_server.py
+```
+
+**With custom config:**
+```bash
+python server/run_server.py --config /path/to/app.config
+```
+
+### Health Check
+
+Verify the server is running:
+```bash
+curl http://localhost:8283/mcp/healthcheck
+curl http://localhost:8283/mcpserver/healthcheck
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "service": "GatekeeperMCPServer",
+  "details": {
+    "dashboard_client": "available",
+    "dashboard_api": "configured"
+  }
+}
+```
+
+### Client Integration
+
+#### VS Code with GitHub Copilot
+
+Create `.vscode/mcp.json`:
+```json
+{
+  "inputs": [
+    {
+      "id": "dashboard-key",
+      "type": "promptString",
+      "description": "CAST Dashboard API Key"
+    }
+  ],
+  "servers": {
+    "gatekeeper": {
+      "type": "http",
+      "url": "http://localhost:8090/mcp/gatekeeper",
+      "headers": {
+        "x-api-key": "${input:dashboard-key}"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to Claude Desktop settings (`%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "gatekeeper": {
+      "type": "http",
+      "url": "http://localhost:8090/mcp/gatekeeper",
+      "headers": {
+        "x-api-key": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to Cursor settings (`.cursor/mcp.json` in your project or workspace):
+
+```json
+{
+  "mcpServers": {
+    "gatekeeper": {
+      "type": "http",
+      "url": "http://localhost:8090/mcp/gatekeeper",
+      "headers": {
+        "x-api-key": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+> The MCP server must be running before connecting clients.
+
+### Available Tools
+
+The MCP server exposes one primary tool:
+
+#### `get_compliance_status`
+
+Get compliance status for an application with violation details, quality indicators, and standard filtering.
+
+**Parameters:**
+- `application_name` (required): Application name
+- `quality_indicators` (optional): Comma-separated quality-indicator IDs (e.g., "60017,4672")
+- `snapshot` (optional): Snapshot number
+  - Not provided: Uses snapshot-id=-1 to get latest snapshot
+  - `"6"`: Gets snapshot 6
+- `standard` (optional): Filter by standard (e.g., "ISO-5055", "CISQ", "OWASP")
+- `technologies` (optional): Technology filter (comma-separated or "$all")
+- `modules` (optional): Module filter (comma-separated or "$all")
+
+**Example Usage:**
+
+```
+Get compliance status for MyApp with ISO-5055 standard
+```
+
+AI agent translates to:
+```json
+{
+  "tool": "get_compliance_status",
+  "arguments": {
+    "application_name": "MyApp",
+    "standard": "ISO-5055"
+  }
+}
+```
+
+## 🏗️ Architecture
+
+### Layered Architecture
+
+```
+┌─────────────────────────────────────────┐
+│   MCP Client (Claude/Copilot)           │
+└─────────────────┬───────────────────────┘
+                  │ Streamable HTTP (port 8283/mcp)
+┌─────────────────▼───────────────────────┐
+│   Tool Layer                             │
+│   (quality_tools.py)                  │
+│   - get_compliance_status                │
+└─────────────────┬───────────────────────┘
+                  │
+┌─────────────────▼───────────────────────┐
+│   Business Logic Layer                   │
+│   (dashboard_service.py)                 │
+│   - Validation & Caching                 │
+│   - Response Normalization               │
+└─────────────────┬───────────────────────┘
+                  │
+┌─────────────────▼───────────────────────┐
+│   Data Access Layer                      │
+│   (dashboard_server.py)                  │
+│   - HTTP Client & Connection Pooling     │
+│   - Authentication Resolution            │
+└─────────────────┬───────────────────────┘
+                  │
+┌─────────────────▼───────────────────────┐
+│   Dashboard REST API                     │
+└─────────────────────────────────────────┘
+```
+
+### Key Components
+
+- **FastMCP Instance**: `server/__init__.py` - Core MCP protocol handler
+- **Main Entry**: `server/run_server.py` - Server startup and configuration
+- **Tool Layer**: `server/services/dashboard_api/tools/quality_tools.py` - MCP tool definitions
+- **Business Logic**: `server/services/dashboard_api/utils/dashboard_service.py` - Validation and caching
+- **Data Access**: `server/services/dashboard_api/dashboard_server.py` - HTTP client operations
+- **Configuration**: `server/config.py` - Multi-source configuration management
+
+## 🔒 Security
+
+### Best Practices
+
+1. **Always use HTTPS in production** (Docker): place certificates in `deploy/server/certificates/` and run via `./run.sh`. nginx handles TLS termination — see [Docker Deployment](#-docker-deployment).
+
+2. **Corporate / self-signed CA certificates**: Set `SSL_CERT_FILE` (or `REQUESTS_CA_BUNDLE`) to your PEM chain before starting:
+   ```powershell
+   $Env:SSL_CERT_FILE = "C:\path\to\mmc-chain.pem"
+   python server/run_server.py
+   ```
+   On Windows, the server also reads this from system environment variables in the registry automatically.
+
+3. **Secure credential storage**:
+   - Use environment variables or secure config files
+   - Never commit credentials to version control
+   - Rotate API keys regularly
+
+3. **Rate limiting**: Configured in `deploy/server/nginx/nginx.conf` via `limit_req_zone` (rate) and `limit_req` (burst). No app.config settings required.
+
+4. **Input validation**: All inputs are automatically validated to prevent:
+   - Path traversal attacks
+   - SQL injection
+   - Length overflow
+   - Header injection
+
+5. **SSL certificate verification**: Enabled by default, only disable in development with explicit flags
+
+## 📊 Monitoring & Logging
+
+### Log Files
+
+Logs are stored with rotation (30 files × 10MB, gzipped):
+```
+/app/logs/mcp_dashboard.log
+/app/logs/mcp_dashboard.log.1.gz
+...
+```
+
+### Debug Mode
+
+Enable detailed logging:
+```ini
+DEBUG_MODE=true
+```
+
+Or via environment:
+```bash
+DEBUG_MODE=true python server/run_server.py
+```
+
+### Metrics
+
+Monitor via health check endpoint:
+```bash
+curl http://localhost:8283/mcp/healthcheck
+curl http://localhost:8283/mcpserver/healthcheck
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**1. "Dashboard API is not available"**
+- Check `HOST_CONTROL_PANEL` and `PORT_CONTROL_PANEL` settings
+- Verify network connectivity to Dashboard API
+- Ensure Dashboard REST API is running
+
+**2. "No applications will be authorized"**
+- Check API key is valid and active
+- Confirm user has application permissions in Dashboard
+
+**3. "Rate limit exceeded" (HTTP 429)**
+- Wait for the rate limit window to reset (Nginx returns `Retry-After` header)
+- Adjust `limit_req_zone` rate or `limit_req` burst in `deploy/server/nginx/nginx.conf`
+- Check for runaway client processes
+
+**4. SSL/TLS Errors**
+- For self-signed / corporate CA certs: set `SSL_CERT_FILE` env var to your PEM chain file before starting
+- For Docker HTTPS: verify certificates are in `deploy/server/certificates/` and you ran `./run.sh` from `deploy/server/`
+- Ensure certificates are valid and not expired
+
+### Testing Connectivity
+
+**Test Dashboard API directly:**
+```bash
+curl -H "x-api-key: <key>" \
+  http://localhost:8090/rest
+```
+
+**Test MCP server:**
+```bash
+python test_server.py
+```
+
+### Viewing Logs
+
+**Docker deployment:**
+```bash
+docker logs <container-id>
+```
+
+**Local deployment:**
+```bash
+tail -f /app/logs/mcp_dashboard.log
+```
+
+## 🔄 Development
+
+### Running Tests
+
+```bash
+# Basic connectivity test
+python test_server.py
+
+# Manual API testing
+curl http://localhost:8283/mcp/healthcheck
+curl http://localhost:8283/mcpserver/healthcheck
+```
+
+### Project Structure
+
+```
+mcp-server/
+├── server/
+│   ├── __init__.py              # FastMCP instance
+│   ├── run_server.py            # Main entry point
+│   ├── config.py                # Configuration management
+│   ├── config/
+│   │   └── app.config           # Configuration file
+│   ├── services/
+│   │   └── dashboard_api/
+│   │       ├── tools/
+│   │       │   └── quality_tools.py   # MCP tools
+│   │       ├── utils/
+│   │       │   └── dashboard_service.py  # Business logic
+│   │       └── dashboard_server.py       # Data access
+│   ├── shared/
+│   │   ├── dependencies.py      # Dependency injection
+│   │   ├── exceptions.py        # Error handling
+│   │   ├── validators.py        # Input validation
+│   │   ├── logging_config.py    # Logging setup
+│   │   └── middleware.py        # Security middleware
+│   └── eureka/
+│       └── eureka_client.py     # Service discovery
+├── deploy/
+│   └── server/
+│       ├── Dockerfile
+│       ├── run.sh
+│       └── config/
+├── requirements.txt
+├── CLAUDE.md                    # Developer guide
+└── README.md                    # This file
+```
+
+### Adding New Tools
+
+See [CLAUDE.md](CLAUDE.md) for detailed developer documentation on extending the server.
+
+## 🐳 Docker Deployment
+
+### Building the Image
+
+```bash
+cd deploy/server
+docker build -t gatekeeper-mcp-server .
+```
+
+### Running with Docker Compose
+
+Create `docker-compose.yml`:
+```yaml
+version: '3.8'
+services:
+  mcp-server:
+    image: gatekeeper-mcp-server
+    ports:
+      - "8283:8283"
+    environment:
+      - HOST_CONTROL_PANEL=your-controlpanel-host
+      - PORT_CONTROL_PANEL=8098
+      - DASHBOARD_API_KEY=your-api-key
+    volumes:
+      - ./logs:/app/logs
+    restart: unless-stopped
+```
+
+Run:
+```bash
+docker-compose up -d
+```
+