BitSight Community MCP Server

# Birre – Requirements Specification ## 1. Context and Scope - **Purpose:** Build a general-purpose MCP server for BitSight. This server exposes BitSight data retrieval/functionality as callable MCP “tools” (endpoints) to any client able to speak the Model Context Protocol (MCP)—including but not limited to LLMs such as Claude Code. - **MCP Role:** This is a backend service (“MCP server”), not an LLM client, plugin, or IDE extension. It responds to standardized MCP method calls from AI clients; it does not initiate them. - **Deployment:** Service can be run locally or remotely (cloud/server), and must support multi-tenant LLM/AI agent access, with basic authentication in advanced versions. - **BitSight Interaction:** All interactions with BitSight must go through the brandon-smith-187/bitsight Python package—no direct REST API usage or HTTP requests except via this library. ## 2. Functional Requirements, by Version ### Version 1.0 – MVP **2.1. Authentication** - The server uses the BitSight API key, read from `BST_API_KEY` environment variable. No interactive authentication is required at runtime. **2.2. Endpoints/Tools** - **Company Search** - **Purpose:** Find companies by name or domain in BitSight. - **Inputs:** - `name` (string, optional) — company name to search for - `domain` (string, optional) — company domain to search for - **Output:** - List of companies matching the query, each with: - `guid` (BitSight unique identifier) - `name` - `domain` - `industry` - Any additional fields provided by the package - Total `count` of matches - **Behavior:** Must handle both single and multiple matches gracefully, and partial or exact queries. - **Get Company Rating** - **Purpose:** Retrieve security rating for a company, managing ephemeral BitSight subscription if necessary. - **Inputs:** - `guid` (string, required) — BitSight GUID of the company - **Behavior:** - If already subscribed to the company (type: `continuous_monitoring`), fetch and return rating. - If not subscribed, subscribe (with `continuous_monitoring`), fetch rating, then unsubscribe immediately. - If BitSight API quota or subscription fails, return an explicit error and abort. - **Output:** - Rating number - Date of rating - Grade or other context fields from BitSight - Flags indicating if the operation required auto-subscribing and/or unsubscribing - Any errors in a structured response format **2.3. General** - No data is cached or persisted—each request operates independently. - Errors are returned as structured objects for user-facing failures; system/internal errors may raise exceptions. ### Version 2.0 – Category Risk Ratings - **Get Company Risk Ratings by Category** - **Purpose:** Retrieve all available risk vector/category ratings for a company. - **Inputs:** - `guid` (string, required) — BitSight GUID of the company - `category` (string, optional) — filter for a specific category/type, if supported - **Output:** - All BitSight category/risk vector ratings for the company, structured. - Support filtering by category if possible. - Error formats as above. ### Version 3.0 – Retrieve Company Report (PDF) - **Download Company Report** - **Purpose:** Retrieve/download the official BitSight report (PDF) for a given company. - **Inputs:** - `guid` (string, required) — BitSight GUID of the company - **Output:** - PDF file data or a link/stream (per MCP and package constraints) - If report generation/downloading is unsupported or rate/feature limits exceeded, return an explanatory error. - Error formats as above. ### Version 4.0 – Database Caching - **Daily Company Data Caching** - **Purpose:** Cache per-company rating data for a full day to avoid duplicate live API calls. - **Inputs:** - Any input to rating or category endpoints may trigger/use caching behavior. - **Behavior:** - If rating/category data for the requested company GUID is cached for the current day, return cache instantly. - Otherwise, do a live fetch, then store the new result in the cache for that day. - **Output:** - Same as in previous endpoint, with cache/miss status indicator. - Errors per previous conventions. ### Version 5.0 – Standalone, Multi-LLM, Remote Service with Authentication - **Multi-User, Cloud/Distributed Deployment** - **Purpose:** Run as a network-facing service, available to multiple LLMs/clients concurrently, no local-only constraint. - **Authentication:** All endpoints/tools must require valid credentials or tokens for access. - **Security:** API keys or credentials never exposed to clients; authentication must follow secure best practices (e.g., token-based, password, or API key auth). - **Concurrency:** Must allow for multiple simultaneous calls/users; enforce concurrent usage/error/rate limits as needed. - **Service Registry/Discovery:** (Optional/future-proofing) Allow for registration/discovery of endpoints if deployed in distributed/cloud environments. - **Interface/Protocol:** All interaction is through standard MCP tool contracts; no direct HTTP/REST, CLI, or IDE-bound interfaces. - **Error Handling and Quotas:** Must handle and communicate API quota/rate limit errors per-user/client; clean, structured error reporting. ## 3. Non-Functional Requirements - **Performance:** The service enforces BitSight API quota restrictions and avoids exceeding limits. On quota breach, errors are returned directly with no retries or waiting. - **Security:** All sensitive configuration, especially `BST_API_KEY`, is handled securely; never logged or included in outputs or client responses. - **Extensibility:** Requirements ensure future expansion to new endpoints, data formats, authentication strategies, and deployment models without major redesign. - **Maintainability:** Codebase modularity and clarity are a must; all endpoints and logic should be independently updatable and testable. - **Compatibility:** The MCP server must work with any LLM/AI agent that supports the MCP protocol and should be designed for maximum protocol compliance. ## 4. Guidance for Architect - Requirements specify only interface, contract, data flow, and error handling. - Implementation decisions—such as async vs sync, database engine or format, server framework, concurrency model—are left entirely to architectural preference and context. - If ambiguity or edge cases arise, clarify with explicit options and recommendations (don’t default or assume).