@primitivehub/mcp-server 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to `@primitivehub/mcp-server` are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Version tracks Trust Contract spec version (for `verify_bundle`) and
+Context CI Top 10 version (for `scan_text` / `audit_workspace`);
+`0.1.x` of this package is conformant to both v0.1.
+
+## [Unreleased]
+
+### Added (PR 5.7.5 — MCP runtime gate, ADR-0029)
+- **`verify_before_load`** tool — the composite runtime gate. Combines
+  `check_lock` + scanner verdict + optional `verify_bundle` into one
+  call. Returns `{safe, reasons[], checks}`. Refuses-by-default for
+  drift, unattested artifacts (`requireAttestation: true`), scanner
+  findings, missing locks, and invalid bundles. Eight stable refusal
+  codes (`LOCK_MISSING`, `PATH_NOT_IN_LOCK`, `PATH_DIGEST_MISMATCH`,
+  `PATH_FLAGGED_BY_SCANNER`, `PATH_UNATTESTED`, …) plus
+  `BUNDLE_<code>` for every `VerificationErrorCode` from the verify
+  library.
+- Tool count is now **5** (was 4). Per ADR-0031 § 2 rule #2 the
+  surface is additive — no breaking changes to existing tools.
+- Trust-decision logic lives in `@primitivehub/phub` (exported as
+  `verifyBeforeLoad`) per ADR-0031 § 2 rule #1. The MCP wrapper is
+  pure transport.
+
+## [0.1.0] — 2026-06-02
+
+**Not yet published to npm.** Per
+[ADR-0022](../../docs/decisions/0022-publishing-deferred-to-launch.md)
+publishing is gated to the project launch event. The server is fully
+functional inside the monorepo today; `npx @primitivehub/mcp-server`
+is a launch-day capability.
+
+### Added — initial Gate G-D release
+
+Per [ADR-0031](../../docs/decisions/0031-mcp-server-as-transport.md)
+the v0.1 server is a pure transport layer over existing primitives.
+Zero custom trust logic; every tool delegates.
+
+- **`verify_bundle`** — wraps `@primitivehub/verify`'s `verifyBundle`.
+  Accepts a Trust Bundle as a JSON string OR a pre-parsed object.
+  Levels: `structural` / `policy` / `full` (steps 3-6 stubbed per
+  verify v0.1).
+- **`scan_text`** — runs the v0.1 detector roster (T1/T2/T5) over
+  arbitrary text. Wraps phub's `runScan`. Honors `--policy` /
+  `--strict` / `--allow-fail` / `--detector`.
+- **`audit_workspace`** — active-surface tool. Walks + classifies +
+  scans every agent-context artifact under a root path. Wraps phub's
+  `runAudit`. Output includes per-artifact verdicts + project
+  summary.
+- **`check_lock`** — compares the workspace against
+  `.primitivehub/phub.lock` and reports drift. Wraps phub's
+  `runAudit` with `lockMode: "check"`.
+- **stdio transport** (default) — `primitivehub-mcp` binary speaks
+  MCP over stdin/stdout. Standard pattern; works with every MCP host
+  (Claude Code, Cursor, Aider, …).
+- **Programmatic API** — `buildServer()`, `runStdio()`, individual
+  tool callables for in-process / SSE / HTTP transports.
+- **Worked examples** (`examples/`) — Claude Code, Cursor, Aider
+  config snippets verified to register the server with four
+  visible tools.
+
+### Runtime deps
+
+- `@modelcontextprotocol/sdk` `^1.0.0` — the official MCP SDK; not
+  hand-rolled (justified in ADR-0031 § "Alternatives").
+- `@primitivehub/verify` `^0.1.0` (via `file:` pre-launch).
+- `@primitivehub/phub` `^0.1.0` (via `file:` pre-launch).
+
+### Tests
+- `test/tools.test.ts` — 16 cases, in-process tool wrappers.
+- `test/server.test.ts` — 6 cases, JSON-RPC via `InMemoryTransport`.
+- 22/22 passing.
+
+### Forward-looking (next PRs, not in this release)
+
+- **MCP runtime gate** (planned [ADR-0029](../../docs/decisions/0026-phub-lock-format-and-drift-detection.md))
+  — `verify_before_load` composite tool that combines `check_lock`
+  + `verify_bundle` and is consulted by agents at primitive-read
+  time. Refuses-by-default for unattested content.
+- **SSE / HTTP transports** — for browser-based agents that can't
+  spawn stdio child processes.
+- **Tool surface additions as detectors land** — `verify_bundle`
+  inherits verify v0.2 (signature/cert/Rekor); `scan_text` and
+  `audit_workspace` inherit new detector classes via phub's
+  detector registry.
+
+[Unreleased]: https://github.com/PrimitiveHub-AI/context-ci/compare/mcp-server-v0.1.0...HEAD
+[0.1.0]: https://github.com/PrimitiveHub-AI/context-ci/releases/tag/mcp-server-v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PrimitiveHub AI / CyberOrca Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# @primitivehub/mcp-server
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+**Model Context Protocol server exposing PrimitiveHub verification +
+scanning to AI agents** (Claude Code, Cursor, Aider, etc.). Pure
+transport over [`@primitivehub/verify`](../verify/) and
+[`@primitivehub/phub`](../phub/) — **zero custom trust logic** per
+Gate G-D acceptance + [ADR-0031](../../docs/decisions/0031-mcp-server-as-transport.md).
+
+## What it does
+
+Lets an AI agent ask, mid-task:
+
+- "Is this Trust Bundle valid?" → `verify_bundle`
+- "Does this text trip Context CI Top 10?" → `scan_text`
+- "What context primitives are in this workspace, and which are
+  flagged?" → `audit_workspace`
+- "Has any context primitive in this workspace changed since the
+  operator last sealed it?" → `check_lock`
+
+Every tool is a pure wrapper. If the verify library changes its
+behavior, this server inherits it. If the scanner roster expands
+(T3/T4/T6..T10), this server surfaces it. There is one authoritative
+trust implementation; this package is the wire format.
+
+## Install
+
+Per [ADR-0022](../../docs/decisions/0022-publishing-deferred-to-launch.md)
+publishing is gated to the project launch event. Post-launch:
+
+```bash
+# Add to Claude Code (one line):
+claude mcp add primitivehub --command "npx @primitivehub/mcp-server"
+
+# Or globally:
+pnpm add -g @primitivehub/mcp-server
+primitivehub-mcp   # speaks MCP over stdio
+```
+
+Requires Node ≥ 20.
+
+## Quick-start configurations
+
+### Claude Code
+
+`~/.claude.json` (or `.claude.json` in the project):
+
+```json
+{
+  "mcpServers": {
+    "primitivehub": {
+      "command": "npx",
+      "args": ["@primitivehub/mcp-server"]
+    }
+  }
+}
+```
+
+Then `claude mcp list` shows `primitivehub` with four tools.
+
+### Cursor
+
+`.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "primitivehub": {
+      "command": "npx",
+      "args": ["-y", "@primitivehub/mcp-server"]
+    }
+  }
+}
+```
+
+### Aider
+
+`~/.aider.conf.yml`:
+
+```yaml
+# MCP support landed in Aider 0.85+
+mcp-servers:
+  primitivehub:
+    command: npx
+    args: ["@primitivehub/mcp-server"]
+```
+
+See [`examples/`](./examples/) for full end-to-end configurations.
+
+## Tools
+
+### `verify_bundle`
+
+Verify a [Trust Contract v0.1](../../docs/trust-contract-v0.1.md)
+bundle. Wraps `@primitivehub/verify`'s `verifyBundle`. Steps 3-6
+stubbed in v0.1 (see verify README).
+
+**Arguments:**
+
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `bundle` | string \| object | yes | — |
+| `level` | `"structural"` \| `"policy"` \| `"full"` | no | `"policy"` |
+| `strict` | boolean | no | `false` |
+| `allow_fail_for` | string[] | no | `[]` |
+
+### `scan_text`
+
+Run the v0.1 detector roster (T1/T2/T5) against text. Wraps phub's
+`runScan`.
+
+**Arguments:**
+
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `content` | string | yes | — |
+| `filename` | string | no | `"<inline>"` |
+| `detectors` | string[] | no | all |
+| `strict` | boolean | no | `false` |
+| `policy_path` | string | no | auto-discover |
+| `allow_fail` | string[] | no | `[]` |
+
+### `audit_workspace`
+
+Active surface — discovers + classifies + scans every agent-context
+artifact under a root. Wraps phub's `runAudit` per [ADR-0025](../../docs/decisions/0025-active-posture-and-phub-audit.md).
+
+**Arguments:**
+
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `root` | string | no | `process.cwd()` |
+| `max_files` | number | no | `10000` |
+| `max_depth` | number | no | `16` |
+| `strict` | boolean | no | `false` |
+| `detectors` | string[] | no | all |
+| `policy_path` | string | no | auto-discover |
+| `allow_fail` | string[] | no | `[]` |
+
+### `check_lock`
+
+Compares the workspace against `.primitivehub/phub.lock` per
+[ADR-0026](../../docs/decisions/0026-phub-lock-format-and-drift-detection.md)
+and reports drift (added / modified / removed / reclassified).
+
+**Arguments:**
+
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `root` | string | no | `process.cwd()` |
+| `lock_path` | string | no | `./.primitivehub/phub.lock` |
+| `policy_path` | string | no | auto-discover |
+| `max_files` | number | no | `10000` |
+| `max_depth` | number | no | `16` |
+
+## Design discipline
+
+Per [ADR-0031](../../docs/decisions/0031-mcp-server-as-transport.md)
+this package is a transport layer with three load-bearing rules:
+
+1. **Zero custom trust logic.** Every tool delegates to a primitive
+   that already exists (verify / phub). If a behavioral question
+   doesn't have an answer in the delegated primitive, the answer is
+   "we don't ship that tool yet" — not "we'll re-implement it here."
+2. **Schema-stable tool surface.** Adding a tool is additive (no
+   breaking change). Renaming or removing a tool requires a SemVer
+   major bump on this package.
+3. **No state retention.** Every tool call is stateless. The server
+   does not cache, queue, or remember invocations. The agent's
+   conversation is the only state that matters.
+
+The MCP runtime gate `verify_before_load` (planned [ADR-0029](../../docs/decisions/0026-phub-lock-format-and-drift-detection.md))
+is a composite of `check_lock` + `verify_bundle` applied at the
+agent's read time. v0.1 of this package exposes the primitives; the
+composite gate ships when ADR-0029 lands.
+
+## Programmatic embedding
+
+For tests / alternative transports (SSE, HTTP in v0.2+):
+
+```ts
+import { buildServer } from "@primitivehub/mcp-server"
+
+const server = buildServer()
+// Connect over an SDK transport of your choice:
+//   StdioServerTransport, InMemoryTransport, etc.
+```
+
+## Versioning + publishing
+
+Tracks Trust Contract spec version + Context CI Top 10 version
+(both v0.1 in this release).
+
+Per [ADR-0022](../../docs/decisions/0022-publishing-deferred-to-launch.md)
+publishing is gated to launch via the same three-lock model as
+`@primitivehub/verify` and `@primitivehub/phub`.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## References
+
+- [ADR-0031 — `@primitivehub/mcp-server` as the MCP transport layer](../../docs/decisions/0031-mcp-server-as-transport.md)
+- [ADR-0023 — `phub` CLI + detector parity](../../docs/decisions/0023-phub-cli-and-detector-parity.md)
+- [ADR-0025 — Active posture + `phub audit`](../../docs/decisions/0025-active-posture-and-phub-audit.md)
+- [ADR-0026 — `phub.lock` format + drift detection](../../docs/decisions/0026-phub-lock-format-and-drift-detection.md)
+- [ADR-0018 — Context Policy Language v0.1](../../docs/decisions/0018-context-policy-language.md)
+- [Model Context Protocol](https://modelcontextprotocol.io/) — the protocol spec

package/bin/primitivehub-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runStdio } from "../dist/server.js"
+
+runStdio().catch((err) => {
+  console.error(err instanceof Error ? err.stack ?? err.message : String(err))
+  process.exit(1)
+})

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Programmatic API surface.
+ *
+ * The primary distribution is the `primitivehub-mcp` binary
+ * (`bin/primitivehub-mcp.js`) which connects over stdio. The exports
+ * below let the server be embedded inline (e.g. for in-process tests
+ * or alternative transports like SSE / HTTP that ship in v0.2+).
+ */
+export { buildServer, runStdio, SERVER_NAME, SERVER_VERSION, TOOLS } from "./server.js";
+export { VERIFY_BUNDLE_TOOL, callVerifyBundle } from "./tools/verify-bundle.js";
+export { SCAN_TEXT_TOOL, callScanText } from "./tools/scan-text.js";
+export { AUDIT_WORKSPACE_TOOL, callAuditWorkspace } from "./tools/audit-workspace.js";
+export { CHECK_LOCK_TOOL, callCheckLock } from "./tools/check-lock.js";
+export { VERIFY_BEFORE_LOAD_TOOL, callVerifyBeforeLoad } from "./tools/verify-before-load.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACvF,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC/E,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnE,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACrF,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACtE,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * Programmatic API surface.
+ *
+ * The primary distribution is the `primitivehub-mcp` binary
+ * (`bin/primitivehub-mcp.js`) which connects over stdio. The exports
+ * below let the server be embedded inline (e.g. for in-process tests
+ * or alternative transports like SSE / HTTP that ship in v0.2+).
+ */
+export { buildServer, runStdio, SERVER_NAME, SERVER_VERSION, TOOLS } from "./server.js";
+export { VERIFY_BUNDLE_TOOL, callVerifyBundle } from "./tools/verify-bundle.js";
+export { SCAN_TEXT_TOOL, callScanText } from "./tools/scan-text.js";
+export { AUDIT_WORKSPACE_TOOL, callAuditWorkspace } from "./tools/audit-workspace.js";
+export { CHECK_LOCK_TOOL, callCheckLock } from "./tools/check-lock.js";
+export { VERIFY_BEFORE_LOAD_TOOL, callVerifyBeforeLoad } from "./tools/verify-before-load.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACvF,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC/E,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnE,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACrF,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACtE,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA"}

package/dist/server.d.ts

@@ -0,0 +1,214 @@
+/**
+ * @primitivehub/mcp-server — Model Context Protocol server exposing
+ * PrimitiveHub verification + scanning to AI agents.
+ *
+ * Zero custom trust logic (Gate G-D acceptance criterion). Every
+ * tool is a pure transport over an existing primitive:
+ *
+ *   verify_bundle    → @primitivehub/verify (ADR-0020)
+ *   scan_text        → @primitivehub/phub runScan (ADR-0023)
+ *   audit_workspace  → @primitivehub/phub runAudit (ADR-0025)
+ *   check_lock       → @primitivehub/phub runAudit + lockMode:check (ADR-0026)
+ *
+ * If the verifier changes its behavior, the MCP server inherits it.
+ * If the scanner roster expands (T3/T4/T6..T10), the MCP server
+ * surfaces it automatically. The trust chain has one authoritative
+ * implementation; this package is just a wire format.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare const SERVER_NAME = "primitivehub";
+export declare const SERVER_VERSION = "0.1.0";
+export declare const TOOLS: readonly [{
+    readonly name: "verify_bundle";
+    readonly description: "Verify a PrimitiveHub Trust Bundle against the v0.1 wire format. Runs schema validation, content-digest verification, and Context CI policy evaluation. Steps 3-6 (signature/cert/Rekor) are stubbed in v0.1 — pass level: 'full' to see DEFERRED failures. All verification runs locally; no network calls.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["bundle"];
+        readonly properties: {
+            readonly bundle: {
+                readonly description: "The Trust Bundle as a JSON string OR a pre-parsed JSON object. Strings are JSON.parse'd before verification.";
+                readonly oneOf: readonly [{
+                    readonly type: "string";
+                }, {
+                    readonly type: "object";
+                }];
+            };
+            readonly level: {
+                readonly type: "string";
+                readonly enum: readonly ["structural", "policy", "full"];
+                readonly description: "Verification depth. 'structural' = schema + digest (steps 1+2). 'policy' (default) = + Context CI policy (steps 1+2+7). 'full' = + signature/cert/Rekor (steps 1-7; steps 3-6 stubbed in v0.1).";
+            };
+            readonly strict: {
+                readonly type: "boolean";
+                readonly description: "Treat predicate WARN verdicts as FAIL during policy evaluation.";
+            };
+            readonly allow_fail_for: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Detector names, CCI IDs, or threat categories that are permitted to FAIL without rejecting the bundle.";
+            };
+        };
+    };
+}, {
+    readonly name: "scan_text";
+    readonly description: "Run the PrimitiveHub Context CI Top 10 v0.1 detectors (T1 prompt-injection, T2 Unicode-steganography, T5 unsafe-shell-install) against a string. Pure-local scan; no network. Returns per-detector verdicts, post-policy. Use this BEFORE loading any agent-context content from an untrusted source.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["content"];
+        readonly properties: {
+            readonly content: {
+                readonly type: "string";
+                readonly description: "The text to scan (typically markdown — AGENTS.md, CLAUDE.md, .cursorrules, a skill body, etc.).";
+            };
+            readonly filename: {
+                readonly type: "string";
+                readonly description: "Optional filename for the content (used for policy matching against per-file allow rules). Defaults to '<inline>'.";
+            };
+            readonly detectors: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Restrict to specific detectors. Accepts detector names (t1.prompt_injection), CCI IDs (CCI-001), or threat categories (T1). Empty/omitted = all.";
+            };
+            readonly strict: {
+                readonly type: "boolean";
+                readonly description: "Treat WARN verdicts as FAIL for the policy exit code.";
+            };
+            readonly policy_path: {
+                readonly type: "string";
+                readonly description: "Path to a .primitivehub/policy.yaml file (ADR-0018). Without this: auto-discover from cwd → git root, fall back to implicit default.";
+            };
+            readonly allow_fail: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Detector/CCI/threat IDs permitted to FAIL without rejecting the scan. Appended to policy.allow as synthetic entries.";
+            };
+        };
+    };
+}, {
+    readonly name: "audit_workspace";
+    readonly description: "Recursively discover, classify, and scan every agent-context artifact (AGENTS.md, CLAUDE.md, .cursorrules, .claude/skills/**, mcp.json, …) under a root path. Reuses the same T1/T2/T5 detector roster as scan_text. Returns inventory + per-artifact verdicts + project-level summary. Use this as the active default — file-at-a-time scanning can't defend against files the agent didn't know about.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly root: {
+                readonly type: "string";
+                readonly description: "Directory to audit. Defaults to the server's cwd.";
+            };
+            readonly max_files: {
+                readonly type: "number";
+                readonly description: "Hard cap on artifacts traversed. Default 10000.";
+            };
+            readonly max_depth: {
+                readonly type: "number";
+                readonly description: "Maximum directory depth from root. Default 16.";
+            };
+            readonly strict: {
+                readonly type: "boolean";
+                readonly description: "Treat WARN verdicts as FAIL.";
+            };
+            readonly detectors: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Restrict to specific detectors. Accepts names / CCI IDs / threat categories.";
+            };
+            readonly policy_path: {
+                readonly type: "string";
+                readonly description: "Path to a .primitivehub/policy.yaml. Without this: auto-discover from cwd → git root.";
+            };
+            readonly allow_fail: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+        };
+    };
+}, {
+    readonly name: "check_lock";
+    readonly description: "Compare the workspace against .primitivehub/phub.lock and report drift (added / modified / removed / reclassified artifacts). Use this BEFORE consuming any agent-context primitive — drift means an artifact changed since the operator last sealed it. Returns drift summary; the agent decides whether to proceed.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly root: {
+                readonly type: "string";
+                readonly description: "Workspace root to check. Defaults to server cwd.";
+            };
+            readonly lock_path: {
+                readonly type: "string";
+                readonly description: "Override the auto-discovered lock path. Without this: ./.primitivehub/phub.lock.";
+            };
+            readonly policy_path: {
+                readonly type: "string";
+                readonly description: "Policy file path (same semantics as scan_text/audit_workspace).";
+            };
+            readonly max_files: {
+                readonly type: "number";
+                readonly description: "Hard cap on artifacts walked. Default 10000.";
+            };
+            readonly max_depth: {
+                readonly type: "number";
+                readonly description: "Max directory depth. Default 16.";
+            };
+        };
+    };
+}, {
+    readonly name: "verify_before_load";
+    readonly description: "Composite runtime gate. Call this BEFORE loading any agent-context primitive — refuses-by-default for drift, unattested artifacts, scanner findings, or invalid Trust Bundles. Returns {safe, reasons[], checks}. The composite of check_lock + scan_text + (optional) verify_bundle.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["path"];
+        readonly properties: {
+            readonly path: {
+                readonly type: "string";
+                readonly description: "The artifact path to gate (relative to workspace_root, or absolute). The agent's 'I'm about to read this file' anchor.";
+            };
+            readonly workspace_root: {
+                readonly type: "string";
+                readonly description: "Workspace root. Defaults to the server's cwd.";
+            };
+            readonly policy_path: {
+                readonly type: "string";
+                readonly description: "Path to .primitivehub/policy.yaml. Auto-discover if absent.";
+            };
+            readonly lock_path: {
+                readonly type: "string";
+                readonly description: "Explicit lock path. Auto-discover if absent.";
+            };
+            readonly require_attestation: {
+                readonly type: "boolean";
+                readonly description: "If true, an 'unattested' lock entry counts as unsafe. Use when consuming registry primitives that should carry rekor:* or registry:* attestations. Default false (matches v0.1 lock semantics).";
+            };
+            readonly bundle: {
+                readonly description: "Optional Trust Bundle (JSON string OR parsed object). When provided, verify_bundle runs at the requested level and contributes its failures to the unsafe reasons.";
+                readonly oneOf: readonly [{
+                    readonly type: "string";
+                }, {
+                    readonly type: "object";
+                }];
+            };
+            readonly level: {
+                readonly type: "string";
+                readonly enum: readonly ["structural", "policy", "full"];
+                readonly description: "Bundle verification depth. Only meaningful when 'bundle' is provided. Default 'policy'.";
+            };
+        };
+    };
+}];
+/** Build a configured but not-yet-connected MCP server. */
+export declare function buildServer(): Server;
+/** Connect over stdio. Used by `bin/primitivehub-mcp.js`. */
+export declare function runStdio(): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAalE,eAAO,MAAM,WAAW,iBAAiB,CAAA;AACzC,eAAO,MAAM,cAAc,UAAU,CAAA;AAErC,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMR,CAAA;AAEV,2DAA2D;AAC3D,wBAAgB,WAAW,IAAI,MAAM,CAsCpC;AAED,6DAA6D;AAC7D,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAI9C"}

package/dist/server.js

@@ -0,0 +1,71 @@
+/**
+ * @primitivehub/mcp-server — Model Context Protocol server exposing
+ * PrimitiveHub verification + scanning to AI agents.
+ *
+ * Zero custom trust logic (Gate G-D acceptance criterion). Every
+ * tool is a pure transport over an existing primitive:
+ *
+ *   verify_bundle    → @primitivehub/verify (ADR-0020)
+ *   scan_text        → @primitivehub/phub runScan (ADR-0023)
+ *   audit_workspace  → @primitivehub/phub runAudit (ADR-0025)
+ *   check_lock       → @primitivehub/phub runAudit + lockMode:check (ADR-0026)
+ *
+ * If the verifier changes its behavior, the MCP server inherits it.
+ * If the scanner roster expands (T3/T4/T6..T10), the MCP server
+ * surfaces it automatically. The trust chain has one authoritative
+ * implementation; this package is just a wire format.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { AUDIT_WORKSPACE_TOOL, callAuditWorkspace } from "./tools/audit-workspace.js";
+import { CHECK_LOCK_TOOL, callCheckLock } from "./tools/check-lock.js";
+import { SCAN_TEXT_TOOL, callScanText } from "./tools/scan-text.js";
+import { VERIFY_BEFORE_LOAD_TOOL, callVerifyBeforeLoad } from "./tools/verify-before-load.js";
+import { VERIFY_BUNDLE_TOOL, callVerifyBundle } from "./tools/verify-bundle.js";
+export const SERVER_NAME = "primitivehub";
+export const SERVER_VERSION = "0.1.0";
+export const TOOLS = [
+    VERIFY_BUNDLE_TOOL,
+    SCAN_TEXT_TOOL,
+    AUDIT_WORKSPACE_TOOL,
+    CHECK_LOCK_TOOL,
+    VERIFY_BEFORE_LOAD_TOOL,
+];
+/** Build a configured but not-yet-connected MCP server. */
+export function buildServer() {
+    const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: rawArgs } = request.params;
+        switch (name) {
+            case "verify_bundle":
+                return await callVerifyBundle(rawArgs);
+            case "scan_text":
+                return callScanText(rawArgs);
+            case "audit_workspace":
+                return callAuditWorkspace(rawArgs);
+            case "check_lock":
+                return callCheckLock(rawArgs);
+            case "verify_before_load":
+                return await callVerifyBeforeLoad(rawArgs);
+            default:
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({ error: `unknown tool: ${name}` }, null, 2) },
+                    ],
+                    isError: true,
+                };
+        }
+    });
+    return server;
+}
+/** Connect over stdio. Used by `bin/primitivehub-mcp.js`. */
+export async function runStdio() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oCAAoC,CAAA;AAE3C,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AACrF,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACtE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnE,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAC7F,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAE/E,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAA;AACzC,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAA;AAErC,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,kBAAkB;IAClB,cAAc;IACd,oBAAoB;IACpB,eAAe;IACf,uBAAuB;CACf,CAAA;AAEV,2DAA2D;AAC3D,MAAM,UAAU,WAAW;IACzB,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,EAC9C,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAA;IAED,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAC5D,KAAK,EAAE,KAIL;KACH,CAAC,CAAC,CAAA;IAEH,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAChE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAA;QACnD,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,eAAe;gBAClB,OAAO,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAA;YACxC,KAAK,WAAW;gBACd,OAAO,YAAY,CAAC,OAAO,CAAC,CAAA;YAC9B,KAAK,iBAAiB;gBACpB,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAA;YACpC,KAAK,YAAY;gBACf,OAAO,aAAa,CAAC,OAAO,CAAC,CAAA;YAC/B,KAAK,oBAAoB;gBACvB,OAAO,MAAM,oBAAoB,CAAC,OAAO,CAAC,CAAA;YAC5C;gBACE,OAAO;oBACL,OAAO,EAAE;wBACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,iBAAiB,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;qBACpF;oBACD,OAAO,EAAE,IAAI;iBACd,CAAA;QACL,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,OAAO,MAAM,CAAA;AACf,CAAC;AAED,6DAA6D;AAC7D,MAAM,CAAC,KAAK,UAAU,QAAQ;IAC5B,MAAM,MAAM,GAAG,WAAW,EAAE,CAAA;IAC5B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAA;IAC5C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;AACjC,CAAC"}