@thorcollective/hearth-mcp 0.0.1 → 0.1.1

package/README.md

@@ -86,6 +86,31 @@ Add this to `.vscode/mcp.json` in your workspace:
 
 Set them in your client's config, for example `"env": { "HEARTH_OFFLINE": "1" }` next to `"args"`.
 
+### Locked-down setup (enterprise)
+
+For teams that review every change before it reaches analysts:
+
+- **Pin the version.** `npx -y @thorcollective/hearth-mcp` always fetches the latest release. Name an exact version instead, and nothing changes until you choose to upgrade.
+- **Turn off the network.** `HEARTH_OFFLINE=1` stops the daily check, so the server only uses the hunt data that shipped with the version you pinned.
+- **Or use your own mirror.** Set `HEARTH_DATA_URL` to an internal copy of the site's data files, which you update on your own schedule.
+- **Verify the package.** After installing, run `npm audit signatures` to check that the package was built from this repository by GitHub Actions.
+
+For example, in Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "hearth": {
+      "command": "npx",
+      "args": ["-y", "@thorcollective/hearth-mcp@0.1.1"],
+      "env": { "HEARTH_OFFLINE": "1" }
+    }
+  }
+}
+```
+
+[Releases](https://www.npmjs.com/package/@thorcollective/hearth-mcp?activeTab=versions) lists every version.
+
 ### Other clients
 
 Any MCP client that supports stdio servers can run the same command: `npx -y @thorcollective/hearth-mcp`.
@@ -124,7 +149,7 @@ The server reuses the site's own logic from `src/lib`, so search behaves the sam
 
 Maintainers only:
 
-1. Bump `version` in `mcp/package.json` and `mcp/server.json`. A test fails if they differ.
+1. Bump `version` in `mcp/package.json`, `mcp/server.json` and the pinned example under **Locked-down setup** in this README. A test fails if any of them differ.
 2. Merge to `main`.
 3. Push a tag named `mcp-v<version>`, for example `mcp-v0.1.0`.
 
@@ -132,4 +157,7 @@ The [publish workflow](../.github/workflows/publish-mcp.yml) then:
 
 1. Waits for approval in the `npm-publish` environment.
 2. Publishes to npm with provenance, using trusted publishing (no npm token is stored).
-3. Lists the release in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.THORCollective/hearth`.
+3. Waits for npm to serve the new version, which can take several minutes.
+4. Lists the release in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.THORCollective/hearth`.
+
+If the run fails after the npm publish, use **Re-run failed jobs**. A version already on npm is never published twice, so the re-run picks up at the registry step.

package/dist/index.js

@@ -567,6 +567,11 @@ async function refresh(opts, meta) {
 import { McpServer } from "@modelcontextprotocol/server";
 import * as z2 from "zod/v4";
 
+// ../src/lib/coverage.ts
+function gapSubmitUrl(techniqueId) {
+  return `submit.html?technique=${encodeURIComponent(techniqueId)}`;
+}
+
 // ../src/lib/hunt-search.ts
 var DEFAULT_LIMIT = 20;
 var MAX_LIMIT = 100;
@@ -678,9 +683,13 @@ function searchHunts(hunts, q, index = EMPTY_INDEX) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.0.1" : "dev";
+var VERSION = true ? "0.1.1" : "dev";
 var REPO_URL = "https://github.com/THORCollective/HEARTH/blob/main/";
 var MAX_GAPS = 25;
+var SITE_URL = "https://hearth.thorcollective.com/";
+var SUBMIT_URL = SITE_URL + "submit.html";
+var SUBMIT_HUNT = `No HEARTH hunt covers this yet. Anyone can submit one: ${SUBMIT_URL}`;
+var SubmitHunt = z2.string().optional().describe("Present when HEARTH has no hunt for part of the request: where to submit one");
 var DataSourceList = z2.array(z2.enum(DATA_SOURCE_IDS)).min(1).max(DATA_SOURCE_IDS.length).describe(
   "Data source categories you have: endpoint (EDR/Sysmon), windows (Windows event logs), network (firewall/flow/DNS/IDS), cloud (cloud & M365/Workspace audit), identity (AD/IdP/auth), email, web_proxy, application (SaaS/CI/web server), macos, appliance (network appliance & hypervisor logs)"
 );
@@ -835,7 +844,8 @@ function createServer(source) {
       }),
       outputSchema: z2.object({
         total: z2.number().int(),
-        hunts: z2.array(HuntSummary)
+        hunts: z2.array(HuntSummary),
+        submit_hunt: SubmitHunt
       }),
       annotations: { readOnlyHint: true, openWorldHint: false }
     },
@@ -853,7 +863,11 @@ function createServer(source) {
         },
         data.index
       );
-      return result({ total, hunts: hunts.map((h) => summary(h, data)) });
+      return result({
+        total,
+        hunts: hunts.map((h) => summary(h, data)),
+        submit_hunt: total === 0 ? SUBMIT_HUNT : void 0
+      });
     }
   );
   server.registerTool(
@@ -895,7 +909,8 @@ function createServer(source) {
             )
           })
         ),
-        gaps: z2.array(z2.object({ technique: z2.string(), tactic: z2.string() })).describe(`Actor techniques no HEARTH hunt covers (first ${MAX_GAPS})`)
+        gaps: z2.array(z2.object({ technique: z2.string(), tactic: z2.string(), submit_url: z2.string() })).describe(`Actor techniques no HEARTH hunt covers (first ${MAX_GAPS})`),
+        submit_hunt: SubmitHunt
       }),
       annotations: { readOnlyHint: true, openWorldHint: false }
     },
@@ -920,6 +935,7 @@ function createServer(source) {
       })).sort(
         (a, b) => Number(b.reasons.includes("MENTION")) - Number(a.reasons.includes("MENTION")) || Number(b.missing?.length === 0) - Number(a.missing?.length === 0) || b.relevance - a.relevance || idNumber2(b.hunt.id) - idNumber2(a.hunt.id)
       );
+      const gaps = computeGap(actor.id, allMatches, data.actors);
       const url = actor.external_references?.find((r) => r.source === "mitre-attack")?.url;
       return result({
         actor: { id: groupId(actor.id), name: actor.label, aliases: actor.aliases, url },
@@ -939,7 +955,12 @@ function createServer(source) {
           shared_techniques: m.sharedTechniques,
           relevance: m.relevance
         })),
-        gaps: computeGap(actor.id, allMatches, data.actors).slice(0, MAX_GAPS).map((g) => ({ technique: g.id, tactic: g.tactic }))
+        gaps: gaps.slice(0, MAX_GAPS).map((g) => ({
+          technique: g.id,
+          tactic: g.tactic,
+          submit_url: SITE_URL + gapSubmitUrl(g.id)
+        })),
+        submit_hunt: gaps.length > 0 || matches.length === 0 ? SUBMIT_HUNT : void 0
       });
     }
   );
@@ -964,7 +985,8 @@ function createServer(source) {
             have_all_sources: z2.boolean(),
             missing_sources: z2.array(z2.enum(DATA_SOURCE_IDS))
           })
-        )
+        ),
+        submit_hunt: SubmitHunt
       }),
       annotations: { readOnlyHint: true, openWorldHint: false }
     },
@@ -993,7 +1015,8 @@ function createServer(source) {
         total: rows.length,
         full_matches: rows.filter((r) => r.have_all_sources).length,
         by_category: byCategory,
-        hunts: rows.slice(0, args.limit ?? DEFAULT_LIMIT)
+        hunts: rows.slice(0, args.limit ?? DEFAULT_LIMIT),
+        submit_hunt: rows.length === 0 ? SUBMIT_HUNT : void 0
       });
     }
   );
@@ -1009,7 +1032,7 @@ async function main() {
     ...config,
     bundledDir: DATA_DIR,
     cacheDir: process.env.HEARTH_CACHE_DIR || defaultCacheDir(),
-    snapshotAt: true ? "2026-11-09T21:50:25.103Z" : void 0,
+    snapshotAt: true ? "2026-11-10T16:49:28.515Z" : void 0,
     userAgent: `hearth-mcp/${VERSION}`,
     log
   };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thorcollective/hearth-mcp",
   "mcpName": "io.github.THORCollective/hearth",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "Read-only MCP server for HEARTH, the community threat hunting hypothesis library",
   "keywords": [
     "mcp",