@stigmer/mcp-server 3.3.0 → 3.4.0

package/src/domains/search/tools.ts

@@ -24,12 +24,15 @@ import { rpcError } from "../rpcerr.js";
 import { textOrError } from "../toolresult.js";
 
 /**
- * The searchable kinds and their proto enum values. This is deliberately the
- * four searchable kinds (not every ApiResourceKind), mirroring the Go server's
- * `knownKinds` map and its validation surface.
+ * The searchable kinds and their proto enum values. Deliberately a curated
+ * subset (not every ApiResourceKind): the kinds an MCP client can also read
+ * and manage through tools. The backend's extractor registry supports more
+ * (sessions, executions, ...) — add here only alongside a tool surface.
  */
 const knownKinds: Readonly<Record<string, ApiResourceKind>> = {
   agent: ApiResourceKind.agent,
+  datastore: ApiResourceKind.datastore,
+  environment: ApiResourceKind.environment,
   skill: ApiResourceKind.skill,
   mcp_server: ApiResourceKind.mcp_server,
   workflow: ApiResourceKind.workflow,
@@ -50,14 +53,16 @@ export function registerSearchTools(server: McpServer, target: BackendTarget): s
     "search",
     {
       description:
-        "Search and list Stigmer resources (agents, skills, MCP servers, workflows). " +
-        "Set 'kinds' to filter by resource type. Set 'query' for full-text search. " +
+        "Search and list Stigmer resources (agents, skills, MCP servers, workflows, environments, " +
+        "datastores). Set 'kinds' to filter by resource type. Set 'query' for full-text search. " +
         "Set 'org' to scope to an organization. Omit 'query' to list all accessible resources.",
       inputSchema: {
         kinds: z
           .array(z.string())
           .optional()
-          .describe("Resource kinds to search. Valid: agent, skill, mcp_server, workflow. Empty searches all."),
+          .describe(
+            "Resource kinds to search. Valid: agent, skill, mcp_server, workflow, environment, datastore. Empty searches all.",
+          ),
         query: z
           .string()
           .optional()
@@ -125,7 +130,7 @@ function parseKinds(raw: string[] | undefined): ApiResourceKind[] {
     const kind = knownKinds[s];
     if (kind === undefined) {
       throw new Error(
-        `unknown resource kind "${s}"; valid kinds: agent, skill, mcp_server, workflow`,
+        `unknown resource kind "${s}"; valid kinds: agent, skill, mcp_server, workflow, environment, datastore`,
       );
     }
     return kind;

package/src/domains/skills/tools.ts

@@ -12,6 +12,7 @@ import { resolveToken, type BackendTarget } from "../client.js";
 import { textOrError } from "../toolresult.js";
 import { deleteSkill } from "./delete.js";
 import { fetchSkill } from "./fetch.js";
+import { listSkillVersions } from "./versions.js";
 
 /** Register every Skill-domain tool; returns the registered tool names. */
 export function registerSkillTools(server: McpServer, target: BackendTarget): string[] {
@@ -63,5 +64,37 @@ export function registerSkillTools(server: McpServer, target: BackendTarget): st
       ),
   );
 
-  return ["get_skill", "delete_skill"];
+  server.registerTool(
+    "list_skill_versions",
+    {
+      description:
+        "List a skill's version history (newest first): version hash, tag, who pushed it and " +
+        "when, and which version is current. Fetch one version's full content with get_skill and " +
+        "its hash or tag.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the skill."),
+        slug: z.string().describe("Skill slug — unique identifier within the org."),
+        page_size: z
+          .number()
+          .int()
+          .optional()
+          .describe("Maximum versions per page (default 50)."),
+        page_token: z
+          .string()
+          .optional()
+          .describe("Pagination token from a previous response's next_page_token."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        listSkillVersions(target.serverAddress, resolveToken(extra, target.apiKey), {
+          org: args.org,
+          slug: args.slug,
+          pageSize: args.page_size,
+          pageToken: args.page_token,
+        }),
+      ),
+  );
+
+  return ["get_skill", "delete_skill", "list_skill_versions"];
 }

package/src/domains/skills/versions.ts

@@ -0,0 +1,47 @@
+// Skill version-timeline path (SkillQueryController.listVersions). Each push
+// creates an immutable version identified by the artifact's SHA-256 hash;
+// entries carry hash, tag, push audit, and provenance (no artifact content, so
+// no projection is needed — unlike the workflow timeline).
+
+import type { MessageInitShape } from "@bufbuild/protobuf";
+import {
+  type ListSkillVersionsInputSchema,
+  ListSkillVersionsResponseSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { SkillQueryController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/query_pb";
+
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+export interface ListSkillVersionsArgs {
+  readonly org: string;
+  readonly slug: string;
+  readonly pageSize?: number;
+  readonly pageToken?: string;
+}
+
+/** List a skill's version history (newest first) as protojson. */
+export async function listSkillVersions(
+  serverAddress: string,
+  token: string,
+  args: ListSkillVersionsArgs,
+): Promise<string> {
+  return withClient(SkillQueryController, serverAddress, token, async (client, callOptions) => {
+    const req: MessageInitShape<typeof ListSkillVersionsInputSchema> = {
+      org: args.org,
+      slug: args.slug,
+      pageToken: args.pageToken ?? "",
+    };
+    // Forward page_size only when set, letting the server apply its default.
+    if ((args.pageSize ?? 0) > 0) {
+      req.pageSize = args.pageSize;
+    }
+    try {
+      const resp = await client.listVersions(req, callOptions);
+      return toProtoJson(ListSkillVersionsResponseSchema, resp);
+    } catch (err) {
+      throw rpcError(err, `versions of skill "${args.slug}" in org "${args.org}"`);
+    }
+  });
+}

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

@@ -0,0 +1,212 @@
+// In-process integration test for the versioning tools: list_workflow_versions
+// (timeline projection — validated_yaml stripped), get_workflow's version
+// argument (slug→ID two-step into getVersion), tag_workflow_version, and
+// list_skill_versions. Same harness as reads.integration.test.ts.
+
+import { create, toJson } from "@bufbuild/protobuf";
+import 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 { SkillQueryController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/query_pb";
+import {
+  ListSkillVersionsResponseSchema,
+  type ListSkillVersionsInput,
+} from "@stigmer/protos/ai/stigmer/agentic/skill/v1/io_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import {
+  ListWorkflowVersionsResponseSchema,
+  WorkflowVersionEntrySchema,
+  type GetWorkflowVersionInput,
+  type TagWorkflowVersionInput,
+} from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/version_pb";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../logger";
+import { createServer } from "../server";
+
+configureLogger({ level: "error", format: "text" });
+
+const HASH_A = "a".repeat(64);
+const HASH_B = "b".repeat(64);
+
+const knownWorkflow = create(WorkflowSchema, {
+  apiVersion: "v1",
+  kind: "workflow",
+  metadata: { name: "Release", slug: "release", org: "acme", id: "wkf_1" },
+});
+
+const workflowVersions = create(ListWorkflowVersionsResponseSchema, {
+  versions: [
+    { versionHash: HASH_A, tag: "stable", isCurrent: true, validatedYaml: "document: {}" },
+    { versionHash: HASH_B, validatedYaml: "document: {old: true}" },
+  ],
+  totalCount: 2,
+});
+
+const versionEntry = create(WorkflowVersionEntrySchema, {
+  versionHash: HASH_B,
+  validatedYaml: "document: {old: true}",
+});
+
+const skillVersions = create(ListSkillVersionsResponseSchema, {
+  versions: [{ versionHash: HASH_A, tag: "stable", isCurrent: true }],
+  totalCount: 1,
+});
+
+let backend: Http2Server;
+let client: Client;
+let lastGetVersion: GetWorkflowVersionInput | undefined;
+let lastTagVersion: TagWorkflowVersionInput | undefined;
+let lastSkillVersionsRequest: ListSkillVersionsInput | undefined;
+const openSessions = new Set<ServerHttp2Session>();
+
+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;
+}
+
+function parseText(result: ToolResult): Record<string, unknown> {
+  return JSON.parse(result.content[0]?.text ?? "{}") as Record<string, unknown>;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(WorkflowQueryController, {
+      getByReference: () => knownWorkflow,
+      listVersions: () => workflowVersions,
+      getVersion: (req) => {
+        lastGetVersion = req;
+        return versionEntry;
+      },
+    });
+    router.service(WorkflowCommandController, {
+      tagVersion: (req) => {
+        lastTagVersion = req;
+        return knownWorkflow;
+      },
+    });
+    router.service(SkillQueryController, {
+      listVersions: (req) => {
+        lastSkillVersionsRequest = req;
+        return skillVersions;
+      },
+    });
+  };
+  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;
+
+  const mcp = createServer({ serverAddress: `127.0.0.1:${port}`, apiKey: "" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  client = new Client({ name: "versions-integration", version: "test" });
+  await Promise.all([mcp.connect(serverTransport), client.connect(clientTransport)]);
+});
+
+beforeEach(() => {
+  lastGetVersion = undefined;
+  lastTagVersion = undefined;
+  lastSkillVersionsRequest = undefined;
+});
+
+afterAll(async () => {
+  await client?.close();
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("versioning tools integration", () => {
+  it("advertises the versioning tools", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name)).toEqual(
+      expect.arrayContaining([
+        "list_workflow_versions",
+        "tag_workflow_version",
+        "list_skill_versions",
+      ]),
+    );
+  });
+
+  it("list_workflow_versions strips validated_yaml from the timeline", async () => {
+    const result = await callTool("list_workflow_versions", { org: "acme", slug: "release" });
+    expect(result.isError).toBeFalsy();
+
+    const body = parseText(result);
+    expect(body.total_count).toBe(2);
+    const versions = body.versions as Array<Record<string, unknown>>;
+    expect(versions).toHaveLength(2);
+    expect(versions[0]).toMatchObject({ version_hash: HASH_A, tag: "stable", is_current: true });
+    for (const entry of versions) {
+      expect(entry.validated_yaml).toBeUndefined();
+    }
+  });
+
+  it("get_workflow with a version resolves the id and fetches that version", async () => {
+    const result = await callTool("get_workflow", {
+      org: "acme",
+      slug: "release",
+      version: HASH_B,
+    });
+    expect(result.isError).toBeFalsy();
+    expect(lastGetVersion?.workflowId).toBe("wkf_1");
+    expect(lastGetVersion?.versionHash).toBe(HASH_B);
+    // The version entry carries the YAML the timeline omits.
+    expect(parseText(result)).toEqual(
+      toJson(WorkflowVersionEntrySchema, versionEntry, { useProtoFieldName: true }),
+    );
+  });
+
+  it("get_workflow without a version returns the live workflow", async () => {
+    const result = await callTool("get_workflow", { org: "acme", slug: "release" });
+    expect(result.isError).toBeFalsy();
+    expect(lastGetVersion).toBeUndefined();
+    expect(parseText(result)).toEqual(
+      toJson(WorkflowSchema, knownWorkflow, { useProtoFieldName: true }),
+    );
+  });
+
+  it("tag_workflow_version resolves the id and forwards hash and tag", async () => {
+    const result = await callTool("tag_workflow_version", {
+      org: "acme",
+      slug: "release",
+      version: HASH_B,
+      tag: "stable",
+    });
+    expect(result.isError).toBeFalsy();
+    expect(lastTagVersion?.workflowId).toBe("wkf_1");
+    expect(lastTagVersion?.versionHash).toBe(HASH_B);
+    expect(lastTagVersion?.tag).toBe("stable");
+  });
+
+  it("list_skill_versions forwards the reference and returns the timeline", async () => {
+    const result = await callTool("list_skill_versions", {
+      org: "acme",
+      slug: "code-review",
+      page_size: 10,
+    });
+    expect(result.isError).toBeFalsy();
+    expect(lastSkillVersionsRequest?.org).toBe("acme");
+    expect(lastSkillVersionsRequest?.slug).toBe("code-review");
+    expect(lastSkillVersionsRequest?.pageSize).toBe(10);
+    expect(parseText(result)).toEqual(
+      toJson(ListSkillVersionsResponseSchema, skillVersions, { useProtoFieldName: true }),
+    );
+  });
+});

package/src/domains/workflowexecutions/approvals.ts

@@ -0,0 +1,102 @@
+// Workflow-execution approval paths: the org-wide pending-approvals inbox
+// (listPendingApprovals) and the reviewer decision for a human_input task
+// (submitWorkflowTaskApproval).
+//
+// listPendingApprovals is org-scoped by contract (io.proto), not
+// execution-scoped — it answers "what is waiting on a human right now"
+// across the org. Each entry carries everything a decision needs: the
+// execution ID, task name, requester, timeout, and the form schema when the
+// task defines one. Agent-execution approvals are a different surface
+// entirely (embedded in get_agent_execution status; see
+// agentexecutions/approve.ts).
+
+import type { JsonObject, MessageInitShape } from "@bufbuild/protobuf";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import {
+  type ListPendingApprovalsRequestSchema,
+  PendingApprovalsListSchema,
+  type SubmitWorkflowTaskApprovalInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
+
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+export interface ListPendingApprovalsArgs {
+  readonly org: string;
+  readonly pageSize?: number;
+  readonly pageToken?: string;
+}
+
+/** List human_input tasks awaiting a reviewer decision across an org. */
+export async function listPendingApprovals(
+  serverAddress: string,
+  token: string,
+  args: ListPendingApprovalsArgs,
+): Promise<string> {
+  return withClient(
+    WorkflowExecutionQueryController,
+    serverAddress,
+    token,
+    async (client, callOptions) => {
+      const req: MessageInitShape<typeof ListPendingApprovalsRequestSchema> = {
+        org: args.org,
+        pageToken: args.pageToken ?? "",
+      };
+      // Forward page_size only when set, letting the server apply its default.
+      if ((args.pageSize ?? 0) > 0) {
+        req.pageSize = args.pageSize;
+      }
+      try {
+        const resp = await client.listPendingApprovals(req, callOptions);
+        return toProtoJson(PendingApprovalsListSchema, resp);
+      } catch (err) {
+        throw rpcError(err, `pending approvals in org "${args.org}"`);
+      }
+    },
+  );
+}
+
+export interface SubmitWorkflowTaskApprovalArgs {
+  readonly executionId: string;
+  readonly taskName: string;
+  readonly outcome: string;
+  readonly comment?: string;
+  readonly formData?: Record<string, unknown>;
+}
+
+/** Submit a reviewer decision for a waiting human_input task. */
+export async function submitWorkflowTaskApproval(
+  serverAddress: string,
+  token: string,
+  args: SubmitWorkflowTaskApprovalArgs,
+): Promise<string> {
+  return withClient(
+    WorkflowExecutionCommandController,
+    serverAddress,
+    token,
+    async (client, callOptions) => {
+      const req: MessageInitShape<typeof SubmitWorkflowTaskApprovalInputSchema> = {
+        executionId: args.executionId,
+        taskName: args.taskName,
+        outcome: args.outcome,
+        comment: args.comment ?? "",
+      };
+      if (args.formData !== undefined) {
+        // google.protobuf.Struct fields are plain JSON objects in protobuf-es v2.
+        req.formData = args.formData as JsonObject;
+      }
+      try {
+        const execution = await client.submitWorkflowTaskApproval(req, callOptions);
+        return toProtoJson(WorkflowExecutionSchema, execution);
+      } catch (err) {
+        throw rpcError(
+          err,
+          `approval for task "${args.taskName}" in workflow execution "${args.executionId}"`,
+        );
+      }
+    },
+  );
+}

package/src/domains/workflowexecutions/run.ts

@@ -0,0 +1,87 @@
+// Workflow-execution start path for the run_workflow tool.
+//
+// Mirrors the CLI's workflow run branch (client-apps/cli/src/commands/run.ts +
+// resources/run/create.ts): resolve the org/slug reference to the workflow ID,
+// then create the execution. Asynchronous like run_agent — the tool returns
+// the created execution (wex_* ID) and observation happens through the
+// existing get_workflow_execution / get_workflow_execution_events tools.
+
+import { createClient } from "@connectrpc/connect";
+import { create as createMessage } from "@bufbuild/protobuf";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import { WorkflowExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/spec_pb";
+import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { executionName, toExecutionValues } from "../agentexecutions/run.js";
+import { withTransport } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/** apiVersion stamped on created executions; mirrors the CLI's run stack. */
+const API_VERSION = "agentic.stigmer.ai/v1";
+
+export interface RunWorkflowArgs {
+  readonly org: string;
+  readonly workflow: string;
+  readonly message?: string;
+  readonly runtimeEnv?: Record<string, string>;
+}
+
+/**
+ * Start a workflow execution: resolve org/slug → workflow ID, then create the
+ * execution. Returns the created execution as protojson.
+ */
+export async function runWorkflow(
+  serverAddress: string,
+  token: string,
+  args: RunWorkflowArgs,
+): Promise<string> {
+  const desc = `workflow "${args.workflow}" in org "${args.org}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    const query = createClient(WorkflowQueryController, transport);
+    let workflowId: string;
+    try {
+      const workflow = await query.getByReference(
+        { org: args.org, kind: ApiResourceKind.workflow, slug: args.workflow },
+        callOptions,
+      );
+      workflowId = workflow.metadata?.id ?? "";
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+
+    // Workflow tasks resolve their org through the runtime env; the CLI
+    // injects STIGMER_ORG_ID the same way, so a caller-supplied value wins.
+    const runtimeEnv = toExecutionValues(args.runtimeEnv);
+    if (runtimeEnv.STIGMER_ORG_ID === undefined) {
+      runtimeEnv.STIGMER_ORG_ID = createMessage(ExecutionValueSchema, {
+        value: args.org,
+        isSecret: false,
+      });
+    }
+
+    const execution = createMessage(WorkflowExecutionSchema, {
+      apiVersion: API_VERSION,
+      kind: "WorkflowExecution",
+      metadata: createMessage(ApiResourceMetadataSchema, { name: executionName(), org: args.org }),
+      spec: createMessage(WorkflowExecutionSpecSchema, {
+        workflowId,
+        // Empty message means "just run" — the CLI applies the same default.
+        triggerMessage: (args.message ?? "") === "" ? "execute" : args.message,
+        runtimeEnv,
+      }),
+    });
+
+    const command = createClient(WorkflowExecutionCommandController, transport);
+    try {
+      const created = await command.create(execution, callOptions);
+      return toProtoJson(WorkflowExecutionSchema, created);
+    } catch (err) {
+      throw rpcError(err, `execution of ${desc}`);
+    }
+  });
+}