@stigmer/mcp-server 3.0.8-dev.20260612122433

package/src/domains/mcpservers/apply.ts

@@ -0,0 +1,36 @@
+// McpServer apply path: create-or-update via the McpServerCommandController.apply
+// RPC. The flat MCP input is projected into a fully-formed McpServer proto by the
+// generated mcpServerInputToProto bridge (codegen, src/gen/mcpserver.ts), which
+// also rebuilds the stdio/http oneof, before the call.
+// Go parity: mcp-server/internal/domains/mcpservers/apply.go.
+
+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 { mcpServerInputToProto, type McpServerInput } from "../../gen/mcpserver.js";
+import { withClient } from "../client.js";
+import { toProtoJson } from "../marshal.js";
+import { rpcError } from "../rpcerr.js";
+
+/** Create or update an MCP server, returning the persisted server as protojson. */
+export async function applyMcpServer(
+  serverAddress: string,
+  token: string,
+  input: McpServerInput,
+): Promise<string> {
+  const server = mcpServerInputToProto(input);
+  const desc = `mcp server "${server.metadata?.slug ?? ""}" in org "${server.metadata?.org ?? ""}"`;
+  return withClient(
+    McpServerCommandController,
+    serverAddress,
+    token,
+    async (client, callOptions) => {
+      try {
+        const result = await client.apply(server, callOptions);
+        return toProtoJson(McpServerSchema, result);
+      } catch (err) {
+        throw rpcError(err, desc);
+      }
+    },
+  );
+}

package/src/domains/mcpservers/delete.ts

@@ -0,0 +1,51 @@
+// MCP server delete path: resolve org/slug → id, then delete, both over a single
+// shared transport.
+// Go parity: mcp-server/internal/domains/mcpservers/delete.go.
+//
+// Outlier: unlike the agent/skill/workflow command controllers (which take a
+// typed {X}Id), McpServerCommandController.delete takes the generic
+// ApiResourceDeleteInput{resource_id}.
+
+import { createClient } from "@connectrpc/connect";
+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 { 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 MCP server by org and slug, returning the deleted MCP server as
+ * protojson.
+ */
+export async function deleteMcpServer(
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+): Promise<string> {
+  const desc = `MCP server "${slug}" in org "${org}"`;
+  return withTransport(serverAddress, token, async (transport, callOptions) => {
+    const query = createClient(McpServerQueryController, transport);
+    let id: string;
+    try {
+      const mcpServer = await query.getByReference(
+        { org, kind: ApiResourceKind.mcp_server, slug },
+        callOptions,
+      );
+      id = mcpServer.metadata?.id ?? "";
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+
+    const command = createClient(McpServerCommandController, transport);
+    try {
+      const deleted = await command.delete({ resourceId: id }, callOptions);
+      return toProtoJson(McpServerSchema, deleted);
+    } catch (err) {
+      throw rpcError(err, desc);
+    }
+  });
+}

package/src/domains/mcpservers/fetch.ts

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

package/src/domains/mcpservers/resources.ts

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

package/src/domains/mcpservers/tools.ts

@@ -0,0 +1,74 @@
+// MCP tools for the McpServer domain.
+// Go parity: mcp-server/internal/domains/mcpservers/tools.go.
+//
+// Tool name, description, and per-field input descriptions are part of the
+// parity contract (clients surface them to the model verbatim).
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { McpServerInputShape } from "../../gen/mcpserver.js";
+import { resolveToken, type BackendTarget } from "../client.js";
+import { textOrError } from "../toolresult.js";
+import { applyMcpServer } from "./apply.js";
+import { deleteMcpServer } from "./delete.js";
+import { fetchMcpServer } from "./fetch.js";
+
+/** Register every McpServer-domain tool; returns the registered tool names. */
+export function registerMcpServerTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "get_mcp_server",
+    {
+      description:
+        "Get full details of a Stigmer MCP server by its org and slug (e.g. org=acme slug=my-server).",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the MCP server (e.g. acme)."),
+        slug: z
+          .string()
+          .describe("MCP server slug — the unique identifier within the org (e.g. my-server)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        fetchMcpServer(target.serverAddress, resolveToken(extra, target.apiKey), args.org, args.slug),
+      ),
+  );
+
+  server.registerTool(
+    "apply_mcp_server",
+    {
+      description:
+        "Create or update a Stigmer MCP server definition (idempotent). Provide identity fields (name, org) and server configuration (stdio/http, tools, env, etc.).",
+      inputSchema: McpServerInputShape,
+    },
+    (args, extra) =>
+      textOrError(() =>
+        applyMcpServer(target.serverAddress, resolveToken(extra, target.apiKey), args),
+      ),
+  );
+
+  server.registerTool(
+    "delete_mcp_server",
+    {
+      description:
+        "Delete a Stigmer MCP server definition by its org and slug. Returns the deleted MCP server.",
+      inputSchema: {
+        org: z.string().describe("Organization slug that owns the MCP server (e.g. acme)."),
+        slug: z
+          .string()
+          .describe("MCP server slug — the unique identifier within the org (e.g. github)."),
+      },
+    },
+    (args, extra) =>
+      textOrError(() =>
+        deleteMcpServer(
+          target.serverAddress,
+          resolveToken(extra, target.apiKey),
+          args.org,
+          args.slug,
+        ),
+      ),
+  );
+
+  return ["get_mcp_server", "apply_mcp_server", "delete_mcp_server"];
+}

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

@@ -0,0 +1,134 @@
+// In-process integration test for the read tools (get_mcp_server, get_skill,
+// get_workflow). Stands up a real Connect backend serving the three query
+// controllers, drives the MCP server through an in-memory client, and asserts
+// each tool returns the backend's protojson verbatim (the parity contract) and
+// that get_skill forwards its optional version to the backend.
+
+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 { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { SkillQueryController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/query_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/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 knownMcpServer = create(McpServerSchema, {
+  apiVersion: "v1",
+  kind: "mcp_server",
+  metadata: { name: "GitHub", slug: "github", org: "acme", id: "mcp-1" },
+});
+
+const knownSkill = create(SkillSchema, {
+  apiVersion: "v1",
+  kind: "skill",
+  metadata: { name: "Code Review", slug: "code-review", org: "acme", id: "skl-1" },
+});
+
+const knownWorkflow = create(WorkflowSchema, {
+  apiVersion: "v1",
+  kind: "workflow",
+  metadata: { name: "Release", slug: "release", org: "acme", id: "wkf-1" },
+});
+
+let backend: Http2Server;
+let client: Client;
+let lastSkillVersion: 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(McpServerQueryController, { getByReference: () => knownMcpServer });
+    router.service(SkillQueryController, {
+      getByReference: (req) => {
+        lastSkillVersion = req.version;
+        return knownSkill;
+      },
+    });
+    router.service(WorkflowQueryController, { getByReference: () => knownWorkflow });
+  };
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  // Force keep-alive sessions closed on teardown, else backend.close() blocks.
+  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: "reads-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("read tools integration", () => {
+  it("advertises all read tools", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name)).toEqual(
+      expect.arrayContaining(["get_agent", "get_mcp_server", "get_skill", "get_workflow"]),
+    );
+  });
+
+  it("get_mcp_server returns the backend protojson", async () => {
+    const result = await callTool("get_mcp_server", { org: "acme", slug: "github" });
+    expect(result.isError).toBeFalsy();
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(McpServerSchema, knownMcpServer, { useProtoFieldName: true }),
+    );
+  });
+
+  it("get_workflow returns the backend protojson", async () => {
+    const result = await callTool("get_workflow", { org: "acme", slug: "release" });
+    expect(result.isError).toBeFalsy();
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(WorkflowSchema, knownWorkflow, { useProtoFieldName: true }),
+    );
+  });
+
+  it("get_skill returns the backend protojson and defaults version to latest", async () => {
+    const result = await callTool("get_skill", { org: "acme", slug: "code-review" });
+    expect(result.isError).toBeFalsy();
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual(
+      toJson(SkillSchema, knownSkill, { useProtoFieldName: true }),
+    );
+    // Omitted version is forwarded as the empty string ("latest").
+    expect(lastSkillVersion).toBe("");
+  });
+
+  it("get_skill forwards an explicit version to the backend", async () => {
+    await callTool("get_skill", { org: "acme", slug: "code-review", version: "stable" });
+    expect(lastSkillVersion).toBe("stable");
+  });
+});

package/src/domains/resourcehandler.ts

@@ -0,0 +1,90 @@
+// Registration helpers for MCP resource templates.
+// Go parity: mcp-server/internal/domains/resourcehandler.go.
+//
+// Every Stigmer resource template resolves the per-request credential the same
+// way tools do (resolveToken over extra.authInfo), parses org/slug[/version]
+// from the request URI, delegates to the domain fetch, and returns a single
+// application/json content entry. These helpers keep each domain's resources.ts
+// a one-liner and ensure the auth + result shape stay identical across domains.
+
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+
+import { resolveToken, type BackendTarget } from "./client.js";
+import { parseResourceURI, parseVersionedResourceURI } from "./resourceuri.js";
+
+/** Domain read used by a non-versioned resource template. */
+export type ResourceFetch = (
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+) => Promise<string>;
+
+/** Domain read used by a versioned resource template ("" version means latest). */
+export type VersionedResourceFetch = (
+  serverAddress: string,
+  token: string,
+  org: string,
+  slug: string,
+  version: string,
+) => Promise<string>;
+
+/** Options shared by both registration helpers. */
+interface ResourceOptions {
+  /** Stable resource name surfaced in resources/templates/list (e.g. stigmer_agent). */
+  readonly name: string;
+  /** Human title surfaced to clients (e.g. "Stigmer Agent"). */
+  readonly title: string;
+  /** Human description surfaced to clients. */
+  readonly description: string;
+  /** RFC-6570 URI template, e.g. stigmer://agents/{org}/{slug}. */
+  readonly template: string;
+}
+
+/** Register a stigmer://{authority}/{org}/{slug} resource template. */
+export function registerResource(
+  server: McpServer,
+  target: BackendTarget,
+  opts: ResourceOptions & { readonly fetch: ResourceFetch },
+): void {
+  server.registerResource(
+    opts.name,
+    new ResourceTemplate(opts.template, { list: undefined }),
+    { title: opts.title, description: opts.description, mimeType: "application/json" },
+    async (uri, _vars, extra) => {
+      const { org, slug } = parseResourceURI(uri.href);
+      const text = await opts.fetch(target.serverAddress, resolveToken(extra, target.apiKey), org, slug);
+      return jsonResource(uri.href, text);
+    },
+  );
+}
+
+/** Register a stigmer://{authority}/{org}/{slug}[/{version}] resource template. */
+export function registerVersionedResource(
+  server: McpServer,
+  target: BackendTarget,
+  opts: ResourceOptions & { readonly fetch: VersionedResourceFetch },
+): void {
+  server.registerResource(
+    opts.name,
+    new ResourceTemplate(opts.template, { list: undefined }),
+    { title: opts.title, description: opts.description, mimeType: "application/json" },
+    async (uri, _vars, extra) => {
+      const { org, slug, version } = parseVersionedResourceURI(uri.href);
+      const text = await opts.fetch(
+        target.serverAddress,
+        resolveToken(extra, target.apiKey),
+        org,
+        slug,
+        version,
+      );
+      return jsonResource(uri.href, text);
+    },
+  );
+}
+
+/** Wrap fetched JSON text into the single-entry ReadResourceResult tools expect. */
+function jsonResource(uri: string, text: string): ReadResourceResult {
+  return { contents: [{ uri, mimeType: "application/json", text }] };
+}

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

@@ -0,0 +1,139 @@
+// In-process integration test for the 5 resource templates. Verifies template
+// discovery, that each read returns the backend protojson as a single
+// application/json entry, and that the skill templates resolve latest (empty
+// version) vs a pinned version.
+
+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 { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { SkillSchema } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/api_pb";
+import { SkillQueryController } from "@stigmer/protos/ai/stigmer/agentic/skill/v1/query_pb";
+import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/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 agent = create(AgentSchema, { apiVersion: "v1", kind: "agent", metadata: { slug: "a", org: "acme" } });
+const mcpServer = create(McpServerSchema, {
+  apiVersion: "v1",
+  kind: "mcp_server",
+  metadata: { slug: "m", org: "acme" },
+});
+const skill = create(SkillSchema, { apiVersion: "v1", kind: "skill", metadata: { slug: "s", org: "acme" } });
+const workflow = create(WorkflowSchema, {
+  apiVersion: "v1",
+  kind: "workflow",
+  metadata: { slug: "w", org: "acme" },
+});
+
+let backend: Http2Server;
+let client: Client;
+let lastSkillVersion: string | undefined;
+const openSessions = new Set<ServerHttp2Session>();
+
+interface ResourceResult {
+  contents: Array<{ uri: string; mimeType?: string; text?: string }>;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(AgentQueryController, { getByReference: () => agent });
+    router.service(McpServerQueryController, { getByReference: () => mcpServer });
+    router.service(SkillQueryController, {
+      getByReference: (req) => {
+        lastSkillVersion = req.version;
+        return skill;
+      },
+    });
+    router.service(WorkflowQueryController, { getByReference: () => workflow });
+  };
+  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: "resources-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("resource templates integration", () => {
+  it("advertises all five templates", async () => {
+    const { resourceTemplates } = await client.listResourceTemplates();
+    expect(resourceTemplates.map((t) => t.name)).toEqual(
+      expect.arrayContaining([
+        "stigmer_agent",
+        "stigmer_mcp_server",
+        "stigmer_skill",
+        "stigmer_skill_version",
+        "stigmer_workflow",
+      ]),
+    );
+  });
+
+  it("reads an agent resource", async () => {
+    const result = (await client.readResource({ uri: "stigmer://agents/acme/a" })) as ResourceResult;
+    expect(result.contents[0]?.mimeType).toBe("application/json");
+    expect(JSON.parse(result.contents[0]?.text ?? "{}")).toEqual(
+      toJson(AgentSchema, agent, { useProtoFieldName: true }),
+    );
+  });
+
+  it("reads an mcp-server resource", async () => {
+    const result = (await client.readResource({
+      uri: "stigmer://mcp-servers/acme/m",
+    })) as ResourceResult;
+    expect(JSON.parse(result.contents[0]?.text ?? "{}")).toEqual(
+      toJson(McpServerSchema, mcpServer, { useProtoFieldName: true }),
+    );
+  });
+
+  it("reads a workflow resource", async () => {
+    const result = (await client.readResource({
+      uri: "stigmer://workflows/acme/w",
+    })) as ResourceResult;
+    expect(JSON.parse(result.contents[0]?.text ?? "{}")).toEqual(
+      toJson(WorkflowSchema, workflow, { useProtoFieldName: true }),
+    );
+  });
+
+  it("reads the latest skill (empty version)", async () => {
+    const result = (await client.readResource({ uri: "stigmer://skills/acme/s" })) as ResourceResult;
+    expect(JSON.parse(result.contents[0]?.text ?? "{}")).toEqual(
+      toJson(SkillSchema, skill, { useProtoFieldName: true }),
+    );
+    expect(lastSkillVersion).toBe("");
+  });
+
+  it("reads a pinned skill version", async () => {
+    await client.readResource({ uri: "stigmer://skills/acme/s/v2.0.0" });
+    expect(lastSkillVersion).toBe("v2.0.0");
+  });
+});