sde-mcp

> **Warning** > This project is a **work in progress**. Use at your own risk. ### SD Elements MCP Server MCP server for **SD Elements API v2** (STDIO only). Use it from MCP clients to manage projects, surveys, countermeasures, scans, reports, diagrams, and users. ### Quick start ```bash npm ci npm run start ``` ### Required configuration - **`SDE_HOST`**: `https://your-sdelements-instance.com` - **`SDE_API_KEY`**: `your-api-key-here` ### HTTP setup Use HTTP mode when you want a long-running server instead of STDIO. ```bash npm run start:http ``` - **Credentials**: do **not** set `SDE_HOST` or `SDE_API_KEY` in the server process. The HTTP server refuses to start if either is set (including `SDE_API_KEY`). Each client request must provide credentials instead. - **Instance allowlist (required)**: set `MCP_SDE_INSTANCE_ALLOWLIST` to a comma-separated list of allowed SDE hosts (for example `https://sde.example.com,https://sde2.example.com`). Requests with `SDE_HOST` outside this list are rejected. - **Port/host**: configure with `MCP_PORT` (default `3000`) and `MCP_HOST` (default `127.0.0.1`). - **Per-request auth**: send `SDE_HOST` and `SDE_API_KEY` as headers (or `sde_host` / `sde_api_key` in the initialize request body). ### HTTPS unsafe mode By default, the server rejects non-HTTPS `SDE_HOST` values. For local/dev instances that only serve HTTP, set: ```bash SDE_ALLOW_INSECURE_HTTP=true ``` This allows `http://` hosts. Use only in trusted environments. Example initialize request: ```bash curl -sS http://127.0.0.1:3000/mcp \ -H "Content-Type: application/json" \ -H "SDE_HOST: https://your-sdelements-instance.com" \ -H "SDE_API_KEY: your-api-key-here" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"example","version":"0.0.0"}}}' ``` ### Client setup (Cursor + Claude Desktop) Both clients use the same `mcpServers` object — the only difference is **where you paste it**. - **Cursor**: add this under MCP settings (Cursor “MCP Servers” / `mcpServers`). - **Claude Desktop**: add this to `claude_desktop_config.json`. Pick one execution style: - **Option A (recommended)**: run from the GitHub repo via `npx` (builds on install) ```json { "mcpServers": { "sdelements": { "command": "npx", "args": ["-y", "github:sdelements/sde-mcp"], "env": { "SDE_HOST": "https://your-sdelements-instance.com", "SDE_API_KEY": "your-api-key-here" } } } } ``` - **Option B**: run from a local checkout (build output) ```json { "mcpServers": { "sdelements": { "command": "node", "args": ["/absolute/path/to/sde-mcp/dist/main.js"], "env": { "SDE_HOST": "https://your-sdelements-instance.com", "SDE_API_KEY": "your-api-key-here" } } } } ``` ### HTTP client setup (Cursor) Start the HTTP server (`npm run start:http`) and set `MCP_SDE_INSTANCE_ALLOWLIST` as described above. Then configure Cursor with an HTTP MCP server entry: ```json { "mcpServers": { "sdelements-http": { "url": "http://127.0.0.1:3000/mcp", "headers": { "SDE_HOST": "https://your-sdelements-instance.com", "SDE_API_KEY": "your-api-key-here" } } } } ``` ### Build ```bash npm run build ``` ### Local checkout build (for Option B) ```bash npm ci npm run build ``` ### Tools - **Toolset selection**: default is **compact**. Set `SDE_TOOLSET=full` to expose the legacy toolset. - **Note**: diagrams and reporting tools are not exposed. - **Compact tools (default)**: - `project`, `application`, `business_unit`, `project_survey`, `project_countermeasures`, `library_search` - plus **Generic**: `test_connection`, `api_request` - **Legacy tools (when `SDE_TOOLSET=full`)**: - **Projects**: `list_projects`, `get_project`, `create_project`, `update_project`, `create_project_from_code` - **Library search**: `library_search` (supports countermeasures, threats, components, weaknesses, profiles, risk policies, answers, countermeasure statuses, countermeasure how-tos) - **Applications**: `list_applications`, `get_application`, `create_application`, `update_application` - **Business units**: `list_business_units`, `get_business_unit`, `create_business_unit`, `update_business_unit` - **Countermeasures**: `list_countermeasures`, `get_countermeasure`, `update_countermeasure`, `add_countermeasure_note`, `get_task_status_choices` - **Surveys**: `get_project_survey`, `get_survey_answers_for_project`, `update_project_survey`, `find_survey_answers`, `set_project_survey_by_text`, `add_survey_answers_by_text`, `remove_survey_answers_by_text`, `commit_survey_draft`, `add_survey_question_comment` - **Scans**: `list_scan_connections`, `scan_repository`, `get_scan_status`, `list_scans` - **Users**: `list_users`, `get_user`, `get_current_user` - **Library**: `library_search` - **Generic**: `test_connection`, `api_request` ### Notes - **Missing env vars**: tools will fail if `SDE_HOST` / `SDE_API_KEY` aren’t set.