@openagentid/mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to `@openagent/mcp` are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- **Breaking:** package renamed from `@openagent/mcp` to `@openagentid/mcp`. The `@openagent` npm scope is squatted by a third party; the project now publishes under the `@openagentid` scope, matching the GitHub org OpenAgentID. Consumers must update dependency names and imports. Effective with the first npm publish under the new scope.
+
+## [0.1.0] - 2026-04-11
+
+### Added
+
+- `withOpenAgent(server, config)` — Proxy-based middleware that wraps any
+  `@modelcontextprotocol/sdk` `McpServer` instance and runs every tool
+  call through an OpenAgent identity verification + scope enforcement
+  pipeline. Intercepts both `tool()` (deprecated) and `registerTool()`
+  registration paths.
+- `withOpenAgentClient(client, config)` — Client-side interceptor that
+  signs outbound `callTool` requests with the caller's DID and proof
+  (Arsenal ACT or challenge response), injecting an
+  `_meta.openagent.identity` envelope. Forwards all other client
+  methods unchanged.
+- `OpenAgentMcpConfig` — `agent`, `requireScopes`, `requireIdentity`,
+  `skillsPolicy`, `preCall`, `postCall`, `onError`, `scopeFormat`.
+- `createSkillsPolicy(options)` — Composable hook for SKILLS.md-style
+  policy enforcement on skill-like tool calls. Default matchers:
+  `invoke_skill`, `run_skill`, `execute_skill`, `skill.invoke`,
+  `skill.run`.
+- `InMemorySkillsPolicyStore` — Reference implementation of the
+  `SkillsPolicyStore` interface, suitable for tests and small
+  deployments.
+- Typed errors: `OpenAgentMcpError`, `MissingIdentityError`,
+  `IdentityVerificationError`, `AuthorizationDeniedError`,
+  `SkillsPolicyDeniedError`. Each carries a JSON-RPC error code in the
+  `-32000`..`-32099` server-error range.
+- Audit metadata stamping — successful tool results carry an
+  `audit_id`, `verified_did`, and `scopes` block under
+  `_meta.openagent` so callers can correlate logs end-to-end.
+- Vitest test suite — unit tests against a synthetic server and
+  integration tests against a real `@modelcontextprotocol/sdk`
+  `McpServer` connected via `InMemoryTransport`.
+- Built and published against `@modelcontextprotocol/sdk@^1.27.0`.
+- Documentation: README quickstart, hooks reference, errors table,
+  configuration reference, links to <https://openagent.id/docs/integrations/mcp>.

package/LICENSE-APACHE

@@ -0,0 +1,100 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form.
+
+   "Work" shall mean the work of authorship made available under the License.
+
+   "Contribution" shall mean any work of authorship submitted to the Licensor
+   for inclusion in the Work.
+
+   "Contributor" shall mean Licensor and any Legal Entity on behalf of whom
+   a Contribution has been received by the Licensor.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   patent license to make, have made, use, offer to sell, sell,
+   import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work; and
+
+   (d) If the Work includes a "NOTICE" text file, You must include
+       a readable copy of the attribution notices contained within
+       such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+8. Limitation of Liability. In no event shall any Contributor be liable
+   for any damages arising from the use of the Work.
+
+9. Accepting Warranty or Additional Liability. You may act as a
+   commercial distributor and offer support, warranty, or indemnity
+   obligations for a fee.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 L1fe AI
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 L1fe AI
+
+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,168 @@
+# @openagentid/mcp
+
+OpenAgent middleware for the [Model Context Protocol](https://modelcontextprotocol.io).
+
+Add OAS identity verification, Arsenal capability tokens, and AEGIS authorization to any MCP server in three lines.
+
+## Install
+
+```bash
+npm install @openagentid/mcp @modelcontextprotocol/sdk @openagentid/sdk
+```
+
+## Server: add auth to MCP in 3 lines
+
+```ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { withOpenAgent } from '@openagentid/mcp';
+import { agent } from './my-agent.js';
+
+const server = new McpServer({ name: 'my-tools', version: '0.1.0' });
+
+const authedServer = withOpenAgent(server, {
+  agent,
+  requireScopes: (toolName) => [`mcp:${toolName}:invoke`],
+});
+
+authedServer.registerTool(
+  'search_web',
+  { description: 'search the web', inputSchema: { q: z.string() } },
+  async ({ q }) => ({ content: [{ type: 'text', text: `results for ${q}` }] }),
+);
+```
+
+That is it. Every tool call now:
+
+1. Pulls the identity envelope from `extra._meta.openagent.identity`.
+2. Verifies it against your `IdentityVerifier` (OAS DID + Arsenal ACT + AEGIS policy).
+3. Enforces the per-tool scopes returned by `requireScopes`.
+4. Runs the optional `skillsPolicy` hook (consults SKILLS.md-style rules).
+5. Runs the user's tool body.
+6. Stamps `audit_id`, `verified_did`, and `scopes` into the response `_meta.openagent`.
+
+## Client: sign every outbound call
+
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { withOpenAgentClient } from '@openagentid/mcp';
+import { agent } from './my-agent.js';
+
+const client = new Client({ name: 'my-agent', version: '0.1.0' });
+const authedClient = withOpenAgentClient(client, {
+  agent,
+  audience: 'did:oas:vendor:tools-server',
+});
+
+await authedClient.callTool({
+  name: 'search_web',
+  arguments: { q: 'mcp' },
+});
+```
+
+The interceptor wraps `callTool` only — `listTools`, `listResources`, `getPrompt`, and every other client method pass straight through.
+
+## Hooks
+
+`withOpenAgent` accepts three optional hooks plus the skills policy:
+
+```ts
+withOpenAgent(server, {
+  agent,
+  preCall: ({ toolName, identity }) => {
+    metrics.increment('mcp.tool.calls', { tool: toolName, did: identity.did });
+  },
+  postCall: ({ toolName, identity, durationMs, result }) => {
+    audit.write({ tool: toolName, did: identity.did, ms: durationMs });
+  },
+  onError: ({ toolName, identity, error }) => {
+    audit.writeError({ tool: toolName, did: identity?.did ?? null, error });
+  },
+});
+```
+
+## Skills policy
+
+MCP tools and SKILLS.md entries describe the same thing — a capability an
+agent can invoke. When an MCP server exposes a skill-like tool (default
+matchers: `invoke_skill`, `run_skill`, `execute_skill`, `skill.invoke`,
+`skill.run`), the middleware consults a policy hook before allowing the
+call.
+
+```ts
+import {
+  withOpenAgent,
+  createSkillsPolicy,
+  InMemorySkillsPolicyStore,
+} from '@openagentid/mcp';
+
+const skillsPolicy = createSkillsPolicy({
+  store: new InMemorySkillsPolicyStore([
+    { skillName: 'cook_dinner', dids: ['did:oas:org:kitchen:agent:alice'] },
+    { skillName: 'order_pizza', dids: null }, // any verified caller
+  ]),
+});
+
+withOpenAgent(server, { agent, skillsPolicy });
+```
+
+You can also write your own store that reads from `SKILLS.md` files, a
+remote service, or AEGIS policy bundles — just implement the
+`SkillsPolicyStore` interface.
+
+## Errors
+
+Every middleware-rejected call surfaces a typed error:
+
+| Error                          | Code     | When                                            |
+| ------------------------------ | -------- | ----------------------------------------------- |
+| `MissingIdentityError`         | `-32001` | `_meta.openagent.identity` was absent           |
+| `IdentityVerificationError`    | `-32001` | The verifier rejected the envelope              |
+| `AuthorizationDeniedError`     | `-32002` | Caller does not hold the required scopes        |
+| `SkillsPolicyDeniedError`      | `-32003` | The skills policy hook returned `allow: false`  |
+
+All extend `OpenAgentMcpError`, which carries a `code`, `message`, and
+optional `data` payload — ready for serialization through the JSON-RPC
+error envelope the MCP SDK expects.
+
+## Configuration reference
+
+```ts
+interface OpenAgentMcpConfig {
+  agent: Agent;
+  requireScopes?: (toolName: string, args: unknown) => readonly string[];
+  requireIdentity?: boolean;            // default: true
+  skillsPolicy?: SkillsPolicyHook;
+  preCall?: PreCallHook;
+  postCall?: PostCallHook;
+  onError?: ErrorHook;
+  scopeFormat?: (toolName: string) => string;
+}
+```
+
+## Versioning
+
+This package is built against `@modelcontextprotocol/sdk@^1.27.0`. Both
+the deprecated `tool(name, schema, cb)` overloads and the current
+`registerTool(name, config, cb)` API are intercepted, so any 1.x server
+works without code changes.
+
+## Testing
+
+```bash
+npm test
+```
+
+The test suite uses [vitest](https://vitest.dev) and exercises the
+middleware against both a synthetic MCP server and a real
+`@modelcontextprotocol/sdk` server connected over the SDK's
+`InMemoryTransport`.
+
+## Documentation
+
+- Spec: <https://openagent.id/docs/integrations/mcp>
+- OpenAgent SDK: <https://openagent.id/docs/sdk>
+- MCP: <https://modelcontextprotocol.io>
+
+## License
+
+Apache-2.0

package/dist/client.cjs

@@ -0,0 +1,91 @@
+'use strict';
+
+// src/client.ts
+function withOpenAgentClient(client, config) {
+  if (config === null || typeof config !== "object") {
+    throw new TypeError("OpenAgentClientConfig must be an object");
+  }
+  if (config.agent === void 0 || config.agent === null) {
+    throw new TypeError("OpenAgentClientConfig.agent is required");
+  }
+  if (typeof config.agent.signRequest !== "function") {
+    throw new TypeError("OpenAgentClientConfig.agent.signRequest is required");
+  }
+  const interceptor = new ClientInterceptor(config);
+  return new Proxy(client, {
+    get(target, property, receiver) {
+      const value = Reflect.get(target, property, receiver);
+      if (typeof value !== "function") {
+        return value;
+      }
+      if (property === "callTool") {
+        return interceptor.wrapCallTool(
+          value,
+          target
+        );
+      }
+      return value.bind(target);
+    }
+  });
+}
+var ClientInterceptor = class {
+  agent;
+  audience;
+  beforeCall;
+  constructor(config) {
+    this.agent = config.agent;
+    this.audience = config.audience;
+    this.beforeCall = config.beforeCall;
+  }
+  wrapCallTool(original, thisArg) {
+    const interceptor = this;
+    return async function wrappedCallTool(params, ...rest) {
+      const signed = await interceptor.signParams(params);
+      let toSend = signed;
+      if (interceptor.beforeCall !== void 0) {
+        const replacement = await Promise.resolve(
+          interceptor.beforeCall(signed)
+        );
+        if (replacement !== void 0) {
+          toSend = {
+            ...replacement,
+            _meta: replacement._meta ?? signed._meta
+          };
+        }
+      }
+      return original.call(thisArg, toSend, ...rest);
+    };
+  }
+  async signParams(params) {
+    const identity = await this.agent.signRequest(params.name, this.audience);
+    const existingMeta = params._meta ?? {};
+    const existingOpenAgent = typeof existingMeta["openagent"] === "object" && existingMeta["openagent"] !== null ? existingMeta["openagent"] : {};
+    return {
+      ...params,
+      _meta: {
+        ...existingMeta,
+        openagent: {
+          ...existingOpenAgent,
+          identity
+        }
+      }
+    };
+  }
+};
+function buildIdentityMeta(identity) {
+  return {
+    openagent: {
+      identity: {
+        did: identity.did,
+        proof: identity.proof,
+        ...identity.nonce !== void 0 ? { nonce: identity.nonce } : {},
+        ...identity.context !== void 0 ? { context: identity.context } : {}
+      }
+    }
+  };
+}
+
+exports.buildIdentityMeta = buildIdentityMeta;
+exports.withOpenAgentClient = withOpenAgentClient;
+//# sourceMappingURL=client.cjs.map
+//# sourceMappingURL=client.cjs.map

package/dist/client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"names":[],"mappings":";;;AAqEO,SAAS,mBAAA,CACd,QACA,MAAA,EACG;AACH,EAAA,IAAI,MAAA,KAAW,IAAA,IAAQ,OAAO,MAAA,KAAW,QAAA,EAAU;AACjD,IAAA,MAAM,IAAI,UAAU,yCAAyC,CAAA;AAAA,EAC/D;AACA,EAAA,IAAI,MAAA,CAAO,KAAA,KAAU,MAAA,IAAa,MAAA,CAAO,UAAU,IAAA,EAAM;AACvD,IAAA,MAAM,IAAI,UAAU,yCAAyC,CAAA;AAAA,EAC/D;AACA,EAAA,IAAI,OAAO,MAAA,CAAO,KAAA,CAAM,WAAA,KAAgB,UAAA,EAAY;AAClD,IAAA,MAAM,IAAI,UAAU,qDAAqD,CAAA;AAAA,EAC3E;AAEA,EAAA,MAAM,WAAA,GAAc,IAAI,iBAAA,CAAkB,MAAM,CAAA;AAEhD,EAAA,OAAO,IAAI,MAAM,MAAA,EAAQ;AAAA,IACvB,GAAA,CAAI,MAAA,EAAQ,QAAA,EAAU,QAAA,EAAU;AAC9B,MAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,GAAA,CAAI,MAAA,EAAQ,UAAU,QAAQ,CAAA;AACpD,MAAA,IAAI,OAAO,UAAU,UAAA,EAAY;AAC/B,QAAA,OAAO,KAAA;AAAA,MACT;AACA,MAAA,IAAI,aAAa,UAAA,EAAY;AAC3B,QAAA,OAAO,WAAA,CAAY,YAAA;AAAA,UACjB,KAAA;AAAA,UACA;AAAA,SACF;AAAA,MACF;AACA,MAAA,OAAO,KAAA,CAAM,KAAK,MAAM,CAAA;AAAA,IAC1B;AAAA,GACD,CAAA;AACH;AAEA,IAAM,oBAAN,MAAwB;AAAA,EACL,KAAA;AAAA,EACA,QAAA;AAAA,EACA,UAAA;AAAA,EAEjB,YAAY,MAAA,EAA+B;AACzC,IAAA,IAAA,CAAK,QAAQ,MAAA,CAAO,KAAA;AACpB,IAAA,IAAA,CAAK,WAAW,MAAA,CAAO,QAAA;AACvB,IAAA,IAAA,CAAK,aAAa,MAAA,CAAO,UAAA;AAAA,EAC3B;AAAA,EAEA,YAAA,CACE,UACA,OAAA,EAC2B;AAC3B,IAAA,MAAM,WAAA,GAAc,IAAA;AACpB,IAAA,OAAO,eAAe,eAAA,CAEpB,MAAA,EAAA,GAKG,IAAA,EACe;AAClB,MAAA,MAAM,MAAA,GAAS,MAAM,WAAA,CAAY,UAAA,CAAW,MAAM,CAAA;AAClD,MAAA,IAAI,MAAA,GAIA,MAAA;AACJ,MAAA,IAAI,WAAA,CAAY,eAAe,MAAA,EAAW;AACxC,QAAA,MAAM,WAAA,GAAc,MAAM,OAAA,CAAQ,OAAA;AAAA,UAChC,WAAA,CAAY,WAAW,MAAM;AAAA,SAC/B;AACA,QAAA,IAAI,gBAAgB,MAAA,EAAW;AAE7B,UAAA,MAAA,GAAS;AAAA,YACP,GAAG,WAAA;AAAA,YACH,KAAA,EAAO,WAAA,CAAY,KAAA,IAAS,MAAA,CAAO;AAAA,WACrC;AAAA,QACF;AAAA,MACF;AACA,MAAA,OAAO,QAAA,CAAS,IAAA,CAAK,OAAA,EAAS,MAAA,EAAQ,GAAG,IAAI,CAAA;AAAA,IAC/C,CAAA;AAAA,EACF;AAAA,EAEA,MAAc,WAAW,MAAA,EAQtB;AACD,IAAA,MAAM,QAAA,GAAW,MAAM,IAAA,CAAK,KAAA,CAAM,YAAY,MAAA,CAAO,IAAA,EAAM,KAAK,QAAQ,CAAA;AACxE,IAAA,MAAM,YAAA,GAAe,MAAA,CAAO,KAAA,IAAS,EAAC;AACtC,IAAA,MAAM,iBAAA,GACJ,OAAO,YAAA,CAAa,WAAW,CAAA,KAAM,QAAA,IACrC,YAAA,CAAa,WAAW,CAAA,KAAM,IAAA,GACzB,YAAA,CAAa,WAAW,IACzB,EAAC;AACP,IAAA,OAAO;AAAA,MACL,GAAG,MAAA;AAAA,MACH,KAAA,EAAO;AAAA,QACL,GAAG,YAAA;AAAA,QACH,SAAA,EAAW;AAAA,UACT,GAAG,iBAAA;AAAA,UACH;AAAA;AACF;AACF,KACF;AAAA,EACF;AACF,CAAA;AAOO,SAAS,kBAAkB,QAAA,EAKN;AAC1B,EAAA,OAAO;AAAA,IACL,SAAA,EAAW;AAAA,MACT,QAAA,EAAU;AAAA,QACR,KAAK,QAAA,CAAS,GAAA;AAAA,QACd,OAAO,QAAA,CAAS,KAAA;AAAA,QAChB,GAAI,SAAS,KAAA,KAAU,MAAA,GAAY,EAAE,KAAA,EAAO,QAAA,CAAS,KAAA,EAAM,GAAI,EAAC;AAAA,QAChE,GAAI,SAAS,OAAA,KAAY,MAAA,GACrB,EAAE,OAAA,EAAS,QAAA,CAAS,OAAA,EAAQ,GAC5B;AAAC;AACP;AACF,GACF;AACF","file":"client.cjs","sourcesContent":["/**\n * Client-side interceptor for @openagentid/mcp.\n *\n * Adds an OpenAgent identity envelope (`_meta.openagent.identity`) to\n * outbound MCP `tools/call` requests so an authenticated server can\n * verify the caller. The interceptor wraps the MCP client's `callTool`\n * method via a JavaScript Proxy — the rest of the client surface (list\n * tools, list resources, prompts) is forwarded unchanged.\n *\n * Usage:\n *\n * ```ts\n * import { Client } from '@modelcontextprotocol/sdk/client/index.js';\n * import { withOpenAgentClient } from '@openagentid/mcp/client';\n *\n * const client = new Client({ name: 'my-agent', version: '0.1.0' });\n * const authedClient = withOpenAgentClient(client, { agent });\n *\n * await authedClient.callTool({ name: 'search_web', arguments: { q: 'mcp' } });\n * ```\n */\n\nimport { Agent } from './types.js';\n\n/**\n * Minimal MCP client surface used by the interceptor. Like the server\n * adapter, we describe just the methods we need to keep peer-dep\n * compatibility broad.\n */\nexport interface McpClientLike {\n  callTool(\n    params: {\n      name: string;\n      arguments?: Record<string, unknown>;\n      _meta?: Record<string, unknown>;\n    },\n    ...rest: unknown[]\n  ): Promise<unknown>;\n}\n\nexport interface OpenAgentClientConfig {\n  /** The agent doing the calling — used to sign each request. */\n  agent: Agent;\n  /**\n   * Optional audience DID. When set, it is passed to\n   * {@link Agent.signRequest} so the proof can be bound to a specific\n   * server. Most production deployments should set this.\n   */\n  audience?: string;\n  /**\n   * Optional hook fired before every outbound call. Use it for client-\n   * side metrics or to mutate the params (e.g., add tracing headers).\n   * Returning a value replaces the params.\n   */\n  beforeCall?: (params: {\n    name: string;\n    arguments?: Record<string, unknown>;\n    _meta?: Record<string, unknown>;\n  }) => Promise<\n    | { name: string; arguments?: Record<string, unknown>; _meta?: Record<string, unknown> }\n    | void\n  > | { name: string; arguments?: Record<string, unknown>; _meta?: Record<string, unknown> }\n    | void;\n}\n\n/**\n * Wrap an MCP client so every outbound `callTool` carries an OpenAgent\n * identity envelope.\n */\nexport function withOpenAgentClient<T extends McpClientLike>(\n  client: T,\n  config: OpenAgentClientConfig,\n): T {\n  if (config === null || typeof config !== 'object') {\n    throw new TypeError('OpenAgentClientConfig must be an object');\n  }\n  if (config.agent === undefined || config.agent === null) {\n    throw new TypeError('OpenAgentClientConfig.agent is required');\n  }\n  if (typeof config.agent.signRequest !== 'function') {\n    throw new TypeError('OpenAgentClientConfig.agent.signRequest is required');\n  }\n\n  const interceptor = new ClientInterceptor(config);\n\n  return new Proxy(client, {\n    get(target, property, receiver) {\n      const value = Reflect.get(target, property, receiver);\n      if (typeof value !== 'function') {\n        return value;\n      }\n      if (property === 'callTool') {\n        return interceptor.wrapCallTool(\n          value as McpClientLike['callTool'],\n          target,\n        );\n      }\n      return value.bind(target);\n    },\n  }) as T;\n}\n\nclass ClientInterceptor {\n  private readonly agent: Agent;\n  private readonly audience: string | undefined;\n  private readonly beforeCall: OpenAgentClientConfig['beforeCall'];\n\n  constructor(config: OpenAgentClientConfig) {\n    this.agent = config.agent;\n    this.audience = config.audience;\n    this.beforeCall = config.beforeCall;\n  }\n\n  wrapCallTool(\n    original: McpClientLike['callTool'],\n    thisArg: unknown,\n  ): McpClientLike['callTool'] {\n    const interceptor = this;\n    return async function wrappedCallTool(\n      this: unknown,\n      params: {\n        name: string;\n        arguments?: Record<string, unknown>;\n        _meta?: Record<string, unknown>;\n      },\n      ...rest: unknown[]\n    ): Promise<unknown> {\n      const signed = await interceptor.signParams(params);\n      let toSend: {\n        name: string;\n        arguments?: Record<string, unknown>;\n        _meta: Record<string, unknown>;\n      } = signed;\n      if (interceptor.beforeCall !== undefined) {\n        const replacement = await Promise.resolve(\n          interceptor.beforeCall(signed),\n        );\n        if (replacement !== undefined) {\n          // Re-attach the signed _meta if the hook stripped it.\n          toSend = {\n            ...replacement,\n            _meta: replacement._meta ?? signed._meta,\n          };\n        }\n      }\n      return original.call(thisArg, toSend, ...rest);\n    };\n  }\n\n  private async signParams(params: {\n    name: string;\n    arguments?: Record<string, unknown>;\n    _meta?: Record<string, unknown>;\n  }): Promise<{\n    name: string;\n    arguments?: Record<string, unknown>;\n    _meta: Record<string, unknown>;\n  }> {\n    const identity = await this.agent.signRequest(params.name, this.audience);\n    const existingMeta = params._meta ?? {};\n    const existingOpenAgent =\n      typeof existingMeta['openagent'] === 'object' &&\n      existingMeta['openagent'] !== null\n        ? (existingMeta['openagent'] as Record<string, unknown>)\n        : {};\n    return {\n      ...params,\n      _meta: {\n        ...existingMeta,\n        openagent: {\n          ...existingOpenAgent,\n          identity,\n        },\n      },\n    };\n  }\n}\n\n/**\n * Helper for tests and tools that want to construct the identity\n * envelope manually without going through a full Agent. Returns a `_meta`\n * object that can be merged into a CallToolRequest's params.\n */\nexport function buildIdentityMeta(identity: {\n  did: string;\n  proof: string;\n  nonce?: string;\n  context?: Record<string, unknown>;\n}): Record<string, unknown> {\n  return {\n    openagent: {\n      identity: {\n        did: identity.did,\n        proof: identity.proof,\n        ...(identity.nonce !== undefined ? { nonce: identity.nonce } : {}),\n        ...(identity.context !== undefined\n          ? { context: identity.context }\n          : {}),\n      },\n    },\n  };\n}\n"]}

package/dist/client.d.cts

@@ -0,0 +1,82 @@
+import { Agent } from './types.cjs';
+
+/**
+ * Client-side interceptor for @openagentid/mcp.
+ *
+ * Adds an OpenAgent identity envelope (`_meta.openagent.identity`) to
+ * outbound MCP `tools/call` requests so an authenticated server can
+ * verify the caller. The interceptor wraps the MCP client's `callTool`
+ * method via a JavaScript Proxy — the rest of the client surface (list
+ * tools, list resources, prompts) is forwarded unchanged.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+ * import { withOpenAgentClient } from '@openagentid/mcp/client';
+ *
+ * const client = new Client({ name: 'my-agent', version: '0.1.0' });
+ * const authedClient = withOpenAgentClient(client, { agent });
+ *
+ * await authedClient.callTool({ name: 'search_web', arguments: { q: 'mcp' } });
+ * ```
+ */
+
+/**
+ * Minimal MCP client surface used by the interceptor. Like the server
+ * adapter, we describe just the methods we need to keep peer-dep
+ * compatibility broad.
+ */
+interface McpClientLike {
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    }, ...rest: unknown[]): Promise<unknown>;
+}
+interface OpenAgentClientConfig {
+    /** The agent doing the calling — used to sign each request. */
+    agent: Agent;
+    /**
+     * Optional audience DID. When set, it is passed to
+     * {@link Agent.signRequest} so the proof can be bound to a specific
+     * server. Most production deployments should set this.
+     */
+    audience?: string;
+    /**
+     * Optional hook fired before every outbound call. Use it for client-
+     * side metrics or to mutate the params (e.g., add tracing headers).
+     * Returning a value replaces the params.
+     */
+    beforeCall?: (params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    }) => Promise<{
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    } | void> | {
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    } | void;
+}
+/**
+ * Wrap an MCP client so every outbound `callTool` carries an OpenAgent
+ * identity envelope.
+ */
+declare function withOpenAgentClient<T extends McpClientLike>(client: T, config: OpenAgentClientConfig): T;
+/**
+ * Helper for tests and tools that want to construct the identity
+ * envelope manually without going through a full Agent. Returns a `_meta`
+ * object that can be merged into a CallToolRequest's params.
+ */
+declare function buildIdentityMeta(identity: {
+    did: string;
+    proof: string;
+    nonce?: string;
+    context?: Record<string, unknown>;
+}): Record<string, unknown>;
+
+export { type McpClientLike, type OpenAgentClientConfig, buildIdentityMeta, withOpenAgentClient };

package/dist/client.d.ts

@@ -0,0 +1,82 @@
+import { Agent } from './types.js';
+
+/**
+ * Client-side interceptor for @openagentid/mcp.
+ *
+ * Adds an OpenAgent identity envelope (`_meta.openagent.identity`) to
+ * outbound MCP `tools/call` requests so an authenticated server can
+ * verify the caller. The interceptor wraps the MCP client's `callTool`
+ * method via a JavaScript Proxy — the rest of the client surface (list
+ * tools, list resources, prompts) is forwarded unchanged.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+ * import { withOpenAgentClient } from '@openagentid/mcp/client';
+ *
+ * const client = new Client({ name: 'my-agent', version: '0.1.0' });
+ * const authedClient = withOpenAgentClient(client, { agent });
+ *
+ * await authedClient.callTool({ name: 'search_web', arguments: { q: 'mcp' } });
+ * ```
+ */
+
+/**
+ * Minimal MCP client surface used by the interceptor. Like the server
+ * adapter, we describe just the methods we need to keep peer-dep
+ * compatibility broad.
+ */
+interface McpClientLike {
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    }, ...rest: unknown[]): Promise<unknown>;
+}
+interface OpenAgentClientConfig {
+    /** The agent doing the calling — used to sign each request. */
+    agent: Agent;
+    /**
+     * Optional audience DID. When set, it is passed to
+     * {@link Agent.signRequest} so the proof can be bound to a specific
+     * server. Most production deployments should set this.
+     */
+    audience?: string;
+    /**
+     * Optional hook fired before every outbound call. Use it for client-
+     * side metrics or to mutate the params (e.g., add tracing headers).
+     * Returning a value replaces the params.
+     */
+    beforeCall?: (params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    }) => Promise<{
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    } | void> | {
+        name: string;
+        arguments?: Record<string, unknown>;
+        _meta?: Record<string, unknown>;
+    } | void;
+}
+/**
+ * Wrap an MCP client so every outbound `callTool` carries an OpenAgent
+ * identity envelope.
+ */
+declare function withOpenAgentClient<T extends McpClientLike>(client: T, config: OpenAgentClientConfig): T;
+/**
+ * Helper for tests and tools that want to construct the identity
+ * envelope manually without going through a full Agent. Returns a `_meta`
+ * object that can be merged into a CallToolRequest's params.
+ */
+declare function buildIdentityMeta(identity: {
+    did: string;
+    proof: string;
+    nonce?: string;
+    context?: Record<string, unknown>;
+}): Record<string, unknown>;
+
+export { type McpClientLike, type OpenAgentClientConfig, buildIdentityMeta, withOpenAgentClient };