@stigmer/mcp-server 3.0.8-dev.20260612122433

package/src/domains/agents/apply.ts

@@ -0,0 +1,30 @@
+// Agent apply path: create-or-update via the AgentCommandController.apply RPC.
+// The flat MCP input is projected into a fully-formed Agent proto by the
+// generated agentInputToProto bridge (codegen, src/gen/agent.ts) before the call.
+// Go parity: mcp-server/internal/domains/agents/apply.go.
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+
+import { agentInputToProto, type AgentInput } from "../../gen/agent.js";
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/** Create or update an agent, returning the persisted agent as protojson. */
+export async function applyAgent(
+  serverAddress: string,
+  token: string,
+  input: AgentInput,
+): Promise<string> {
+  const agent = agentInputToProto(input);
+  const desc = `agent "${agent.metadata?.slug ?? ""}" in org "${agent.metadata?.org ?? ""}"`;
+  return withClient(AgentCommandController, serverAddress, token, async (client, callOptions) => {
+    try {
+      const result = await client.apply(agent, callOptions);
+      return toProtoJson(AgentSchema, result);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}

package/src/domains/agents/delete.ts

@@ -0,0 +1,41 @@
+// Agent delete path: resolve org/slug → id via the Query controller, then
+// delete via the Command controller, both over a single shared transport.
+// Go parity: mcp-server/internal/domains/agents/delete.go.
+
+import { createClient } from "@connectrpc/connect";
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { withTransport } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/** Delete an agent by org and slug, returning the deleted agent as protojson. */
+export async function deleteAgent(
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+): Promise<string> {
+  const desc = `agent "${slug}" in org "${org}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    const query = createClient(AgentQueryController, transport);
+    let id: string;
+    try {
+      const agent = await query.getByReference({ org, kind: ApiResourceKind.agent, slug }, callOptions);
+      id = agent.metadata?.id ?? "";
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+
+    const command = createClient(AgentCommandController, transport);
+    try {
+      const deleted = await command.delete({ value: id }, callOptions);
+      return toProtoJson(AgentSchema, deleted);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}

package/src/domains/agents/fetch.ts

@@ -0,0 +1,33 @@
+// Agent read path: the single RPC both the get_agent tool and the agent
+// resource template delegate to. Mirrors Go internal/domains/agents/fetch.go.
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/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 agent by org and slug, returning its protojson representation.
+ * Errors are classified into user-facing messages via {@link rpcError}.
+ */
+export async function fetchAgent(
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+): Promise<string> {
+  return withClient(AgentQueryController, serverAddress, token, async (client, callOptions) => {
+    try {
+      const agent = await client.getByReference(
+        { org, kind: ApiResourceKind.agent, slug },
+        callOptions,
+      );
+      return toProtoJson(AgentSchema, agent);
+    } catch (err) {
+      throw rpcError(err, `agent "${slug}" in org "${org}"`);
+    }
+  });
+}

package/src/domains/agents/resources.ts

@@ -0,0 +1,20 @@
+// Agent resource template (stigmer://agents/{org}/{slug}).
+// Go parity: mcp-server/internal/domains/agents/resources.go.
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+import type { BackendTarget } from "../client.js";
+import { registerResource } from "../resourcehandler.js";
+import { fetchAgent } from "./fetch.js";
+
+/** Register the agent resource template; returns the registered resource names. */
+export function registerAgentResources(server: McpServer, target: BackendTarget): string[] {
+  registerResource(server, target, {
+    name: "stigmer_agent",
+    title: "Stigmer Agent",
+    description: "Full definition of a Stigmer agent, identified by organization and slug.",
+    template: "stigmer://agents/{org}/{slug}",
+    fetch: fetchAgent,
+  });
+  return ["stigmer_agent"];
+}

package/src/domains/agents/tools.ts

@@ -0,0 +1,68 @@
+// MCP tools for the Agent domain. Mirrors Go internal/domains/agents/tools.go.
+//
+// The tool name, description, and per-field input descriptions are part of the
+// parity contract (MCP clients surface them to the model verbatim), so they are
+// copied exactly from the Go definitions. This file is the canonical pattern the
+// remaining domains follow in T02: define the tool, resolve the per-request
+// credential, delegate to the domain fetch, and shape the result.
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { AgentInputShape } from "../../gen/agent.js";
+import { resolveToken, type BackendTarget } from "../client.js";
+import { textOrError } from "../toolresult.js";
+import { applyAgent } from "./apply.js";
+import { deleteAgent } from "./delete.js";
+import { fetchAgent } from "./fetch.js";
+
+/** Register every Agent-domain tool; returns the registered tool names. */
+export function registerAgentTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "get_agent",
+    {
+      description:
+        "Get full details of a Stigmer agent by its org and slug (e.g. org=stigmer slug=code-reviewer).",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the agent (e.g. stigmer)."),
+        slug: z
+          .string()
+          .describe("Agent slug — the unique identifier within the org (e.g. code-reviewer)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        fetchAgent(target.serverAddress, resolveToken(extra, target.apiKey), args.org, args.slug),
+      ),
+  );
+
+  server.registerTool(
+    "apply_agent",
+    {
+      description:
+        "Create or update a Stigmer agent (idempotent). Provide identity fields (name, org) and agent configuration (instructions, skills, MCP servers, etc.).",
+      inputSchema: AgentInputShape,
+    },
+    (args, extra) =>
+      textOrError(() => applyAgent(target.serverAddress, resolveToken(extra, target.apiKey), args)),
+  );
+
+  server.registerTool(
+    "delete_agent",
+    {
+      description: "Delete a Stigmer agent by its org and slug. Returns the deleted agent.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the agent (e.g. stigmer)."),
+        slug: z
+          .string()
+          .describe("Agent slug — the unique identifier within the org (e.g. code-reviewer)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        deleteAgent(target.serverAddress, resolveToken(extra, target.apiKey), args.org, args.slug),
+      ),
+  );
+
+  return ["get_agent", "apply_agent", "delete_agent"];
+}

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

@@ -0,0 +1,220 @@
+// In-process integration test for the apply tools. Drives apply_agent,
+// apply_mcp_server, and apply_workflow through the full MCP boundary and asserts
+// the codegen projection (src/gen/*) reconstitutes the proto correctly: metadata
+// hoist + slug generation, enum-string conversion, ApiResourceReference kind
+// injection, the stdio/http oneof, and the recursive workflow task_config
+// expansion (http_call leaf, fork/for_each nesting).
+
+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 type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import type { McpServer as McpServerProto } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../logger";
+import { createServer } from "../server";
+
+configureLogger({ level: "error", format: "text" });
+
+let backend: Http2Server;
+let client: Client;
+let appliedAgent: Agent | undefined;
+let appliedMcpServer: McpServerProto | undefined;
+let appliedWorkflow: Workflow | 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;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(AgentCommandController, {
+      apply: (req) => {
+        appliedAgent = req;
+        return req;
+      },
+    });
+    router.service(McpServerCommandController, {
+      apply: (req) => {
+        appliedMcpServer = req;
+        return req;
+      },
+    });
+    router.service(WorkflowCommandController, {
+      apply: (req) => {
+        appliedWorkflow = req;
+        return req;
+      },
+    });
+  };
+  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: "apply-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("apply tools integration", () => {
+  it("advertises every apply tool", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name)).toEqual(
+      expect.arrayContaining(["apply_agent", "apply_mcp_server", "apply_workflow"]),
+    );
+  });
+
+  it("apply_agent hoists metadata, generates slug, and injects reference kinds", async () => {
+    const result = await callTool("apply_agent", {
+      name: "Code Reviewer",
+      org: "acme",
+      visibility: "PUBLIC",
+      instructions: "Review code carefully.",
+      skill_refs: [{ slug: "web-search", version: "stable" }],
+      mcp_server_usages: [{ mcp_server_ref: { slug: "github" }, enabled_tools: ["create_pr"] }],
+    });
+    expect(result.isError).toBeFalsy();
+
+    const agent = appliedAgent;
+    expect(agent?.apiVersion).toBe("agentic.stigmer.ai/v1");
+    expect(agent?.kind).toBe("Agent");
+    expect(agent?.metadata?.name).toBe("Code Reviewer");
+    expect(agent?.metadata?.slug).toBe("code-reviewer"); // auto-generated from name
+    expect(agent?.metadata?.org).toBe("acme");
+    expect(agent?.metadata?.visibility).toBe(ApiResourceVisibility.visibility_public);
+    expect(agent?.spec?.instructions).toBe("Review code carefully.");
+
+    const skillRef = agent?.spec?.skillRefs?.[0];
+    expect(skillRef?.slug).toBe("web-search");
+    expect(skillRef?.kind).toBe(ApiResourceKind.skill);
+    expect(skillRef?.version).toBe("stable"); // version kept for versioned kind
+
+    const usage = agent?.spec?.mcpServerUsages?.[0];
+    expect(usage?.mcpServerRef?.slug).toBe("github");
+    expect(usage?.mcpServerRef?.kind).toBe(ApiResourceKind.mcp_server);
+    expect(usage?.enabledTools).toEqual(["create_pr"]);
+  });
+
+  it("apply_mcp_server rebuilds the stdio oneof", async () => {
+    const result = await callTool("apply_mcp_server", {
+      name: "GitHub",
+      org: "acme",
+      stdio: { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] },
+    });
+    expect(result.isError).toBeFalsy();
+    expect(appliedMcpServer?.spec?.serverType?.case).toBe("stdio");
+    expect(appliedMcpServer?.spec?.serverType?.value).toMatchObject({ command: "npx" });
+  });
+
+  it("apply_mcp_server rebuilds the http oneof", async () => {
+    const result = await callTool("apply_mcp_server", {
+      name: "Remote",
+      org: "acme",
+      http: { url: "https://mcp.example.com/v1" },
+    });
+    expect(result.isError).toBeFalsy();
+    expect(appliedMcpServer?.spec?.serverType?.case).toBe("http");
+    expect(appliedMcpServer?.spec?.serverType?.value).toMatchObject({
+      url: "https://mcp.example.com/v1",
+    });
+  });
+
+  it("apply_workflow expands typed task_config and nests recursive tasks", async () => {
+    const result = await callTool("apply_workflow", {
+      name: "Triage",
+      org: "acme",
+      document: { namespace: "support", name: "triage", version: "1.0.0" },
+      tasks: [
+        {
+          name: "fetch",
+          kind: "http_call",
+          http_call: { method: "POST", endpoint: { uri: "https://api.example.com" } },
+        },
+        {
+          name: "parallel",
+          kind: "fork",
+          fork: {
+            branches: [
+              {
+                name: "b1",
+                do: [{ name: "set_x", kind: "set_vars", set_vars: { variables: { x: "1" } } }],
+              },
+            ],
+          },
+        },
+        {
+          name: "loop",
+          kind: "for_each",
+          for_each: {
+            each: "item",
+            in: "${ $data.items }",
+            do: [
+              {
+                name: "call",
+                kind: "http_call",
+                http_call: { method: "GET", endpoint: { uri: "https://api.example.com/item" } },
+              },
+            ],
+          },
+        },
+      ],
+    });
+    expect(result.isError).toBeFalsy();
+
+    const wf = appliedWorkflow;
+    expect(wf?.apiVersion).toBe("agentic.stigmer.ai/v1");
+    expect(wf?.metadata?.slug).toBe("triage");
+    expect(wf?.spec?.document?.namespace).toBe("support");
+
+    const tasks = wf?.spec?.tasks ?? [];
+    expect(tasks).toHaveLength(3);
+
+    // http_call leaf: task_config Struct carries the serialized config.
+    expect(tasks[0]?.kind).toBe(WorkflowTaskKind.http_call);
+    expect(tasks[0]?.taskConfig).toMatchObject({ method: "POST" });
+
+    // fork: recursive nesting — branches[].do[] are full tasks.
+    expect(tasks[1]?.kind).toBe(WorkflowTaskKind.fork);
+    const forkCfg = tasks[1]?.taskConfig as { branches?: Array<{ do?: unknown[] }> };
+    expect(forkCfg.branches?.[0]?.do).toHaveLength(1);
+
+    // for_each: recursive nesting via z.lazy.
+    expect(tasks[2]?.kind).toBe(WorkflowTaskKind.for_each);
+    const forCfg = tasks[2]?.taskConfig as { each?: string; do?: unknown[] };
+    expect(forCfg.each).toBe("item");
+    expect(forCfg.do).toHaveLength(1);
+  });
+});

package/src/domains/client.ts

@@ -0,0 +1,95 @@
+// Per-request gRPC client construction for tool handlers.
+//
+// Parity contract (mirrors Go internal/domains/conn.go WithConnection + the
+// auth/grpc layer): each tool call resolves its credential, opens a short-lived
+// authenticated client to stigmer-server with a fixed RPC timeout, runs the
+// call, and discards the client. This is intentionally simple — the MCP server
+// handles a low volume of calls and transport setup is cheap. Pooling can be
+// introduced later without touching call sites.
+//
+// Credential source mirrors Go precisely:
+//   - stdio: the API key is captured once at startup (constant per process).
+//   - http: every request carries its own Bearer token via authInfo, which the
+//     transport injected from the Authorization header.
+
+import { createClient, type Client, type CallOptions, type Transport } from "@connectrpc/connect";
+import type { DescService } from "@bufbuild/protobuf";
+import { createNodeTransport, normalizeEndpoint } from "@stigmer/sdk/node";
+
+/**
+ * Per-call RPC timeout. Mirrors Go's DefaultRPCTimeout: generous for both
+ * localhost (milliseconds) and remote endpoints (low seconds), while still
+ * failing fast against a misconfigured or unreachable address.
+ */
+export const DEFAULT_RPC_TIMEOUT_MS = 30_000;
+
+/**
+ * The stigmer-server endpoint and startup credential captured at registration
+ * time and shared by every tool handler. Mirrors the `serverAddress` closure +
+ * startup API key that the Go handlers capture.
+ */
+export interface BackendTarget {
+  readonly serverAddress: string;
+  /** stdio startup API key; "" when targeting an unauthenticated backend. */
+  readonly apiKey: string;
+}
+
+/** The subset of the MCP request `extra` this layer reads to resolve a token. */
+export interface RequestAuth {
+  readonly authInfo?: { readonly token?: string };
+}
+
+/**
+ * Resolve the credential for an inbound tool call: the per-request Bearer token
+ * (http) when present, otherwise the startup API key (stdio). Returns "" when
+ * targeting an unauthenticated backend, in which case no credential is attached.
+ */
+export function resolveToken(extra: RequestAuth | undefined, fallback: string): string {
+  const token = extra?.authInfo?.token;
+  return token !== undefined && token !== "" ? token : fallback;
+}
+
+/**
+ * Build an authenticated transport to stigmer-server for a single credential.
+ * The address is normalized (scheme/TLS rules) before the transport is built;
+ * an empty token attaches no Authorization header.
+ */
+export function transportForToken(serverAddress: string, token: string): Transport {
+  return createNodeTransport({
+    baseUrl: normalizeEndpoint(serverAddress),
+    apiKey: token === "" ? undefined : token,
+  });
+}
+
+/**
+ * Open a short-lived authenticated transport and invoke `fn` with it and the
+ * standard call options (RPC timeout pre-applied). Mirrors Go's WithConnection:
+ * the single place that owns transport construction and the timeout. Use this
+ * when an operation needs more than one controller over the SAME connection —
+ * e.g. the two-step deletes that resolve via the Query controller and delete via
+ * the Command controller.
+ */
+export async function withTransport<T>(
+  serverAddress: string,
+  token: string,
+  fn: (transport: Transport, callOptions: CallOptions) => Promise<T>,
+): Promise<T> {
+  return fn(transportForToken(serverAddress, token), { timeoutMs: DEFAULT_RPC_TIMEOUT_MS });
+}
+
+/**
+ * Open a short-lived raw controller client and invoke `fn` with it and the
+ * standard call options. The single-controller convenience over
+ * {@link withTransport}; call sites that only touch one service stay a
+ * one-liner.
+ */
+export async function withClient<S extends DescService, T>(
+  service: S,
+  serverAddress: string,
+  token: string,
+  fn: (client: Client<S>, callOptions: CallOptions) => Promise<T>,
+): Promise<T> {
+  return withTransport(serverAddress, token, (transport, callOptions) =>
+    fn(createClient(service, transport), callOptions),
+  );
+}

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

@@ -0,0 +1,124 @@
+// In-process integration test for the delete tools. Verifies the two-step
+// resolve→delete flow forwards the resolved id into the correct per-domain
+// delete-input shape: typed {value} for agent/skill/workflow, and the
+// ApiResourceDeleteInput {resource_id} outlier for mcp_server.
+
+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 { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../logger";
+import { createServer } from "../server";
+
+configureLogger({ level: "error", format: "text" });
+
+const resolvedAgent = create(AgentSchema, {
+  apiVersion: "v1",
+  kind: "agent",
+  metadata: { name: "Code Reviewer", slug: "code-reviewer", org: "acme", id: "agt-123" },
+});
+const resolvedMcpServer = create(McpServerSchema, {
+  apiVersion: "v1",
+  kind: "mcp_server",
+  metadata: { name: "GitHub", slug: "github", org: "acme", id: "mcp-456" },
+});
+
+let backend: Http2Server;
+let client: Client;
+let deletedAgentId: string | undefined;
+let deletedMcpResourceId: string | 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;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(AgentQueryController, { getByReference: () => resolvedAgent });
+    router.service(AgentCommandController, {
+      delete: (req) => {
+        deletedAgentId = req.value;
+        return resolvedAgent;
+      },
+    });
+    router.service(McpServerQueryController, { getByReference: () => resolvedMcpServer });
+    router.service(McpServerCommandController, {
+      delete: (req) => {
+        deletedMcpResourceId = req.resourceId;
+        return resolvedMcpServer;
+      },
+    });
+  };
+  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: "deletes-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("delete tools integration", () => {
+  it("advertises every delete tool", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name)).toEqual(
+      expect.arrayContaining([
+        "delete_agent",
+        "delete_skill",
+        "delete_workflow",
+        "delete_mcp_server",
+      ]),
+    );
+  });
+
+  it("delete_agent resolves the id then deletes via the typed AgentId", async () => {
+    const result = await callTool("delete_agent", { org: "acme", slug: "code-reviewer" });
+    expect(result.isError).toBeFalsy();
+    expect(deletedAgentId).toBe("agt-123");
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(AgentSchema, resolvedAgent, { useProtoFieldName: true }),
+    );
+  });
+
+  it("delete_mcp_server resolves the id then deletes via ApiResourceDeleteInput", async () => {
+    const result = await callTool("delete_mcp_server", { org: "acme", slug: "github" });
+    expect(result.isError).toBeFalsy();
+    expect(deletedMcpResourceId).toBe("mcp-456");
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(McpServerSchema, resolvedMcpServer, { useProtoFieldName: true }),
+    );
+  });
+});

package/src/domains/marshal.ts

@@ -0,0 +1,21 @@
+// Canonical protobuf → JSON serialization shared by every tool response.
+//
+// Parity contract (mirrors Go internal/domains/marshal.go): the Go server emits
+// protojson with UseProtoNames=true and EmitUnpopulated=false, 2-space indented.
+// protobuf-es `toJson` with { useProtoFieldName: true } reproduces this exactly —
+// snake_case field names, omitted defaults, base64 bytes, string enums, and
+// RFC-3339 timestamps — and JSON.stringify(..., 2) applies the same indentation.
+
+import { toJson, type DescMessage, type MessageShape } from "@bufbuild/protobuf";
+
+/**
+ * Serialize a protobuf message to the human-friendly JSON string returned in
+ * MCP tool output. Field names use the proto (snake_case) names so the payload
+ * is byte-comparable, after parsing, with the Go server's protojson.
+ */
+export function toProtoJson<Desc extends DescMessage>(
+  schema: Desc,
+  message: MessageShape<Desc>,
+): string {
+  return JSON.stringify(toJson(schema, message, { useProtoFieldName: true }), null, 2);
+}