@stigmer/mcp-server 3.2.3 → 3.4.0

package/src/domains/environments/fetch.ts

@@ -0,0 +1,39 @@
+// Environment read path: the single RPC both the get_environment tool and the
+// environment resource template delegate to.
+//
+// Secret handling happens entirely server-side: the response pipeline replaces
+// every is_secret value with the ***REDACTED*** sentinel before it leaves the
+// server (backend environment domain, preserve_redacted_secrets.go), so this
+// layer adds no redaction logic of its own — the server is the single
+// enforcement point.
+
+import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentQueryController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/query_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/**
+ * Retrieve an environment by org and slug, returning its protojson
+ * representation (secret values arrive already redacted by the server).
+ */
+export async function fetchEnvironment(
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+): Promise<string> {
+  return withClient(EnvironmentQueryController, serverAddress, token, async (client, callOptions) => {
+    try {
+      const environment = await client.getByReference(
+        { org, kind: ApiResourceKind.environment, slug },
+        callOptions,
+      );
+      return toProtoJson(EnvironmentSchema, environment);
+    } catch (err) {
+      throw rpcError(err, `environment "${slug}" in org "${org}"`);
+    }
+  });
+}

package/src/domains/environments/resources.ts

@@ -0,0 +1,21 @@
+// Environment resource template (stigmer://environments/{org}/{slug}).
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+import type { BackendTarget } from "../client.js";
+import { registerResource } from "../resourcehandler.js";
+import { fetchEnvironment } from "./fetch.js";
+
+/** Register the environment resource template; returns the registered resource names. */
+export function registerEnvironmentResources(server: McpServer, target: BackendTarget): string[] {
+  registerResource(server, target, {
+    name: "stigmer_environment",
+    title: "Stigmer Environment",
+    description:
+      "Full definition of a Stigmer environment, identified by organization and slug. " +
+      "Secret values are redacted.",
+    template: "stigmer://environments/{org}/{slug}",
+    fetch: fetchEnvironment,
+  });
+  return ["stigmer_environment"];
+}

package/src/domains/environments/tools.ts

@@ -0,0 +1,81 @@
+// MCP tools for the Environment domain. Environments hold the configuration
+// and secrets that agents, workflows, and MCP servers resolve at runtime —
+// without these tools, an assistant authoring an agent hits a dead end the
+// moment env config is involved.
+//
+// The secret contract every description teaches: reads return secret values
+// redacted to ***REDACTED*** (server-enforced); an apply that echoes the
+// marker back preserves the existing secret, so get → edit → apply is always
+// safe. Secret values are only ever sent when setting or rotating them, and
+// they can never be read back through MCP.
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { EnvironmentInputShape } from "../../gen/environment.js";
+import { resolveToken, type BackendTarget } from "../client.js";
+import { textOrError } from "../toolresult.js";
+import { applyEnvironment } from "./apply.js";
+import { deleteEnvironment } from "./delete.js";
+import { fetchEnvironment } from "./fetch.js";
+
+/** Register every Environment-domain tool; returns the registered tool names. */
+export function registerEnvironmentTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "get_environment",
+    {
+      description:
+        "Get full details of a Stigmer environment by its org and slug, including its variable " +
+        "declarations. Secret values are redacted to ***REDACTED*** — they can never be read " +
+        "back through this tool.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the environment (e.g. stigmer)."),
+        slug: z
+          .string()
+          .describe("Environment slug — the unique identifier within the org (e.g. github-creds)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        fetchEnvironment(target.serverAddress, resolveToken(extra, target.apiKey), args.org, args.slug),
+      ),
+  );
+
+  server.registerTool(
+    "apply_environment",
+    {
+      description:
+        "Create or update a Stigmer environment (idempotent). The spec is applied in full, so " +
+        "include every variable the environment should keep. When updating, secret values read " +
+        "back as ***REDACTED*** — echoing that marker preserves the existing secret, so a " +
+        "get → edit → apply round-trip never destroys secrets; send a real value only to set " +
+        "or rotate one.",
+      inputSchema: EnvironmentInputShape,
+    },
+    (args, extra) =>
+      textOrError(() =>
+        applyEnvironment(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  server.registerTool(
+    "delete_environment",
+    {
+      description:
+        "Delete a Stigmer environment by its org and slug. Returns the deleted environment. " +
+        "Agents and workflows referencing it will fail to resolve their variables at run time.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the environment (e.g. stigmer)."),
+        slug: z
+          .string()
+          .describe("Environment slug — the unique identifier within the org (e.g. github-creds)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        deleteEnvironment(target.serverAddress, resolveToken(extra, target.apiKey), args.org, args.slug),
+      ),
+  );
+
+  return ["get_environment", "apply_environment", "delete_environment"];
+}

package/src/domains/executions/cancel.ts

@@ -0,0 +1,148 @@
+// Cross-kind execution cancellation for the cancel_execution tool.
+//
+// Executions are the one place the MCP surface routes on ID prefix rather
+// than a kind argument: agent (aex_*) and workflow (wex_*) executions live on
+// dedicated controllers but cancel with identical arguments, so one tool
+// serves both — mirroring the CLI's routing seam
+// (client-apps/cli/src/resources/execution.ts), including its cancel
+// semantics: read the execution first and short-circuit with
+// "already terminal" instead of issuing a futile cancel, so the
+// success/no-op distinction comes from authoritative state.
+
+import { createClient } from "@connectrpc/connect";
+import { type AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
+import { ExecutionPhase as AgentExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
+import {
+  WorkflowExecutionSchema,
+  type WorkflowExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import { ExecutionPhase as WorkflowExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
+
+import { compactExecution, DEFAULT_MESSAGE_LIMIT } from "../agentexecutions/fetch.js";
+import { withTransport } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+// Terminal phases per kind. The two ExecutionPhase enums live in different
+// proto packages with different numeric values (agent TERMINATED is 8,
+// workflow TERMINATED is 6), so these are deliberately separate sets.
+const TERMINAL_AGENT_PHASES: ReadonlySet<AgentExecutionPhase> = new Set([
+  AgentExecutionPhase.EXECUTION_COMPLETED,
+  AgentExecutionPhase.EXECUTION_FAILED,
+  AgentExecutionPhase.EXECUTION_CANCELLED,
+  AgentExecutionPhase.EXECUTION_TERMINATED,
+]);
+
+const TERMINAL_WORKFLOW_PHASES: ReadonlySet<WorkflowExecutionPhase> = new Set([
+  WorkflowExecutionPhase.EXECUTION_COMPLETED,
+  WorkflowExecutionPhase.EXECUTION_FAILED,
+  WorkflowExecutionPhase.EXECUTION_CANCELLED,
+  WorkflowExecutionPhase.EXECUTION_TERMINATED,
+]);
+
+/**
+ * Resolve an execution ID to its controller family by prefix. Matching is
+ * case-sensitive and accepts both separators the backend does ("_" canonical,
+ * "-" legacy), mirroring the CLI's resolveExecutionType.
+ */
+function resolveExecutionType(id: string): "agent" | "workflow" {
+  const trimmed = id.trim();
+  if (trimmed.startsWith("aex_") || trimmed.startsWith("aex-")) return "agent";
+  if (trimmed.startsWith("wex_") || trimmed.startsWith("wex-")) return "workflow";
+  throw new Error(
+    `unrecognized execution ID format: ${id}\n\n` +
+      "Expected formats:\n" +
+      "  Agent execution:    aex_<26-char-ulid>\n" +
+      "  Workflow execution: wex_<26-char-ulid>",
+  );
+}
+
+/**
+ * Cancel an execution of either kind. Returns a wrapper documenting whether a
+ * cancel was actually issued: `{"already_terminal": bool, "execution": …}`.
+ * Agent executions are returned in the compact projection (their status embeds
+ * the full message history); workflow executions as plain protojson, matching
+ * get_workflow_execution.
+ */
+export async function cancelExecution(
+  serverAddress: string,
+  token: string,
+  executionId: string,
+  reason: string,
+): Promise<string> {
+  return resolveExecutionType(executionId) === "agent"
+    ? cancelAgentExecution(serverAddress, token, executionId, reason)
+    : cancelWorkflowExecution(serverAddress, token, executionId, reason);
+}
+
+async function cancelAgentExecution(
+  serverAddress: string,
+  token: string,
+  id: string,
+  reason: string,
+): Promise<string> {
+  const desc = `agent execution "${id}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    try {
+      const query = createClient(AgentExecutionQueryController, transport);
+      const current = await query.get({ value: id }, callOptions);
+      const phase = current.status?.phase ?? AgentExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+      if (TERMINAL_AGENT_PHASES.has(phase)) {
+        return wrapAgent(current, true);
+      }
+      const command = createClient(AgentExecutionCommandController, transport);
+      const cancelled = await command.cancel({ id, reason }, callOptions);
+      return wrapAgent(cancelled, false);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}
+
+async function cancelWorkflowExecution(
+  serverAddress: string,
+  token: string,
+  id: string,
+  reason: string,
+): Promise<string> {
+  const desc = `workflow execution "${id}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    try {
+      const query = createClient(WorkflowExecutionQueryController, transport);
+      const current = await query.get({ value: id }, callOptions);
+      const phase = current.status?.phase ?? WorkflowExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+      if (TERMINAL_WORKFLOW_PHASES.has(phase)) {
+        return wrapWorkflow(current, true);
+      }
+      const command = createClient(WorkflowExecutionCommandController, transport);
+      const cancelled = await command.cancel({ id, reason }, callOptions);
+      return wrapWorkflow(cancelled, false);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}
+
+function wrapAgent(execution: AgentExecution, alreadyTerminal: boolean): string {
+  const { totalMessages, data } = compactExecution(execution, DEFAULT_MESSAGE_LIMIT);
+  return JSON.stringify(
+    { already_terminal: alreadyTerminal, view: "compact", total_messages: totalMessages, execution: data },
+    null,
+    2,
+  );
+}
+
+function wrapWorkflow(execution: WorkflowExecution, alreadyTerminal: boolean): string {
+  return JSON.stringify(
+    {
+      already_terminal: alreadyTerminal,
+      execution: JSON.parse(toProtoJson(WorkflowExecutionSchema, execution)),
+    },
+    null,
+    2,
+  );
+}

package/src/domains/executions/tools.ts

@@ -0,0 +1,45 @@
+// Cross-kind execution-control tools. Currently just cancel_execution — the
+// one control verb whose argument shape is identical for agent and workflow
+// executions, so a single ID-prefix-dispatched tool serves both (the
+// "crisp schemas over fewer tools" principle cuts the other way for
+// approvals, whose shapes are disjoint). pause/resume/terminate stay
+// CLI-only until a real MCP need shows up.
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { resolveToken, type BackendTarget } from "../client.js";
+import { textOrError } from "../toolresult.js";
+import { cancelExecution } from "./cancel.js";
+
+/** Register the cross-kind execution-control tools; returns the registered tool names. */
+export function registerExecutionControlTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "cancel_execution",
+    {
+      description:
+        "Gracefully cancel a running agent (aex_*) or workflow (wex_*) execution — the kind is " +
+        "inferred from the ID prefix. Cancellation is terminal: the run stops after cleanup and " +
+        "cannot be resumed. Executions already in a terminal phase are returned with " +
+        "already_terminal=true instead of an error.",
+      inputSchema: {
+        execution_id: z.string().describe("Execution ID to cancel (aex_* or wex_* format)."),
+        reason: z
+          .string()
+          .optional()
+          .describe("Human-readable reason for the cancellation, stored in the audit trail."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        cancelExecution(
+          target.serverAddress,
+          resolveToken(extra, target.apiKey),
+          args.execution_id,
+          args.reason ?? "",
+        ),
+      ),
+  );
+
+  return ["cancel_execution"];
+}