@atlasauth/pca-mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlas Authorization
+
+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

@@ -1,3 +1,59 @@
-# 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 (PCA). `withPCA` wraps an MCP tool handler so every call first builds a signed PCActn (failing fast if the agent's own grant does not permit it), hands you the proof to forward to the resource server, and then runs the original handler.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-mcp @atlasauth/pca
+npm i @modelcontextprotocol/sdk   # optional peer dependency (^1)
+```
+
+## Usage
+
+```ts
+import { agent, generateKeyPair } from '@atlasauth/pca';
+import { withPCA } from '@atlasauth/pca-mcp';
+
+const pcaAgent = agent({
+  principal: generateKeyPair(),
+  goal: 'process refunds',
+  permissions: { stripe: ['refund'] },
+  limits: { refund: '$500/day' },
+  aud: 'ins_acme',
+});
+
+server.tool(
+  'refund',
+  schema,
+  withPCA(
+    pcaAgent,
+    {
+      verb: 'stripe.refund',
+      resource: (args) => `ch_${args.chargeId}`,
+      onProof: (pca, args) => {
+        // forward pca.headers (PCA-Action) to the resource server with your request
+      },
+    },
+    async (args) => ({ content: [{ type: 'text', text: await doRefund(args) }] }),
+  ),
+);
+```
+
+The wrapped handler keeps the MCP handler shape `(args, extra?) => result`. When the local dry-run denies the action it returns an MCP error result (`isError: true`) instead of throwing, so the model can see the refusal.
+
+## API
+
+- `withPCA(agent, spec, handler)` - spec is `{ verb, resource, aud?, failFast?, onProof? }`.
+- `guardToolResult(pca, result)` - adds the encoded PCActn to a tool result's `_meta['x-pca-action']`, keeping existing content.
+- Re-exports `bridgeToolCall`, `pcaHeaders`, and the `PcaCall` type from `@atlasauth/pca`.
+
+To make the server that receives these calls an OAuth resource server, see `@atlasauth/pca-mcp-rs`.
+
+## Status
+
+This package does not authorize anything. It attaches a proof-carrying action; the resource server's verifier (see `@atlasauth/pca`) decides. The MCP SDK is matched structurally and never imported. PCA cryptography has not been independently audited.
+
+## License
+
+MIT - see LICENSE

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,64 @@
 {
   "name": "@atlasauth/pca-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.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.",
+  "keywords": [
+    "mcp",
+    "model context protocol",
+    "tool calling",
+    "agent authorization",
+    "proof-carrying authority",
+    "pca",
+    "ai agents"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Atlas-Authorization/pca#readme",
+  "bugs": {
+    "url": "https://github.com/Atlas-Authorization/pca/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Atlas-Authorization/pca.git",
+    "directory": "packages/pca-mcp"
+  },
+  "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.2.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }