sophos-central-mcp-server 0.4.2 → 0.6.0

package/README.md

@@ -1,56 +1,51 @@
-# Sophos Central MCP Server
+# Sophos Fusion MCP Server (formerly Sophos Central)
 
-MCP (Model Context Protocol) server for interacting with Sophos Central APIs. Supports partner, organisation, and single-tenant credential types with automatic region routing. **288 tools** covering 20 Sophos API namespaces.
+MCP (Model Context Protocol) server for the Sophos Fusion and Sophos Central APIs. Supports partner, organisation, and single-tenant credential types with automatic region routing. **310 tools** covering 22 Sophos API namespaces: the Sophos Central REST APIs plus the Sophos Fusion GraphQL APIs (`sophos_fusion_*`). Install it as a Claude Desktop extension (`.mcpb`), run it with npx, or host it yourself over streamable HTTP.
 
-## Quick Start
+The npm package, the `.mcpb` bundle and the binaries keep the `sophos-central-mcp-server` name so existing installs update in place.
 
-### Claude Desktop
+## Prerequisites
 
-No installation needed. Open your `claude_desktop_config.json` (File > Settings > Developer > Edit Config) and add the `sophos-central` block inside `mcpServers`:
+You need these before any of the install options below.
 
-**macOS / Linux:**
+### Sophos Central API credentials
 
-```json
-{
-  "mcpServers": {
-    "sophos-central": {
-      "command": "npx",
-      "args": ["-y", "sophos-central-mcp-server"],
-      "env": {
-        "SOPHOS_CLIENT_ID": "your-client-id",
-        "SOPHOS_CLIENT_SECRET": "your-client-secret",
-        "TRANSPORT": "stdio"
-      }
-    }
-  }
-}
-```
+Every install method needs a Client ID and Client Secret. The same credential authorises both the Sophos Central REST tools and the Sophos Fusion GraphQL tools; there is no second credential. The credential type decides what the server can see:
 
-**Windows:**
-
-```json
-{
-  "mcpServers": {
-    "sophos-central": {
-      "command": "cmd",
-      "args": ["/c", "npx", "-y", "sophos-central-mcp-server"],
-      "env": {
-        "SOPHOS_CLIENT_ID": "your-client-id",
-        "SOPHOS_CLIENT_SECRET": "your-client-secret",
-        "TRANSPORT": "stdio"
-      }
-    }
-  }
-}
-```
+- **Tenant-level**: In Sophos Central, go to **Settings > API Credentials Management** and create a new credential. The server operates on that one tenant.
+- **Partner-level**: In the Sophos Partner Dashboard, create API credentials under **Settings > API Credentials**. The server can query every tenant the partner manages.
+- **Organisation-level**: In Sophos Central Enterprise, use **Global Settings > API Credentials Management**. Same cross-tenant behaviour as partner credentials.
+
+### Node.js 20 or later (npm and self-hosted installs only)
+
+The `.mcpb` bundle for Claude Desktop does not need Node.js on your machine: Claude Desktop ships its own Node.js runtime and the bundle carries the server and all of its dependencies. Install Node.js 20+ only if you use the Claude Code or self-hosted options.
+
+## Install
+
+Pick one:
+
+| Option | Best for | Needs Node.js? |
+|--------|----------|----------------|
+| [Claude Desktop extension (.mcpb)](#option-1-claude-desktop-extension-mcpb-recommended) | Claude Desktop users who want a two-minute install | No |
+| [Claude Code](#option-2-claude-code) | Terminal use with Claude Code | Yes |
+| [Self-hosted with npm](#option-3-self-hosted-with-npm-streamable-http-or-stdio) | Running the server yourself for any MCP client, over streamable HTTP or stdio | Yes |
+
+### Option 1: Claude Desktop extension (.mcpb, recommended)
+
+The `.mcpb` file is an [MCP Bundle](https://github.com/modelcontextprotocol/mcpb): a zip containing the built server, its production dependencies, and a manifest that tells Claude Desktop how to run it and which settings to ask for. No terminal and no config file edits.
 
-> **If you already have other MCP servers configured**, don't replace the whole file — just add the `"sophos-central": { ... }` entry alongside your existing servers inside the `"mcpServers"` object.
+1. Download `sophos-central-mcp-server-<version>.mcpb` from the [latest GitHub release](https://github.com/Aaronjacobs000/sophos-central-mcp/releases/latest).
+2. Open the file with Claude Desktop. Double-clicking it works on macOS and Windows. You can also go to **Settings > Extensions > Advanced settings**, find the **Extension Developer** section, click **Install Extension...** and pick the file.
+3. Claude Desktop shows the extension details and asks for your **Sophos Central Client ID** and **Client Secret**. Both fields are marked sensitive in the manifest, so Claude Desktop keeps them in the operating system's secure storage instead of a config file.
+4. Click **Install**, make sure the extension is enabled, then start a new chat. The `sophos_*` tools are available straight away.
 
-Replace `your-client-id` and `your-client-secret` with your [Sophos Central API credentials](#creating-api-credentials). Restart Claude Desktop after saving — it will download and run the server automatically on first use.
+To update, download the newer `.mcpb` and install it the same way. To remove it, open **Settings > Extensions** and uninstall the extension.
 
-### Claude Code
+The bundle runs the server in stdio mode and sets `TRANSPORT=stdio` for you. Which tools you get depends on the credential type, exactly as with the other install options: partner and organisation credentials unlock the cross-tenant tools, tenant credentials do not.
 
-Run this once in your terminal. The `-e` flags save the credentials permanently to Claude Code's MCP config so you don't need to re-export them each session:
+### Option 2: Claude Code
+
+Requires Node.js. Run this once in your terminal. The `-e` flags save the credentials permanently to Claude Code's MCP config so you don't need to re-export them each session:
 
 **macOS / Linux:**
 
@@ -72,17 +67,105 @@ claude mcp add sophos-central ^
   -- cmd /c npx -y sophos-central-mcp-server
 ```
 
+### Option 3: Self-hosted with npm (streamable HTTP or stdio)
+
+Use this when you want to run the server yourself, on a workstation, a jump box, or in a container, for any MCP client that speaks streamable HTTP or can spawn a stdio process. Nothing here depends on the `.mcpb` bundle.
+
+**Install from npm:**
+
+```bash
+npm install -g sophos-central-mcp-server
+```
+
+**Or from source:**
+
+```bash
+git clone https://github.com/Aaronjacobs000/sophos-central-mcp.git
+cd sophos-central-mcp
+npm install
+npm run build
+```
+
+**Configure.** Either export the variables in your shell or put them in a `.env` file in the directory you start the server from. The full table is under [Configuration](#configuration).
+
+```
+SOPHOS_CLIENT_ID=your-client-id
+SOPHOS_CLIENT_SECRET=your-client-secret
+PORT=3100
+TRANSPORT=http
+```
+
+**Run:**
+
+```bash
+sophos-central-mcp      # global npm install
+npm start               # from a source checkout
+```
+
+With `TRANSPORT=http` (the default) the server listens on `http://127.0.0.1:3100/mcp` and answers `GET /health` with `{"status":"ok"}`. The MCP endpoint is stateless: every request gets a fresh transport. Point any streamable HTTP client at it, for example Claude Code:
+
+```bash
+claude mcp add --transport http sophos-central http://127.0.0.1:3100/mcp
+```
+
+With `TRANSPORT=stdio` the server speaks MCP over stdin/stdout and is meant to be spawned by the client, which is what Options 1 and 2 do for you.
+
+The HTTP server binds to `127.0.0.1` only and has no authentication of its own. If it needs to be reachable from another host, put it behind something that adds TLS and auth (an SSH tunnel or an authenticating reverse proxy) rather than changing the bind address.
+
+### Build the .mcpb yourself (maintainers)
+
+The bundle is produced by `scripts/build-mcpb.mjs` using the `mcpb` CLI, which is a dev dependency. From a source checkout:
+
+```bash
+npm install
+npm run build:mcpb
+```
+
+The script:
+
+1. Compiles TypeScript to `dist/` (via `npm run build`).
+2. Rewrites `manifest.json` so its `version` matches `package.json` and its `tools` list matches every `registerTool` call in `src/tools/`. Commit the result. The manifest in git is always the one that was last built.
+3. Validates the manifest with `mcpb validate`.
+4. Stages `dist/`, `package.json`, `LICENSE`, and `manifest.json` in `build/mcpb/` and runs `npm ci --omit=dev` there, so only production dependencies are bundled. `.mcpbignore` adds a few exclusions on top of the CLI's defaults.
+5. Packs the staging directory into `release/sophos-central-mcp-server-<version>.mcpb`.
+
+`build/` and `release/` are git-ignored. To inspect a bundle without installing it, `npx mcpb info release/<file>.mcpb` prints its size and signature state, and `npx mcpb unpack release/<file>.mcpb <dir>` extracts it. Signing is optional; `npx mcpb sign --self-signed release/<file>.mcpb` adds a self-signed signature if you want one.
+
+### Tests (maintainers)
+
+```bash
+npm test
+```
+
+Builds, then runs the `node:test` suites in `test/` with `fetch` stubbed: the Fusion GraphQL transport (including the HTTP 200 with `errors` case), the QL builder, the reference-data cache, and the path-keyed retry for the intermittent case-write fault, the migration guard, and a registration check that lists all 310 tools over an in-memory transport and checks the descriptions for the measured warnings. Nothing in `npm test` reaches Sophos.
+
+To exercise the Fusion tools against a live tenant, put credentials in `.env` (or export them) and run:
+
+```bash
+node scripts/fusion-smoke.mjs                  # read-only, tenant credential
+node scripts/fusion-smoke.mjs <tenant-id>      # read-only, partner or organisation credential
+node scripts/fusion-smoke.mjs --write          # plus the Fusion write tools on one new case
+node scripts/fusion-smoke.mjs --write-classic  # plus the Classic case tools on one new case
+node scripts/fusion-smoke.mjs --all            # everything
+```
+
+It spawns the built server over stdio and calls the tools through an MCP client, so what runs is what a host runs. Read-only mode covers the reference data, the case list with filter and cursor variants, the newest case by short ID, its evidence, summary, comments and files, the detection search, the not-found and legacy-ID refusals, and the Classic side: on a migrated tenant the migration refusal, otherwise the six Classic read tools. `--write` creates one case titled `MCP smoke test <timestamp>` (managed_by CUSTOMER), exercises comment add, edit and delete with the mention read-back, link create, update and delete, tag merge and replace, evidence add and remove_all, file upload, list and soft delete, the verdict clear on reopen, the one way door on new and the closed-case freeze, then closes it with a verdict and archives it (Fusion has no delete). `--write-classic` creates, updates and deletes one Classic case; the Cases API requires an assignee and a detection that still exists, so set `SMOKE_CLASSIC_ASSIGNEE` (a tenant admin email) and, if needed, `SMOKE_CLASSIC_DETECTION_ID` (a recent detection ID). Every write is listed at the end. Existing cases are never modified.
+
+**Cutting a release:** bump `version` in `package.json`, run `npm run build:mcpb`, commit `package.json`, `package-lock.json`, and `manifest.json`, tag, and attach the `.mcpb` from `release/` to the GitHub release. Publish to npm as before so the Claude Code and self-hosted options pick up the same version.
 
 ## Features
 
 - **Universal caller support**: Works with partner, organisation, and tenant-level API credentials
 - **Multi-tenant**: Partner/org callers can query across all managed tenants
-- **Partner gap analysis**: Single-call sales opportunity report across all managed tenants — fetches health data in parallel and returns a compact ranked list of security gaps per customer
+- **Partner gap analysis**: Single-call sales opportunity report across all managed tenants. Fetches health data in parallel and returns a compact ranked list of security gaps per customer
 - **Auto region routing**: Discovers tenant data regions via `/whoami/v1` and routes requests to the correct regional API host
 - **Token lifecycle**: Automatic OAuth2 token refresh before expiry
 - **Rate limit handling**: Retry with backoff on 429 responses
-- **Dual transport**: Streamable HTTP (for Claude Desktop / Claude Code) or stdio
-- **Full API coverage**: 288 tools across endpoints, alerts, policies, firewalls, web filtering, licensing, audit events, email, mobile, XDR, cases, SIEM, and more
+- **Dual transport**: stdio (Claude Desktop, Claude Code, and the `.mcpb` bundle) or streamable HTTP (self-hosted)
+- **One-click install**: Ships as a Claude Desktop extension (`.mcpb`) with credentials held in the OS secure store
+- **Two API generations**: the Sophos Central REST APIs and the Sophos Fusion GraphQL APIs on one credential, with `sophos_fusion_*` tools for the GraphQL side
+- **Migration aware**: the Classic case and detection tools refuse a tenant that has moved to Sophos Fusion and name the `sophos_fusion_*` tool to use instead
+- **Full API coverage**: 310 tools across endpoints, alerts, policies, firewalls, web filtering, licensing, audit events, email, mobile, XDR, cases, SIEM, and more
 
 ## Screenshots
 
@@ -96,21 +179,10 @@ claude mcp add sophos-central ^
 
 ![Tenant health detail and endpoints](docs/screenshots/tenant-health-detail.png)
 
-## Prerequisites
-
-- Node.js 20 or later
-- Sophos Central API credentials (Client ID + Client Secret)
-
-### Creating API Credentials
-
-**Tenant-level**: In Sophos Central, go to **Settings > API Credentials Management** and create a new credential.
-
-**Partner-level**: In the Sophos Partner Dashboard, create API credentials under **Settings > API Credentials**.
-
-**Organisation-level**: In Sophos Central Enterprise, use **Global Settings > API Credentials Management**.
-
 ## Configuration
 
+Applies to the Claude Code and self-hosted options. The Claude Desktop extension asks for the credentials in its install dialog and sets `TRANSPORT=stdio` itself.
+
 Copy `.env.example` to `.env` and set your credentials:
 
 ```
@@ -124,12 +196,25 @@ TRANSPORT=http
 |----------|----------|---------|-------------|
 | `SOPHOS_CLIENT_ID` | Yes | - | OAuth2 client ID |
 | `SOPHOS_CLIENT_SECRET` | Yes | - | OAuth2 client secret |
-| `SOPHOS_TENANT_ID` | No | - | Lock to a single tenant (useful for tenant-level creds) |
 | `PORT` | No | 3100 | HTTP server port |
 | `TRANSPORT` | No | http | `http` for streamable HTTP, `stdio` for subprocess mode |
+| `CHARACTER_LIMIT` | No | 50000 | Maximum characters per tool response before truncation (minimum 10000) |
+| `SOPHOS_FUSION_GRAPHQL_URL` | No | `https://api.taegis.sophos.com/graphql` | Sophos Fusion GraphQL endpoint. Override when the Fusion branded hostnames ship |
+| `SOPHOS_CLASSIC_MIGRATION_CHECK` | No | on | `off` skips the migration check on the Classic case and detection tools (they then run for every tenant) |
 
 ## Tools
 
+### Two API generations
+
+The server speaks to two Sophos API generations on one credential:
+
+- **Sophos Central REST APIs** (retained). Every tool without the `fusion` prefix. Regional hosts, discovered from `/whoami/v1`.
+- **Sophos Fusion GraphQL APIs** (new, 18/09/2026). The `sophos_fusion_*` tools. One endpoint, `https://api.taegis.sophos.com/graphql`, same token, same `X-Tenant-ID` header. Filters are written in Fusion Query Language (QL). Case types, statuses and verdicts are tenant reference data resolved to IDs at runtime, case severity is an integer (2 to 10), and assignees are Subject IDs, not email addresses. A GraphQL failure arrives as HTTP 200 with an `errors` array; the client treats that as an error, and a partial response (data plus errors) is returned with a `warnings` list rather than as a clean result.
+
+Sophos is moving tenants to Fusion over the coming months (the [upgrade centre](https://community.sophos.com/sophos-xdr/sophos-xdr-mdr-expansion/upgrade-center) announces each account's slot). This is a point in time change, not a fallback: once a tenant has moved, the Classic Cases and Detections REST APIs reference the pre-migration Sophos Central objects, so their answers are wrong rather than stale. The Classic tools therefore check which world a tenant is in before every call, using the Fusion case reference data (a tenant that has not moved gets an empty case type list), and refuse a migrated tenant with a message naming the `sophos_fusion_*` tool to use. For a tenant that has not moved they stay correct and carry no deprecation label. Fusion holds a separate case set (a UUID plus a `CSE#####` short ID) and neither ID form resolves in the other API. Live Discover and XDR Query are unaffected. Data Lake search over GraphQL has not shipped (Sophos says October 2026), so `sophos_run_xdr_query` stays on the SQL XDR Query API. Fusion tools for events, threat timeline and live endpoint search are planned.
+
+Two Fusion case writes, `createCase` and `addEvidenceToCase`, fail 74% of the time with `not allowed` on `partnerPreferences` from `investigations-v2`. It is an intermittent downstream fault, not authorisation: the identical call succeeds on retry, and `updateCase` does not carry the fault at all. Measured on a live tenant 22/09/2026: 111 faults in 150 calls, drifting from 60% to 85% across four samples six minutes apart. The client retries a call whose first error path is `partnerPreferences`, and only that, up to 20 times with a short backoff, which leaves about 1 call in 410 failing at the measured rate and about 1 in 26 at the worst rate observed; an error naming the operation in its path is a real input or permission error and surfaces at once.
+
 ### Partner & Organisation (18 tools)
 
 > These tools are only available with **partner or organisation-level** credentials. They operate across all managed tenants.
@@ -321,11 +406,13 @@ TRANSPORT=http
 
 ### Cases (9 tools)
 
+Sophos Central Cases REST API. Correct for a tenant that has not moved to Fusion, and the only way to read its legacy cases (IDs like `1-598868`). Refused for a tenant that has moved, with a pointer to the `sophos_fusion_*` tool to use (see "Two API generations").
+
 | Tool | Description |
 |------|-------------|
 | `sophos_list_cases` | List investigation cases |
 | `sophos_get_case` | Get full case details |
-| `sophos_create_case` | Create a new investigation case |
+| `sophos_create_case` | Create a new investigation case (the API requires an assignee and a detection that still exists) |
 | `sophos_update_case` | Update case status, severity, assignee |
 | `sophos_delete_case` | Delete a case |
 | `sophos_list_case_detections` | List detections linked to a case |
@@ -333,9 +420,47 @@ TRANSPORT=http
 | `sophos_list_case_impacted_entities` | List impacted entities for a case |
 | `sophos_get_case_mitre_summary` | Get MITRE ATT&CK breakdown for a case |
 
+### Fusion Cases (21 tools)
+
+Sophos Fusion Cases GraphQL API v2. Case IDs are UUIDs; short IDs (`CSE00001`) are accepted and resolved. Severity is 2 informational, 4 low, 6 medium, 8 high, 10 critical. Detection severity inside the case summary is a 0 to 1 float, a different scale from both the case severity and the Classic REST 0 to 10 detection severity; none of them convert. There is no delete: close the case (with a verdict when its type needs one), then archive it.
+
+`managed_by` is required on create and decides who works the case: `PROVIDER` hands it to Sophos MDR, `CUSTOMER` keeps it self managed. It cannot be changed afterwards, and a case created without it is unclaimed, so the tool never omits it. Detection and event IDs on the evidence tools are six section resource names (`alert://priv:event-filter:123456:1789526908712:<uuid>`), which `sophos_fusion_search_detections` returns. Evidence writes are queued jobs that land category by category (an add showed after about 5 seconds, a three category removal took about 25 seconds), so read the evidence back with a poll; adding a detection also attaches its linked asset and events, and removing it does not retract them (`remove_all` does). Comment @mentions (`@authorized_contacts`, `@customer`, `@sophos`) fire wherever they appear, including in prose, and an unrecognised token is dropped silently, so the comment tools read the stored mentions back. Tags are merged on update unless `replace_tags` is set. File deletion is soft. Split and merge are irreversible and need a confirmation argument.
+
+| Tool | Description |
+|------|-------------|
+| `sophos_fusion_list_cases` | List cases with QL filters (type, status, verdict resolved to IDs), offset or cursor pagination |
+| `sophos_fusion_get_case` | Full case detail including key findings, verdict, links and processing status |
+| `sophos_fusion_get_case_evidence` | Detection, event, asset and saved-search source IDs attached to a case |
+| `sophos_fusion_get_case_summary` | Case plus its detections resolved in one batched call and a MITRE ATT&CK roll-up |
+| `sophos_fusion_list_case_reference_data` | The tenant's case types, primary statuses and verdicts (15 minute cache) |
+| `sophos_fusion_create_case` | Create a case: required managed_by, type and status by name or ID, integer severity, Markdown key findings, genesis evidence |
+| `sophos_fusion_update_case` | Update fields, merge or replace tags, close with a verdict, reopen (verdict cleared), archive or unarchive; refuses frozen fields on a closed case rather than reopening it |
+| `sophos_fusion_split_case` | Move named evidence into a new case (irreversible, confirm_split) |
+| `sophos_fusion_merge_cases` | Merge source cases into a target and close them (asynchronous, irreversible, confirm_merge) |
+| `sophos_fusion_list_case_comments` | List comments (raw author IDs, resolved mentions, read state) |
+| `sophos_fusion_add_case_comment` | Add a comment and report which @mentions actually fired |
+| `sophos_fusion_update_case_comment` | Edit a comment or mark it read |
+| `sophos_fusion_delete_case_comment` | Delete a comment |
+| `sophos_fusion_add_case_evidence` | Attach detections, events, hosts or saved searches (asynchronous, RNs checked) |
+| `sophos_fusion_remove_case_evidence` | Detach evidence by source ID, or everything with remove_all (asynchronous) |
+| `sophos_fusion_list_case_files` | List a case's files (deleted hidden by default, download URLs on request) |
+| `sophos_fusion_upload_case_file` | Attach a file: register, PUT to the presigned URL, poll to UPLOADED |
+| `sophos_fusion_delete_case_file` | Soft delete a file |
+| `sophos_fusion_create_case_link` | Attach an external link (ServiceNow ticket, report) |
+| `sophos_fusion_update_case_link` | Change a link's URL, title, type or reference |
+| `sophos_fusion_delete_case_link` | Remove a link |
+
+### Fusion Detections (1 tool)
+
+Sophos Fusion Detections GraphQL API v2. One QL search replaces the Classic run, poll, results triple. Source keyword `alert`; working example `from alert severity >= 0.1 EARLIEST=-90d`. Severity is a 0 to 1 float.
+
+| Tool | Description |
+|------|-------------|
+| `sophos_fusion_search_detections` | Search detections with QL; returns the resource-name IDs the case evidence tools take |
+
 ### Detections (6 tools)
 
-Async API — start a query, poll for completion, then fetch results.
+Sophos Central Detections REST API, async: start a query, poll for completion, then fetch results. Refused for a tenant that has moved to Fusion, with a pointer to `sophos_fusion_search_detections`.
 
 | Tool | Description |
 |------|-------------|
@@ -355,7 +480,7 @@ Async API — start a query, poll for completion, then fetch results.
 
 ### XDR Data Lake (9 tools)
 
-Async API — submit SQL queries against historical telemetry.
+Async API: submit SQL queries against historical telemetry.
 
 | Tool | Description |
 |------|-------------|
@@ -371,7 +496,7 @@ Async API — submit SQL queries against historical telemetry.
 
 ### Live Discover (4 tools)
 
-Async API — run OSquery SQL on live endpoints. Rate limited to 10 runs/minute, 500/day.
+Async API: run OSquery SQL on live endpoints. Rate limited to 10 runs/minute, 500/day.
 
 | Tool | Description |
 |------|-------------|
@@ -604,6 +729,7 @@ Register tools based on identity type
     |
     v
 Per tool call: resolve tenant -> regional API host -> execute request
+Per sophos_fusion_* call: resolve tenant -> POST api.taegis.sophos.com/graphql -> inspect data and errors
 ```
 
 ### Key decisions
@@ -621,10 +747,21 @@ src/
 ├── config/config.ts             # Environment config
 ├── auth/token-manager.ts        # OAuth2 token lifecycle
 ├── client/
-│   ├── sophos-client.ts         # HTTP client with region routing
+│   ├── sophos-client.ts         # REST client with region routing (Sophos Central)
+│   ├── fusion-client.ts         # GraphQL client (Sophos Fusion), 200-with-errors handling, path-keyed retry
 │   └── tenant-resolver.ts       # Whoami + tenant cache
+├── fusion/
+│   ├── queries/cases.ts         # Cases v2 GraphQL documents
+│   ├── queries/detections.ts    # Detections v2 documents: the case summary lookup and the QL search
+│   ├── case-reference-data.ts   # Per-tenant cache of case types, statuses, verdicts
+│   ├── cases-ql.ts              # QL builder for the cases search
+│   ├── format.ts                # Severity scales, timestamps, ID checks, mentions, tags, detection rows
+│   ├── migration.ts             # Has this tenant moved to Fusion? Gates the Classic case and detection tools
+│   └── types.ts                 # Fusion response types
 ├── tools/
 │   ├── helpers.ts               # Shared response formatting
+│   ├── fusion-cases.ts          # Sophos Fusion cases (GraphQL)
+│   ├── fusion-detections.ts     # Sophos Fusion detection search (GraphQL)
 │   ├── tenants.ts               # Tenant listing (partner/org only)
 │   ├── partner.ts               # Partner admin, roles, billing (partner/org only)
 │   ├── alerts.ts                # Alert list, get, acknowledge, search
@@ -652,6 +789,8 @@ src/
 └── types/sophos.ts              # Sophos API response types
 ```
 
+Packaging files at the repo root: `manifest.json` (MCPB manifest, regenerated by the build), `scripts/build-mcpb.mjs` (bundle builder), and `.mcpbignore` (extra exclusions applied when packing). `schemas/fusion/` holds the five Fusion GraphQL schemas as downloaded from `https://developer.sophos.com/assets/graphql/<api>.graphql` on 21/09/2026, unmodified, for reference and for diffing when Sophos changes them. `test/` holds the `node:test` suites and `scripts/fusion-smoke.mjs` the live check.
+
 ## Security
 
 - Credentials are read from environment variables only, never logged
@@ -659,6 +798,7 @@ src/
 - HTTP server binds to `127.0.0.1` (localhost only)
 - Write actions have `destructiveHint` annotations so clients can warn users
 - Partner/org callers require explicit `tenant_id` on every call
+- With the `.mcpb` install, Claude Desktop holds the credentials in the OS secure store (they are `sensitive` in `manifest.json`) and hands them to the server as environment variables when it starts the process
 
 ## License
 

package/dist/client/fusion-client.d.ts

@@ -0,0 +1,132 @@
+/**
+ * GraphQL client for the Sophos Fusion APIs (Cases v2, Detections v2, Threat
+ * Timeline v2, Events v1, Live Endpoint Search v1). Sits beside SophosClient,
+ * which keeps serving the Sophos Central REST APIs.
+ *
+ * One endpoint for every tenant, no regional host lookup. Auth is unchanged:
+ * the same bearer token from TokenManager and the same X-Tenant-ID header the
+ * REST client sends.
+ *
+ * The rule that shapes this file: a GraphQL-layer failure comes back as HTTP
+ * 200 with an `errors` array beside `data`. A 200 is not success until the
+ * body has been read. Transport failures (expired token, 429, 5xx) use the
+ * usual non-2xx status and the standard Sophos error object, and those are
+ * retried the same way SophosClient retries them. GraphQL-layer errors are
+ * not retried, with one measured exception: the intermittent
+ * partnerPreferences fault on the case write path, which is keyed on the
+ * error path and bounded (see FusionGraphQLError.isTransientPartnerPreferences).
+ */
+import type { TokenManager } from "../auth/token-manager.js";
+/** One entry of a GraphQL response `errors` array. */
+export interface GraphQLErrorEntry {
+    message: string;
+    path?: Array<string | number>;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    extensions?: Record<string, unknown>;
+}
+interface GraphQLResponseBody<T> {
+    data?: T | null;
+    errors?: GraphQLErrorEntry[];
+}
+export interface FusionQueryResult<T> {
+    /** The response `data` object. Never null: a response with no usable data throws. */
+    data: T;
+    /**
+     * GraphQL errors that arrived beside usable data (a partial response, for
+     * example a federated field that could not be resolved). Empty on a clean
+     * response. Tools must surface these; they are not silently dropped.
+     */
+    warnings: string[];
+}
+export interface FusionClientOptions {
+    /** GraphQL endpoint. Defaults to SOPHOS_FUSION_GRAPHQL_URL. */
+    url?: string;
+    /** Per-attempt timeout. Default 30 s, matching SophosClient. */
+    timeoutMs?: number;
+    /** Retries after the first attempt for 429, 5xx and network errors. Default 2. */
+    retries?: number;
+    /** Base for the full-jitter exponential backoff. Default 1000 ms. */
+    backoffBaseMs?: number;
+    /**
+     * Total attempts for a call that hits the transient partnerPreferences
+     * fault, which affects createCase and addEvidenceToCase. Measured on a live
+     * tenant 22/09/2026: 111 faults in 150 calls, so 74%, and it drifts, with
+     * four samples over six minutes running 60%, 85%, 72.5% and 80%. Default 20:
+     * about 1 call in 410 fails at the measured 74%, and about 1 in 26 at the
+     * worst rate observed. updateCase does not carry the fault at all, 0 in 30
+     * in the same minute addEvidenceToCase was 24 in 30, so the defect is in the
+     * two resolvers that read partner preferences.
+     */
+    transientAttempts?: number;
+    /** Base for the short full-jitter backoff between those attempts. Default 300 ms, capped at 2 s. */
+    transientBackoffMs?: number;
+}
+/** Thrown when the GraphQL layer returns errors and no usable data. */
+export declare class FusionGraphQLError extends Error {
+    readonly errors: GraphQLErrorEntry[];
+    constructor(message: string, errors: GraphQLErrorEntry[]);
+    /**
+     * True when every error says the record does not exist. Fusion reports an
+     * unknown case ID this way, as HTTP 200 with "record not found" beside a
+     * null root field, rather than as a bare null (live tenant, 21/09/2026).
+     */
+    get notFound(): boolean;
+    /**
+     * True for the intermittent investigations-v2 fault on the case write
+     * path: `errors[0].path[0]` is "partnerPreferences" ("not allowed",
+     * DOWNSTREAM_SERVICE_ERROR). It is not an authorisation failure: the
+     * identical call with identical input succeeds on retry. Keyed on the path
+     * and nothing else, because `extensions.code` is DOWNSTREAM_SERVICE_ERROR
+     * for transient faults, not found and malformed queries alike, while a
+     * genuine input or permission error carries the operation name in the path
+     * (createCase, addEvidenceToCase, tdrusers) with a specific message.
+     */
+    get isTransientPartnerPreferences(): boolean;
+}
+export declare class FusionClient {
+    private tokenManager;
+    private readonly url;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly backoffBaseMs;
+    private readonly transientAttempts;
+    private readonly transientBackoffMs;
+    constructor(tokenManager: TokenManager, options?: FusionClientOptions);
+    /** The endpoint this client posts to. */
+    get endpoint(): string;
+    /**
+     * Run a GraphQL query or mutation for a tenant.
+     *
+     * Returns the `data` object plus any partial-response warnings. Throws
+     * FusionGraphQLError when the response carries errors and no usable data,
+     * and a plain Error for transport failures. The transient partnerPreferences
+     * fault is retried up to transientAttempts times; every other GraphQL-layer
+     * error surfaces at once.
+     */
+    query<T extends object>(tenantId: string, document: string, variables?: Record<string, unknown>): Promise<FusionQueryResult<T>>;
+    /**
+     * PUT raw bytes to a presigned upload URL (case files). The signature lives
+     * in the URL, so no bearer token is sent, and the Content-Type must match
+     * what startCaseFileUpload was told. One attempt, no retry.
+     */
+    putPresigned(url: string, body: Uint8Array, contentType: string): Promise<void>;
+    private executeWithRetry;
+    private sleep;
+}
+/**
+ * Decide what a 200 response actually means.
+ *
+ * - errors present, no usable data: throw with every message joined.
+ * - errors present beside usable data: return the data with the errors as warnings.
+ * - no errors, data present: clean result. A root field that is null with no
+ *   error (for example `case` for an unknown ID) is legitimate and passes
+ *   through for the tool to report.
+ * - no errors, no data: malformed, throw.
+ */
+export declare function interpretGraphQLBody<T extends object>(body: GraphQLResponseBody<T> | null | undefined): FusionQueryResult<T>;
+export declare function formatGraphQLError(error: GraphQLErrorEntry): string;
+export {};
+//# sourceMappingURL=fusion-client.d.ts.map

package/dist/client/fusion-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion-client.d.ts","sourceRoot":"","sources":["../../src/client/fusion-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC9B,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,UAAU,mBAAmB,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAChB,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,qFAAqF;IACrF,IAAI,EAAE,CAAC,CAAC;IACR;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oGAAoG;IACpG,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID,uEAAuE;AACvE,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,EAAE;gBADpC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,iBAAiB,EAAE;IAMtC;;;;OAIG;IACH,IAAI,QAAQ,IAAI,OAAO,CAKtB;IAED;;;;;;;;;OASG;IACH,IAAI,6BAA6B,IAAI,OAAO,CAE3C;CACF;AAED,qBAAa,YAAY;IASrB,OAAO,CAAC,YAAY;IARtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;gBAGlC,YAAY,EAAE,YAAY,EAClC,OAAO,GAAE,mBAAwB;IAUnC,yCAAyC;IACzC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;;;;;OAQG;IACG,KAAK,CAAC,CAAC,SAAS,MAAM,EAC1B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACtC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAsChC;;;;OAIG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YA2BvE,gBAAgB;IAqF9B,OAAO,CAAC,KAAK;CAGd;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,EACnD,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GAC9C,iBAAiB,CAAC,CAAC,CAAC,CAqBtB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAUnE"}