# mcp-bitsight

A focused [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes BitSight Security Ratings as tools for AI assistants.

> **Note:** This repo will be renamed from `mcp-gateway` to `mcp-bitsight` to reflect its single purpose.

## Architecture Context

This is one component in a larger MCP architecture:

```
┌─────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│    User     │────▶│  LLM Layer   │────▶│  MCP Gateway │────▶│ mcp-bitsight │ ← This repo
│  (Cursor)   │     │ (AI Foundry) │     │   (Router)   │     │              │
└─────────────┘     └──────────────┘     └──────┬───────┘     └──────────────┘
                                                │
                                                ├────▶ mcp-servicenow (future)
                                                └────▶ mcp-* (future)
```

| Component | Purpose | Repo |
|-----------|---------|------|
| **mcp-bitsight** | BitSight API tools | This repo |
| **mcp-gateway** | Routes to MCP servers | Separate repo (TBD) |
| **ai-orchestrator** | LLM reasoning layer | Separate repo (TBD) |

## Available Tools

| Tool | Description |
|------|-------------|
| `get_bitsight_score` | Get security rating for any company by name |
| `search_companies` | Search for companies in BitSight |
| `get_company_details` | Get full company details by GUID |
| `get_security_findings` | Get vulnerabilities and security findings |
| `get_portfolio` | View your monitored companies |
| `get_risk_vectors` | List all risk categories |
| `get_alerts` | Get portfolio alerts |

## Quick Start

### 1. Clone and Setup

```bash
git clone https://github.com/your-org/mcp-bitsight.git
cd mcp-bitsight

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .
```

### 2. Configure Environment

Create a `.env` file:

```bash
BITSIGHT_API_TOKEN=your-api-key-here
LOG_LEVEL=WARNING
```

### 3. Connect to Cursor

Add to `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows):

```json
{
  "mcpServers": {
    "bitsight": {
      "command": "/full/path/to/mcp-bitsight/venv/bin/python",
      "args": ["/full/path/to/mcp-bitsight/main.py"],
      "cwd": "/full/path/to/mcp-bitsight"
    }
  }
}
```

### 4. Restart Cursor

After updating `mcp.json`, restart Cursor completely (Cmd+Q / Alt+F4, then reopen).

## Corporate Proxy / SSL Certificates

If behind a corporate firewall that intercepts HTTPS, place CA certificates in `certs/`:

```
certs/
├── combined_ca_bundle.pem
└── ca_bundle.pem
```

Or set via environment:

```bash
MCP_CA_BUNDLE=/path/to/your/ca_bundle.pem
```

## Cloud Deployment (Azure)

### CI/CD

Push to `dev` branch triggers automatic build and deploy via GitHub Actions.

**Required GitHub Secrets:**

| Secret | Description |
|--------|-------------|
| `ACR_LOGIN_SERVER` | ACR login server |
| `ACR_USERNAME` | Azure Container Registry username |
| `ACR_PASSWORD` | Azure Container Registry password |
| `AZURE_CLIENT_ID` | Service principal client ID |
| `AZURE_TENANT_ID` | Azure AD tenant ID |
| `AZURE_SUBSCRIPTION_ID` | Azure subscription ID |

### Connect Cursor to Cloud

```json
{
  "mcpServers": {
    "bitsight": {
      "url": "https://your-app.azurecontainerapps.io/sse"
    }
  }
}
```

## Project Structure

```
mcp-bitsight/
├── app/
│   ├── __init__.py
│   ├── bitsight.py      # BitSight API client
│   └── server.py        # MCP tools
├── certs/               # SSL certificates
├── Documentation/
├── .github/workflows/   # CI/CD
├── main.py              # Entry point
├── pyproject.toml       # Dependencies
└── Dockerfile
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `BITSIGHT_API_TOKEN` | BitSight API key | Required |
| `MCP_TRANSPORT` | `stdio` or `http` | `stdio` |
| `PORT` | HTTP port | `8000` |
| `LOG_LEVEL` | DEBUG, INFO, WARNING, ERROR | `WARNING` |
| `MCP_CA_BUNDLE` | Custom CA certificate path | Auto-detected |

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check .
ruff format .
```

## License

MIT