@strixgov/mcp-proxy 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2]
+
+### Fixed
+- The published package now ships its test suite (`test/`, except the monorepo-only
+  `installed-tarball.test.mjs`) and `scripts/preflight.mjs`, so `npm test` runs in an installed
+  copy. `scripts/run-tests.mjs` exits non-zero if no test files are found, if the runner reports
+  zero or skipped-only tests, or if fewer than 60 tests run (Node counts an empty test file as one
+  passing test).
+
+## [0.2.1]
+
+### Fixed
+- `npm test` in the published package crashed with a missing
+  `scripts/preflight.mjs` (the tarball did not ship `scripts/`). `test` now runs
+  `scripts/run-tests.mjs`, which runs the suite in a source checkout and, in an
+  installed copy, exits non-zero with an explanation rather than crashing or
+  passing on zero tests. Reported by an external tester.
+
 ## [0.2.0]
 
 Minor, not a patch: this release carries the already-merged shadow-discovery

package/examples/youspot/README.md

@@ -0,0 +1,58 @@
+# Govern YouSpot with the Strix MCP proxy
+
+This example uses YouSpot's official stdio bridge as the upstream server:
+
+`MCP host -> @strixgov/mcp-proxy -> @youspot/mcp -> https://youspot.com/mcp/v1`
+
+No YouSpot tool implementation is changed.
+
+## 1. Provide the YouSpot token to the host environment
+
+```bash
+export YOUSPOT_TOKEN="..."
+```
+
+`@youspot/mcp` requires the token for `tools/call`. The example config intentionally does not store it; the proxy passes the process environment through to the upstream when `upstream.env` is omitted.
+
+## 2. Point the MCP host at Strix
+
+```json
+{
+  "mcpServers": {
+    "youspot-governed": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@strixgov/mcp-proxy",
+        "--config",
+        "/absolute/path/to/youspot-proxy-config.json"
+      ]
+    }
+  }
+}
+```
+
+The same shape works in stdio-capable hosts that accept command/args MCP definitions. Use the host's normal secure environment mechanism for `YOUSPOT_TOKEN`.
+
+## 3. What the starter policy does
+
+- reviewed read tools -> explicit ALLOW rules
+- every other LOW/MEDIUM/HIGH tool -> APPROVAL_REQUIRED
+- CRITICAL -> DENY
+- policy default -> DENY
+
+The explicit rules are intentional. `@strixgov/mcp-proxy` documents name heuristics as a discovery fallback, not a production security boundary. A YouSpot tool added after this example was reviewed therefore does not inherit an automatic LOW/ALLOW path.
+- bundled approval channel -> disabled
+
+With approval disabled, any call that evaluates to `APPROVAL_REQUIRED` is refused rather than auto-approved. Configure a separate approver only when the response channel is not writable by the acting agent.
+
+## 4. Verify
+
+```bash
+npx @strixgov/verifier chain ~/.strix-mcp-proxy/youspot/receipts.jsonl \
+  --jwks ~/.strix-mcp-proxy/youspot/keys/public-jwk.json
+```
+
+## Coverage boundary
+
+Only traffic routed through this local proxy is governed. Direct `https://youspot.com/mcp/v1` connections remain outside this example. Remote-HTTP-only clients require a hosted Strix gateway.

package/examples/youspot-proxy-config.json

@@ -0,0 +1,236 @@
+{
+  "serverId": "youspot",
+  "upstream": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "@youspot/mcp"
+    ]
+  },
+  "capabilities": [
+    {
+      "id": "mcp.youspot.get_graph_object",
+      "name": "get_graph_object",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "Read one object from the YouSpot graph."
+    },
+    {
+      "id": "mcp.youspot.list_graph_objects",
+      "name": "list_graph_objects",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "List objects from the YouSpot graph."
+    },
+    {
+      "id": "mcp.youspot.search_graph_objects",
+      "name": "search_graph_objects",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "Search the YouSpot graph."
+    },
+    {
+      "id": "mcp.youspot.get_gmail_message",
+      "name": "get_gmail_message",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "Read one Gmail message."
+    },
+    {
+      "id": "mcp.youspot.search_gmail_messages",
+      "name": "search_gmail_messages",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "Search connected Gmail mailboxes."
+    },
+    {
+      "id": "mcp.youspot.list_gmail_labels",
+      "name": "list_gmail_labels",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "List Gmail labels."
+    },
+    {
+      "id": "mcp.youspot.get_calendar_events",
+      "name": "get_calendar_events",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "Read calendar events."
+    },
+    {
+      "id": "mcp.youspot.list_google_calendars",
+      "name": "list_google_calendars",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "List Google calendars."
+    },
+    {
+      "id": "mcp.youspot.list_slack_channels",
+      "name": "list_slack_channels",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "List Slack channels known to YouSpot."
+    },
+    {
+      "id": "mcp.youspot.get_slack_thread",
+      "name": "get_slack_thread",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "Read a saved Slack thread."
+    },
+    {
+      "id": "mcp.youspot.search_slack_messages",
+      "name": "search_slack_messages",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "Search saved Slack messages."
+    },
+    {
+      "id": "mcp.youspot.list_integrations",
+      "name": "list_integrations",
+      "risk": "LOW",
+      "mode": "READ",
+      "description": "List connected integrations."
+    },
+    {
+      "id": "mcp.youspot.add_slack_reaction",
+      "name": "add_slack_reaction",
+      "risk": "MEDIUM",
+      "mode": "WRITE",
+      "description": "Add a reaction to a Slack message."
+    },
+    {
+      "id": "mcp.youspot.archive_gmail_message",
+      "name": "archive_gmail_message",
+      "risk": "MEDIUM",
+      "mode": "WRITE",
+      "description": "Archive a Gmail message."
+    },
+    {
+      "id": "mcp.youspot.connect_graph_objects",
+      "name": "connect_graph_objects",
+      "risk": "MEDIUM",
+      "mode": "WRITE",
+      "description": "Create a directed edge between graph objects."
+    },
+    {
+      "id": "mcp.youspot.create_gmail_draft",
+      "name": "create_gmail_draft",
+      "risk": "MEDIUM",
+      "mode": "WRITE",
+      "description": "Create a Gmail draft."
+    },
+    {
+      "id": "mcp.youspot.create_graph_object",
+      "name": "create_graph_object",
+      "risk": "MEDIUM",
+      "mode": "WRITE",
+      "description": "Create a YouSpot graph object."
+    },
+    {
+      "id": "mcp.youspot.disconnect_graph_objects",
+      "name": "disconnect_graph_objects",
+      "risk": "MEDIUM",
+      "mode": "WRITE",
+      "description": "Remove a graph-object edge."
+    },
+    {
+      "id": "mcp.youspot.set_follow_up",
+      "name": "set_follow_up",
+      "risk": "MEDIUM",
+      "mode": "WRITE",
+      "description": "Create a dated follow-up fact."
+    },
+    {
+      "id": "mcp.youspot.set_notification_emails",
+      "name": "set_notification_emails",
+      "risk": "MEDIUM",
+      "mode": "WRITE",
+      "description": "Change YouSpot notification-email settings."
+    },
+    {
+      "id": "mcp.youspot.update_graph_object",
+      "name": "update_graph_object",
+      "risk": "MEDIUM",
+      "mode": "WRITE",
+      "description": "Update fields on a graph object."
+    },
+    {
+      "id": "mcp.youspot.create_calendar_event",
+      "name": "create_calendar_event",
+      "risk": "HIGH",
+      "mode": "WRITE",
+      "description": "Create or queue a calendar event."
+    },
+    {
+      "id": "mcp.youspot.send_email",
+      "name": "send_email",
+      "risk": "HIGH",
+      "mode": "WRITE",
+      "description": "Send email to the signed-in user's own address."
+    },
+    {
+      "id": "mcp.youspot.send_slack_message",
+      "name": "send_slack_message",
+      "risk": "HIGH",
+      "mode": "WRITE",
+      "description": "Post a Slack message or DM."
+    },
+    {
+      "id": "mcp.youspot.send_text_to_user",
+      "name": "send_text_to_user",
+      "risk": "HIGH",
+      "mode": "WRITE",
+      "description": "Send an iMessage/SMS to the user's verified phone."
+    },
+    {
+      "id": "mcp.youspot.delete_graph_object",
+      "name": "delete_graph_object",
+      "risk": "CRITICAL",
+      "mode": "WRITE",
+      "description": "Delete one graph object."
+    },
+    {
+      "id": "mcp.youspot.delete_graph_objects",
+      "name": "delete_graph_objects",
+      "risk": "CRITICAL",
+      "mode": "WRITE",
+      "description": "Delete all graph objects of one type."
+    },
+    {
+      "id": "mcp.youspot.disconnect_integration",
+      "name": "disconnect_integration",
+      "risk": "CRITICAL",
+      "mode": "WRITE",
+      "description": "Disconnect an integration; may delete synced records."
+    }
+  ],
+  "policy": {
+    "rules": {
+      "mcp.youspot.get_graph_object": "ALLOW",
+      "mcp.youspot.list_graph_objects": "ALLOW",
+      "mcp.youspot.search_graph_objects": "ALLOW",
+      "mcp.youspot.get_gmail_message": "ALLOW",
+      "mcp.youspot.search_gmail_messages": "ALLOW",
+      "mcp.youspot.list_gmail_labels": "ALLOW",
+      "mcp.youspot.get_calendar_events": "ALLOW",
+      "mcp.youspot.list_google_calendars": "ALLOW",
+      "mcp.youspot.list_slack_channels": "ALLOW",
+      "mcp.youspot.get_slack_thread": "ALLOW",
+      "mcp.youspot.search_slack_messages": "ALLOW",
+      "mcp.youspot.list_integrations": "ALLOW"
+    },
+    "riskOverrides": {
+      "LOW": "APPROVAL_REQUIRED",
+      "MEDIUM": "APPROVAL_REQUIRED",
+      "HIGH": "APPROVAL_REQUIRED",
+      "CRITICAL": "DENY"
+    },
+    "default": "DENY"
+  },
+  "approval": {
+    "enabled": false
+  },
+  "storagePath": "~/.strix-mcp-proxy/youspot",
+  "keyPath": "~/.strix-mcp-proxy/youspot/keys"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strixgov/mcp-proxy",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Strix MCP Proxy — the distribution wedge for governed agent tool execution. Point your MCP client at the proxy instead of the underlying server; every callTool is intercepted, evaluated against policy, and emits a signed Ed25519 receipt. Designed so Mode 3 (capability-enforced) is the v0.2.0 upgrade path, not a rewrite.",
   "license": "Elastic-2.0",
   "type": "module",
@@ -20,6 +20,9 @@
     "@strixgov/mcp-adapter": "^0.1.0",
     "@strixgov/tool-gateway": "^0.5.0"
   },
+  "devDependencies": {
+    "zod": "^3.25.76"
+  },
   "keywords": [
     "strix",
     "mcp",
@@ -40,6 +43,9 @@
   "files": [
     "src/",
     "bin/",
+    "scripts/",
+    "test/",
+    "!test/installed-tarball.test.mjs",
     "examples/",
     "README.md",
     "CHANGELOG.md",
@@ -54,6 +60,6 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node scripts/preflight.mjs && node --test"
+    "test": "node scripts/run-tests.mjs"
   }
 }

package/scripts/preflight.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * Fresh-clone guard for @strixgov/mcp-proxy's test suite.
+ *
+ * Sibling of packages/strixgov-mcp-adapter/scripts/preflight.mjs. The two are
+ * deliberately duplicated rather than shared: these packages publish
+ * independently, and importing a guard across the workspace would either add a
+ * dependency edge that does not exist at runtime or require shipping the guard
+ * in the tarball. The REQUIRED list below is this package's own, not a copy.
+ *
+ * This package resolves its Strix dependencies through pnpm workspace links
+ * (`workspace:^` entries resolved in pnpm-lock.yaml as `link:../<pkg>`). In a
+ * checkout that has not been installed, those links do not exist, and
+ * `node --test` fails with a wall of ERR_MODULE_NOT_FOUND traces that name the
+ * missing specifiers but never say what to do about it. Read cold, that looks
+ * like a broken package rather than an uninstalled tree.
+ *
+ * This guard prints the one command that fixes it and exits non-zero instead.
+ * It is silent on success, so CI — which runs `pnpm install --frozen-lockfile`
+ * first — never sees extra output.
+ *
+ * Why dynamic import() and not require.resolve():
+ * tool-gateway's package.json "exports" map declares only an "import"
+ * condition and does not export "./package.json", so BOTH
+ * require.resolve("@strixgov/tool-gateway") and
+ * require.resolve("@strixgov/tool-gateway/package.json") throw even when the
+ * package is correctly installed. import() is also the exact operation src/
+ * and the tests perform, which makes a pass here a faithful predicate for
+ * "the suite can load" rather than an approximation of it.
+ */
+
+/**
+ * Every specifier the suite needs in order to run.
+ *
+ * - @strixgov/tool-gateway and @strixgov/mcp-adapter are imported by
+ *   src/proxy.mjs at module scope.
+ * - @modelcontextprotocol/sdk is a registry dependency, not a workspace link,
+ *   but it fails the same way in an uninstalled tree and deserves the same
+ *   message. The subpath is checked rather than the bare name because the SDK
+ *   ships an "exports" map with no root export.
+ * - @strixgov/capabilities-mcp-common is dynamically imported by
+ *   resolveCapabilities() in src/config.mjs and exercised by
+ *   test/config.test.mjs, so its absence is a real test failure.
+ *
+ * Deliberately NOT listed: @strixgov/mcp-proxy itself. The only import of it
+ * lives inside a generated temp project in test/installed-tarball.test.mjs,
+ * which resolves it from that project's own install, not from this workspace.
+ */
+const REQUIRED = [
+  "@strixgov/tool-gateway",
+  "@strixgov/mcp-adapter",
+  "@modelcontextprotocol/sdk/client/index.js",
+  "@strixgov/capabilities-mcp-common/notion",
+];
+
+/**
+ * @param {string} specifier
+ * @returns {Promise<boolean>} true if the specifier loads.
+ */
+async function resolves(specifier) {
+  try {
+    await import(specifier);
+    return true;
+  } catch (err) {
+    if (err?.code === "ERR_MODULE_NOT_FOUND") return false;
+    // The package is present but threw while loading (a syntax error inside
+    // it, a broken transitive import). That is a real failure, but it is not
+    // the one this guard exists to explain — let the test run surface it
+    // verbatim rather than mislabelling it as "not installed".
+    return true;
+  }
+}
+
+/** @type {string[]} */
+const missing = [];
+for (const specifier of REQUIRED) {
+  if (!(await resolves(specifier))) missing.push(specifier);
+}
+
+if (missing.length > 0) {
+  // Deduplicate to package names: reporting several subpaths of one missing
+  // package is noise for what is a single missing install.
+  const packages = [
+    ...new Set(missing.map((s) => s.split("/").slice(0, 2).join("/"))),
+  ];
+
+  process.stderr.write(
+    [
+      "",
+      "  @strixgov/mcp-proxy: dependencies are not installed.",
+      "",
+      "  Cannot resolve:",
+      ...packages.map((p) => `    - ${p}`),
+      "",
+      "  This package resolves its Strix dependencies through the pnpm",
+      "  workspace (and the rest from the registry), so the repository has",
+      "  to be installed once before its tests can run:",
+      "",
+      "      pnpm install                                 # from the repo root",
+      "      pnpm --dir packages/strixgov-mcp-proxy test",
+      "",
+      "  Nothing is wrong with the published package: installing it from npm",
+      "  pulls these in automatically as regular dependencies. This only",
+      "  affects running the suite from a source checkout.",
+      "",
+    ].join("\n") + "\n",
+  );
+  process.exit(1);
+}

package/scripts/run-tests.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * `npm test` entry point for @strixgov/mcp-proxy.
+ *
+ * Works both in a source checkout and in an installed copy of the published
+ * tarball (the suite ships in the package; only test/installed-tarball.test.mjs,
+ * which needs sibling monorepo packages, is excluded from the tarball).
+ *
+ * Fails closed: a run that executes ZERO tests, finds no test files, or cannot
+ * read a test count exits non-zero. "No tests" must never read as a pass.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const testDir = fileURLToPath(new URL("../test", import.meta.url));
+const preflight = fileURLToPath(new URL("./preflight.mjs", import.meta.url));
+
+// Node counts an empty test file as one passing test, so "> 0" is not enough:
+// an emptied suite would still pass. Require a floor close to the real size (66 at 0.2.2).
+const MIN_TESTS = 60;
+
+const fail = (msg) => {
+  process.stderr.write(`\n  @strixgov/mcp-proxy: ${msg}\n\n`);
+  process.exit(1);
+};
+
+const files = existsSync(testDir) ? readdirSync(testDir).filter((f) => f.endsWith(".test.mjs")) : [];
+if (files.length === 0 || !existsSync(preflight)) {
+  fail("no tests to run (test/*.test.mjs or scripts/preflight.mjs missing). Exiting non-zero: zero tests run must not read as a pass.");
+}
+
+const pre = spawnSync(process.execPath, [preflight], { cwd: root, stdio: "inherit" });
+if (pre.status !== 0) process.exit(pre.status ?? 1);
+
+// Run via the node test runner and read its own summary so we can refuse a zero count.
+const run = spawnSync(process.execPath, ["--test", ...files.map((f) => `test/${f}`)], {
+  cwd: root,
+  encoding: "utf8",
+  maxBuffer: 64 * 1024 * 1024,
+});
+process.stdout.write(run.stdout ?? "");
+process.stderr.write(run.stderr ?? "");
+if (run.status !== 0) process.exit(run.status ?? 1);
+
+const text = `${run.stdout}\n${run.stderr}`;
+const count = (label) => {
+  const m = text.match(new RegExp(`(?:ℹ|#)\\s+${label}\\s+(\\d+)`));
+  return m ? Number(m[1]) : null;
+};
+const tests = count("tests");
+const passed = count("pass");
+if (tests === null || passed === null) fail("could not read the test runner's summary; refusing to report success.");
+if (tests === 0 || passed === 0) fail(`test runner executed ${tests} tests (${passed} passed). Exiting non-zero: zero tests run must not read as a pass.`);
+if (tests < MIN_TESTS) fail(`test runner executed only ${tests} tests; expected at least ${MIN_TESTS}. A truncated or emptied suite must not read as a pass.`);

package/test/cli.test.mjs

@@ -0,0 +1,46 @@
+/**
+ * CLI sanity tests.
+ *
+ * Doesn't run the full MCP loop (covered by proxy-end-to-end), just
+ * confirms the CLI parses args correctly, surfaces --help / --version,
+ * and refuses to start without enough configuration.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import url from "node:url";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const BIN = path.resolve(__dirname, "..", "bin", "strix-mcp-proxy.mjs");
+
+function runCli(args, opts = {}) {
+  return spawnSync("node", [BIN, ...args], { encoding: "utf8", timeout: 10_000, ...opts });
+}
+
+test("--help prints usage and exits 0", () => {
+  const out = runCli(["--help"]);
+  assert.equal(out.status, 0);
+  assert.match(out.stdout, /strix-mcp-proxy/);
+  assert.match(out.stdout, /CONFIG-FILE MODE/);
+  assert.match(out.stdout, /FLAG MODE/);
+});
+
+test("--version prints the package version and exits 0", () => {
+  const out = runCli(["--version"]);
+  assert.equal(out.status, 0);
+  assert.match(out.stdout, /^strix-mcp-proxy \d+\.\d+\.\d+/);
+});
+
+test("no args: refuses to start with a clear error", () => {
+  const out = runCli([], { input: "" });
+  assert.notEqual(out.status, 0, "must exit non-zero without enough config");
+  assert.match(out.stderr, /missing --config or --upstream-command/);
+});
+
+test("missing --config file: clear error", () => {
+  const out = runCli(["--config", "/nonexistent/strix-proxy-cli-test.json"], { input: "" });
+  assert.notEqual(out.status, 0);
+  assert.match(out.stderr, /could not read/);
+});