@orangecheck/agent-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OrangeCheck
+
+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,145 @@
+# @orangecheck/agent-mcp
+
+Wrap [Model Context Protocol](https://modelcontextprotocol.io/) tool invocations in [OC Agent](https://github.com/orangecheck/oc-agent-protocol) envelopes. Every call produces a signed, scope-constrained, verifiable `agent-action` stamp.
+
+## Why
+
+MCP servers expose tools to AI agents. The MCP wire protocol has no native notion of "who authorized this invocation" beyond whatever the transport layer carries. For anything consequential — sending email, moving sats, committing code, publishing content — the server (or any downstream auditor) should be able to verify:
+
+1. **Which principal stands behind this agent.** A Bitcoin address, not an opaque issuer.
+2. **What scope authorizes this specific call.** A declarative string like `mcp:invoke(server=…,tool=…)`.
+3. **That the agent hasn't exceeded its grant.** Automatic via OC Agent's sub-scope algorithm.
+4. **That the invocation happened before any revocation.** Optional OTS anchoring.
+
+`@orangecheck/agent-mcp` canonicalizes the `(server, tool, arguments)` tuple, hashes it, and stamps the hash as an `agent-action`. The server sees a verifiable authority artifact alongside the call itself.
+
+## Install
+
+```bash
+npm i @orangecheck/agent-mcp
+# peer deps:
+npm i @orangecheck/agent-core @orangecheck/agent-signer
+```
+
+## Quickstart
+
+```ts
+import { invokeWithStamp } from '@orangecheck/agent-mcp';
+
+// You already have an agent SignerRef and a DelegationEnvelope from
+// @orangecheck/agent-signer. The delegation grants something like
+//   mcp:invoke(server=https://mcp.example.com,tool=search)
+
+const { result, action } = await invokeWithStamp({
+    agent,
+    delegation,
+    invocation: {
+        server: 'https://mcp.example.com',
+        tool: 'search',
+        arguments: { query: 'bitcoin identity', limit: 10 },
+    },
+    call: async (inv) => myMcpClient.invoke(inv.server, inv.tool, inv.arguments),
+});
+
+// `result` is whatever the MCP server returned.
+// `action` is the signed envelope; ship it alongside the result, publish to
+// Nostr kind-30084, anchor to OpenTimestamps, etc.
+```
+
+## What gets stamped
+
+The stamp's `content.hash` is a SHA-256 of the RFC-8785-canonicalized JSON:
+
+```json
+{
+  "arguments": <canonical-json of invocation.arguments>,
+  "server":    <invocation.server, trimmed>,
+  "tool":      <invocation.tool>
+}
+```
+
+This shape is minimal by design — a verifier reconstructs it from the three fields without knowing anything MCP-server-specific.
+
+The action's `scope_exercised` defaults to `mcp:invoke(server=<server>,tool=<tool>)`, which is the tightest scope that exactly identifies the call. Callers who want a narrower or different scope can pass `scopeExercised` explicitly; `stampInvocation` pre-flights sub-scope containment against the delegation.
+
+## API
+
+### `canonicalizeInvocation(inv) -> Uint8Array`
+
+RFC 8785 JSON canonicalization of `{server, tool, arguments}`. Byte-identical across implementations.
+
+### `invocationHash(inv) -> "sha256:<64-hex>"`
+
+SHA-256 of the canonical bytes, prefixed for the envelope's `content.hash`.
+
+### `stampInvocation(input) -> Promise<ActionEnvelope>`
+
+Produces a signed `agent-action` without calling the tool. Useful for pre-authorization flows or batch stamping.
+
+### `invokeWithStamp(input) -> Promise<{ result, action }>`
+
+Stamps the invocation first, then calls the tool. The stamp is returned alongside the tool's result — ship them together.
+
+Rationale for stamping-before-calling: if the downstream call hangs or fails, there is still an on-record commitment that this agent attempted this specific invocation. The server-side verifier sees a stamped intent plus the server's own transcript.
+
+## Server-side verification
+
+A server receiving a stamped invocation verifies it with `@orangecheck/agent-core`:
+
+```ts
+import { verifyAction } from '@orangecheck/agent-core';
+
+const r = await verifyAction({
+    action,
+    delegation,
+    verifyBip322: async (m, s, a) => bip322.verify(a, m, s),
+});
+if (!r.ok) throw new Error(`auth failed: ${r.code}`);
+
+// Also re-hash the incoming (server, tool, arguments) to confirm the stamp
+// covers exactly this request:
+import { invocationHash } from '@orangecheck/agent-mcp';
+const expectedHash = invocationHash({
+    server: myUrl,
+    tool: req.tool,
+    arguments: req.arguments,
+});
+if (expectedHash !== action.content.hash) {
+    throw new Error('stamp does not cover this request');
+}
+```
+
+## Composing with OpenTimestamps
+
+For invocations where priority-against-revocation matters:
+
+```ts
+import { stampCommit } from '@orangecheck/stamp-ots';
+
+const { action } = await invokeWithStamp({ /* … */ });
+action.ots = await stampCommit(action.id);
+```
+
+## Composing with Nostr
+
+Publish the action for public auditability (OC Agent reuses OC Stamp's kind-30084 transport, disambiguated by envelope `kind`):
+
+```ts
+await nostr.publish({
+    kind: 30084,
+    tags: [
+        ['d', 'oc-agent-act:' + action.id],
+        ['kind', 'agent-action'],
+        ['delegation', action.delegation_id],
+        ['agent', action.signer.address],
+        ['scope', action.scope_exercised],
+        ['hash', action.content.hash],
+        ['signed_at', action.signed_at],
+    ],
+    content: JSON.stringify(action),
+});
+```
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/index.d.mts

@@ -0,0 +1,29 @@
+import { DelegationEnvelope } from '@orangecheck/agent-core';
+import { SignerRef, ActionEnvelope } from '@orangecheck/agent-signer';
+
+interface McpInvocation {
+    server: string;
+    tool: string;
+    arguments: Record<string, unknown>;
+}
+declare function canonicalizeInvocation(inv: McpInvocation): Uint8Array;
+declare function invocationHash(inv: McpInvocation): string;
+declare function invocationId(agentAddress: string, signedAt: string, delegationId: string, scopeExercised: string, inv: McpInvocation): string;
+interface StampInvocationInput {
+    agent: SignerRef;
+    delegation: DelegationEnvelope;
+    invocation: McpInvocation;
+    scopeExercised?: string;
+    signedAt?: Date;
+}
+declare function stampInvocation(input: StampInvocationInput): Promise<ActionEnvelope>;
+interface InvokeWithStampInput<T> extends StampInvocationInput {
+    call: (inv: McpInvocation) => Promise<T>;
+}
+interface InvokeWithStampResult<T> {
+    result: T;
+    action: ActionEnvelope;
+}
+declare function invokeWithStamp<T>(input: InvokeWithStampInput<T>): Promise<InvokeWithStampResult<T>>;
+
+export { type InvokeWithStampInput, type InvokeWithStampResult, type McpInvocation, type StampInvocationInput, canonicalizeInvocation, invocationHash, invocationId, invokeWithStamp, stampInvocation };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { DelegationEnvelope } from '@orangecheck/agent-core';
+import { SignerRef, ActionEnvelope } from '@orangecheck/agent-signer';
+
+interface McpInvocation {
+    server: string;
+    tool: string;
+    arguments: Record<string, unknown>;
+}
+declare function canonicalizeInvocation(inv: McpInvocation): Uint8Array;
+declare function invocationHash(inv: McpInvocation): string;
+declare function invocationId(agentAddress: string, signedAt: string, delegationId: string, scopeExercised: string, inv: McpInvocation): string;
+interface StampInvocationInput {
+    agent: SignerRef;
+    delegation: DelegationEnvelope;
+    invocation: McpInvocation;
+    scopeExercised?: string;
+    signedAt?: Date;
+}
+declare function stampInvocation(input: StampInvocationInput): Promise<ActionEnvelope>;
+interface InvokeWithStampInput<T> extends StampInvocationInput {
+    call: (inv: McpInvocation) => Promise<T>;
+}
+interface InvokeWithStampResult<T> {
+    result: T;
+    action: ActionEnvelope;
+}
+declare function invokeWithStamp<T>(input: InvokeWithStampInput<T>): Promise<InvokeWithStampResult<T>>;
+
+export { type InvokeWithStampInput, type InvokeWithStampResult, type McpInvocation, type StampInvocationInput, canonicalizeInvocation, invocationHash, invocationId, invokeWithStamp, stampInvocation };

package/dist/index.js

@@ -0,0 +1,62 @@
+'use strict';
+
+var sha256 = require('@noble/hashes/sha256');
+var agentCore = require('@orangecheck/agent-core');
+var agentSigner = require('@orangecheck/agent-signer');
+
+// src/index.ts
+function canonicalizeInvocation(inv) {
+  const canon = {
+    arguments: inv.arguments,
+    server: inv.server.trim(),
+    tool: inv.tool
+  };
+  const str = agentCore.canonicalize(canon);
+  return new TextEncoder().encode(str + "\n");
+}
+function invocationHash(inv) {
+  return "sha256:" + agentCore.hexEncode(sha256.sha256(canonicalizeInvocation(inv)));
+}
+function invocationId(agentAddress, signedAt, delegationId, scopeExercised, inv) {
+  return agentCore.computeActionId({
+    address: agentAddress,
+    content_hash: invocationHash(inv),
+    content_length: canonicalizeInvocation(inv).byteLength,
+    content_mime: "application/vnd.oc-agent.mcp-invocation+json",
+    signed_at: signedAt,
+    delegation_id: delegationId,
+    scope_exercised: scopeExercised
+  });
+}
+async function stampInvocation(input) {
+  const scopeExercised = input.scopeExercised ?? `mcp:invoke(server=${input.invocation.server.trim()},tool=${input.invocation.tool})`;
+  const granted = input.delegation.scopes.map(agentCore.parseScope);
+  const exercisedParsed = agentCore.parseScope(scopeExercised);
+  if (!granted.some((g) => agentCore.isSubScope(exercisedParsed, g))) {
+    throw new Error(
+      `stampInvocation: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`
+    );
+  }
+  const bytes = canonicalizeInvocation(input.invocation);
+  return agentSigner.signAsAgent({
+    agent: input.agent,
+    delegation: input.delegation,
+    content: { hash: invocationHash(input.invocation), length: bytes.byteLength },
+    mime: "application/vnd.oc-agent.mcp-invocation+json",
+    scopeExercised,
+    signedAt: input.signedAt
+  });
+}
+async function invokeWithStamp(input) {
+  const action = await stampInvocation(input);
+  const result = await input.call(input.invocation);
+  return { result, action };
+}
+
+exports.canonicalizeInvocation = canonicalizeInvocation;
+exports.invocationHash = invocationHash;
+exports.invocationId = invocationId;
+exports.invokeWithStamp = invokeWithStamp;
+exports.stampInvocation = stampInvocation;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["canonicalize","hexEncode","sha256","computeActionId","parseScope","isSubScope","signAsAgent"],"mappings":";;;;;;;AAqDO,SAAS,uBAAuB,GAAA,EAAgC;AACnE,EAAA,MAAM,KAAA,GAAQ;AAAA,IACV,WAAW,GAAA,CAAI,SAAA;AAAA,IACf,MAAA,EAAQ,GAAA,CAAI,MAAA,CAAO,IAAA,EAAK;AAAA,IACxB,MAAM,GAAA,CAAI;AAAA,GACd;AACA,EAAA,MAAM,GAAA,GAAMA,uBAAa,KAAsD,CAAA;AAC/E,EAAA,OAAO,IAAI,WAAA,EAAY,CAAE,MAAA,CAAO,MAAM,IAAI,CAAA;AAC9C;AAEO,SAAS,eAAe,GAAA,EAA4B;AACvD,EAAA,OAAO,YAAYC,mBAAA,CAAUC,aAAA,CAAO,sBAAA,CAAuB,GAAG,CAAC,CAAC,CAAA;AACpE;AAEO,SAAS,YAAA,CACZ,YAAA,EACA,QAAA,EACA,YAAA,EACA,gBACA,GAAA,EACM;AACN,EAAA,OAAOC,yBAAA,CAAgB;AAAA,IACnB,OAAA,EAAS,YAAA;AAAA,IACT,YAAA,EAAc,eAAe,GAAG,CAAA;AAAA,IAChC,cAAA,EAAgB,sBAAA,CAAuB,GAAG,CAAA,CAAE,UAAA;AAAA,IAC5C,YAAA,EAAc,8CAAA;AAAA,IACd,SAAA,EAAW,QAAA;AAAA,IACX,aAAA,EAAe,YAAA;AAAA,IACf,eAAA,EAAiB;AAAA,GACpB,CAAA;AACL;AAoBA,eAAsB,gBAAgB,KAAA,EAAsD;AACxF,EAAA,MAAM,cAAA,GACF,KAAA,CAAM,cAAA,IACN,CAAA,kBAAA,EAAqB,KAAA,CAAM,UAAA,CAAW,MAAA,CAAO,IAAA,EAAM,CAAA,MAAA,EAAS,KAAA,CAAM,UAAA,CAAW,IAAI,CAAA,CAAA,CAAA;AAKrF,EAAA,MAAM,OAAA,GAAU,KAAA,CAAM,UAAA,CAAW,MAAA,CAAO,IAAIC,oBAAU,CAAA;AACtD,EAAA,MAAM,eAAA,GAAkBA,qBAAW,cAAc,CAAA;AACjD,EAAA,IAAI,CAAC,QAAQ,IAAA,CAAK,CAAC,MAAMC,oBAAA,CAAW,eAAA,EAAiB,CAAC,CAAC,CAAA,EAAG;AACtD,IAAA,MAAM,IAAI,KAAA;AAAA,MACN,qCAAqC,cAAc,CAAA,yCAAA;AAAA,KACvD;AAAA,EACJ;AAEA,EAAA,MAAM,KAAA,GAAQ,sBAAA,CAAuB,KAAA,CAAM,UAAU,CAAA;AACrD,EAAA,OAAOC,uBAAA,CAAY;AAAA,IACf,OAAO,KAAA,CAAM,KAAA;AAAA,IACb,YAAY,KAAA,CAAM,UAAA;AAAA,IAClB,OAAA,EAAS,EAAE,IAAA,EAAM,cAAA,CAAe,MAAM,UAAU,CAAA,EAAG,MAAA,EAAQ,KAAA,CAAM,UAAA,EAAW;AAAA,IAC5E,IAAA,EAAM,8CAAA;AAAA,IACN,cAAA;AAAA,IACA,UAAU,KAAA,CAAM;AAAA,GACnB,CAAA;AACL;AAyBA,eAAsB,gBAAmB,KAAA,EAAmE;AACxG,EAAA,MAAM,MAAA,GAAS,MAAM,eAAA,CAAgB,KAAK,CAAA;AAC1C,EAAA,MAAM,MAAA,GAAS,MAAM,KAAA,CAAM,IAAA,CAAK,MAAM,UAAU,CAAA;AAChD,EAAA,OAAO,EAAE,QAAQ,MAAA,EAAO;AAC5B","file":"index.js","sourcesContent":["// @orangecheck/agent-mcp — wrap MCP tool invocations in OC Agent envelopes.\n//\n// An MCP client calls tools on an MCP server: { server, name, arguments }.\n// This module stamps each invocation as an `agent-action` whose `content.hash`\n// is a SHA-256 of the canonicalized (server, name, arguments) tuple, scoped\n// as `mcp:invoke(server=<url>,tool=<name>)`. The server — or any counterparty\n// — verifies the action before trusting the call.\n//\n// The wrapper is transport-agnostic. Wire it into whatever MCP client you use\n// by calling `invokeWithStamp()` around the raw call.\n\nimport { sha256 } from '@noble/hashes/sha256';\nimport {\n    canonicalize,\n    computeActionId,\n    hexEncode,\n    isSubScope,\n    parseScope,\n    type DelegationEnvelope,\n} from '@orangecheck/agent-core';\nimport {\n    signAsAgent,\n    type ActionEnvelope,\n    type SignerRef,\n} from '@orangecheck/agent-signer';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Canonicalization of an MCP invocation\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface McpInvocation {\n    /** Origin URL of the MCP server. Trimmed and lowercased for canonicalization. */\n    server: string;\n    /** Tool name (method) being invoked. */\n    tool: string;\n    /** JSON-serializable arguments. */\n    arguments: Record<string, unknown>;\n}\n\n/**\n * Produce the canonical bytes for an MCP invocation. The bytes are what the\n * action envelope's `content.hash` is a SHA-256 of.\n *\n * Shape:\n *   {\n *     \"arguments\": <canonical JSON of args>,\n *     \"server\":    <server url>,\n *     \"tool\":      <tool name>\n *   }\n *\n * The shape is intentionally minimal so verifiers can reconstruct it without\n * knowing anything server- or tool-specific.\n */\nexport function canonicalizeInvocation(inv: McpInvocation): Uint8Array {\n    const canon = {\n        arguments: inv.arguments,\n        server: inv.server.trim(),\n        tool: inv.tool,\n    };\n    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);\n    return new TextEncoder().encode(str + '\\n');\n}\n\nexport function invocationHash(inv: McpInvocation): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeInvocation(inv)));\n}\n\nexport function invocationId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    inv: McpInvocation\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: invocationHash(inv),\n        content_length: canonicalizeInvocation(inv).byteLength,\n        content_mime: 'application/vnd.oc-agent.mcp-invocation+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamped invocation\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface StampInvocationInput {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n    invocation: McpInvocation;\n    /** Defaults to `mcp:invoke(server=<server>,tool=<tool>)` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\n/**\n * Stamp an MCP invocation without actually calling it. Useful when the caller\n * wants the signed envelope for out-of-band auditing before (or independent of)\n * running the tool.\n */\nexport async function stampInvocation(input: StampInvocationInput): Promise<ActionEnvelope> {\n    const scopeExercised =\n        input.scopeExercised ??\n        `mcp:invoke(server=${input.invocation.server.trim()},tool=${input.invocation.tool})`;\n\n    // Tiny pre-flight: confirm the exercised scope is a sub-scope of *some*\n    // granted scope. This keeps a common integration mistake from producing\n    // an envelope that later fails verifier-side.\n    const granted = input.delegation.scopes.map(parseScope);\n    const exercisedParsed = parseScope(scopeExercised);\n    if (!granted.some((g) => isSubScope(exercisedParsed, g))) {\n        throw new Error(\n            `stampInvocation: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`\n        );\n    }\n\n    const bytes = canonicalizeInvocation(input.invocation);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation,\n        content: { hash: invocationHash(input.invocation), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.mcp-invocation+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// invokeWithStamp — call the tool AND produce the stamp around it\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface InvokeWithStampInput<T> extends StampInvocationInput {\n    /** The underlying transport call. Returns whatever the MCP server returns. */\n    call: (inv: McpInvocation) => Promise<T>;\n}\n\nexport interface InvokeWithStampResult<T> {\n    result: T;\n    action: ActionEnvelope;\n}\n\n/**\n * Stamp the invocation *first*, then execute the call. The stamped envelope\n * is returned alongside the result so the caller can ship them together.\n *\n * Rationale for stamping first: if the downstream call hangs or fails, we\n * still have an on-record commitment that this agent attempted this specific\n * invocation. The server-side verifier sees a stamped intent plus the server's\n * own transcript.\n */\nexport async function invokeWithStamp<T>(input: InvokeWithStampInput<T>): Promise<InvokeWithStampResult<T>> {\n    const action = await stampInvocation(input);\n    const result = await input.call(input.invocation);\n    return { result, action };\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,56 @@
+import { sha256 } from '@noble/hashes/sha256';
+import { canonicalize, hexEncode, computeActionId, parseScope, isSubScope } from '@orangecheck/agent-core';
+import { signAsAgent } from '@orangecheck/agent-signer';
+
+// src/index.ts
+function canonicalizeInvocation(inv) {
+  const canon = {
+    arguments: inv.arguments,
+    server: inv.server.trim(),
+    tool: inv.tool
+  };
+  const str = canonicalize(canon);
+  return new TextEncoder().encode(str + "\n");
+}
+function invocationHash(inv) {
+  return "sha256:" + hexEncode(sha256(canonicalizeInvocation(inv)));
+}
+function invocationId(agentAddress, signedAt, delegationId, scopeExercised, inv) {
+  return computeActionId({
+    address: agentAddress,
+    content_hash: invocationHash(inv),
+    content_length: canonicalizeInvocation(inv).byteLength,
+    content_mime: "application/vnd.oc-agent.mcp-invocation+json",
+    signed_at: signedAt,
+    delegation_id: delegationId,
+    scope_exercised: scopeExercised
+  });
+}
+async function stampInvocation(input) {
+  const scopeExercised = input.scopeExercised ?? `mcp:invoke(server=${input.invocation.server.trim()},tool=${input.invocation.tool})`;
+  const granted = input.delegation.scopes.map(parseScope);
+  const exercisedParsed = parseScope(scopeExercised);
+  if (!granted.some((g) => isSubScope(exercisedParsed, g))) {
+    throw new Error(
+      `stampInvocation: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`
+    );
+  }
+  const bytes = canonicalizeInvocation(input.invocation);
+  return signAsAgent({
+    agent: input.agent,
+    delegation: input.delegation,
+    content: { hash: invocationHash(input.invocation), length: bytes.byteLength },
+    mime: "application/vnd.oc-agent.mcp-invocation+json",
+    scopeExercised,
+    signedAt: input.signedAt
+  });
+}
+async function invokeWithStamp(input) {
+  const action = await stampInvocation(input);
+  const result = await input.call(input.invocation);
+  return { result, action };
+}
+
+export { canonicalizeInvocation, invocationHash, invocationId, invokeWithStamp, stampInvocation };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;AAqDO,SAAS,uBAAuB,GAAA,EAAgC;AACnE,EAAA,MAAM,KAAA,GAAQ;AAAA,IACV,WAAW,GAAA,CAAI,SAAA;AAAA,IACf,MAAA,EAAQ,GAAA,CAAI,MAAA,CAAO,IAAA,EAAK;AAAA,IACxB,MAAM,GAAA,CAAI;AAAA,GACd;AACA,EAAA,MAAM,GAAA,GAAM,aAAa,KAAsD,CAAA;AAC/E,EAAA,OAAO,IAAI,WAAA,EAAY,CAAE,MAAA,CAAO,MAAM,IAAI,CAAA;AAC9C;AAEO,SAAS,eAAe,GAAA,EAA4B;AACvD,EAAA,OAAO,YAAY,SAAA,CAAU,MAAA,CAAO,sBAAA,CAAuB,GAAG,CAAC,CAAC,CAAA;AACpE;AAEO,SAAS,YAAA,CACZ,YAAA,EACA,QAAA,EACA,YAAA,EACA,gBACA,GAAA,EACM;AACN,EAAA,OAAO,eAAA,CAAgB;AAAA,IACnB,OAAA,EAAS,YAAA;AAAA,IACT,YAAA,EAAc,eAAe,GAAG,CAAA;AAAA,IAChC,cAAA,EAAgB,sBAAA,CAAuB,GAAG,CAAA,CAAE,UAAA;AAAA,IAC5C,YAAA,EAAc,8CAAA;AAAA,IACd,SAAA,EAAW,QAAA;AAAA,IACX,aAAA,EAAe,YAAA;AAAA,IACf,eAAA,EAAiB;AAAA,GACpB,CAAA;AACL;AAoBA,eAAsB,gBAAgB,KAAA,EAAsD;AACxF,EAAA,MAAM,cAAA,GACF,KAAA,CAAM,cAAA,IACN,CAAA,kBAAA,EAAqB,KAAA,CAAM,UAAA,CAAW,MAAA,CAAO,IAAA,EAAM,CAAA,MAAA,EAAS,KAAA,CAAM,UAAA,CAAW,IAAI,CAAA,CAAA,CAAA;AAKrF,EAAA,MAAM,OAAA,GAAU,KAAA,CAAM,UAAA,CAAW,MAAA,CAAO,IAAI,UAAU,CAAA;AACtD,EAAA,MAAM,eAAA,GAAkB,WAAW,cAAc,CAAA;AACjD,EAAA,IAAI,CAAC,QAAQ,IAAA,CAAK,CAAC,MAAM,UAAA,CAAW,eAAA,EAAiB,CAAC,CAAC,CAAA,EAAG;AACtD,IAAA,MAAM,IAAI,KAAA;AAAA,MACN,qCAAqC,cAAc,CAAA,yCAAA;AAAA,KACvD;AAAA,EACJ;AAEA,EAAA,MAAM,KAAA,GAAQ,sBAAA,CAAuB,KAAA,CAAM,UAAU,CAAA;AACrD,EAAA,OAAO,WAAA,CAAY;AAAA,IACf,OAAO,KAAA,CAAM,KAAA;AAAA,IACb,YAAY,KAAA,CAAM,UAAA;AAAA,IAClB,OAAA,EAAS,EAAE,IAAA,EAAM,cAAA,CAAe,MAAM,UAAU,CAAA,EAAG,MAAA,EAAQ,KAAA,CAAM,UAAA,EAAW;AAAA,IAC5E,IAAA,EAAM,8CAAA;AAAA,IACN,cAAA;AAAA,IACA,UAAU,KAAA,CAAM;AAAA,GACnB,CAAA;AACL;AAyBA,eAAsB,gBAAmB,KAAA,EAAmE;AACxG,EAAA,MAAM,MAAA,GAAS,MAAM,eAAA,CAAgB,KAAK,CAAA;AAC1C,EAAA,MAAM,MAAA,GAAS,MAAM,KAAA,CAAM,IAAA,CAAK,MAAM,UAAU,CAAA;AAChD,EAAA,OAAO,EAAE,QAAQ,MAAA,EAAO;AAC5B","file":"index.mjs","sourcesContent":["// @orangecheck/agent-mcp — wrap MCP tool invocations in OC Agent envelopes.\n//\n// An MCP client calls tools on an MCP server: { server, name, arguments }.\n// This module stamps each invocation as an `agent-action` whose `content.hash`\n// is a SHA-256 of the canonicalized (server, name, arguments) tuple, scoped\n// as `mcp:invoke(server=<url>,tool=<name>)`. The server — or any counterparty\n// — verifies the action before trusting the call.\n//\n// The wrapper is transport-agnostic. Wire it into whatever MCP client you use\n// by calling `invokeWithStamp()` around the raw call.\n\nimport { sha256 } from '@noble/hashes/sha256';\nimport {\n    canonicalize,\n    computeActionId,\n    hexEncode,\n    isSubScope,\n    parseScope,\n    type DelegationEnvelope,\n} from '@orangecheck/agent-core';\nimport {\n    signAsAgent,\n    type ActionEnvelope,\n    type SignerRef,\n} from '@orangecheck/agent-signer';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Canonicalization of an MCP invocation\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface McpInvocation {\n    /** Origin URL of the MCP server. Trimmed and lowercased for canonicalization. */\n    server: string;\n    /** Tool name (method) being invoked. */\n    tool: string;\n    /** JSON-serializable arguments. */\n    arguments: Record<string, unknown>;\n}\n\n/**\n * Produce the canonical bytes for an MCP invocation. The bytes are what the\n * action envelope's `content.hash` is a SHA-256 of.\n *\n * Shape:\n *   {\n *     \"arguments\": <canonical JSON of args>,\n *     \"server\":    <server url>,\n *     \"tool\":      <tool name>\n *   }\n *\n * The shape is intentionally minimal so verifiers can reconstruct it without\n * knowing anything server- or tool-specific.\n */\nexport function canonicalizeInvocation(inv: McpInvocation): Uint8Array {\n    const canon = {\n        arguments: inv.arguments,\n        server: inv.server.trim(),\n        tool: inv.tool,\n    };\n    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);\n    return new TextEncoder().encode(str + '\\n');\n}\n\nexport function invocationHash(inv: McpInvocation): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeInvocation(inv)));\n}\n\nexport function invocationId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    inv: McpInvocation\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: invocationHash(inv),\n        content_length: canonicalizeInvocation(inv).byteLength,\n        content_mime: 'application/vnd.oc-agent.mcp-invocation+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamped invocation\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface StampInvocationInput {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n    invocation: McpInvocation;\n    /** Defaults to `mcp:invoke(server=<server>,tool=<tool>)` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\n/**\n * Stamp an MCP invocation without actually calling it. Useful when the caller\n * wants the signed envelope for out-of-band auditing before (or independent of)\n * running the tool.\n */\nexport async function stampInvocation(input: StampInvocationInput): Promise<ActionEnvelope> {\n    const scopeExercised =\n        input.scopeExercised ??\n        `mcp:invoke(server=${input.invocation.server.trim()},tool=${input.invocation.tool})`;\n\n    // Tiny pre-flight: confirm the exercised scope is a sub-scope of *some*\n    // granted scope. This keeps a common integration mistake from producing\n    // an envelope that later fails verifier-side.\n    const granted = input.delegation.scopes.map(parseScope);\n    const exercisedParsed = parseScope(scopeExercised);\n    if (!granted.some((g) => isSubScope(exercisedParsed, g))) {\n        throw new Error(\n            `stampInvocation: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`\n        );\n    }\n\n    const bytes = canonicalizeInvocation(input.invocation);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation,\n        content: { hash: invocationHash(input.invocation), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.mcp-invocation+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// invokeWithStamp — call the tool AND produce the stamp around it\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface InvokeWithStampInput<T> extends StampInvocationInput {\n    /** The underlying transport call. Returns whatever the MCP server returns. */\n    call: (inv: McpInvocation) => Promise<T>;\n}\n\nexport interface InvokeWithStampResult<T> {\n    result: T;\n    action: ActionEnvelope;\n}\n\n/**\n * Stamp the invocation *first*, then execute the call. The stamped envelope\n * is returned alongside the result so the caller can ship them together.\n *\n * Rationale for stamping first: if the downstream call hangs or fails, we\n * still have an on-record commitment that this agent attempted this specific\n * invocation. The server-side verifier sees a stamped intent plus the server's\n * own transcript.\n */\nexport async function invokeWithStamp<T>(input: InvokeWithStampInput<T>): Promise<InvokeWithStampResult<T>> {\n    const action = await stampInvocation(input);\n    const result = await input.call(input.invocation);\n    return { result, action };\n}\n"]}

package/package.json

@@ -0,0 +1,62 @@
+{
+    "name": "@orangecheck/agent-mcp",
+    "version": "0.1.0",
+    "description": "Wrap Model Context Protocol tool invocations in OC Agent envelopes — every call produces a signed, scope-constrained, verifiable agent-action stamp.",
+    "keywords": [
+        "bitcoin",
+        "agent",
+        "authority",
+        "mcp",
+        "model-context-protocol",
+        "bip322",
+        "oc-agent",
+        "orangecheck"
+    ],
+    "author": "OrangeCheck",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/orangecheck/oc-packages.git",
+        "directory": "agent-mcp"
+    },
+    "homepage": "https://github.com/orangecheck/oc-agent-protocol",
+    "bugs": {
+        "url": "https://github.com/orangecheck/oc-agent-protocol/issues"
+    },
+    "main": "./dist/index.js",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsup",
+        "dev": "tsup --watch",
+        "type-check": "tsc --noEmit",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "clean": "rm -rf dist",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "dependencies": {
+        "@noble/hashes": "^1.5.0",
+        "@orangecheck/agent-core": "^0.1.0",
+        "@orangecheck/agent-signer": "^0.1.0"
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.2",
+        "tsup": "^8.3.5",
+        "typescript": "^5.7.2",
+        "vitest": "^3.2.4"
+    }
+}

package/src/index.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest';
+
+import { verifyAction } from '@orangecheck/agent-core';
+import { createDelegation } from '@orangecheck/agent-signer';
+
+import { canonicalizeInvocation, invocationHash, invokeWithStamp, stampInvocation } from './index.js';
+
+const PRINCIPAL = 'bc1qprincipal000000000000000000000000000000';
+const AGENT = 'bc1qagent0000000000000000000000000000000000';
+
+const fakeSign = (address: string) => async (msg: string) =>
+    Buffer.from(`sig:${address}:${msg}`, 'utf8').toString('base64');
+
+const fakeVerify = async (msg: string, sig: string, address: string) =>
+    sig === Buffer.from(`sig:${address}:${msg}`, 'utf8').toString('base64');
+
+describe('canonicalizeInvocation', () => {
+    it('produces byte-identical output for identical inputs', () => {
+        const a = canonicalizeInvocation({
+            server: 'https://mcp.example.com',
+            tool: 'search',
+            arguments: { q: 'bitcoin', limit: 10 },
+        });
+        const b = canonicalizeInvocation({
+            server: 'https://mcp.example.com',
+            tool: 'search',
+            arguments: { limit: 10, q: 'bitcoin' }, // keys reordered
+        });
+        expect(a).toEqual(b);
+    });
+
+    it('produces different hashes for different argument values', () => {
+        const h1 = invocationHash({
+            server: 'https://mcp.example.com',
+            tool: 'search',
+            arguments: { q: 'a' },
+        });
+        const h2 = invocationHash({
+            server: 'https://mcp.example.com',
+            tool: 'search',
+            arguments: { q: 'b' },
+        });
+        expect(h1).not.toBe(h2);
+    });
+});
+
+describe('stampInvocation', () => {
+    it('produces an action that verifies against its delegation', async () => {
+        const delegation = await createDelegation({
+            principal: { address: PRINCIPAL, signMessage: fakeSign(PRINCIPAL) },
+            agentAddress: AGENT,
+            scopes: ['mcp:invoke(server=https://mcp.example.com,tool=search)'],
+            ttlMs: 60 * 60 * 1000,
+        });
+        const action = await stampInvocation({
+            agent: { address: AGENT, signMessage: fakeSign(AGENT) },
+            delegation,
+            invocation: {
+                server: 'https://mcp.example.com',
+                tool: 'search',
+                arguments: { q: 'bitcoin' },
+            },
+        });
+        expect(action.content.mime).toBe('application/vnd.oc-agent.mcp-invocation+json');
+        const r = await verifyAction({ action, delegation, verifyBip322: fakeVerify });
+        expect(r.ok).toBe(true);
+    });
+
+    it('rejects when exercised scope is not a sub-scope of granted', async () => {
+        const delegation = await createDelegation({
+            principal: { address: PRINCIPAL, signMessage: fakeSign(PRINCIPAL) },
+            agentAddress: AGENT,
+            scopes: ['mcp:invoke(server=https://mcp.example.com,tool=search)'],
+            ttlMs: 60 * 60 * 1000,
+        });
+        await expect(
+            stampInvocation({
+                agent: { address: AGENT, signMessage: fakeSign(AGENT) },
+                delegation,
+                invocation: {
+                    server: 'https://mcp.example.com',
+                    tool: 'send_email',
+                    arguments: {},
+                },
+            })
+        ).rejects.toThrow(/not a sub-scope/);
+    });
+});
+
+describe('invokeWithStamp', () => {
+    it('stamps first then calls', async () => {
+        const delegation = await createDelegation({
+            principal: { address: PRINCIPAL, signMessage: fakeSign(PRINCIPAL) },
+            agentAddress: AGENT,
+            scopes: ['mcp:invoke(server=https://mcp.example.com,tool=search)'],
+            ttlMs: 60 * 60 * 1000,
+        });
+        const { result, action } = await invokeWithStamp({
+            agent: { address: AGENT, signMessage: fakeSign(AGENT) },
+            delegation,
+            invocation: {
+                server: 'https://mcp.example.com',
+                tool: 'search',
+                arguments: { q: 'bitcoin' },
+            },
+            call: async () => ({ hits: 42 }),
+        });
+        expect(result).toEqual({ hits: 42 });
+        expect(action.kind).toBe('agent-action');
+        expect(action.delegation_id).toBe(delegation.id);
+    });
+});

package/src/index.ts

@@ -0,0 +1,158 @@
+// @orangecheck/agent-mcp — wrap MCP tool invocations in OC Agent envelopes.
+//
+// An MCP client calls tools on an MCP server: { server, name, arguments }.
+// This module stamps each invocation as an `agent-action` whose `content.hash`
+// is a SHA-256 of the canonicalized (server, name, arguments) tuple, scoped
+// as `mcp:invoke(server=<url>,tool=<name>)`. The server — or any counterparty
+// — verifies the action before trusting the call.
+//
+// The wrapper is transport-agnostic. Wire it into whatever MCP client you use
+// by calling `invokeWithStamp()` around the raw call.
+
+import { sha256 } from '@noble/hashes/sha256';
+import {
+    canonicalize,
+    computeActionId,
+    hexEncode,
+    isSubScope,
+    parseScope,
+    type DelegationEnvelope,
+} from '@orangecheck/agent-core';
+import {
+    signAsAgent,
+    type ActionEnvelope,
+    type SignerRef,
+} from '@orangecheck/agent-signer';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Canonicalization of an MCP invocation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface McpInvocation {
+    /** Origin URL of the MCP server. Trimmed and lowercased for canonicalization. */
+    server: string;
+    /** Tool name (method) being invoked. */
+    tool: string;
+    /** JSON-serializable arguments. */
+    arguments: Record<string, unknown>;
+}
+
+/**
+ * Produce the canonical bytes for an MCP invocation. The bytes are what the
+ * action envelope's `content.hash` is a SHA-256 of.
+ *
+ * Shape:
+ *   {
+ *     "arguments": <canonical JSON of args>,
+ *     "server":    <server url>,
+ *     "tool":      <tool name>
+ *   }
+ *
+ * The shape is intentionally minimal so verifiers can reconstruct it without
+ * knowing anything server- or tool-specific.
+ */
+export function canonicalizeInvocation(inv: McpInvocation): Uint8Array {
+    const canon = {
+        arguments: inv.arguments,
+        server: inv.server.trim(),
+        tool: inv.tool,
+    };
+    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);
+    return new TextEncoder().encode(str + '\n');
+}
+
+export function invocationHash(inv: McpInvocation): string {
+    return 'sha256:' + hexEncode(sha256(canonicalizeInvocation(inv)));
+}
+
+export function invocationId(
+    agentAddress: string,
+    signedAt: string,
+    delegationId: string,
+    scopeExercised: string,
+    inv: McpInvocation
+): string {
+    return computeActionId({
+        address: agentAddress,
+        content_hash: invocationHash(inv),
+        content_length: canonicalizeInvocation(inv).byteLength,
+        content_mime: 'application/vnd.oc-agent.mcp-invocation+json',
+        signed_at: signedAt,
+        delegation_id: delegationId,
+        scope_exercised: scopeExercised,
+    });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Stamped invocation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface StampInvocationInput {
+    agent: SignerRef;
+    delegation: DelegationEnvelope;
+    invocation: McpInvocation;
+    /** Defaults to `mcp:invoke(server=<server>,tool=<tool>)` — the tightest admissible sub-scope. */
+    scopeExercised?: string;
+    signedAt?: Date;
+}
+
+/**
+ * Stamp an MCP invocation without actually calling it. Useful when the caller
+ * wants the signed envelope for out-of-band auditing before (or independent of)
+ * running the tool.
+ */
+export async function stampInvocation(input: StampInvocationInput): Promise<ActionEnvelope> {
+    const scopeExercised =
+        input.scopeExercised ??
+        `mcp:invoke(server=${input.invocation.server.trim()},tool=${input.invocation.tool})`;
+
+    // Tiny pre-flight: confirm the exercised scope is a sub-scope of *some*
+    // granted scope. This keeps a common integration mistake from producing
+    // an envelope that later fails verifier-side.
+    const granted = input.delegation.scopes.map(parseScope);
+    const exercisedParsed = parseScope(scopeExercised);
+    if (!granted.some((g) => isSubScope(exercisedParsed, g))) {
+        throw new Error(
+            `stampInvocation: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`
+        );
+    }
+
+    const bytes = canonicalizeInvocation(input.invocation);
+    return signAsAgent({
+        agent: input.agent,
+        delegation: input.delegation,
+        content: { hash: invocationHash(input.invocation), length: bytes.byteLength },
+        mime: 'application/vnd.oc-agent.mcp-invocation+json',
+        scopeExercised,
+        signedAt: input.signedAt,
+    });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// invokeWithStamp — call the tool AND produce the stamp around it
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface InvokeWithStampInput<T> extends StampInvocationInput {
+    /** The underlying transport call. Returns whatever the MCP server returns. */
+    call: (inv: McpInvocation) => Promise<T>;
+}
+
+export interface InvokeWithStampResult<T> {
+    result: T;
+    action: ActionEnvelope;
+}
+
+/**
+ * Stamp the invocation *first*, then execute the call. The stamped envelope
+ * is returned alongside the result so the caller can ship them together.
+ *
+ * Rationale for stamping first: if the downstream call hangs or fails, we
+ * still have an on-record commitment that this agent attempted this specific
+ * invocation. The server-side verifier sees a stamped intent plus the server's
+ * own transcript.
+ */
+export async function invokeWithStamp<T>(input: InvokeWithStampInput<T>): Promise<InvokeWithStampResult<T>> {
+    const action = await stampInvocation(input);
+    const result = await input.call(input.invocation);
+    return { result, action };
+}