@stigmer/mcp-server 3.11.0 → 3.12.0

package/src/domains/records/calls.ts

@@ -1,209 +0,0 @@
-// Record-RPC invocations for the five record tools — 1:1 projections
-// of DatastoreRecordQueryController / DatastoreRecordCommandController
-// (DD-005: the tool layer adds no semantics; validation, grants,
-// scopes, constraints, and messages all live in record-RPC domain
-// logic on the control plane).
-//
-// One file for the five thin calls rather than the resource domains'
-// file-per-verb split: resource verbs each carry orchestration
-// (reference resolution, YAML parsing, two-step deletes); record calls
-// are each "build request, call, marshal" and the shared argument
-// mapping (filter/value building) is the only substance.
-
-import { create, fromJson, type JsonObject } from "@bufbuild/protobuf";
-import { ValueSchema, type Value } from "@bufbuild/protobuf/wkt";
-import {
-  DatastoreRecordCommandController,
-} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_command_pb";
-import {
-  DatastoreRecordQueryController,
-} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_query_pb";
-import {
-  DatastoreDescriptionSchema,
-  DeleteRecordRequestSchema,
-  DescribeDatastoreRequestSchema,
-  FindRecordsRequestSchema,
-  InsertRecordRequestSchema,
-  RecordConditionOp,
-  RecordConditionSchema,
-  RecordEnvelopeSchema,
-  RecordFilterSchema,
-  RecordListSchema,
-  RecordOrderBySchema,
-  RecordSortDirection,
-  UpdateRecordRequestSchema,
-  type RecordCondition,
-  type RecordFilter,
-  type RecordOrderBy,
-} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
-import { withClient } from "../client.js";
-import { toProtoJson } from "../marshal.js";
-
-/**
- * A filter condition as the model supplies it. `op` uses the natural
- * spelling "in" (the proto enum's `is_in` exists only because `in` is
- * reserved in Java/Python — a substrate detail the model never sees).
- */
-export interface ConditionArg {
-  field: string;
-  op: string;
-  value?: string | number | boolean | null;
-  values?: (string | number | boolean)[];
-}
-
-export interface FindArgs {
-  datastore: string;
-  org?: string;
-  collection: string;
-  conditions?: ConditionArg[];
-  order_by?: { field: string; direction?: string };
-  limit?: number;
-  offset?: number;
-}
-
-/** Model-facing operator spelling → proto enum. */
-const CONDITION_OPS: Readonly<Record<string, RecordConditionOp>> = {
-  eq: RecordConditionOp.eq,
-  neq: RecordConditionOp.neq,
-  gt: RecordConditionOp.gt,
-  gte: RecordConditionOp.gte,
-  lt: RecordConditionOp.lt,
-  lte: RecordConditionOp.lte,
-  in: RecordConditionOp.is_in,
-  not_in: RecordConditionOp.not_in,
-  is_null: RecordConditionOp.is_null,
-  not_null: RecordConditionOp.not_null,
-};
-
-export async function findRecords(
-  serverAddress: string,
-  token: string,
-  args: FindArgs,
-): Promise<string> {
-  const request = create(FindRecordsRequestSchema, {
-    datastore: args.datastore,
-    org: args.org ?? "",
-    collection: args.collection,
-    filter: buildFilter(args.conditions),
-    orderBy: buildOrderBy(args.order_by),
-    limit: args.limit ?? 0,
-    offset: args.offset ?? 0,
-  });
-  return withClient(DatastoreRecordQueryController, serverAddress, token, async (client, opts) =>
-    toProtoJson(RecordListSchema, await client.findRecords(request, opts)),
-  );
-}
-
-export async function insertRecord(
-  serverAddress: string,
-  token: string,
-  args: { datastore: string; org?: string; collection: string; record: Record<string, unknown> },
-): Promise<string> {
-  const request = create(InsertRecordRequestSchema, {
-    datastore: args.datastore,
-    org: args.org ?? "",
-    collection: args.collection,
-    // google.protobuf.Struct fields are plain JSON objects in
-    // protobuf-es v2 — no conversion.
-    record: args.record as JsonObject,
-  });
-  return withClient(DatastoreRecordCommandController, serverAddress, token, async (client, opts) =>
-    toProtoJson(RecordEnvelopeSchema, await client.insertRecord(request, opts)),
-  );
-}
-
-export async function updateRecord(
-  serverAddress: string,
-  token: string,
-  args: {
-    datastore: string;
-    org?: string;
-    collection: string;
-    id: string;
-    fields: Record<string, unknown>;
-  },
-): Promise<string> {
-  const request = create(UpdateRecordRequestSchema, {
-    datastore: args.datastore,
-    org: args.org ?? "",
-    collection: args.collection,
-    id: args.id,
-    fields: args.fields as JsonObject,
-  });
-  return withClient(DatastoreRecordCommandController, serverAddress, token, async (client, opts) =>
-    toProtoJson(RecordEnvelopeSchema, await client.updateRecord(request, opts)),
-  );
-}
-
-export async function deleteRecord(
-  serverAddress: string,
-  token: string,
-  args: { datastore: string; org?: string; collection: string; id: string },
-): Promise<string> {
-  const request = create(DeleteRecordRequestSchema, {
-    datastore: args.datastore,
-    org: args.org ?? "",
-    collection: args.collection,
-    id: args.id,
-  });
-  return withClient(DatastoreRecordCommandController, serverAddress, token, async (client, opts) =>
-    toProtoJson(RecordEnvelopeSchema, await client.deleteRecord(request, opts)),
-  );
-}
-
-export async function describeDatastore(
-  serverAddress: string,
-  token: string,
-  args: { datastore: string; org?: string },
-): Promise<string> {
-  const request = create(DescribeDatastoreRequestSchema, {
-    datastore: args.datastore,
-    org: args.org ?? "",
-  });
-  return withClient(DatastoreRecordQueryController, serverAddress, token, async (client, opts) =>
-    toProtoJson(DatastoreDescriptionSchema, await client.describeDatastore(request, opts)),
-  );
-}
-
-/**
- * Build the typed AND-only filter (DD-005 SD-2). An unknown operator is
- * left unspecified for the server to reject with its own domain
- * message — the bridge never fabricates validation of its own.
- */
-function buildFilter(conditions: ConditionArg[] | undefined): RecordFilter | undefined {
-  if (conditions === undefined || conditions.length === 0) {
-    return undefined;
-  }
-  return create(RecordFilterSchema, {
-    conditions: conditions.map(buildCondition),
-  });
-}
-
-function buildCondition(arg: ConditionArg): RecordCondition {
-  return create(RecordConditionSchema, {
-    field: arg.field,
-    op: CONDITION_OPS[arg.op] ?? RecordConditionOp.record_condition_op_unspecified,
-    value: arg.value !== undefined ? scalarValue(arg.value) : undefined,
-    values: (arg.values ?? []).map(scalarValue),
-  });
-}
-
-function buildOrderBy(
-  orderBy: { field: string; direction?: string } | undefined,
-): RecordOrderBy | undefined {
-  if (orderBy === undefined) {
-    return undefined;
-  }
-  return create(RecordOrderBySchema, {
-    field: orderBy.field,
-    direction: orderBy.direction === "desc"
-      ? RecordSortDirection.desc
-      : orderBy.direction === "asc"
-        ? RecordSortDirection.asc
-        : RecordSortDirection.record_sort_direction_unspecified,
-  });
-}
-
-function scalarValue(v: string | number | boolean | null): Value {
-  return fromJson(ValueSchema, v);
-}

package/src/domains/records/errors.ts

@@ -1,98 +0,0 @@
-// The records-domain error mapper (DD-005 SD-6) — a deliberate,
-// documented divergence from the shared ../rpcerr.ts.
-//
-// Record-RPC domain errors carry agent-relayable messages that are
-// cross-edition contract bytes (DD-002 SD-5): "that slot is already
-// booked", "you are not allowed to insert records in bookings". The
-// shared helper would rewrite them ("Check your API key permissions")
-// and discards google.rpc.ErrorInfo. Here the domain codes pass the
-// server's message through VERBATIM as isError JSON text
-// `{error, code, reason, constraint}` — reason/constraint extracted
-// from ErrorInfo — so the model can self-correct (retry another slot
-// on CONSTRAINT_VIOLATION; stop and relay on PERMISSION_DENIED).
-// Transport codes still delegate to the shared helper, whose advice is
-// right for them.
-
-import { Code, ConnectError } from "@connectrpc/connect";
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { ErrorInfoSchema } from "@stigmer/protos/google/rpc/error_details_pb";
-import { rpcError } from "../rpcerr.js";
-import { errorResult, textResult } from "../toolresult.js";
-
-/**
- * The gRPC codes whose messages are the record-RPC domain contract
- * (DD-005 SD-6): declared constraint messages, fixed denial texts, and
- * domain validation — all written to be relayed to end users verbatim.
- */
-const DOMAIN_CODES: ReadonlySet<Code> = new Set([
-  Code.PermissionDenied,
-  Code.AlreadyExists,
-  Code.FailedPrecondition,
-  Code.InvalidArgument,
-  Code.NotFound,
-]);
-
-/** The structured error payload record tools return for domain errors. */
-export interface RecordToolError {
-  /** The server's relayable message, byte-for-byte. */
-  error: string;
-  /** gRPC status name in SCREAMING_SNAKE (e.g. ALREADY_EXISTS). */
-  code: string;
-  /** ErrorInfo reason (e.g. CONSTRAINT_VIOLATION), when present. */
-  reason?: string;
-  /** Violated constraint name from ErrorInfo metadata, when present. */
-  constraint?: string;
-}
-
-/**
- * Run a record-tool body: a string payload becomes a text result; a
- * domain error becomes an isError JSON result carrying the verbatim
- * message + ErrorInfo companions; a transport error delegates to the
- * shared classifier. The records analog of ../toolresult.ts
- * textOrError, and the only try/catch in this domain.
- */
-export async function recordResult(
-  toolContext: string,
-  produce: () => Promise<string>,
-): Promise<CallToolResult> {
-  try {
-    return textResult(await produce());
-  } catch (err) {
-    const ce = ConnectError.from(err);
-    if (DOMAIN_CODES.has(ce.code)) {
-      return {
-        content: [{ type: "text", text: JSON.stringify(domainError(ce)) }],
-        isError: true,
-      };
-    }
-    return errorResult(rpcError(ce, toolContext));
-  }
-}
-
-/** Project a domain ConnectError into the structured tool payload. */
-export function domainError(ce: ConnectError): RecordToolError {
-  const payload: RecordToolError = {
-    error: ce.rawMessage,
-    code: grpcStatusName(ce.code),
-  };
-  // The record RPCs attach one google.rpc.ErrorInfo per domain error
-  // (domain datastore.stigmer.ai); absence means an older server — the
-  // message alone still carries the contract.
-  const details = ce.findDetails(ErrorInfoSchema);
-  if (details.length > 0) {
-    const info = details[0];
-    if (info.reason !== "") {
-      payload.reason = info.reason;
-    }
-    const constraint = info.metadata["constraint"];
-    if (constraint !== undefined && constraint !== "") {
-      payload.constraint = constraint;
-    }
-  }
-  return payload;
-}
-
-/** Connect's PascalCase code name → the gRPC SCREAMING_SNAKE status name. */
-function grpcStatusName(code: Code): string {
-  return Code[code].replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
-}

package/src/domains/records/records.integration.test.ts

@@ -1,313 +0,0 @@
-// In-process integration test for the record tools (search-pattern:
-// real Connect backend with stubbed record services, real MCP client
-// over an in-memory transport).
-//
-// Verifies the T05 contract surface:
-//   - the records-only roster is exactly the five tools (T05 R1), with
-//     honest annotations surfaced through tools/list (pinning the SDK's
-//     annotations support) and NO org argument (agent audience);
-//   - the main roster carries the same five tools WITH the org argument
-//     (direct audience);
-//   - argument → request mapping (typed filter, "in" → is_in, paging);
-//   - the records-own error mapper: domain errors pass the server's
-//     message verbatim as {error, code, reason, constraint} JSON with
-//     ErrorInfo companions; transport errors delegate to the shared
-//     classifier (DD-005 SD-6).
-
-import { create } from "@bufbuild/protobuf";
-import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
-import { connectNodeAdapter } from "@connectrpc/connect-node";
-import {
-  createServer as createHttp2Server,
-  type Http2Server,
-  type ServerHttp2Session,
-} from "node:http2";
-import type { AddressInfo } from "node:net";
-
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import { DatastoreRecordCommandController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_command_pb";
-import {
-  DatastoreDescriptionSchema,
-  RecordEnvelopeSchema,
-  RecordListSchema,
-  type FindRecordsRequest,
-  type InsertRecordRequest,
-} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
-import { DatastoreRecordQueryController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_query_pb";
-import { ErrorInfoSchema } from "@stigmer/protos/google/rpc/error_details_pb";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-
-import { configureLogger } from "../../logger";
-import { createRecordsServer, createServer } from "../../server";
-
-configureLogger({ level: "error", format: "text" });
-
-const RECORD_TOOLS = [
-  "describe_datastore",
-  "find_records",
-  "insert_record",
-  "update_record",
-  "delete_record",
-];
-
-let backend: Http2Server;
-let client: Client;
-const openSessions = new Set<ServerHttp2Session>();
-
-/** The next stubbed outcome per RPC; tests set these. */
-let findResponse: () => ReturnType<typeof create<typeof RecordListSchema>>;
-let insertOutcome: () => ReturnType<typeof create<typeof RecordEnvelopeSchema>>;
-
-/**
- * Requests the stubs captured. An object (not two `let`s) because TS
- * does not reset let-narrowing across awaited calls for closure
- * assignments — property narrowing it does.
- */
-const captured: {
-  find?: FindRecordsRequest;
-  insert?: InsertRecordRequest;
-} = {};
-
-interface ToolResult {
-  content: Array<{ type: string; text?: string }>;
-  isError?: boolean;
-}
-
-async function callTool(name: string, args: Record<string, unknown>): Promise<ToolResult> {
-  return (await client.callTool({ name, arguments: args })) as ToolResult;
-}
-
-beforeAll(async () => {
-  const routes = (router: ConnectRouter) => {
-    router.service(DatastoreRecordQueryController, {
-      findRecords: (req) => {
-        captured.find = req;
-        return findResponse();
-      },
-      describeDatastore: () =>
-        create(DatastoreDescriptionSchema, {
-          datastore: "clinic",
-          timezone: "Asia/Kolkata",
-          partitions: ["default"],
-        }),
-    });
-    router.service(DatastoreRecordCommandController, {
-      insertRecord: (req) => {
-        captured.insert = req;
-        return insertOutcome();
-      },
-      updateRecord: () => create(RecordEnvelopeSchema, { id: "dsr_updated" }),
-      deleteRecord: () => create(RecordEnvelopeSchema, { id: "dsr_deleted" }),
-    });
-  };
-  backend = createHttp2Server(connectNodeAdapter({ routes }));
-  backend.on("session", (session) => {
-    openSessions.add(session);
-    session.on("close", () => openSessions.delete(session));
-  });
-  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
-  const port = (backend.address() as AddressInfo).port;
-
-  // The records-only roster is the surface under test — the audience
-  // the runner-synthesized attachment serves.
-  const mcp = createRecordsServer({ serverAddress: `127.0.0.1:${port}`, apiKey: "" });
-  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-  client = new Client({ name: "records-integration", version: "test" });
-  await Promise.all([mcp.connect(serverTransport), client.connect(clientTransport)]);
-});
-
-afterAll(async () => {
-  await client?.close();
-  for (const session of openSessions) session.destroy();
-  await new Promise<void>((resolve) => backend.close(() => resolve()));
-});
-
-describe("records roster (T05 R1)", () => {
-  it("exposes exactly the five record tools with honest annotations and no org argument", async () => {
-    const { tools } = await client.listTools();
-    expect(tools.map((t) => t.name).sort()).toEqual([...RECORD_TOOLS].sort());
-
-    const byName = new Map(tools.map((t) => [t.name, t]));
-    // Annotations are part of the DD-005 contract for external clients
-    // and the classifier; this pins the SDK actually surfacing them.
-    expect(byName.get("find_records")?.annotations).toMatchObject({ readOnlyHint: true });
-    expect(byName.get("describe_datastore")?.annotations).toMatchObject({ readOnlyHint: true });
-    expect(byName.get("update_record")?.annotations).toMatchObject({ idempotentHint: true });
-    expect(byName.get("delete_record")?.annotations).toMatchObject({
-      destructiveHint: true,
-      idempotentHint: true,
-    });
-
-    // The agent audience gets no org argument — a session-bound
-    // caller's org is server-derived, and offering the argument would
-    // only invite INVALID_ARGUMENT rejections (T05 R3).
-    for (const tool of tools) {
-      const properties = (tool.inputSchema as { properties?: Record<string, unknown> }).properties;
-      expect(Object.keys(properties ?? {}), tool.name).not.toContain("org");
-    }
-  });
-
-  it("the main roster carries the five tools WITH the org argument", async () => {
-    // Direct principals (external MCP clients) must be able to name the
-    // org their credential does not carry (DD-006 session-14 amendment).
-    const full = createServer({ serverAddress: "127.0.0.1:1", apiKey: "" });
-    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-    const fullClient = new Client({ name: "records-full-roster", version: "test" });
-    await Promise.all([full.connect(serverTransport), fullClient.connect(clientTransport)]);
-    try {
-      const { tools } = await fullClient.listTools();
-      const names = tools.map((t) => t.name);
-      for (const name of RECORD_TOOLS) {
-        expect(names).toContain(name);
-      }
-      const find = tools.find((t) => t.name === "find_records");
-      const properties = (find?.inputSchema as { properties?: Record<string, unknown> })
-        .properties;
-      expect(Object.keys(properties ?? {})).toContain("org");
-    } finally {
-      await fullClient.close();
-    }
-  });
-});
-
-describe("argument → request mapping", () => {
-  it("builds the typed filter (in → is_in), order_by, and paging", async () => {
-    findResponse = () =>
-      create(RecordListSchema, {
-        records: [create(RecordEnvelopeSchema, { id: "dsr_1" })],
-        total: 1,
-        limit: 25,
-      });
-    captured.find = undefined;
-
-    const result = await callTool("find_records", {
-      datastore: "clinic",
-      collection: "bookings",
-      conditions: [
-        { field: "status", op: "eq", value: "confirmed" },
-        { field: "patient_name", op: "in", values: ["Asha", "Ravi"] },
-      ],
-      order_by: { field: "slot_start", direction: "desc" },
-      limit: 10,
-      offset: 20,
-    });
-
-    expect(result.isError).toBeFalsy();
-    // Assertion, not annotation: control-flow analysis otherwise pins the
-    // const to the `= undefined` reset above (the stub assigns in a
-    // closure the analysis cannot see across the await).
-    const req = captured.find as FindRecordsRequest | undefined;
-    expect(req?.datastore).toBe("clinic");
-    expect(req?.org).toBe(""); // agent audience: org never travels
-    expect(req?.partition).toBe(""); // partition is never a tool argument (DD-010)
-    expect(req?.filter?.conditions).toHaveLength(2);
-    expect(req?.filter?.conditions[0]).toMatchObject({ field: "status", op: 1 /* eq */ });
-    expect(req?.filter?.conditions[1]).toMatchObject({ field: "patient_name", op: 7 /* is_in */ });
-    expect(req?.filter?.conditions[1]?.values).toHaveLength(2);
-    expect(req?.orderBy).toMatchObject({ field: "slot_start", direction: 2 /* desc */ });
-    expect(req?.limit).toBe(10);
-    expect(req?.offset).toBe(20);
-
-    const body = JSON.parse(result.content[0]?.text ?? "{}") as { total?: number };
-    expect(body.total).toBe(1);
-  });
-
-  it("passes the record payload through as a Struct, untouched", async () => {
-    insertOutcome = () => create(RecordEnvelopeSchema, { id: "dsr_new" });
-    captured.insert = undefined;
-
-    const result = await callTool("insert_record", {
-      datastore: "clinic",
-      collection: "bookings",
-      record: { slot_start: "2026-07-21T04:30:00Z", patient_name: "Asha" },
-    });
-
-    expect(result.isError).toBeFalsy();
-    const req = captured.insert as InsertRecordRequest | undefined;
-    expect(req?.record).toMatchObject({
-      slot_start: "2026-07-21T04:30:00Z",
-      patient_name: "Asha",
-    });
-  });
-});
-
-describe("records error mapper (DD-005 SD-6)", () => {
-  it("passes a constraint violation through verbatim with ErrorInfo companions", async () => {
-    insertOutcome = () => {
-      throw new ConnectError("that slot is already booked", Code.AlreadyExists, undefined, [
-        {
-          desc: ErrorInfoSchema,
-          value: create(ErrorInfoSchema, {
-            reason: "CONSTRAINT_VIOLATION",
-            domain: "datastore.stigmer.ai",
-            metadata: { constraint: "one_confirmed_per_slot" },
-          }),
-        },
-      ]);
-    };
-
-    const result = await callTool("insert_record", {
-      datastore: "clinic",
-      collection: "bookings",
-      record: { slot_start: "2026-07-21T04:30:00Z", patient_name: "Ravi" },
-    });
-
-    expect(result.isError).toBe(true);
-    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual({
-      error: "that slot is already booked",
-      code: "ALREADY_EXISTS",
-      reason: "CONSTRAINT_VIOLATION",
-      constraint: "one_confirmed_per_slot",
-    });
-  });
-
-  it("passes a permission denial through verbatim — never the shared rewrite", async () => {
-    insertOutcome = () => {
-      throw new ConnectError(
-        "you are not allowed to insert records in schedule_exceptions",
-        Code.PermissionDenied,
-        undefined,
-        [
-          {
-            desc: ErrorInfoSchema,
-            value: create(ErrorInfoSchema, {
-              reason: "VERB_DENIED",
-              domain: "datastore.stigmer.ai",
-            }),
-          },
-        ],
-      );
-    };
-
-    const result = await callTool("insert_record", {
-      datastore: "clinic",
-      collection: "schedule_exceptions",
-      record: { exception_date: "2026-07-22" },
-    });
-
-    expect(result.isError).toBe(true);
-    const body = JSON.parse(result.content[0]?.text ?? "{}") as Record<string, string>;
-    // The relayable domain bytes — NOT "Check your API key permissions".
-    expect(body.error).toBe("you are not allowed to insert records in schedule_exceptions");
-    expect(body.code).toBe("PERMISSION_DENIED");
-    expect(body.reason).toBe("VERB_DENIED");
-    expect(body.constraint).toBeUndefined();
-  });
-
-  it("delegates transport codes to the shared classifier", async () => {
-    findResponse = () => {
-      throw new ConnectError("upstream down", Code.Unavailable);
-    };
-
-    const result = await callTool("find_records", {
-      datastore: "clinic",
-      collection: "bookings",
-    });
-
-    expect(result.isError).toBe(true);
-    expect(result.content[0]?.text).toBe(
-      "Stigmer server is unavailable. Ensure it is running and reachable.",
-    );
-  });
-});