@trigguard/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @trigguard/mcp-server
+
+Production-grade **stdio MCP server** for TrigGuard authority.
+
+Transport only — all decisions flow through:
+
+```
+MCP tool → @trigguard/agent-sdk → POST /v1/execute
+```
+
+**Decision model:** PERMIT · DENY · SILENCE (no ESCALATE wire state)
+
+## Install (npm)
+
+```bash
+npm install -g @trigguard/mcp-server
+export TRIGGUARD_API_KEY=tg_live_…
+```
+
+Full setup: [MCP npm quickstart](../../docs/adoption/MCP_NPM_QUICKSTART.md)
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `authorize_action` | Governed PERMIT / DENY / SILENCE |
+| `verify_receipt` | Lookup execution by id |
+| `get_surface` | Surface registry metadata via gateway (read-only) |
+| `get_policy` | Bundled policy metadata (read-only, no evaluation) |
+
+## Cursor / Claude configuration
+
+Use the `trigguard-mcp-server` binary:
+
+```json
+{
+  "mcpServers": {
+    "trigguard": {
+      "command": "trigguard-mcp-server",
+      "env": {
+        "TRIGGUARD_GATEWAY_URL": "https://api.trigguardai.com",
+        "TRIGGUARD_API_KEY": "${env:TRIGGUARD_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+## Environment
+
+| Variable | Purpose |
+|---|---|
+| `TRIGGUARD_GATEWAY_URL` | Gateway base URL (default: `https://api.trigguardai.com`) |
+| `TRIGGUARD_API_KEY` | API key (`tg_live_…`) — required for `authorize_action` |
+| `TRIGGUARD_MCP_ACTOR_ID` | Actor id for authorize calls (default: `trigguard-mcp-server`) |
+| `TRIGGUARD_SURFACE_REGISTRY_PATH` | Optional local registry override (dev only) |
+| `TRIGGUARD_POLICY_BUNDLE_PATH` | Optional local policy metadata override (dev only) |
+
+Credentials stay in the MCP server process — never in LLM context.
+
+## Monorepo development
+
+```bash
+npm run build -w @trigguard/mcp-server
+TRIGGUARD_API_KEY=tg_live_… npm run start -w @trigguard/mcp-server
+```

package/assets/policy-metadata.json

@@ -0,0 +1,84 @@
+{
+  "bundle_id": "tg-staging",
+  "version": "1.1.0",
+  "created_at": "2026-05-31",
+  "note": "Read-only policy metadata for MCP get_policy. Not an authority evaluation. Production decisions come from POST /v1/execute.",
+  "policies": [
+    {
+      "id": "deploy-main",
+      "surface": "deploy.release",
+      "conditions": [
+        {
+          "field": "repository",
+          "operator": "in",
+          "value": ["TrigGuard-AI/TrigGuard", "TrigGuard-AI/trigguard-example-deploy"]
+        }
+      ],
+      "decision": "PERMIT",
+      "reason": "AUTHORIZED_REPOSITORY_DEPLOY"
+    },
+    {
+      "id": "pr-docs-permit",
+      "surface": "pr.docs.write",
+      "conditions": [],
+      "decision": "PERMIT",
+      "reason": "PR_DOCS_WRITE_PERMIT"
+    },
+    {
+      "id": "pr-tests-permit",
+      "surface": "pr.tests.write",
+      "conditions": [],
+      "decision": "PERMIT",
+      "reason": "PR_TESTS_WRITE_PERMIT"
+    },
+    {
+      "id": "pr-examples-permit",
+      "surface": "pr.examples.write",
+      "conditions": [],
+      "decision": "PERMIT",
+      "reason": "PR_EXAMPLES_WRITE_PERMIT"
+    },
+    {
+      "id": "pr-scripts-review",
+      "surface": "pr.scripts.write",
+      "conditions": [],
+      "decision": "SILENCE",
+      "reason": "PR_SCRIPTS_WRITE_REVIEW"
+    },
+    {
+      "id": "pr-workflows-review",
+      "surface": "pr.workflows.write",
+      "conditions": [],
+      "decision": "SILENCE",
+      "reason": "PR_WORKFLOWS_WRITE_REVIEW"
+    },
+    {
+      "id": "pr-governance-review",
+      "surface": "pr.governance.write",
+      "conditions": [],
+      "decision": "SILENCE",
+      "reason": "PR_GOVERNANCE_WRITE_REVIEW"
+    },
+    {
+      "id": "pr-mixed-review",
+      "surface": "pr.mixed.write",
+      "conditions": [],
+      "decision": "SILENCE",
+      "reason": "PR_MIXED_WRITE_REVIEW"
+    },
+    {
+      "id": "pr-runtime-deny",
+      "surface": "pr.runtime.write",
+      "conditions": [],
+      "decision": "DENY",
+      "reason": "PR_RUNTIME_WRITE_DENIED"
+    },
+    {
+      "id": "pr-kernel-deny",
+      "surface": "pr.kernel.write",
+      "conditions": [],
+      "decision": "DENY",
+      "reason": "PR_KERNEL_WRITE_DENIED"
+    }
+  ]
+}

package/dist/gatewayRegistry.d.ts

@@ -0,0 +1,10 @@
+export type GatewayRegistryDocument = {
+    readonly surfaces: readonly string[];
+    readonly hash: string;
+    readonly registry_id?: string;
+    readonly version?: string;
+};
+export type FetchFn = typeof fetch;
+/** GET /.well-known/trigguard/registry.json — live execution surface allowlist. */
+export declare function fetchGatewayRegistry(gatewayUrl: string, fetchImpl?: FetchFn): Promise<GatewayRegistryDocument>;
+//# sourceMappingURL=gatewayRegistry.d.ts.map

package/dist/gatewayRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatewayRegistry.d.ts","sourceRoot":"","sources":["../src/gatewayRegistry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,OAAO,KAAK,CAAC;AAEnC,mFAAmF;AACnF,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,OAAe,GACzB,OAAO,CAAC,uBAAuB,CAAC,CAgBlC"}

package/dist/gatewayRegistry.js

@@ -0,0 +1,18 @@
+/** GET /.well-known/trigguard/registry.json — live execution surface allowlist. */
+export async function fetchGatewayRegistry(gatewayUrl, fetchImpl = fetch) {
+    const base = gatewayUrl.replace(/\/$/, "");
+    const res = await fetchImpl(`${base}/.well-known/trigguard/registry.json`, {
+        headers: { Accept: "application/json" },
+    });
+    if (!res.ok) {
+        throw new Error(`gateway registry unavailable: HTTP ${res.status}`);
+    }
+    const body = (await res.json());
+    const surfaces = Array.isArray(body.surfaces) ? body.surfaces.map(String) : [];
+    return {
+        surfaces,
+        hash: String(body.hash ?? ""),
+        registry_id: body.registry_id ? String(body.registry_id) : undefined,
+        version: body.version ? String(body.version) : undefined,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# 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":""}

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { startStdioServer } from "./server.js";
+startStdioServer().catch((err) => {
+    console.error("trigguard-mcp-server failed:", err);
+    process.exit(1);
+});

package/dist/policyMetadata.d.ts

@@ -0,0 +1,17 @@
+export type PolicyRuleMetadata = {
+    readonly id: string;
+    readonly surface: string;
+    readonly decision: string;
+    readonly reason: string;
+    readonly conditions: ReadonlyArray<Record<string, unknown>>;
+};
+export type PolicyMetadataResult = {
+    readonly bundleId: string;
+    readonly version: string;
+    readonly surface: string;
+    readonly matchingPolicies: ReadonlyArray<PolicyRuleMetadata>;
+    readonly note: string;
+};
+export declare function resolvePolicyMetadataPath(): string;
+export declare function loadPolicyMetadataForSurface(surface: string): PolicyMetadataResult;
+//# sourceMappingURL=policyMetadata.d.ts.map

package/dist/policyMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policyMetadata.d.ts","sourceRoot":"","sources":["../src/policyMetadata.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAaF,wBAAgB,yBAAyB,IAAI,MAAM,CAclD;AAYD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,oBAAoB,CA4BlF"}

package/dist/policyMetadata.js

@@ -0,0 +1,57 @@
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { matchSurface } from "@trigguard/surface-registry";
+const PACKAGED_METADATA = join(dirname(fileURLToPath(import.meta.url)), "..", "assets", "policy-metadata.json");
+function tryFile(p) {
+    return existsSync(p) ? p : null;
+}
+export function resolvePolicyMetadataPath() {
+    const fromEnv = (process.env.TRIGGUARD_POLICY_BUNDLE_PATH || "").trim();
+    if (fromEnv) {
+        const resolved = tryFile(fromEnv);
+        if (resolved)
+            return resolved;
+        throw new Error(`Policy metadata not found at ${fromEnv}. TRIGGUARD_POLICY_BUNDLE_PATH must point to a readable JSON file.`);
+    }
+    const packaged = tryFile(PACKAGED_METADATA);
+    if (packaged)
+        return packaged;
+    return PACKAGED_METADATA;
+}
+function loadPolicyDocument() {
+    const path = resolvePolicyMetadataPath();
+    if (!existsSync(path)) {
+        throw new Error(`Policy metadata not found at ${path}. Set TRIGGUARD_POLICY_BUNDLE_PATH to a readable JSON file.`);
+    }
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+export function loadPolicyMetadataForSurface(surface) {
+    const raw = loadPolicyDocument();
+    const bundleId = String(raw.bundle_id ?? raw.bundleId ?? "unknown");
+    const version = String(raw.version ?? "unknown");
+    const policies = Array.isArray(raw.policies) ? raw.policies : [];
+    const matchingPolicies = [];
+    for (const p of policies) {
+        if (!p || typeof p !== "object")
+            continue;
+        const rule = p;
+        const ruleSurface = String(rule.surface ?? "");
+        if (!ruleSurface || !matchSurface(ruleSurface, surface))
+            continue;
+        matchingPolicies.push({
+            id: String(rule.id ?? ""),
+            surface: ruleSurface,
+            decision: String(rule.decision ?? ""),
+            reason: String(rule.reason ?? ""),
+            conditions: Array.isArray(rule.conditions) ? rule.conditions : [],
+        });
+    }
+    return {
+        bundleId,
+        version,
+        surface,
+        matchingPolicies,
+        note: "Metadata only — not an authority decision. Call authorize_action for governed evaluation.",
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type McpServerConfig } from "./tools.js";
+export declare function createTrigGuardMcpServer(config: McpServerConfig): McpServer;
+export declare function startStdioServer(config?: McpServerConfig): 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,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAQpB,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAgE3E;AAED,wBAAsB,gBAAgB,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9E"}

package/dist/server.js

@@ -0,0 +1,57 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createTrigGuardAgent } from "@trigguard/agent-sdk";
+import * as z from "zod";
+import { handleAuthorizeAction, handleGetPolicy, handleGetSurface, handleVerifyReceipt, loadMcpServerConfig, } from "./tools.js";
+function jsonContent(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+export function createTrigGuardMcpServer(config) {
+    const agent = createTrigGuardAgent({
+        gatewayUrl: config.gatewayUrl,
+        apiKey: config.apiKey,
+        defaultActorId: config.defaultActorId,
+    });
+    const server = new McpServer({
+        name: "trigguard-mcp-server",
+        version: "0.1.0",
+    });
+    server.registerTool("authorize_action", {
+        description: "Request TrigGuard authority for an action. Returns PERMIT, DENY, or SILENCE with execution receipt metadata.",
+        inputSchema: {
+            surface: z.string().describe("Execution surface (e.g. deploy.release)"),
+            subject: z.string().optional().describe("Optional subject digest"),
+            context: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Execution context (repository, environment, etc.)"),
+        },
+    }, async (input) => jsonContent(await handleAuthorizeAction(agent, config, input)));
+    server.registerTool("verify_receipt", {
+        description: "Verify a TrigGuard execution receipt by execution id.",
+        inputSchema: {
+            execution_id: z.string().describe("Execution id (exec_…)"),
+        },
+    }, async (input) => jsonContent(await handleVerifyReceipt(agent, input)));
+    server.registerTool("get_surface", {
+        description: "Read execution surface registry metadata (read-only, no evaluation).",
+        inputSchema: {
+            surface: z.string().describe("Surface id"),
+        },
+    }, async (input) => jsonContent(await handleGetSurface(config, input)));
+    server.registerTool("get_policy", {
+        description: "Read human-readable policy metadata for a surface from the bundled policy artifact. Does NOT evaluate policy.",
+        inputSchema: {
+            surface: z.string().describe("Surface id"),
+        },
+    }, async (input) => jsonContent(handleGetPolicy(input)));
+    return server;
+}
+export async function startStdioServer(config) {
+    const cfg = config ?? loadMcpServerConfig();
+    const server = createTrigGuardMcpServer(cfg);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/tools.d.ts

@@ -0,0 +1,48 @@
+import type { TrigGuardAgent } from "@trigguard/agent-sdk";
+import { BUILTIN_SURFACE_DEFINITIONS } from "@trigguard/surface-registry";
+import { type FetchFn } from "./gatewayRegistry.js";
+export type McpServerConfig = {
+    readonly gatewayUrl: string;
+    readonly apiKey?: string;
+    readonly defaultActorId: string;
+    readonly registryPath?: string;
+    readonly fetchImpl?: FetchFn;
+};
+export declare function loadMcpServerConfig(): McpServerConfig;
+export type AuthorizeActionInput = {
+    readonly surface: string;
+    readonly subject?: string;
+    readonly context?: Record<string, unknown>;
+};
+export type AuthorizeActionOutput = {
+    readonly decision: string;
+    readonly execution_id: string | null;
+    readonly receipt_hash: string | null;
+    readonly verify_url: string | null;
+};
+export declare function handleAuthorizeAction(agent: TrigGuardAgent, config: McpServerConfig, input: AuthorizeActionInput): Promise<AuthorizeActionOutput>;
+export type VerifyReceiptInput = {
+    readonly execution_id: string;
+};
+export type VerifyReceiptOutput = {
+    readonly valid: boolean;
+    readonly decision: string | null;
+    readonly surface: string | null;
+};
+export declare function handleVerifyReceipt(agent: TrigGuardAgent, input: VerifyReceiptInput): Promise<VerifyReceiptOutput>;
+export type GetSurfaceInput = {
+    readonly surface: string;
+};
+export type GetSurfaceOutput = {
+    readonly surface: string;
+    readonly registered: boolean;
+    readonly metadata: (typeof BUILTIN_SURFACE_DEFINITIONS)[string] | null;
+    readonly registryHash: string;
+    readonly source: "gateway" | "local";
+};
+export declare function handleGetSurface(config: McpServerConfig, input: GetSurfaceInput): Promise<GetSurfaceOutput>;
+export type GetPolicyInput = {
+    readonly surface: string;
+};
+export declare function handleGetPolicy(input: GetPolicyInput): import("./policyMetadata.js").PolicyMetadataResult;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,2BAA2B,EAAyB,MAAM,6BAA6B,CAAC;AACjG,OAAO,EAAwB,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAG1E,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,wBAAgB,mBAAmB,IAAI,eAAe,CAUrD;AAED,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC,CAAC;AAEF,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,qBAAqB,CAAC,CAahC;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAW9B;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACvE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;CACtC,CAAC;AAEF,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,gBAAgB,CAAC,CA0B3B;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,sDAEpD"}

package/dist/tools.js

@@ -0,0 +1,66 @@
+import { BUILTIN_SURFACE_DEFINITIONS, createSurfaceRegistry } from "@trigguard/surface-registry";
+import { fetchGatewayRegistry } from "./gatewayRegistry.js";
+import { loadPolicyMetadataForSurface } from "./policyMetadata.js";
+export function loadMcpServerConfig() {
+    const gatewayUrl = process.env.TRIGGUARD_GATEWAY_URL?.trim() ||
+        process.env.TRIGGUARD_ENDPOINT?.trim() ||
+        "https://api.trigguardai.com";
+    const apiKey = process.env.TRIGGUARD_API_KEY?.trim() || undefined;
+    const defaultActorId = process.env.TRIGGUARD_MCP_ACTOR_ID?.trim() || "trigguard-mcp-server";
+    const registryPath = process.env.TRIGGUARD_SURFACE_REGISTRY_PATH?.trim() || undefined;
+    return { gatewayUrl, apiKey, defaultActorId, registryPath };
+}
+export async function handleAuthorizeAction(agent, config, input) {
+    const decision = await agent.authorize({
+        surface: input.surface,
+        actorId: config.defaultActorId,
+        subjectDigest: input.subject,
+        context: input.context,
+    });
+    return {
+        decision: decision.label(),
+        execution_id: decision.executionId ?? null,
+        receipt_hash: decision.receipt?.receiptHash ?? null,
+        verify_url: decision.verifyUrl() ?? null,
+    };
+}
+export async function handleVerifyReceipt(agent, input) {
+    const result = await agent.verifyExecution(input.execution_id);
+    const receipt = result.receipt && typeof result.receipt === "object"
+        ? result.receipt
+        : null;
+    return {
+        valid: result.valid,
+        decision: receipt ? String(receipt.decision ?? null) : null,
+        surface: receipt ? String(receipt.surface ?? null) : null,
+    };
+}
+export async function handleGetSurface(config, input) {
+    if (config.registryPath) {
+        const registry = createSurfaceRegistry({ registryPath: config.registryPath });
+        registry.load();
+        const meta = registry.getSurface(input.surface);
+        return {
+            surface: input.surface,
+            registered: Boolean(meta),
+            metadata: meta ?? null,
+            registryHash: registry.registryHash(),
+            source: "local",
+        };
+    }
+    const fetchImpl = config.fetchImpl ?? fetch;
+    const doc = await fetchGatewayRegistry(config.gatewayUrl, fetchImpl);
+    const meta = BUILTIN_SURFACE_DEFINITIONS[input.surface] ?? null;
+    const inAllowlist = doc.surfaces.includes(input.surface);
+    const registered = inAllowlist && Boolean(meta);
+    return {
+        surface: input.surface,
+        registered,
+        metadata: registered ? meta : null,
+        registryHash: doc.hash,
+        source: "gateway",
+    };
+}
+export function handleGetPolicy(input) {
+    return loadPolicyMetadataForSurface(input.surface);
+}

package/mcp-tools-metadata.json

@@ -0,0 +1,76 @@
+{
+  "server": "trigguard-mcp-server",
+  "version": "0.1.0",
+  "package": "@trigguard/mcp-server",
+  "transport": "stdio",
+  "authority_path": "MCP → @trigguard/agent-sdk → POST /v1/execute",
+  "tools": [
+    {
+      "name": "authorize_action",
+      "classification": "AUTHORIZATION",
+      "mutates_reality": false,
+      "description": "Request TrigGuard authority for an action. Returns PERMIT, DENY, or SILENCE with execution receipt metadata.",
+      "parameters": {
+        "surface": { "type": "string", "required": true, "example": "deploy.release" },
+        "subject": { "type": "string", "required": false },
+        "context": { "type": "object", "required": false }
+      },
+      "returns": {
+        "decision": { "enum": ["PERMIT", "DENY", "SILENCE"] },
+        "execution_id": { "type": "string", "nullable": true },
+        "receipt_hash": { "type": "string", "nullable": true },
+        "verify_url": { "type": "string", "nullable": true }
+      },
+      "safety": "Calls production gateway. Does not execute side effects — authorization only."
+    },
+    {
+      "name": "verify_receipt",
+      "classification": "VERIFICATION",
+      "mutates_reality": false,
+      "description": "Verify a TrigGuard execution receipt by execution id via gateway lookup.",
+      "parameters": {
+        "execution_id": { "type": "string", "required": true, "pattern": "^exec_" }
+      },
+      "returns": {
+        "valid": { "type": "boolean" },
+        "decision": { "type": "string", "nullable": true },
+        "surface": { "type": "string", "nullable": true }
+      },
+      "safety": "Read-only verification. No policy evaluation."
+    },
+    {
+      "name": "get_surface",
+      "classification": "READ_ONLY",
+      "mutates_reality": false,
+      "description": "Read execution surface registry metadata. Does not evaluate policy.",
+      "parameters": {
+        "surface": { "type": "string", "required": true }
+      },
+      "returns": {
+        "registered": { "type": "boolean" },
+        "metadata": { "type": "object", "nullable": true },
+        "registryHash": { "type": "string" }
+      },
+      "safety": "Read-only registry lookup."
+    },
+    {
+      "name": "get_policy",
+      "classification": "READ_ONLY",
+      "mutates_reality": false,
+      "description": "Read human-readable policy metadata for a surface from bundled artifact. Does NOT evaluate policy.",
+      "parameters": {
+        "surface": { "type": "string", "required": true }
+      },
+      "returns": {
+        "surface": { "type": "string" },
+        "policyMetadata": { "type": "object", "nullable": true }
+      },
+      "safety": "Read-only metadata. No PERMIT/DENY emission."
+    }
+  ],
+  "classifications": {
+    "READ_ONLY": "No authority decision; safe discovery",
+    "AUTHORIZATION": "Returns PERMIT/DENY/SILENCE — call before mutating actions",
+    "VERIFICATION": "Validates existing receipt evidence"
+  }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@trigguard/mcp-server",
+  "version": "0.1.0",
+  "description": "Production-grade TrigGuard MCP stdio server — authority via @trigguard/agent-sdk only",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "trigguard-mcp-server": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "pretest": "npm run build",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "trigguard",
+    "mcp",
+    "authority",
+    "stdio",
+    "cursor",
+    "claude",
+    "execution-governance",
+    "ai-agents"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TrigGuard-AI/TrigGuard.git",
+    "directory": "packages/trigguard-mcp-server"
+  },
+  "homepage": "https://github.com/TrigGuard-AI/TrigGuard/blob/main/docs/adoption/MCP_NPM_QUICKSTART.md",
+  "bugs": {
+    "url": "https://github.com/TrigGuard-AI/TrigGuard/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "@trigguard/agent-sdk": "^0.1.0",
+    "@trigguard/surface-registry": "^0.1.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "README.md",
+    "mcp-tools-metadata.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}