@stigmer/mcp-server 3.2.3 → 3.3.0

package/src/domains/records/tools.ts

@@ -0,0 +1,206 @@
+// MCP tools for the Datastore record domain — the five agent-facing
+// record tools of DD-005: 1:1 projections of the record RPCs, with the
+// records-own error mapper (errors.ts) and honest MCP annotations (the
+// bridge's first use of annotations; the platform's own connect-time
+// classifier honors destructiveHint fail-closed for external clients,
+// while the runner-synthesized attachment is approval-free by
+// construction and never passes through that classifier).
+//
+// Two audiences, one definition (registered per roster):
+//   - "agent" (the records-only roster the runner-synthesized
+//     attachment connects to): NO `org` argument — a session-bound
+//     caller's org is server-derived from the session, and an explicit
+//     org is rejected (T05 R3), so offering the argument would only
+//     invite rejected calls.
+//   - "direct" (the main roster external MCP clients see): optional
+//     `org`, which cloud direct principals must name (their credential
+//     carries no ambient org — the DD-006 session-14 amendment). OSS
+//     resolves an empty org to the local system org.
+// `partition` is deliberately NOT a tool argument for either audience
+// (DD-010: never from tool arguments); partition-explicit work is the
+// console/CLI/SDK surface.
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { resolveToken, type BackendTarget } from "../client.js";
+import {
+  deleteRecord,
+  describeDatastore,
+  findRecords,
+  insertRecord,
+  updateRecord,
+  type ConditionArg,
+} from "./calls.js";
+import { recordResult } from "./errors.js";
+
+/** Which roster the tools are being registered on (see file header). */
+export type RecordToolAudience = "agent" | "direct";
+
+const ENCODINGS =
+  "Field value encodings: date YYYY-MM-DD, time HH:MM[:SS], timestamp RFC 3339 UTC " +
+  "(e.g. 2026-07-21T04:30:00Z).";
+
+const scalar = z.union([z.string(), z.number(), z.boolean()]);
+
+const conditionShape = z.object({
+  field: z
+    .string()
+    .describe("Declared field name, or a filterable system field (id, created_at, updated_at)."),
+  op: z
+    .enum(["eq", "neq", "gt", "gte", "lt", "lte", "in", "not_in", "is_null", "not_null"])
+    .describe(
+      "Comparison operator. eq/neq/in/not_in for string and enum fields; " +
+        "gt/gte/lt/lte for numeric and temporal fields; is_null/not_null for optional fields.",
+    ),
+  value: scalar
+    .nullable()
+    .optional()
+    .describe("Comparison value for scalar operators, in the field's canonical encoding."),
+  values: z.array(scalar).optional().describe("Comparison values for in / not_in."),
+});
+
+/** Register the five record tools for one audience; returns the tool names. */
+export function registerRecordTools(
+  server: McpServer,
+  target: BackendTarget,
+  audience: RecordToolAudience,
+): string[] {
+  // The org argument exists only on the direct roster (file header).
+  const orgShape: { org?: z.ZodOptional<z.ZodString> } = {};
+  if (audience === "direct") {
+    orgShape.org = z
+      .string()
+      .optional()
+      .describe(
+        "Organization that owns the datastore. Required on Stigmer Cloud; " +
+          "omit against a local backend.",
+      );
+  }
+
+  server.registerTool(
+    "describe_datastore",
+    {
+      description:
+        "Describe a datastore: its collections, field declarations and encodings, constraint " +
+        "messages, data partitions, and the verbs you are allowed to use per collection " +
+        "(empty access means you are not allowed to touch that collection). Call this before " +
+        `the first record operation against an unfamiliar datastore. ${ENCODINGS}`,
+      inputSchema: {
+        datastore: z.string().describe("Datastore slug (e.g. clinic)."),
+        ...orgShape,
+      },
+      annotations: { readOnlyHint: true },
+    },
+    (args, extra) =>
+      recordResult(`datastore "${args.datastore}"`, () =>
+        describeDatastore(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  server.registerTool(
+    "find_records",
+    {
+      description:
+        "Find records in a datastore collection with a typed filter (conditions are AND-combined). " +
+        "Returns records plus total/limit/offset for paging. Results are ordered by created_at " +
+        `descending unless order_by is given. ${ENCODINGS}`,
+      inputSchema: {
+        datastore: z.string().describe("Datastore slug (e.g. clinic)."),
+        ...orgShape,
+        collection: z.string().describe("Collection to query (e.g. bookings)."),
+        conditions: z
+          .array(conditionShape)
+          .optional()
+          .describe("Filter conditions, AND-combined. Omit to list all readable records."),
+        order_by: z
+          .object({
+            field: z.string().describe("Field to sort by."),
+            direction: z.enum(["asc", "desc"]).optional().describe("Sort direction (default asc)."),
+          })
+          .optional()
+          .describe("Sort order. Omit for created_at descending with id tiebreak."),
+        limit: z.number().int().optional().describe("Page size (default 25, max 100)."),
+        offset: z.number().int().optional().describe("Records to skip for paging."),
+      },
+      annotations: { readOnlyHint: true },
+    },
+    (args, extra) =>
+      recordResult(`records in "${args.datastore}/${args.collection}"`, () =>
+        findRecords(target.serverAddress, resolveToken(extra, target.apiKey), {
+          ...args,
+          conditions: args.conditions as ConditionArg[] | undefined,
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "insert_record",
+    {
+      description:
+        "Insert one record into a datastore collection. System fields (id, created_at, " +
+        "updated_at, created_by) are server-stamped — never include them. Declared constraints " +
+        "are enforced by the store; a violation returns the constraint's message verbatim " +
+        "(e.g. a taken slot returns ALREADY_EXISTS — pick another, do not retry the same one). " +
+        `When uncertain whether a record already exists, find first. ${ENCODINGS}`,
+      inputSchema: {
+        datastore: z.string().describe("Datastore slug (e.g. clinic)."),
+        ...orgShape,
+        collection: z.string().describe("Collection to insert into (e.g. bookings)."),
+        record: z
+          .record(z.unknown())
+          .describe("Declared fields for the new record, in canonical encodings."),
+      },
+    },
+    (args, extra) =>
+      recordResult(`record in "${args.datastore}/${args.collection}"`, () =>
+        insertRecord(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  server.registerTool(
+    "update_record",
+    {
+      description:
+        "Update one record by id with a partial merge: only the supplied fields change, and an " +
+        "explicit null clears a field. Constraints are re-evaluated on the merged result. " +
+        `Returns the full updated record. ${ENCODINGS}`,
+      inputSchema: {
+        datastore: z.string().describe("Datastore slug (e.g. clinic)."),
+        ...orgShape,
+        collection: z.string().describe("Collection holding the record."),
+        id: z.string().describe("Record id (from a previous find or insert)."),
+        fields: z
+          .record(z.unknown())
+          .describe("Fields to merge. Explicit null clears a field; omitted fields keep their values."),
+      },
+      annotations: { idempotentHint: true },
+    },
+    (args, extra) =>
+      recordResult(`record "${args.id}" in "${args.datastore}/${args.collection}"`, () =>
+        updateRecord(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  server.registerTool(
+    "delete_record",
+    {
+      description:
+        "Delete one record by id. Returns the deleted record. Record tools never delete " +
+        "collections or datastores.",
+      inputSchema: {
+        datastore: z.string().describe("Datastore slug (e.g. clinic)."),
+        ...orgShape,
+        collection: z.string().describe("Collection holding the record."),
+        id: z.string().describe("Record id (from a previous find or insert)."),
+      },
+      annotations: { destructiveHint: true, idempotentHint: true },
+    },
+    (args, extra) =>
+      recordResult(`record "${args.id}" in "${args.datastore}/${args.collection}"`, () =>
+        deleteRecord(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  return ["describe_datastore", "find_records", "insert_record", "update_record", "delete_record"];
+}

package/src/gen/agent.ts

@@ -6,7 +6,7 @@
 import { generateSlug, visibilityFromString } from "./apply-runtime.js";
 import { create } from "@bufbuild/protobuf";
 import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
-import { AgentSpecSchema, ToolApprovalOverrideSchema, McpServerUsageSchema, McpAccessSchema, SubAgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { AgentSpecSchema, ToolApprovalOverrideSchema, McpServerUsageSchema, McpAccessSchema, SubAgentSchema, DatastoreUsageSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
@@ -28,6 +28,7 @@ export const AgentInputShape = {
   skill_refs: z.array(z.lazy(() => SkillRefInputSchema)).optional().describe("Skill resources providing additional knowledge to the agent."),
   sub_agents: z.array(z.lazy(() => SubAgentInputSchema)).optional().describe("Sub-agents that can be delegated to. Sub-agents can access a subset of the parent's MCP servers and tools."),
   env: z.record(z.lazy(() => EnvVarDeclarationInputSchema)).optional().describe("Environment variable declarations for this agent. Keys are variable names; values describe their metadata and optionality."),
+  datastore_usages: z.array(z.lazy(() => DatastoreUsageInputSchema)).optional().describe("Datastores this agent can use. Each entry must reference a Datastore resource by slug."),
 } as const;
 
 export const AgentInputSchema = z.object(AgentInputShape);
@@ -83,6 +84,17 @@ const EnvVarDeclarationInputSchema = z.object({
 });
 type EnvVarDeclarationInput = z.infer<typeof EnvVarDeclarationInputSchema>;
 
+const DatastoreRefInputSchema = z.object({
+  org: z.string().optional().describe("Organization that owns the referenced resource. When non-empty: must be a valid org slug (lowercase alphanumeric with hyphens, starts with a letter, 1-63 characters). Example: 'stigmer', 'acme-corp'. When empty: the reference is relative — the server resolves it to the parent resource's organization at write time. All stored and returned references always have org populated (absolute form). Use empty org for same-org references (the common case). Use explicit org for cross-org references (e.g., marketplace resources)."),
+  slug: z.string().describe("Resource slug (user-friendly identifier, unique within org). Format: lowercase alphanumeric with hyphens, must start with a letter and end with a letter or digit (e.g., 'web-search', 'code-reviewer'). Length: 2-63 characters."),
+});
+type DatastoreRefInput = z.infer<typeof DatastoreRefInputSchema>;
+
+const DatastoreUsageInputSchema = z.object({
+  datastore_ref: z.lazy(() => DatastoreRefInputSchema).describe("Reference to the Datastore resource."),
+});
+type DatastoreUsageInput = z.infer<typeof DatastoreUsageInputSchema>;
+
 
 /** Build the fully-formed Agent proto from the flat MCP apply input. */
 export function agentInputToProto(input: AgentInput): Agent {
@@ -97,6 +109,7 @@ export function agentInputToProto(input: AgentInput): Agent {
   if (input.env !== undefined) {
     for (const [k, v] of Object.entries(input.env)) spec.env[k] = envVarDeclarationInputToProto(v);
   }
+  if (input.datastore_usages !== undefined) spec.datastoreUsages = input.datastore_usages.map(datastoreUsageInputToProto);
   return Object.assign(create(AgentSchema), {
     apiVersion: "agentic.stigmer.ai/v1",
     kind: "Agent",
@@ -171,3 +184,17 @@ function envVarDeclarationInputToProto(input: EnvVarDeclarationInput) {
   return result;
 }
 
+function datastoreRefInputToProto(input: DatastoreRefInput) {
+  return create(ApiResourceReferenceSchema, {
+    org: input.org,
+    slug: input.slug,
+    kind: ApiResourceKind.datastore,
+  });
+}
+
+function datastoreUsageInputToProto(input: DatastoreUsageInput) {
+  const result = create(DatastoreUsageSchema);
+  if (input.datastore_ref !== undefined) result.datastoreRef = datastoreRefInputToProto(input.datastore_ref);
+  return result;
+}
+

package/src/http.integration.test.ts

@@ -36,6 +36,7 @@ beforeAll(async () => {
     stigmerServerAddress: "localhost:7234",
     apiKey: "",
     transport: "http",
+    roster: "full",
     httpPort: String(port),
     httpAuthEnabled: true,
     oauth: {

package/src/index.ts

@@ -6,12 +6,19 @@
 
 import { loadConfigFromEnv, validateConfig, type Config } from "./config.js";
 import { configureLogger, log } from "./logger.js";
-import { createServer, serveBoth, serveHttp, serveStdio, isNormalShutdown } from "./server.js";
+import {
+  isNormalShutdown,
+  routedServerFactory,
+  serveBoth,
+  serveHttp,
+  serveStdio,
+  stdioServer,
+} from "./server.js";
 import type { BackendTarget } from "./domains/client.js";
 
-export type { Config, OAuthConfig, Transport } from "./config.js";
+export type { Config, OAuthConfig, Roster, Transport } from "./config.js";
 export { loadConfigFromEnv, validateConfig } from "./config.js";
-export { createServer, SERVER_VERSION } from "./server.js";
+export { createServer, createRecordsServer, RECORDS_ROUTE, SERVER_VERSION } from "./server.js";
 
 /** Returns a Config populated from environment variables (no validation). */
 export function defaultConfig(): Config {
@@ -44,10 +51,10 @@ export async function run(cfg: Config, signal: AbortSignal): Promise<void> {
   try {
     switch (cfg.transport) {
       case "stdio":
-        await serveStdio(createServer(target), signal);
+        await serveStdio(stdioServer(target, cfg), signal);
         break;
       case "http":
-        await serveHttp(() => createServer(target), cfg, signal);
+        await serveHttp(routedServerFactory(target), cfg, signal);
         break;
       case "both":
         await serveBoth(target, cfg, signal);

package/src/server.ts

@@ -24,6 +24,7 @@ import { registerAgentTools } from "./domains/agents/tools.js";
 import type { BackendTarget } from "./domains/client.js";
 import { registerMcpServerResources } from "./domains/mcpservers/resources.js";
 import { registerMcpServerTools } from "./domains/mcpservers/tools.js";
+import { registerRecordTools } from "./domains/records/tools.js";
 import { registerSearchTools } from "./domains/search/tools.js";
 import { registerSkillResources } from "./domains/skills/resources.js";
 import { registerSkillTools } from "./domains/skills/tools.js";
@@ -60,6 +61,22 @@ export function createServer(target: BackendTarget): McpServer {
   return server;
 }
 
+/**
+ * Build a records-only MCP server: the five record tools with the
+ * agent-facing argument surface, and nothing else (T05 R1). This is
+ * the roster the runner-synthesized datastore attachment connects to —
+ * a structural guarantee that an agent session never sees the
+ * management tools (apply/delete/…) its empty approval maps would make
+ * approval-free. Served on the /records HTTP route and as the stdio
+ * roster when STIGMER_MCP_ROSTER=records.
+ */
+export function createRecordsServer(target: BackendTarget): McpServer {
+  const server = new McpServer({ name: "mcp-server-stigmer-records", version: SERVER_VERSION });
+  const tools = registerRecordTools(server, target, "agent");
+  log.info("tools registered (records roster)", { count: tools.length, tools });
+  return server;
+}
+
 /**
  * Wire up every domain's tools. Each domain returns the names it registered so
  * the startup log's count and roster cannot drift from what is actually wired,
@@ -75,6 +92,10 @@ function registerTools(server: McpServer, target: BackendTarget): void {
     ...registerValidateWorkflowYamlTool(server, target),
     ...registerTaskKindTools(server, target),
     ...registerWorkflowExecutionTools(server, target),
+    // The record tools also serve external MCP clients — as direct
+    // principals with the org argument and honest annotations (the
+    // agent-facing variant lives on the records-only roster).
+    ...registerRecordTools(server, target, "direct"),
   ];
   log.info("tools registered", { count: tools.length, tools });
 }
@@ -123,6 +144,25 @@ export async function serveStdio(server: McpServer, signal: AbortSignal): Promis
 /** Builds a fresh, fully-registered server. One is created per MCP session. */
 export type ServerFactory = () => McpServer;
 
+/**
+ * Builds the server for an inbound HTTP `initialize` request, selected
+ * by request path. Only the initialize request consults the path — an
+ * established session's transport already carries the server it was
+ * built with, so follow-up requests dispatch by Mcp-Session-Id alone.
+ */
+export type RouteServerFactory = (path: string) => McpServer;
+
+/** HTTP route serving the records-only roster (T05 R1). */
+export const RECORDS_ROUTE = "/records";
+
+/**
+ * The standard HTTP route dispatch: the records-only roster on
+ * {@link RECORDS_ROUTE}, the full roster everywhere else.
+ */
+export function routedServerFactory(target: BackendTarget): RouteServerFactory {
+  return (path) => (path === RECORDS_ROUTE ? createRecordsServer(target) : createServer(target));
+}
+
 /**
  * Serve over Streamable HTTP until `signal` aborts.
  *
@@ -144,7 +184,11 @@ export type ServerFactory = () => McpServer;
  * DNS-rebinding allow-lists are intentionally out of parity scope (the Go server
  * has none).
  */
-export async function serveHttp(makeServer: ServerFactory, cfg: Config, signal: AbortSignal): Promise<void> {
+export async function serveHttp(
+  makeServer: RouteServerFactory,
+  cfg: Config,
+  signal: AbortSignal,
+): Promise<void> {
   const sessions = new Map<string, StreamableHTTPServerTransport>();
 
   const httpServer = createHttpServer((req, res) => {
@@ -189,8 +233,8 @@ export async function serveBoth(target: BackendTarget, cfg: Config, signal: Abor
   signal.addEventListener("abort", onParentAbort, { once: true });
 
   const tasks = [
-    serveStdio(createServer(target), linked.signal),
-    serveHttp(() => createServer(target), cfg, linked.signal),
+    serveStdio(stdioServer(target, cfg), linked.signal),
+    serveHttp(routedServerFactory(target), cfg, linked.signal),
   ];
 
   try {
@@ -215,7 +259,7 @@ async function routeRequest(
   req: IncomingMessage & { auth?: AuthInfo },
   res: ServerResponse,
   sessions: Map<string, StreamableHTTPServerTransport>,
-  makeServer: ServerFactory,
+  makeServer: RouteServerFactory,
   cfg: Config,
 ): Promise<void> {
   if (req.method === "GET" && req.url === "/health") {
@@ -247,6 +291,7 @@ async function routeRequest(
     req.auth = { token, clientId: "stigmer-mcp-passthrough", scopes: [] };
   }
 
+  const path = requestPath(req);
   const sessionId = headerValue(req, "mcp-session-id");
 
   // Established session → dispatch to its transport.
@@ -288,10 +333,19 @@ async function routeRequest(
     if (transport.sessionId !== undefined) sessions.delete(transport.sessionId);
   };
 
-  await makeServer().connect(transport);
+  await makeServer(path).connect(transport);
   await transport.handleRequest(req, res, body);
 }
 
+/**
+ * The stdio server for the configured roster: the records-only roster
+ * when STIGMER_MCP_ROSTER=records (what the OSS runner-synthesized
+ * datastore attachment spawns), the full roster otherwise.
+ */
+export function stdioServer(target: BackendTarget, cfg: Config): McpServer {
+  return cfg.roster === "records" ? createRecordsServer(target) : createServer(target);
+}
+
 /** Return a single header value, collapsing the array form Node may produce. */
 function headerValue(req: IncomingMessage, name: string): string | undefined {
   const v = req.headers[name];