@oribos/mcp-client 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such 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,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   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
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   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,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   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.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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/README.md

@@ -0,0 +1,127 @@
+# `@oribos/mcp-client`
+
+Bridge a remote [MCP](https://modelcontextprotocol.io) server's tools into a
+[Oribos](https://github.com/0xnicholas/oribos-framework) tool container: one `createMcpClient()`
+object with a `tools` snapshot you spread straight into an agent, a `refresh()`, and a `close()`.
+
+```ts
+import { createAgent } from '@oribos/core/agent';
+import { createMcpClient } from '@oribos/mcp-client';
+
+const client = await createMcpClient({
+  transport: { type: 'http', url: 'https://example.com/mcp' },
+  // or: { type: 'stdio', command: 'npx', args: ['my-mcp-server'] }
+});
+
+const agent = createAgent({
+  name: 'assistant',
+  instructions: 'You have remote tools.',
+  model,                                     // any AI SDK provider instance
+  tools: () => client.tools,                 // dynamic: every request resolves the latest snapshot
+});
+
+await client.refresh();                      // re-list remotely, swap the snapshot
+await client.close();                        // tear down (idempotent)
+```
+
+- Spec: [`docs/architecture/tools.md`](https://github.com/0xnicholas/oribos-framework/blob/main/docs/architecture/tools.md)
+- SDK facts this package builds on: [`docs/research/mcp-v2-sdk-surface.md`](https://github.com/0xnicholas/oribos-framework/blob/main/docs/research/mcp-v2-sdk-surface.md)
+- Decisions: [ADR-0008](https://github.com/0xnicholas/oribos-framework/blob/main/docs/adr/0008-tools-mcp-abstraction.md) (tools/MCP), [ADR-0002](https://github.com/0xnicholas/oribos-framework/blob/main/docs/adr/0002-package-structure.md) (packaging)
+- Paired example (server + client in one script): [`examples/mcp-tools`](https://github.com/0xnicholas/oribos-framework/blob/main/examples/mcp-tools)
+
+## Install
+
+```bash
+npm install @oribos/mcp-client @oribos/core
+```
+
+`@oribos/core` is a peer dependency (one core instance by design). The only direct runtime
+dependency is `@modelcontextprotocol/client`.
+
+## Transports and options
+
+```ts
+const client = await createMcpClient({
+  transport:
+    | { type: 'stdio', command: string, args?: string[], env?: Record<string, string> }
+    | { type: 'http', url: string | URL, headers?: Record<string, string> },
+  protocol?: 'auto' | 'legacy' | { pin: '2026-07-28' },  // omitted = 'auto'
+  timeoutMs?: number,                                     // omitted = the SDK's 60s per request
+});
+```
+
+- **stdio** spawns the server subprocess (the SDK owns it: shutdown is stdin → SIGTERM → SIGKILL).
+  `env`, when given, is the child's **whole** environment; omitted, the SDK applies its own safe
+  whitelist — never your full `process.env`. The child's stderr is inherited, so its logs reach
+  yours. `stderr` / `cwd` / `maxBufferSize` are not exposed — wire the official SDK yourself for
+  those (the escape hatch for everything v1 doesn't expose).
+- **http** speaks Streamable HTTP; `headers` go on every request (bearer tokens and the like).
+  OAuth flows, custom `fetch`, `sessionId` reattach: not exposed in v1.
+- **protocol**: `'auto'` (the default — raised here; the SDK's own default is `'legacy'`) probes
+  with `server/discover` first and falls back to the 2025 handshake. `'legacy'` skips the probe.
+  `{ pin: '2026-07-28' }` demands the modern era and fails loudly. Note the probe's cost: on
+  stdio it spawns a short-lived sibling process once per connect; on HTTP a probe timeout is
+  treated as an outage and rejects.
+- **timeoutMs** is passed to the connect handshake and every request (the SDK has no client-level
+  default setting). There is no per-call override — a long-running tool call is what this option
+  is for.
+- The client identity advertised to servers is this package's own name and version, not
+  overridable.
+
+## The snapshot and its lifecycle
+
+`client.tools` is a getter over a frozen `Record<string, Tool>` — keys are the remote tool names.
+The identity is stable until the next `refresh()`; old references never break. There is no
+`listChanged` subscription and **no auto-reconnect**: a dropped connection surfaces as SDK errors
+on the calls in flight and after it; recovery is a new client. `close()` is idempotent — HTTP
+sends `terminateSession` first (failures there are silent), then tears down; in-flight requests
+reject with `CONNECTION_CLOSED`. Not calling `close()` on a stdio client keeps the subprocess
+alive — the host owns the lifetime.
+
+`prefixTools(tools, prefix, separator = '_')` renames bridged tools into a new frozen record
+(`prefix + separator + name`). The prefix never reaches the wire — execute still calls the remote
+name. No collision detection runs (a fixed prefix is an isomorphic mapping), and whether a
+prefixed name is legal for your model provider is your concern.
+
+## What crosses the bridge
+
+**Schemas** arrive as JSON Schema documents and are wrapped in a pass-through Standard Schema:
+`validate` always succeeds locally (validation is the remote's business — failures come back
+through the execute path), and `jsonSchema.input` returns the remote document verbatim — same
+reference, no rewriting between draft versions. `jsonSchema.output` throws: a bridged tool
+carries no `outputSchema`, and the SDK client already validates `structuredContent` against the
+remote's schema. A consequence: MCP→MCP re-exporting loses `structuredContent` (text only) —
+explicit opt-in fidelity is a future minor.
+
+**Context**: of the six `ToolContext` pieces only `signal` crosses — `callTool({ signal })`
+passthrough, no pre-checks. `toolCallId` / `runId` / `traceId` / `spanId` stay local (the protocol
+has no slot for them), and `requestContext` is not transmitted.
+
+**Results**: `structuredContent` returns verbatim when present (any JSON value); otherwise text
+blocks join on newlines; image / audio / resource-link blocks degrade to placeholder text — the
+tool-result channel carries no multimodal parts, an honest v1 boundary. An empty result is `''`.
+An `isError` result **throws**, so the framework turns it into a `Tool 'x' failed: …` error result
+fed back to the model — the same road the server-side failure lines take.
+
+**Errors** propagate as-is: no layer added, no message rewritten. Connect-time: era negotiation
+failures, 401/403, probe timeouts. Runtime: request timeouts, `CONNECTION_CLOSED`, protocol
+errors, output-validation failures. A remote `input_required` answer (multi-round-trip) surfaces
+as a deterministic `SdkError` — this package pins `inputRequired.autoFulfill: false` and registers
+no elicitation/sampling handlers.
+
+On modern HTTP connections the SDK must drop tools whose `x-mcp-header` declarations are illegal
+(SPEC MUST, warned in console) — the snapshot can be smaller than what the server advertises.
+
+## Lightweight
+
+Same axis as the rest of Oribos — install only what you use:
+
+- dependency closure: everything `@modelcontextprotocol/client` pulls in — its OAuth / SSE / stdio
+  closure — recorded in `deps-budget.json`, where count and unpacked size are watched in CI
+- first-party code: the minified baseline is recorded in `byte-budget.json` and checked on every
+  PR — a warning, not a merge gate or a public budget
+- `@oribos/core` stays a peer, so there is exactly one core instance
+
+## License
+
+[Apache-2.0](https://github.com/0xnicholas/oribos-framework/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `@oribos/mcp-client` — the MCP client capability package: bridge a remote MCP server's tools
+ * into the framework's `Record<string, Tool>` container, ready to spread straight into an agent.
+ *
+ * One connection, one object with three members: `tools` (a getter over the current snapshot),
+ * `refresh()` (re-list and swap the snapshot), and `close()` (terminate the session and tear the
+ * connection down, idempotently). No auto-reconnect — a dropped connection surfaces as SDK
+ * errors on the calls in flight and after; recovery is a new client. No `listChanged`
+ * subscription either — a long-lived agent reads the latest snapshot through
+ * `tools: () => client.tools` (a dynamic argument resolves it per request).
+ *
+ * The bridge is deliberately thin. Schemas go over as a JSON Schema pass-through Standard
+ * Schema wrapper (validation is the remote's business; failures come back through the execute
+ * path); results project as `structuredContent` verbatim or joined text; `isError` results
+ * throw so the agent loop turns them into `Tool 'x' failed: …` error results. Everything else —
+ * era negotiation (default raised to `'auto'`: probe `server/discover`, fall back to the 2025
+ * handshake), the 60s per-request timeout, `inputRequired.autoFulfill: false` — is the SDK's
+ * own semantics, configured once here and never re-wrapped.
+ */
+import type { Tool } from '@oribos/core/tools';
+/** How to reach the server: a stdio subprocess the SDK owns, or a Streamable HTTP endpoint. */
+export type McpClientTransport = {
+    readonly type: 'stdio';
+    /** The executable to run (the SDK owns the subprocess and its shutdown: stdin → SIGTERM → SIGKILL). */
+    readonly command: string;
+    readonly args?: readonly string[];
+    /**
+     * The child's whole environment. Given, it replaces everything; omitted, the SDK applies
+     * its own safe-default whitelist (not the full `process.env`).
+     */
+    readonly env?: Readonly<Record<string, string>>;
+} | {
+    readonly type: 'http';
+    /** The Streamable HTTP endpoint. */
+    readonly url: string | URL;
+    /** Request headers applied to every request (bearer tokens and the like). */
+    readonly headers?: Readonly<Record<string, string>>;
+};
+/**
+ * Which protocol generation to speak. `'auto'` (the default — raised here, the SDK's own default
+ * is `'legacy'`) probes with `server/discover` first and falls back to the 2025 handshake;
+ * `'legacy'` skips the probe; `{ pin: '2026-07-28' }` demands the modern era and fails loudly.
+ */
+export type McpClientProtocol = 'auto' | 'legacy' | {
+    readonly pin: '2026-07-28';
+};
+/** Creation-time options. */
+export interface McpClientConfig {
+    readonly transport: McpClientTransport;
+    /** Protocol generation posture; omitted = `'auto'`.
+     */
+    readonly protocol?: McpClientProtocol;
+    /**
+     * Per-request timeout in milliseconds, passed through to the connect handshake and every
+     * request the client makes. The SDK has no client-level default setting — without this the
+     * SDK's own 60s applies (`DEFAULT_REQUEST_TIMEOUT_MSEC`). No per-call override.
+     */
+    readonly timeoutMs?: number;
+}
+/** A connected MCP client: the tool snapshot, a refresh, and a close. */
+export interface McpClient {
+    /**
+     * The current snapshot as a `Record<string, Tool>` — spread it into an agent's tool container.
+     * The object identity is stable until the next `refresh()`; old references never break.
+     */
+    readonly tools: Record<string, Tool>;
+    /** Re-lists the remote tools and swaps the snapshot; on failure keeps the old one and rejects. */
+    refresh(): Promise<void>;
+    /**
+     * Tears the connection down, idempotently: HTTP sends `terminateSession` first (a failure
+     * there is silent), then the client closes — in-flight requests reject with
+     * `CONNECTION_CLOSED`, a stdio subprocess shuts down in the SDK's order.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Connects to an MCP server and bridges its tools into the framework's `Tool` container.
+ *
+ * The connection happens up front: a failed handshake (era negotiation, 401/403, probe timeout)
+ * rejects here, never later. On success `tools` already holds the first snapshot.
+ */
+export declare function createMcpClient(config: McpClientConfig): Promise<McpClient>;
+/**
+ * Renames bridged tools with a fixed prefix: returns a new frozen `Record<string, Tool>` keyed
+ * `prefix + separator + name` (separator defaults to `'_'`). The prefix never reaches the wire —
+ * the tool objects are untouched, and the remote name in each execute closure is unchanged. A
+ * fixed prefix is an isomorphic mapping, so no collision detection runs; whether a prefixed name
+ * is legal for a given provider is the caller's concern. Not part of the client config surface.
+ */
+export declare function prefixTools(tools: Record<string, Tool>, prefix: string, separator?: string): Record<string, Tool>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAWH,OAAO,KAAK,EAAE,IAAI,EAAe,MAAM,oBAAoB,CAAC;AAO5D,+FAA+F;AAC/F,MAAM,MAAM,kBAAkB,GAC1B;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,uGAAuG;IACvG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD,CAAC;AAEN;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAA;CAAE,CAAC;AAEnF,6BAA6B;AAC7B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC;OACG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACrC,kGAAkG;IAClG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAuEjF;AAmFD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,EAC3B,MAAM,EAAE,MAAM,EACd,SAAS,SAAM,GACd,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAItB"}

package/dist/index.js

@@ -0,0 +1,183 @@
+/**
+ * `@oribos/mcp-client` — the MCP client capability package: bridge a remote MCP server's tools
+ * into the framework's `Record<string, Tool>` container, ready to spread straight into an agent.
+ *
+ * One connection, one object with three members: `tools` (a getter over the current snapshot),
+ * `refresh()` (re-list and swap the snapshot), and `close()` (terminate the session and tear the
+ * connection down, idempotently). No auto-reconnect — a dropped connection surfaces as SDK
+ * errors on the calls in flight and after; recovery is a new client. No `listChanged`
+ * subscription either — a long-lived agent reads the latest snapshot through
+ * `tools: () => client.tools` (a dynamic argument resolves it per request).
+ *
+ * The bridge is deliberately thin. Schemas go over as a JSON Schema pass-through Standard
+ * Schema wrapper (validation is the remote's business; failures come back through the execute
+ * path); results project as `structuredContent` verbatim or joined text; `isError` results
+ * throw so the agent loop turns them into `Tool 'x' failed: …` error results. Everything else —
+ * era negotiation (default raised to `'auto'`: probe `server/discover`, fall back to the 2025
+ * handshake), the 60s per-request timeout, `inputRequired.autoFulfill: false` — is the SDK's
+ * own semantics, configured once here and never re-wrapped.
+ */
+import { createRequire } from 'node:module';
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+/** The identity this package advertises to servers — its own name and version, not overridable. */
+const CLIENT_NAME = '@oribos/mcp-client';
+const { version: CLIENT_VERSION } = createRequire(import.meta.url)('../package.json');
+/**
+ * Connects to an MCP server and bridges its tools into the framework's `Tool` container.
+ *
+ * The connection happens up front: a failed handshake (era negotiation, 401/403, probe timeout)
+ * rejects here, never later. On success `tools` already holds the first snapshot.
+ */
+export async function createMcpClient(config) {
+    const timeout = config.timeoutMs;
+    const requestOptions = timeout === undefined ? undefined : { timeout };
+    let terminate;
+    let transport;
+    if (config.transport.type === 'stdio') {
+        transport = new StdioClientTransport({
+            command: config.transport.command,
+            ...(config.transport.args === undefined ? {} : { args: [...config.transport.args] }),
+            ...(config.transport.env === undefined ? {} : { env: { ...config.transport.env } }),
+        });
+    }
+    else {
+        const http = new StreamableHTTPClientTransport(new URL(config.transport.url), {
+            ...(config.transport.headers === undefined
+                ? {}
+                : { requestInit: { headers: { ...config.transport.headers } } }),
+        });
+        transport = http;
+        terminate = () => http.terminateSession();
+    }
+    const client = new Client({ name: CLIENT_NAME, version: CLIENT_VERSION }, {
+        // The default is raised to 'auto' here: probe with server/discover, fall back to legacy.
+        versionNegotiation: { mode: protocolMode(config.protocol) },
+        // No elicitation/sampling handlers exist to fulfil with — an `input_required` result must
+        // surface as a deterministic error, not a silent auto-flow.
+        inputRequired: { autoFulfill: false },
+    });
+    await client.connect(transport, requestOptions);
+    const call = (name, input, ctx) => client
+        .callTool({ name, ...(input === undefined ? {} : { arguments: input }) }, { signal: ctx.signal, ...(timeout === undefined ? {} : { timeout }) })
+        .then((result) => projectResult(name, result));
+    let snapshot = buildSnapshot((await listTools(client, requestOptions)).tools, call);
+    let closed = false;
+    return {
+        get tools() {
+            return snapshot;
+        },
+        async refresh() {
+            // cacheMode 'refresh' forces a real fetch past the SDK's response cache; the snapshot is
+            // only swapped on success, so a failure leaves the old one fully in place.
+            const listed = await client.listTools(undefined, {
+                cacheMode: 'refresh',
+                ...(timeout === undefined ? {} : { timeout }),
+            });
+            snapshot = buildSnapshot(listed.tools, call);
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            if (terminate !== undefined) {
+                try {
+                    await terminate();
+                }
+                catch {
+                    // Silent by spec: the server may not support session teardown, or is already gone.
+                }
+            }
+            await client.close();
+        },
+    };
+}
+/** Maps the package's protocol posture onto the SDK's negotiation mode one-to-one. */
+function protocolMode(protocol) {
+    return protocol ?? 'auto';
+}
+/** One list call shared by connect and refresh; the plain form at connect (empty cache → real fetch). */
+function listTools(client, requestOptions) {
+    return client.listTools(undefined, requestOptions);
+}
+/**
+ * Builds a frozen snapshot: one bridged `Tool` per remote entry. The remote name is the key and
+ * the name used on the wire; remote tool names are neither validated nor mangled here (the MCP
+ * charset is wider than most providers' — renaming, if wanted, is `prefixTools`' caller's call).
+ */
+function buildSnapshot(remoteTools, call) {
+    const snapshot = {};
+    for (const remote of remoteTools) {
+        const { name } = remote;
+        snapshot[name] = Object.freeze({
+            description: remote.description ?? '',
+            inputSchema: jsonSchemaPassthrough(remote.inputSchema),
+            execute: (input, ctx) => call(name, input, ctx),
+        });
+    }
+    return Object.freeze(snapshot);
+}
+/**
+ * The result projection: `structuredContent !== undefined` returns that
+ * value verbatim (any JSON flows — `ToolResultChunk.output` is `unknown`); otherwise the text
+ * blocks join on newlines with non-text blocks degrading to placeholder text — the tool-result
+ * channel carries no multimodal parts, an honest v1 boundary; an empty result is `''`. An
+ * `isError` result throws, so the framework turns it into a `Tool 'x' failed: …` error result
+ * fed back to the model — the same road the three server-side failure lines take.
+ */
+function projectResult(name, result) {
+    const text = contentText(result.content);
+    if (result.isError === true)
+        throw new Error(text === '' ? `Tool '${name}' failed` : text);
+    if (result.structuredContent !== undefined)
+        return result.structuredContent;
+    return text;
+}
+/** Text blocks verbatim, other blocks as placeholders, joined on newlines; empty content is ''. */
+function contentText(content) {
+    if (content === undefined || content.length === 0)
+        return '';
+    return content
+        .map((block) => (block.type === 'text' ? block.text : `[unsupported content block: ${block.type}]`))
+        .join('\n');
+}
+/**
+ * The JSON Schema pass-through wrapper — an internal factory, not
+ * exported. `validate` always succeeds synchronously (validation is the remote's business; a
+ * failure comes back through the execute error path), `jsonSchema.input` returns the remote
+ * document verbatim — same reference, target ignored: remote schemas are commonly 2020-12 while
+ * the core asks providers for draft-07, and this bridge rewrites nothing. `jsonSchema.output`
+ * throws: a bridged tool carries no output schema, and a fake would only validate vacuously.
+ * The wrapper and its `~standard` bag are frozen.
+ */
+function jsonSchemaPassthrough(remote) {
+    const wrapper = {
+        '~standard': Object.freeze({
+            version: 1,
+            vendor: 'oribos',
+            types: Object.freeze({ input: undefined, output: undefined }),
+            validate: Object.freeze((value) => ({ value })),
+            jsonSchema: Object.freeze({
+                input: Object.freeze(() => remote),
+                output: Object.freeze(() => {
+                    throw new Error('A bridged MCP tool has no output schema: the remote schema stays on the server.');
+                }),
+            }),
+        }),
+    };
+    return Object.freeze(wrapper);
+}
+/**
+ * Renames bridged tools with a fixed prefix: returns a new frozen `Record<string, Tool>` keyed
+ * `prefix + separator + name` (separator defaults to `'_'`). The prefix never reaches the wire —
+ * the tool objects are untouched, and the remote name in each execute closure is unchanged. A
+ * fixed prefix is an isomorphic mapping, so no collision detection runs; whether a prefixed name
+ * is legal for a given provider is the caller's concern. Not part of the client config surface.
+ */
+export function prefixTools(tools, prefix, separator = '_') {
+    const prefixed = {};
+    for (const [name, tool] of Object.entries(tools))
+        prefixed[prefix + separator + name] = tool;
+    return Object.freeze(prefixed);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@oribos/mcp-client",
+  "version": "0.5.0",
+  "description": "Oribos MCP client — bridge remote MCP tools into the Tool container (Streamable HTTP + stdio).",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xnicholas/oribos-framework.git",
+    "directory": "packages/mcp-client"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@oribos/core": "^0.5.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/server": "^2.2.0",
+    "@oribos/core": "0.5.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/client": "^2.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check:dist": "node ../../scripts/check-dist.mjs",
+    "check:export-surface": "node ../../scripts/check-export-surface.mjs",
+    "check:runtime-deps": "node ../../scripts/check-runtime-deps.mjs",
+    "check:byte-budget": "node ../../scripts/check-byte-budget.mjs",
+    "byte-budget:update": "node ../../scripts/check-byte-budget.mjs --update",
+    "check:deps-budget": "node ../../scripts/check-deps-budget.mjs",
+    "deps-budget:update": "node ../../scripts/check-deps-budget.mjs --update"
+  }
+}