mcp-tool-bridge 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien
+
+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,492 @@
+# mcp-tool-bridge
+
+A generic [Model Context Protocol](https://modelcontextprotocol.io) server that exposes a
+catalog of **declared** tools to a model, filters them by role, validates every argument
+and holds sensitive calls behind a confirmation the model cannot give itself.
+
+You declare what a tool is (its arguments, how much harm it can do, whether it can be
+undone, who may use it); the bridge enforces it on every call, whatever the model says.
+
+> **Status: 1.1.** Tool declarations, the registry, role-based access, argument
+> validation, the bridge, the confirmation guard with lifetimes per class of tool, an
+> audit log that keeps no content by default, the stdio server and three adapters
+> (`envelope`, `adapt`, `importDefinitions`), with a runnable example in
+> [`examples/minimal`](./examples/minimal). The HTTP transport comes next.
+
+## Requirements
+
+Node.js 20 or later. The package ships as both ES modules and CommonJS. Zod is optional:
+install `zod@^4` only if you use `mcp-tool-bridge/zod`.
+
+## A first look
+
+```ts
+import { defineTool, jsonSchema, ToolRegistry, text } from 'mcp-tool-bridge'
+
+const sendInvoice = defineTool({
+  name: 'send_invoice',
+  description: 'Emails an existing invoice to the customer it belongs to.',
+  args: jsonSchema({
+    type: 'object',
+    properties: { invoiceId: { type: 'string', pattern: '^INV-[0-9]+$' } },
+    required: ['invoiceId'],
+    additionalProperties: false,
+  }),
+  sensitivity: 'high', // none | low | medium | high | critical
+  reversible: false, // an email cannot be unsent
+  roles: ['billing'],
+  summarize: ({ invoiceId }) => `Email invoice ${invoiceId} to its customer`,
+  handler: async ({ invoiceId }) => {
+    // `invoiceId` is a string here: the type comes from the schema above.
+    return text(`Invoice ${invoiceId} sent.`)
+  },
+})
+
+const registry = new ToolRegistry().register(sendInvoice)
+```
+
+With Zod:
+
+```ts
+import * as z from 'zod'
+import { zodSchema } from 'mcp-tool-bridge/zod'
+
+const args = zodSchema(z.object({ invoiceId: z.string().regex(/^INV-[0-9]+$/) }))
+```
+
+The bridge is the only way to run a tool. It works without any transport, which is how
+a host calls it directly and how the tests exercise it:
+
+```ts
+import { createBridge } from 'mcp-tool-bridge'
+
+const bridge = createBridge({
+  registry,
+  context: (principal) => ({ db, tenantId: principal.id }), // what handlers get as call.context
+})
+
+const alice = { id: 'alice', roles: ['billing'] }
+bridge.listTools(alice) // what the model may see
+
+const outcome = await bridge.callTool(alice, {
+  name: 'send_invoice',
+  arguments: { invoiceId: 'INV-12' },
+})
+// send_invoice is high-sensitivity and irreversible: nothing ran.
+// outcome.status === 'confirmation_required'
+// outcome.confirmation = { token, expiresAt, tool, summary: 'Email invoice INV-12 to its customer' }
+
+// Later, once a human has said yes in the host's own interface:
+await bridge.executeConfirmed(alice, outcome.confirmation.token) // { status: 'ok', … }
+// …or no:
+await bridge.revokeConfirmation(alice, outcome.confirmation.token)
+```
+
+Every outcome is a value, never an exception: `ok`, `tool_error`, `invalid_arguments`,
+`confirmation_required` or `rejected`, each with the `callId` found in the audit log.
+
+## Serving over MCP
+
+`serveStdio` serves the bridge over stdin/stdout, for one principal fixed when the
+process starts:
+
+```ts
+import { parsePrincipal, serveStdio } from 'mcp-tool-bridge'
+
+await serveStdio(bridge, {
+  info: { name: 'billing-tools', version: '1.0.0' },
+  principal: parsePrincipal({ id: 'alice', roles: ['billing'] }),
+})
+```
+
+For another transport, `createMcpServer(bridge, options)` returns the SDK's `Server`,
+ready to connect.
+
+On the wire:
+
+- `tools/list` returns the principal's tools only. The server announces
+  `tools.listChanged` and notifies the client whenever the registry changes.
+- An unknown tool, or a tool the principal may not use, is a JSON-RPC error
+  (`-32602 Unknown tool: …`), the same for both. Invalid arguments and handler failures
+  are results with `isError: true`, which the model can read and act on. A refused
+  confirmation token reads the same whatever the reason: "This confirmation cannot be
+  used. Nothing was done."
+- A call that needs confirmation is resolved in one of two ways:
+  - **The client supports elicitation:** the server asks the user through the client
+    and runs the call on a yes. A no, or a dismissed question, withdraws it.
+  - **It does not, or elicitation is turned off** (`elicitConfirmations: false`): the
+    result says that confirmation is pending, and the token travels in the result's
+    `_meta` under `mcp-tool-bridge/confirmation`. To redeem it, the host repeats the same
+    call with `{ token }` under the same key in the request's `_meta`, after a human said
+    yes. The model has no way to do this: it writes arguments, not `_meta`, and a token
+    placed in the arguments is ignored.
+
+Install it in an MCP client such as Claude Code with
+`claude mcp add billing -- npx tsx path/to/server.ts`.
+
+## Plugging in existing code
+
+Most tools already exist somewhere, with their own input shape and their own way of
+reporting failure. Three adapters connect them without rewriting them:
+
+- `envelope()` reads a result envelope such as `{ success, data, error }` or
+  `{ ok, detail }`. A failed envelope becomes a `ToolError`, so the model reads its
+  message; a successful one becomes the tool output.
+- `adapt()` wraps an existing function. The bridge validates the arguments, `input`
+  maps them to what the function expects, and `output` (often an `envelope`) maps the
+  result back.
+
+  ```ts
+  handler: adapt((action: LegacyAction) => legacy.execute(action), {
+    input: (args, call) => ({ userId: call.principal.id, data: JSON.stringify(args) }),
+    output: fromLegacy,
+  }),
+  ```
+
+- `importDefinitions()` turns tool definitions written for an LLM API (Anthropic
+  `input_schema`, MCP `inputSchema`, OpenAI `parameters`) and one dispatcher into
+  tools. What those formats do not say has to be declared, for every tool:
+
+  ```ts
+  const tools = importDefinitions(definitions, (name, args, call) => run(name, args, call), {
+    search_orders: { sensitivity: 'none', reversible: true, roles: ['support'] },
+    refund_order: { sensitivity: 'high', reversible: false, roles: ['billing'] },
+  })
+  ```
+
+  A definition without governance, or governance for a name that has no definition,
+  fails at startup with every name listed. When one tool is unclassified, none starts.
+  Imported schemas are compiled in the same strict mode as `jsonSchema()`.
+
+## What the audit log keeps
+
+An audit log that records arguments and results in full is a second copy of every
+email body, every value written to a spreadsheet, every document read. It is also the
+place nobody thinks of when data is deleted. So the default is the opposite: **the
+audit log keeps no content at all.**
+
+Every event carries metadata only:
+
+| Field                                            | What it is                                                                                                                        |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `tool`, `principal`, `callId`, `transport`, `at` | Who called what, when, and through which channel.                                                                                 |
+| `argsDigest`                                     | SHA-256 of the canonical arguments. It tells two calls apart and links a call to its confirmation, without keeping what was sent. |
+| `type`, `reason`, `detail`                       | The verdict: started, succeeded, failed, rejected, and why.                                                                       |
+| `durationMs`, `result.isError`                   | How long it took, and whether the result was an error.                                                                            |
+
+A tool that needs to keep some content says so, field by field, with JSON Pointers
+into its arguments and into its structured result:
+
+```ts
+defineTool({
+  name: 'read_email',
+  // …
+  audit: { args: ['/messageId'] }, // which message was read; never its content
+})
+
+defineTool({
+  name: 'search_email',
+  // …
+  audit: { result: ['/messages/*/id'] }, // which messages came back
+})
+```
+
+Kept fields appear in the event keyed by their pointer: `"args": { "/messageId":
+"m-1" }`. A `*` segment collects every match. Keeping content is a written decision,
+in the declaration, visible in review. This is the same rule as governance: the default
+path is the safe one, and a forgotten line costs a missing detail in the log, not a
+leaked email.
+
+Some guarantees hold whatever a tool declares:
+
+- **Reduced on the way in.** Arguments are reduced to their digest and their declared
+  fields when the call's audit scope is built, before any event exists. The full value
+  never lives in an audit event object, so it cannot resurface in an exception trace or
+  a debug dump. Serialization only ever sees the reduced value.
+- **Second line of defence.** Inside a kept value, keys that look like secrets
+  (`password`, `token`, `apiKey`, `authorization`, `secret`, `cookie`…) are masked.
+  Kept strings are cut at 500 characters, and at most 100 matches are kept per pointer.
+- **No summary, no text.** The confirmation summary is written from the arguments ("Send
+  'Invoice 12' to ada@…"), so it goes to the host, never to the audit log. Result text
+  and binary content are never kept, only declared fields of the structured result.
+- **Every refused token is recorded with its reason**: `unknown`, `consumed` (a
+  replay), `expired`, `principal_mismatch`, `tool_mismatch`, `arguments_mismatch`. These
+  are the lines that show whether something is trying to force its way. The model gets
+  one generic refusal and never learns which check stopped it.
+
+## Design decisions
+
+### At a glance
+
+**Tools are frozen descriptors that only the bridge can run.** `defineTool` returns an
+immutable description that holds no reference to the handler. The handler is kept
+privately and only the bridge can reach it, so every execution goes through the same
+checks: role, arguments, confirmation, audit. No code in the host can call a handler
+by mistake, and no one can widen a tool's roles after its declaration has been checked.
+
+**`roles` is required and cannot be empty.** A tool without roles would be open to
+everyone or to no one. Either way, that is a decision someone must make, and make
+visibly. Failing at startup turns a forgotten line into an error the developer sees
+immediately. Otherwise it would surface in production as a tool silently open to all,
+or silently dead.
+
+**The same function decides access for the list and for the call.** The access rule
+lives in one place, `canAccess`. The list hides what a principal cannot use. The call
+checks again, because a client can send any tool name and roles can change in between.
+Two implementations would end up disagreeing. Either the model is shown tools it cannot
+call, or, worse, it can call tools it is never shown.
+
+### Why a declarative registry
+
+A tool is two things: code that does something, and facts about that code. How sensitive
+is it? Can it be undone? Who may use it? What arguments does it accept? In most agent
+code these facts live in the head of whoever wrote the handler. At best they are
+scattered: an `if` in the handler, a sentence in the system prompt, a comment.
+
+Here they are fields of the declaration, and the governance fields (`sensitivity`,
+`reversible`, `roles`) have **no default**. A tool nobody classified does not start. It
+does not silently become "low sensitivity, everyone". Because the facts are data, the
+bridge can apply one policy to every tool. It can also hand the facts to a reviewer, or
+to an audit, as a table rather than as code to read.
+
+The registry only accepts descriptors created by `defineTool`, which checks the whole
+declaration at startup. A descriptor carries no handle on the handler: the only way to
+run a tool is through the bridge and its checks. A copy made with `{ ...tool }`
+type-checks, but registering it is refused.
+
+### Why filter twice
+
+The access rule is one function, `canAccess(tool, principal)`: the principal must hold
+at least one of the tool's roles. Names are compared exactly. There is no wildcard and
+no hierarchy, so anyone can read who has access to what from the declarations alone.
+
+The bridge applies this rule twice: when it lists tools for a principal, and again when
+it executes a call. Two reasons:
+
+- **The list is a convenience, not a barrier.** Hiding a tool keeps it out of the
+  model's context. It saves tokens and avoids tempting the model with a tool it cannot
+  use. But nothing forces a client to call only the tools it was shown. A model can
+  hallucinate a name, a prompt injection can supply one, a client can be buggy or
+  hostile. The check that matters is the one made when the call is executed.
+- **Time passes between the two.** Roles can be revoked and tools unregistered while a
+  session is open. The decision is taken again, at the moment the effect would happen.
+
+A call refused for lack of a role gets the same answer as a call to a tool that does not
+exist (`unknown_tool`), so probing names reveals nothing. The audit log still records
+the real reason.
+
+### Why validate on the server
+
+The argument schema is declared once and serves two purposes: the JSON Schema shown to
+the model, and the check enforced before the handler runs. Both adapters (`jsonSchema`
+and `zodSchema`) derive the two from the same declaration, so they cannot drift apart.
+The handler's argument type is inferred from the same source.
+
+Validation is strict on purpose:
+
+- **No coercion.** `"3"` is not a number. A model that gets a type wrong should be told
+  so, not second-guessed.
+- **Defaults are not applied.** In a JSON Schema, `default` tells the model what happens
+  if it leaves a field out. The handler decides what that means. The inferred type keeps
+  defaulted properties optional, so the handler cannot assume they are present.
+- **Only plain JSON gets in.** Arguments are deep-copied, and anything that is not JSON
+  (dates, functions, class instances, cycles, `NaN`) is rejected. The handler, the audit
+  log and the confirmation guard each see a value that nobody else can mutate.
+- **Bad schemas fail at startup.** JSON Schemas are compiled with Ajv in strict mode.
+  Unknown keywords, unknown formats and `required` properties that are never declared
+  are errors. A Zod type with no JSON equivalent (`z.date()`, `z.bigint()`) is refused
+  too, because the model could never send it.
+
+Rejected arguments come back to the model as a tool result, with one JSON Pointer and
+one message per problem (`/to: must match format "email"`). The model can then correct
+itself, and the handler never sees the bad input.
+
+### Why the confirmation lives on the server, not in the prompt
+
+"Ask the user before sending anything" in a system prompt is a request made to the
+model, and the model is the very component the guard protects against. It can lose the
+instruction in a long context. A prompt injection can override it. It can judge that
+this case does not count. And nothing in the code enforces it.
+
+The guard is code on the execution path. A tool whose declaration says
+`sensitivity: 'high'` (or `'medium'` and irreversible) returns `confirmation_required`
+instead of running, and the handler cannot be reached without a valid token. The
+decision comes from the declaration, not from the model's reading of the situation: the
+same tool is always confirmed, or never.
+
+The token is built so that approving one thing cannot authorise another:
+
+- **Bound to the call.** A token belongs to one principal, one tool and the exact
+  arguments. Key order does not matter, values do. Approving "email invoice INV-12"
+  cannot email INV-13, and a token presented by anyone else is refused.
+- **Single-use.** Redeeming takes the record out of the store in one atomic step, and
+  that same step checks the expiry. Two concurrent redemptions cannot both run, and a
+  second presentation is recorded as a replay (`consumed`).
+- **Short-lived, by class.** The lifetime can be a table per sensitivity and
+  reversibility: an irreversible critical action deserves a shorter window than a
+  reversible medium one, because past it the context of the decision is gone. The
+  expiry is computed when the confirmation is issued and stored with it; changing the
+  configuration later does not move confirmations already issued. Five minutes by
+  default.
+- **Never stored.** The store keeps a SHA-256 hash. Whoever can read the store cannot
+  redeem anything.
+- **Checked again.** At redemption the role is checked again and the arguments are
+  revalidated against the tool registered at that moment. The arguments that run are
+  the ones that were confirmed, frozen when the confirmation was issued.
+- **Not for the model.** The token is meant for the host. The MCP server carries it in
+  the result's `_meta`, which MCP clients are not expected to pass to the model,
+  while the model only reads that confirmation is pending. The host redeems it after a
+  human decision: by repeating the call with the token, by calling `executeConfirmed()`
+  later, or through MCP elicitation when the client supports it. There is deliberately
+  no `confirm_action` tool. A model under prompt injection would simply call it, and the
+  guard would be reduced to a delay.
+
+### What the guard does not cover
+
+The guard stops the model from running a sensitive call on its own. It does not make
+the system safe by itself. Each limit below comes with what you should put in place
+around it.
+
+- **A compromised host or client.** Whoever controls the MCP client can attach a token
+  it was given and replay a decision: the guard protects against the model, not against
+  the host.
+  _Put in place:_ run the client in a component you control, authenticate it (the
+  `authenticate` hook of the upcoming HTTP transport), and keep the tokens it receives
+  in memory, out of logs and transcripts.
+- **A host that shows the token to the model.** If a host copies `_meta`, or the whole
+  outcome, into the conversation, the model can confirm its own calls, and the guard is
+  gone.
+  _Put in place:_ strip `_meta` and confirmation outcomes before anything reaches the
+  model's context, and add a test that fails if `mtb_` (the token prefix) ever appears
+  in a transcript.
+- **Misclassified tools.** Below the threshold, tools run directly. A tool declared
+  `low` that actually deletes data is not caught.
+  _Put in place:_ review declarations like permissions: print `registry.list()` as a
+  table (name, sensitivity, reversible, roles) in code review, and require a second
+  reviewer for any new or reclassified tool.
+- **What the handler really does.** The guard confirms a call, not the behaviour of the
+  code behind it.
+  _Put in place:_ give each handler credentials scoped to the one effect its declaration
+  describes, so that it cannot do more even by mistake.
+- **Information leaving through reads.** `sensitivity: 'none'` tools run freely. A
+  model can read data and repeat it elsewhere. Confirmation governs actions, not
+  information flow.
+  _Put in place:_ restrict reads of personal or confidential data by role, return only
+  the fields the task needs, and watch the audit log for unusual read volumes.
+- **The quality of the human decision.** The guard makes sure someone confirmed. It
+  cannot make sure they read what they confirmed.
+  _Put in place:_ write `summarize` for the person who confirms (what happens, to whom,
+  with what consequence) and show it next to the arguments, never as a bare "Confirm?".
+- **A world that changed.** Roles and arguments are checked again at redemption, but
+  the invoice may have been paid in the meantime.
+  _Put in place:_ have handlers check their preconditions when they run (invoice still
+  unpaid, slot still free) and throw a `ToolError` otherwise, and shorten `ttlMs` where
+  the context moves fast.
+- **Timeouts.** A handler that ignores its abort signal keeps running after the bridge
+  has given up. Its result is discarded, but its effects are not undone.
+  _Put in place:_ pass `call.signal` to every I/O the handler starts (`fetch` and most
+  database drivers accept one) and make side effects idempotent, so that a cancelled
+  call either stops or can be retried safely.
+- **Several processes.** The default store lives in one process. A token issued by one
+  instance cannot be redeemed on another.
+  _Put in place:_ before running a second instance, implement `ConfirmationStore` over
+  shared storage with an atomic `take` (Redis `GETDEL`, SQL `DELETE … RETURNING`).
+
+### Why the audit log records before running
+
+Each call that runs leaves two events under one `callId`: `call.started`, then
+`call.succeeded` or `call.failed`. A confirmed call is preceded by `confirmation.issued`
+and possibly `confirmation.declined`, under the same id. Rejections are recorded with
+their real reason (`forbidden`, `invalid_arguments`, an invalid or expired confirmation),
+even when the model is told `unknown_tool`.
+
+`call.started` is written before the handler runs, so the log knows about the call even
+if the process dies during it. With `auditFailure: 'block'`, a call or a confirmation
+that could not be recorded does not happen. The default, `continue`, warns on stderr and
+proceeds. Events that follow an effect (`call.succeeded`, `call.failed`) can only be
+reported: the effect has already happened.
+
+What these events contain is the subject of [What the audit log keeps](#what-the-audit-log-keeps):
+by default, metadata only. Messages of unexpected exceptions go to the log only, cut
+to 500 characters; the model gets a generic failure. The default sink writes JSON
+lines to stderr, because under stdio, stdout is the protocol channel.
+
+## Declaring tools: reference
+
+| Field         | Required | Meaning                                                                                                                                           |
+| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`        | yes      | Unique in a registry. MCP allows `A-Z a-z 0-9 _ - .`, 1–128 characters. Some LLM APIs are stricter (no dots, 64 characters): prefer `snake_case`. |
+| `description` | yes      | What the model reads to decide whether and how to call the tool.                                                                                  |
+| `args`        | yes      | `jsonSchema({...})` or `zodSchema(z.object({...}))`. The root must be an object.                                                                  |
+| `sensitivity` | yes      | `none` (no side effect at all), `low`, `medium`, `high`, `critical`.                                                                              |
+| `reversible`  | yes      | Can the effect be undone?                                                                                                                         |
+| `roles`       | yes      | Non-empty. A principal needs one of them.                                                                                                         |
+| `confirm`     | no       | `auto` (default: the bridge's policy decides) or `always`. There is no opt-out.                                                                   |
+| `summarize`   | no       | One sentence describing a specific call, shown to whoever confirms it.                                                                            |
+| `audit`       | no       | What the audit log may keep: `{ args?, result? }`, JSON Pointers (`*` allowed). Nothing but metadata by default.                                  |
+| `timeoutMs`   | no       | Per-call time limit.                                                                                                                              |
+| `title`       | no       | Human-readable name.                                                                                                                              |
+
+Behaviour hints sent to MCP clients are derived from the declaration. `readOnlyHint`
+is true for `sensitivity: "none"`. `destructiveHint` is true for irreversible tools that
+have an effect. Roles and sensitivity levels are never sent to the client.
+
+Handlers throw `ToolError` for failures the model may read ("no invoice INV-12"). Any
+other exception reaches the model as a generic failure; its details go to the audit log.
+
+## Roadmap
+
+**v1.0**: declarations and registry, role-based access, validation (JSON Schema and
+Zod), the confirmation guard with single-use tokens and MCP elicitation, the audit log,
+the `envelope` adapter, the stdio transport, a three-tool example.
+
+**v1.1**: `adapt()` and `importDefinitions()` (see
+[Plugging in existing code](#plugging-in-existing-code)); confirmation lifetimes per
+sensitivity and reversibility, an atomic take that reports why a token was refused;
+an audit log that keeps no content unless a tool declares it (see
+[What the audit log keeps](#what-the-audit-log-keeps)).
+
+**Next**:
+
+- HTTP transport: Streamable HTTP, with a per-request `authenticate` hook,
+  Origin/Host checks and sessions bound to the principal who opened them. The deprecated
+  HTTP+SSE transport will be available behind `legacySse: true`.
+
+Out of scope for now: an OAuth authorization server, MCP resources and prompts, retries
+and rate limiting.
+
+## Development
+
+```sh
+npm ci
+npm run lint && npm run format:check && npm run typecheck
+npm test
+npm run build && npm run check:dist
+npm run check:mutations
+```
+
+The tests make no network calls.
+
+The safety guards are checked by **targeted mutation testing**: `npm run
+check:mutations` removes each guard in turn and fails if the test suite still passes.
+Eighteen guards are covered, among them:
+
+- the role is checked again at call time;
+- a confirmation token is single-use;
+- a token only runs the exact arguments it was issued for;
+- the role is checked again when a confirmation is redeemed;
+- the token never appears in what the model reads;
+- invalid arguments never reach a handler;
+- an imported tool without governance never starts;
+- the store checks the expiry in the same step as the take, and the bridge checks it
+  again from the expiry stored at issue time;
+- the audit keeps no argument or result content unless the tool declares it, and no
+  confirmation summary;
+- every refused token leaves its reason in the audit, and the model never learns it.
+
+CI runs this on every push. See [CONTRIBUTING](./CONTRIBUTING.md#mutation-checks) for
+the mutants and the tests that catch them.
+
+## License
+
+[MIT](./LICENSE)

package/dist/chunk-XMYSMKGR.cjs

@@ -0,0 +1,111 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2;// src/errors.ts
+var ToolDefinitionError = (_class = class extends Error {
+  __init() {this.name = "ToolDefinitionError"}
+  
+  /** The offending tool, when its name is known. */
+  
+  constructor(code, message, options) {
+    super(message, _optionalChain([options, 'optionalAccess', _ => _.cause]) === void 0 ? void 0 : { cause: options.cause });_class.prototype.__init.call(this);;
+    this.code = code;
+    this.tool = _optionalChain([options, 'optionalAccess', _2 => _2.tool]);
+  }
+}, _class);
+var ToolError = (_class2 = class extends Error {constructor(...args) { super(...args); _class2.prototype.__init2.call(this); }
+  __init2() {this.name = "ToolError"}
+}, _class2);
+
+// src/json.ts
+var NOT_JSON = /* @__PURE__ */ Symbol("not-json");
+function cloneJson(value) {
+  const copy = cloneValue(value, /* @__PURE__ */ new Set());
+  return copy === NOT_JSON ? { ok: false } : { ok: true, value: copy };
+}
+function cloneValue(value, ancestors) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : NOT_JSON;
+  if (typeof value !== "object") return NOT_JSON;
+  if (ancestors.has(value)) return NOT_JSON;
+  if (Array.isArray(value)) {
+    ancestors.add(value);
+    const items = [];
+    for (const item of value) {
+      const copy = cloneValue(item, ancestors);
+      if (copy === NOT_JSON) return NOT_JSON;
+      items.push(copy);
+    }
+    ancestors.delete(value);
+    return items;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return NOT_JSON;
+  ancestors.add(value);
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item === void 0) continue;
+    const copy = cloneValue(item, ancestors);
+    if (copy === NOT_JSON) return NOT_JSON;
+    out[key] = copy;
+  }
+  ancestors.delete(value);
+  return out;
+}
+function isJsonArray(value) {
+  return Array.isArray(value);
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepFreeze(value) {
+  if (typeof value === "object" && value !== null) {
+    for (const item of Object.values(value)) deepFreeze(item);
+    Object.freeze(value);
+  }
+  return value;
+}
+function pointerSegment(segment) {
+  return segment.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function readProperty(source, key) {
+  return Reflect.get(source, key);
+}
+
+// src/schema/types.ts
+var MAX_ISSUES = 20;
+var NOT_JSON_ISSUE = Object.freeze({
+  path: "",
+  message: "must be plain JSON data"
+});
+function freezeRootSchema(schema, tool) {
+  const copy = cloneJson(schema);
+  if (!copy.ok || !isJsonObject(copy.value)) {
+    throw new ToolDefinitionError("invalid_schema", "an argument schema must be plain JSON data", {
+      tool
+    });
+  }
+  const root = copy.value;
+  if (!isRootObjectSchema(root)) {
+    throw new ToolDefinitionError(
+      "invalid_schema",
+      'MCP requires the root of an argument schema to be `type: "object"`',
+      { tool }
+    );
+  }
+  return deepFreeze(root);
+}
+function isRootObjectSchema(schema) {
+  return schema.type === "object";
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.ToolDefinitionError = ToolDefinitionError; exports.ToolError = ToolError; exports.cloneJson = cloneJson; exports.isJsonArray = isJsonArray; exports.isJsonObject = isJsonObject; exports.deepFreeze = deepFreeze; exports.pointerSegment = pointerSegment; exports.readProperty = readProperty; exports.MAX_ISSUES = MAX_ISSUES; exports.NOT_JSON_ISSUE = NOT_JSON_ISSUE; exports.freezeRootSchema = freezeRootSchema;