@fitzzero/quickdraw-core 5.0.1 → 5.1.0

package/dist/server/mcp/index.d.ts

@@ -1,14 +1,14 @@
-import { A as AnyService, i as Caller } from '../../caller-BqCYnpmC.js';
+import { A as AnyService, d as Caller } from '../../caller-CXTFswBO.js';
 import { IncomingHttpHeaders, IncomingMessage } from 'node:http';
-import { ap as MethodName, d as StandardSchemaV1, c as InferOutput } from '../../infer-Dw21kmLw.js';
+import { ap as MethodName, d as StandardSchemaV1, c as InferOutput } from '../../infer-Teo1xpsd.js';
 import { Q as QuickdrawError, a as ErrorCode } from '../../errors-S-bxEIBC.js';
-import { P as PrincipalOfServices, C as ContractOfServices, D as Dispatcher, H as HttpRouter } from '../../http-D3fSFQ57.js';
-import { a as McpContext, b as McpContextOf, M as MaybePromise } from '../../types-Bwg3kIEc.js';
+import { P as PrincipalOfServices, C as ContractOfServices, D as Dispatcher, H as HttpRouter } from '../../http-Djj2Inuu.js';
+import { a as McpContext, b as McpContextOf, M as MaybePromise } from '../../types-Cu0vmx7c.js';
 import { L as Logger } from '../../logger-BY28acW-.js';
-import { A as AuthenticateResult } from '../../auth-CMyRkfjZ.js';
+import { A as AuthenticateResult } from '../../auth-BhWqdyb-.js';
 import { Readable, Writable } from 'node:stream';
-import '../../envelope-nf5eGB-a.js';
-import '../../metrics-C0WvB7-I.js';
+import '../../envelope-Cp3YcVxC.js';
+import '../../metrics-BdBu5o8G.js';
 import 'socket.io';
 
 /** The JSON Schema of a tool's arguments. MCP requires an object schema. */
@@ -134,6 +134,28 @@ interface McpToolCall<S extends readonly AnyService[] = readonly AnyService[], A
     readonly signal: AbortSignal;
     readonly request: McpRequest;
 }
+/** What a function of the registry's `bind` receives: one call of a tool whose method's input has its argument. */
+interface McpBindCall<S extends readonly AnyService[] = readonly AnyService[]> {
+    /**
+     * Who the call acts for, from the registry's `principal`. Never `null`: an
+     * anonymous caller of a tool with a bound argument is refused with
+     * `UNAUTHENTICATED` before any binder runs.
+     */
+    readonly principal: PrincipalOfServices<S>;
+    /** The fields the registry's `context` produced for the call, if any. */
+    readonly mcp: McpContextOfServices<S> | undefined;
+    readonly request: McpRequest;
+    /** The service and method the tool calls, for example `"messageService"` and `"post"`. */
+    readonly service: string;
+    readonly method: string;
+}
+/**
+ * Fills one argument of the registry's `bind` from who is calling, for
+ * example a claim of the principal's token. Returning `undefined` or `null`
+ * refuses the call with `FORBIDDEN`; throwing fails it with `INTERNAL`, or
+ * with the code of a `QuickdrawError`.
+ */
+type McpBinder<S extends readonly AnyService[] = readonly AnyService[]> = (call: McpBindCall<S>) => MaybePromise<unknown>;
 /**
  * Who may call a custom tool: `"authenticated"` callers only, or `"public"`,
  * anonymous callers too. These are the two method access forms that need no
@@ -206,6 +228,21 @@ interface McpRegistryOptions<S extends readonly AnyService[], Tools extends read
      * for example. Runs per call, after `principal`.
      */
     readonly context?: (request: McpRequest, principal: PrincipalOfServices<S> | null) => MaybePromise<McpContextOfServices<S>>;
+    /**
+     * Arguments filled from who is calling instead of by the agent, by name:
+     * `{ taskId: ({ principal }) => principal.claims?.taskId }`. Each one is
+     * left out of the `inputSchema` of every method's tool whose object input
+     * has it, and each call of such a tool, by `call` or `callMethod`, gets the
+     * binder's value before its input is validated. The call is refused
+     * before the method runs when the caller is anonymous (`UNAUTHENTICATED`),
+     * or when the binder returns `undefined` or `null` or the caller sent the
+     * argument with another value (`FORBIDDEN`); a binder that throws fails it
+     * with `INTERNAL`, or with the code of a `QuickdrawError`. Custom tools are
+     * never bound. Binding is not access control: the same principal reaches
+     * the method over a socket or HTTP with nothing bound, so the method's
+     * access must still confine it.
+     */
+    readonly bind?: Readonly<Record<string, McpBinder<S>>>;
     /** The app's own tools, listed after the generated ones. */
     readonly customTools?: {
         readonly [K in keyof Tools]: McpCustomTool<S, Tools[K]>;
@@ -235,7 +272,8 @@ interface McpRegistry {
     /**
      * Calls a method's tool by its service and method name with the method's
      * `input` as it is, without the tool's argument mapping: the shape 4.1's
-     * HTTP route took. A method that is not a tool is `NOT_FOUND`.
+     * HTTP route took. Bound arguments are filled as for `call`. A method that
+     * is not a tool is `NOT_FOUND`.
      */
     callMethod(service: string, method: string, input: unknown, options: McpCallOptions): Promise<McpCallResult>;
 }
@@ -243,8 +281,10 @@ interface McpRegistry {
  * Builds the MCP tools of `services` (see `describeTools`) and the app's
  * `customTools`, served by `dispatcher`. Throws at once when a method's
  * input schema cannot describe itself as JSON Schema (use Zod 4.2 or later
- * for it, or `exclude` the method), when two tools share a name, or when the
- * dispatcher does not serve one of the services.
+ * for it, or `exclude` the method), when two tools share a name, when the
+ * dispatcher does not serve one of the services, or when an argument of
+ * `bind` is in no tool's object input or is in an input that is not an
+ * object.
  *
  * @example
  * const registry = createMcpRegistry({
@@ -366,4 +406,4 @@ type McpHttpReply = {
  */
 declare function createMcpHttpRouter(options: McpHttpRouterOptions): HttpRouter;
 
-export { type DescribeToolsOptions, MCP_PROTOCOL_VERSION, type McpCallOptions, type McpCallResult, type McpContextOfServices, type McpCustomTool, type McpHttpReply, type McpHttpRequest, type McpHttpRouterOptions, type McpInputSchema, type McpMethodRef, type McpRegistry, type McpRegistryOptions, type McpRequest, type McpStdioRequest, type McpStdioServer, type McpStdioServerOptions, type McpTextContent, type McpTool, type McpToolAccess, type McpToolAnnotations, type McpToolArguments, type McpToolCall, type McpToolInputSchema, type McpToolResult, bootstrapMcpServer, createMcpHttpRouter, createMcpRegistry, createMcpStdioServer, describeTools, toToolResult };
+export { type DescribeToolsOptions, MCP_PROTOCOL_VERSION, type McpBindCall, type McpBinder, type McpCallOptions, type McpCallResult, type McpContextOfServices, type McpCustomTool, type McpHttpReply, type McpHttpRequest, type McpHttpRouterOptions, type McpInputSchema, type McpMethodRef, type McpRegistry, type McpRegistryOptions, type McpRequest, type McpStdioRequest, type McpStdioServer, type McpStdioServerOptions, type McpTextContent, type McpTool, type McpToolAccess, type McpToolAnnotations, type McpToolArguments, type McpToolCall, type McpToolInputSchema, type McpToolResult, bootstrapMcpServer, createMcpHttpRouter, createMcpRegistry, createMcpStdioServer, describeTools, toToolResult };

package/dist/server/mcp/index.js

@@ -1,9 +1,12 @@
+import {
+  defaultToolName
+} from "../../chunk-XNLWBZIG.js";
 import {
   NEVER_ABORTED,
   lazyMembers,
   parseInput,
   toQuickdrawError
-} from "../../chunk-2XJFNVHW.js";
+} from "../../chunk-2PWMUVC7.js";
 import {
   describeError
 } from "../../chunk-DD4SKCNO.js";
@@ -122,7 +125,7 @@ function toolNamer(options, fail) {
     fail("name must be a function of (service, method)");
   }
   return (service, method) => {
-    const named = name === void 0 ? `${service}_${method}` : name(service, method);
+    const named = name === void 0 ? defaultToolName(service, method) : name(service, method);
     if (typeof named !== "string" || named === "") {
       const shown = typeof named === "string" ? `""` : String(named);
       fail(`name returned ${shown} for ${service}.${method}; a tool name is a non-empty string`);
@@ -133,7 +136,50 @@ function toolNamer(options, fail) {
 function describeMethod(service, method, kind, text) {
   return typeof text === "string" && text !== "" ? text : `${service}.${method} (${kind})`;
 }
-function planMethodTools(services, options, fail) {
+function propertiesOf(schema) {
+  return isRecord(schema) && isRecord(schema.properties) ? Object.keys(schema.properties) : [];
+}
+function branchProperties(schema, found = /* @__PURE__ */ new Set()) {
+  if (!isRecord(schema)) {
+    return found;
+  }
+  for (const keyword of ["anyOf", "oneOf", "allOf"]) {
+    const branches = schema[keyword];
+    for (const branch of Array.isArray(branches) ? branches : []) {
+      for (const key of propertiesOf(branch)) {
+        found.add(key);
+      }
+      branchProperties(branch, found);
+    }
+  }
+  return found;
+}
+function boundArguments(label, input, bind, fail) {
+  if (input.mode === "object") {
+    const properties = propertiesOf(input.schema);
+    return bind.filter((key) => properties.includes(key));
+  }
+  const wrapped = input.schema.properties?.input;
+  const unbindable = branchProperties(wrapped, new Set(propertiesOf(wrapped)));
+  const misplaced = bind.find((key) => unbindable.has(key));
+  if (misplaced !== void 0) {
+    fail(
+      `bind.${misplaced} names a property of the input of ${label}, which is not an object: bind fills properties of object inputs only; leave ${label} out with exclude, or make its input an object`
+    );
+  }
+  return [];
+}
+function withoutArguments(schema, bound) {
+  const kept = (key) => !bound.includes(key);
+  const { properties = {}, required, ...rest } = schema;
+  const stillRequired = required?.filter(kept) ?? [];
+  return {
+    ...rest,
+    properties: Object.fromEntries(Object.entries(properties).filter(([key]) => kept(key))),
+    ...stillRequired.length === 0 ? {} : { required: stillRequired }
+  };
+}
+function planMethodTools(services, options, fail, bind = []) {
   const given = services;
   if (!Array.isArray(given)) {
     fail("services must be an array of services from qd.defineService");
@@ -148,13 +194,14 @@ function planMethodTools(services, options, fail) {
       }
       const label = `${service.name}.${method}`;
       const input = toolInputOf(label, def.input, fail);
+      const bound = boundArguments(label, input, bind, fail);
       const tool = {
         name: toolName(service.name, method),
         description: describeMethod(service.name, method, def.kind, def.describe),
-        inputSchema: input.schema,
+        inputSchema: bound.length === 0 ? input.schema : withoutArguments(input.schema, bound),
         ...def.kind === "query" ? { annotations: { readOnlyHint: true } } : {}
       };
-      planned.push({ ...input, tool: Object.freeze(tool), service: service.name, method });
+      planned.push({ ...input, tool: Object.freeze(tool), service: service.name, method, bound });
     }
   }
   return planned;
@@ -390,6 +437,31 @@ function checkDispatcher(dispatcher, services, fail) {
     }
   }
 }
+function checkBinders(bind, fail) {
+  if (bind === void 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  if (!isRecord3(bind) || Array.isArray(bind)) {
+    fail("bind must be an object of functions, one per argument it fills");
+  }
+  const binders = /* @__PURE__ */ new Map();
+  for (const [key, binder] of Object.entries(bind)) {
+    if (typeof binder !== "function") {
+      fail(`bind.${key} must be a function of the call, returning the argument's value`);
+    }
+    binders.set(key, binder);
+  }
+  return binders;
+}
+function checkBound(binders, methodTools, fail) {
+  for (const key of binders.keys()) {
+    if (!methodTools.some((tool) => tool.bound.includes(key))) {
+      fail(
+        `bind.${key} fills nothing: no method served as a tool has "${key}" in its object input`
+      );
+    }
+  }
+}
 function resolveRegistry(options) {
   const fail = (message) => {
     throw new TypeError(`createMcpRegistry: ${message}`);
@@ -400,7 +472,9 @@ function resolveRegistry(options) {
   checkDispatcher(options.dispatcher, options.services, fail);
   checkHook("principal", options.principal, fail);
   checkHook("context", options.context, fail);
-  const methodTools = planMethodTools(options.services, options, fail);
+  const binders = checkBinders(options.bind, fail);
+  const methodTools = planMethodTools(options.services, options, fail, [...binders.keys()]);
+  checkBound(binders, methodTools, fail);
   const customTools = checkCustomTools(options.customTools, fail);
   const entries = [
     ...methodTools.map((tool) => ({ kind: "method", ...tool })),
@@ -419,7 +493,8 @@ function resolveRegistry(options) {
     context: options.context,
     logger: options.logger ?? consoleLogger,
     entries: new Map(entries.map((entry2) => [entry2.tool.name, entry2])),
-    methods: new Map(methodTools.map((tool) => [methodKey(tool.service, tool.method), tool]))
+    methods: new Map(methodTools.map((tool) => [methodKey(tool.service, tool.method), tool])),
+    binders
   };
 }
 async function inSession(settings, name, options, run) {
@@ -431,12 +506,58 @@ async function inSession(settings, name, options, run) {
   }
   return run(session);
 }
+async function bindInput(settings, tool, input, session, request) {
+  const { principal } = session;
+  if (principal === null) {
+    throw new QuickdrawError("UNAUTHENTICATED", "Authentication required");
+  }
+  const given = input ?? {};
+  if (!isRecord3(given) || Array.isArray(given)) {
+    throw new QuickdrawError("VALIDATION", `Invalid input for ${tool.service}.${tool.method}`, {
+      issues: [{ path: [], message: "Expected an object" }]
+    });
+  }
+  const call = {
+    principal,
+    mcp: session.mcp,
+    request,
+    service: tool.service,
+    method: tool.method
+  };
+  const filled = [];
+  for (const [key, binder] of settings.binders) {
+    if (!tool.bound.includes(key)) {
+      continue;
+    }
+    const value = await binder(call);
+    if (value === void 0 || value === null) {
+      throw new QuickdrawError("FORBIDDEN", `"${key}" is bound to the caller, who has none`);
+    }
+    const sent = Object.hasOwn(given, key) ? given[key] : void 0;
+    if (sent !== void 0 && JSON.stringify(sent) !== JSON.stringify(value)) {
+      throw new QuickdrawError(
+        "FORBIDDEN",
+        `"${key}" is bound to the caller and cannot be set to another value`
+      );
+    }
+    filled.push([key, value]);
+  }
+  return { ...given, ...Object.fromEntries(filled) };
+}
 async function dispatchMethod(settings, tool, input, session, options) {
+  let bound = input;
+  if (tool.bound.length > 0) {
+    try {
+      bound = await bindInput(settings, tool, input, session, options.request);
+    } catch (error) {
+      return settle(settings, options, failure(settings, error, tool.tool.name));
+    }
+  }
   const { respond } = options;
   const request = sessionRequest(session, {
     service: tool.service,
     method: tool.method,
-    input,
+    input: bound,
     signal: options.signal,
     respond: respond === void 0 ? void 0 : (result) => respond(fromDispatch(result))
   });