@atlasauth/pca-mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @atlasauth/pca-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Model Context Protocol adapter for Proof-Carrying Authority: wrap an MCP tool handler so every call emits a PCActn (and attaches the proof) before the handler runs.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-mcp
+# peer dependency, install alongside:
+npm i @modelcontextprotocol/sdk
+```
+
+`@modelcontextprotocol/sdk` (^1) is an optional peer dependency.
+
+## Usage
+
+```ts
+import { withPCA } from '@atlasauth/pca-mcp';
+
+server.tool(
+  'refund',
+  schema,
+  withPCA(
+    agent,                                       // core @atlasauth/pca Agent
+    {
+      verb: 'stripe.refund',
+      resource: (args) => `ch_${args.chargeId}`,
+      onProof: (pca) => { /* forward pca.encoded to the resource server */ },
+    },
+    async (args) => ({ content: [{ type: 'text', text: await doRefund(args) }] }),
+  ),
+);
+```
+
+The wrapped handler keeps the MCP handler shape. On a local fast-fail it returns an MCP error result (`isError: true`) rather than throwing. It builds + attaches a PCActn; it does not authorize on its own — the resource server's verifier decides.
+
+Part of Proof-Carrying Authority — see `@atlasauth/pca`.

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Model Context Protocol adapter for Proof-Carrying Authority.
+ *
+ * Wrap an MCP tool handler so every call first builds a PCActn (via the core `guard`) — fast-failing on
+ * the agent's local dry-run and handing the proof to your `onProof` so it can be forwarded to / attached
+ * for the resource server — then runs the original handler. Drop-in: the wrapped handler has the SAME
+ * shape as an MCP tool handler, so it slots straight into `server.tool(name, schema, withPCA(agent, {...},
+ * handler))` / `server.registerTool`.
+ *
+ * Structurally compatible with the `@modelcontextprotocol/sdk` package v1 (declared as an OPTIONAL peer
+ * dependency). We never import the SDK's runtime — the handler/result types below are a minimal
+ * structural shim, so this works across minor versions and even when the SDK is absent.
+ *
+ * HONEST: this does not authorize — it attaches a proof-carrying action; the resource server's verifier
+ * decides. A bypassed wrapper just means the action lacks a valid PCActn and fails server-side. The local
+ * dry-run is a convenience fast-fail, not a grant.
+ */
+import { type Agent, type PcaCall, bridgeToolCall, pcaHeaders } from '@atlasauth/pca';
+/** Minimal structural shape of an MCP tool result (`server.tool` / `registerTool` handler return). */
+export interface McpToolResult {
+    content: Array<{
+        type: string;
+        [k: string]: unknown;
+    }>;
+    isError?: boolean;
+    [k: string]: unknown;
+}
+/** An MCP tool handler: `(args, extra?) => result`, as registered via `server.tool` / `registerTool`. */
+export type McpToolHandler<ARGS = Record<string, unknown>> = (args: ARGS, extra?: unknown) => Promise<McpToolResult> | McpToolResult;
+export interface GuardToolSpec<ARGS> {
+    /** Catalog verb this tool maps to (e.g. `stripe.refund`). */
+    verb: string;
+    /** Resource for the call: fixed, or derived from the tool args. */
+    resource: string | ((args: ARGS) => string);
+    /** Audience (resource-server / instance id); falls back to the agent's default. */
+    aud?: string;
+    /** Fast-fail on the local dry-run before running the handler (default true). */
+    failFast?: boolean;
+    /** Receive the PCActn so the proof can be forwarded (e.g. as request headers) to the resource server. */
+    onProof?: (pca: PcaCall, args: ARGS) => void;
+}
+/**
+ * Wrap an MCP tool handler so each call emits + attaches a PCActn before the original handler runs.
+ *
+ * On a local fast-fail (`PcaDenied`), returns an MCP error result (`{ isError: true }`) rather than
+ * throwing — MCP handlers signal tool errors in-band via `isError` so the model can see them.
+ */
+export declare function withPCA<ARGS extends Record<string, unknown>>(agent: Agent, spec: GuardToolSpec<ARGS>, handler: McpToolHandler<ARGS>): McpToolHandler<ARGS>;
+/**
+ * Attach the encoded PCActn into a result's `_meta` so a downstream (gateway / RS) can read the proof off
+ * the tool result. Additive and non-destructive: existing `content`, `isError` and `_meta` keys are kept.
+ */
+export declare function guardToolResult(pca: PcaCall, result: McpToolResult): McpToolResult;
+export { bridgeToolCall, pcaHeaders, type PcaCall };

package/dist/index.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Model Context Protocol adapter for Proof-Carrying Authority.
+ *
+ * Wrap an MCP tool handler so every call first builds a PCActn (via the core `guard`) — fast-failing on
+ * the agent's local dry-run and handing the proof to your `onProof` so it can be forwarded to / attached
+ * for the resource server — then runs the original handler. Drop-in: the wrapped handler has the SAME
+ * shape as an MCP tool handler, so it slots straight into `server.tool(name, schema, withPCA(agent, {...},
+ * handler))` / `server.registerTool`.
+ *
+ * Structurally compatible with the `@modelcontextprotocol/sdk` package v1 (declared as an OPTIONAL peer
+ * dependency). We never import the SDK's runtime — the handler/result types below are a minimal
+ * structural shim, so this works across minor versions and even when the SDK is absent.
+ *
+ * HONEST: this does not authorize — it attaches a proof-carrying action; the resource server's verifier
+ * decides. A bypassed wrapper just means the action lacks a valid PCActn and fails server-side. The local
+ * dry-run is a convenience fast-fail, not a grant.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pcaHeaders = exports.bridgeToolCall = void 0;
+exports.withPCA = withPCA;
+exports.guardToolResult = guardToolResult;
+const pca_1 = require("@atlasauth/pca");
+Object.defineProperty(exports, "bridgeToolCall", { enumerable: true, get: function () { return pca_1.bridgeToolCall; } });
+Object.defineProperty(exports, "pcaHeaders", { enumerable: true, get: function () { return pca_1.pcaHeaders; } });
+/**
+ * Wrap an MCP tool handler so each call emits + attaches a PCActn before the original handler runs.
+ *
+ * On a local fast-fail (`PcaDenied`), returns an MCP error result (`{ isError: true }`) rather than
+ * throwing — MCP handlers signal tool errors in-band via `isError` so the model can see them.
+ */
+function withPCA(agent, spec, handler) {
+    return async (args, extra) => {
+        const run = (0, pca_1.guard)(agent, {
+            verb: spec.verb,
+            resource: spec.resource,
+            ...(spec.aud !== undefined ? { aud: spec.aud } : {}),
+            ...(spec.failFast !== undefined ? { failFast: spec.failFast } : {}),
+        }, async (a, pca) => {
+            spec.onProof?.(pca, a);
+            return handler(a, extra);
+        });
+        try {
+            return await run(args);
+        }
+        catch (err) {
+            if (err instanceof pca_1.PcaDenied) {
+                return { content: [{ type: 'text', text: err.message }], isError: true };
+            }
+            throw err;
+        }
+    };
+}
+/**
+ * Attach the encoded PCActn into a result's `_meta` so a downstream (gateway / RS) can read the proof off
+ * the tool result. Additive and non-destructive: existing `content`, `isError` and `_meta` keys are kept.
+ */
+function guardToolResult(pca, result) {
+    const prevMeta = result._meta && typeof result._meta === 'object' ? result._meta : {};
+    return { ...result, _meta: { ...prevMeta, 'x-pca-action': pca.encoded } };
+}
+//# 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;;;;;;;;;;;;;;;;GAgBG;;;AAoCH,0BA4BC;AAMD,0CAIC;AAxED,wCAAwG;AA0E/F,+FA1EqC,oBAAc,OA0ErC;AAAE,2FA1E4C,gBAAU,OA0E5C;AA9CnC;;;;;GAKG;AACH,SAAgB,OAAO,CACrB,KAAY,EACZ,IAAyB,EACzB,OAA6B;IAE7B,OAAO,KAAK,EAAE,IAAU,EAAE,KAAe,EAA0B,EAAE;QACnE,MAAM,GAAG,GAAG,IAAA,WAAK,EACf,KAAK,EACL;YACE,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpE,EACD,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE;YACf,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACvB,OAAO,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC3B,CAAC,CACF,CAAC;QACF,IAAI,CAAC;YACH,OAAO,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,eAAS,EAAE,CAAC;gBAC7B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC3E,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe,CAAC,GAAY,EAAE,MAAqB;IACjE,MAAM,QAAQ,GACZ,MAAM,CAAC,KAAK,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,MAAM,CAAC,KAAiC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpG,OAAO,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,QAAQ,EAAE,cAAc,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC;AAC5E,CAAC"}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@atlasauth/pca-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Model Context Protocol adapter for Proof-Carrying Authority: wrap an MCP tool handler so every call emits a PCActn (and attaches the proof) before the handler runs.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@atlasauth/pca": "0.1.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }