@stigmer/mcp-server 3.0.8-dev.20260612122433

package/src/http.integration.test.ts

@@ -0,0 +1,140 @@
+// HTTP transport hardening + OAuth discovery tests.
+//
+// Boots the real Streamable HTTP transport on a loopback port and exercises the
+// additive surface added in Phase 6: the /health probe, RFC 9728 protected
+// resource metadata (GET + CORS preflight), and the WWW-Authenticate challenge
+// on token-less requests. Token validation is never performed here — presence is
+// the only check (Go parity: internal/server/http.go).
+
+import { createServer as createNetServer, type AddressInfo } from "node:net";
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import type { Config } from "./config";
+import { configureLogger } from "./logger";
+import { createServer, serveHttp } from "./server";
+
+configureLogger({ level: "error", format: "text" });
+
+let port: number;
+let controller: AbortController;
+let serving: Promise<void>;
+
+function freePort(): Promise<number> {
+  return new Promise((resolve) => {
+    const s = createNetServer();
+    s.listen(0, "127.0.0.1", () => {
+      const p = (s.address() as AddressInfo).port;
+      s.close(() => resolve(p));
+    });
+  });
+}
+
+beforeAll(async () => {
+  port = await freePort();
+  const cfg: Config = {
+    stigmerServerAddress: "localhost:7234",
+    apiKey: "",
+    transport: "http",
+    httpPort: String(port),
+    httpAuthEnabled: true,
+    oauth: {
+      enabled: true,
+      resource: "https://mcp.stigmer.ai",
+      authorizationServers: ["https://auth.example.com"],
+      scopesSupported: ["read", "write"],
+    },
+    logFormat: "text",
+    logLevel: "error",
+  };
+  controller = new AbortController();
+  serving = serveHttp(() => createServer({ serverAddress: cfg.stigmerServerAddress, apiKey: "" }), cfg, controller.signal);
+  // Give the listener a tick to bind.
+  await new Promise((r) => setTimeout(r, 100));
+});
+
+afterAll(async () => {
+  controller.abort();
+  await serving;
+});
+
+const base = () => `http://127.0.0.1:${port}`;
+
+describe("HTTP transport hardening + OAuth discovery", () => {
+  it("answers the /health probe without auth", async () => {
+    const res = await fetch(`${base()}/health`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: "ok" });
+  });
+
+  it("serves RFC 9728 protected resource metadata", async () => {
+    const res = await fetch(`${base()}/.well-known/oauth-protected-resource`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("access-control-allow-origin")).toBe("*");
+    expect(await res.json()).toEqual({
+      resource: "https://mcp.stigmer.ai",
+      authorization_servers: ["https://auth.example.com"],
+      bearer_methods_supported: ["header"],
+      resource_name: "Stigmer MCP Server",
+      scopes_supported: ["read", "write"],
+    });
+  });
+
+  it("answers the CORS preflight for the metadata document", async () => {
+    const res = await fetch(`${base()}/.well-known/oauth-protected-resource`, { method: "OPTIONS" });
+    expect(res.status).toBe(204);
+    expect(res.headers.get("access-control-allow-origin")).toBe("*");
+    expect(res.headers.get("access-control-allow-methods")).toContain("GET");
+  });
+
+  it("challenges token-less requests with WWW-Authenticate", async () => {
+    const res = await fetch(`${base()}/`, { method: "POST", body: "{}" });
+    expect(res.status).toBe(401);
+    const challenge = res.headers.get("www-authenticate") ?? "";
+    expect(challenge).toContain('realm="stigmer"');
+    expect(challenge).toContain(
+      'resource_metadata="https://mcp.stigmer.ai/.well-known/oauth-protected-resource"',
+    );
+    expect(challenge).toContain('scope="read write"');
+  });
+
+  it("rejects a malformed Authorization header as token-less", async () => {
+    // A non-"Bearer " scheme yields an empty token and is treated as missing.
+    const res = await fetch(`${base()}/`, {
+      method: "POST",
+      headers: { authorization: "Basic Zm9vOmJhcg==" },
+      body: "{}",
+    });
+    expect(res.status).toBe(401);
+    expect(res.headers.get("www-authenticate") ?? "").toContain('realm="stigmer"');
+  });
+
+  it("returns 404 for an unknown MCP session even with a valid token", async () => {
+    const res = await fetch(`${base()}/`, {
+      method: "POST",
+      headers: { authorization: "Bearer test-token", "mcp-session-id": "does-not-exist" },
+      body: "{}",
+    });
+    expect(res.status).toBe(404);
+    expect(await res.text()).toContain("unknown or expired MCP session");
+  });
+
+  it("rejects a sessionless non-initialize POST", async () => {
+    const res = await fetch(`${base()}/`, {
+      method: "POST",
+      headers: { authorization: "Bearer test-token", "content-type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
+    });
+    expect(res.status).toBe(400);
+    expect(await res.text()).toContain("an initialize request is required");
+  });
+
+  it("rejects a sessionless GET (no Mcp-Session-Id)", async () => {
+    const res = await fetch(`${base()}/`, {
+      method: "GET",
+      headers: { authorization: "Bearer test-token" },
+    });
+    expect(res.status).toBe(400);
+    expect(await res.text()).toContain("missing Mcp-Session-Id header");
+  });
+});

package/src/index.ts

@@ -0,0 +1,66 @@
+// Public, embeddable surface for the Stigmer MCP server.
+//
+// Mirrors Go pkg/mcpserver: a minimal API — load a Config from the environment,
+// then run() the server until the provided AbortSignal fires. The Stigmer CLI
+// (and any other host) embeds the server through this module.
+
+import { loadConfigFromEnv, validateConfig, type Config } from "./config.js";
+import { configureLogger, log } from "./logger.js";
+import { createServer, serveBoth, serveHttp, serveStdio, isNormalShutdown } from "./server.js";
+import type { BackendTarget } from "./domains/client.js";
+
+export type { Config, OAuthConfig, Transport } from "./config.js";
+export { loadConfigFromEnv, validateConfig } from "./config.js";
+export { createServer, SERVER_VERSION } from "./server.js";
+
+/** Returns a Config populated from environment variables (no validation). */
+export function defaultConfig(): Config {
+  return loadConfigFromEnv();
+}
+
+/**
+ * Start the MCP server with the given configuration and run until `signal`
+ * aborts or a fatal error occurs. The caller owns signal handling:
+ *
+ * ```ts
+ * const ac = new AbortController();
+ * process.on("SIGINT", () => ac.abort());
+ * await run(defaultConfig(), ac.signal);
+ * ```
+ *
+ * A clean client disconnect resolves normally (see {@link isNormalShutdown}).
+ */
+export async function run(cfg: Config, signal: AbortSignal): Promise<void> {
+  configureLogger({ level: cfg.logLevel, format: cfg.logFormat });
+  validateConfig(cfg);
+
+  log.info("mcp-server-stigmer starting", { transport: cfg.transport });
+
+  const target: BackendTarget = {
+    serverAddress: cfg.stigmerServerAddress,
+    apiKey: cfg.apiKey,
+  };
+
+  try {
+    switch (cfg.transport) {
+      case "stdio":
+        await serveStdio(createServer(target), signal);
+        break;
+      case "http":
+        await serveHttp(() => createServer(target), cfg, signal);
+        break;
+      case "both":
+        await serveBoth(target, cfg, signal);
+        break;
+    }
+  } catch (err) {
+    if (!isNormalShutdown(err)) {
+      log.error("mcp-server-stigmer stopped", {
+        error: err instanceof Error ? err.message : String(err),
+      });
+      throw err;
+    }
+  }
+
+  log.info("mcp-server-stigmer stopped");
+}

package/src/logger.ts

@@ -0,0 +1,49 @@
+// Process-wide structured logger for mcp-server-stigmer.
+//
+// All output goes to stderr: in stdio transport mode, stdout is reserved for
+// the MCP JSON-RPC stream, so any stray stdout write would corrupt the
+// protocol. This mirrors the Go server's `initLogger` (slog → stderr).
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogFormat = "text" | "json";
+
+const LEVEL_ORDER: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+
+let minLevel: LogLevel = "info";
+let format: LogFormat = "text";
+
+/**
+ * Configure the default logger. Called once at startup from the resolved config.
+ *
+ * Tolerant of invalid inputs (falls back to info/text) so that configuration
+ * validation can still emit a precise error about the bad value through a
+ * working logger, rather than the logger itself crashing first.
+ */
+export function configureLogger(opts: { level: string; format: string }): void {
+  minLevel = opts.level in LEVEL_ORDER ? (opts.level as LogLevel) : "info";
+  format = opts.format === "json" ? "json" : "text";
+}
+
+function emit(level: LogLevel, msg: string, fields?: Record<string, unknown>): void {
+  if (LEVEL_ORDER[level] < LEVEL_ORDER[minLevel]) return;
+
+  if (format === "json") {
+    process.stderr.write(JSON.stringify({ level, msg, ...fields }) + "\n");
+    return;
+  }
+
+  const suffix = fields
+    ? " " +
+      Object.entries(fields)
+        .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+        .join(" ")
+    : "";
+  process.stderr.write(`${level.toUpperCase()} ${msg}${suffix}\n`);
+}
+
+export const log = {
+  debug: (msg: string, fields?: Record<string, unknown>) => emit("debug", msg, fields),
+  info: (msg: string, fields?: Record<string, unknown>) => emit("info", msg, fields),
+  warn: (msg: string, fields?: Record<string, unknown>) => emit("warn", msg, fields),
+  error: (msg: string, fields?: Record<string, unknown>) => emit("error", msg, fields),
+};

package/src/server.integration.test.ts

@@ -0,0 +1,82 @@
+// In-process integration test for the MCP server (the tester gate).
+//
+// Stands up a real in-process Connect server for AgentQueryController, points
+// the MCP server at it, drives it through an in-memory MCP client, and asserts:
+//   - tools/list advertises get_agent
+//   - get_agent returns the agent's protojson, byte-comparable (after parse)
+//     with the canonical toJson — the parity contract (DD-005).
+
+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 { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { configureLogger } from "./logger";
+import { createServer } from "./server";
+
+configureLogger({ level: "error", format: "text" });
+
+const knownAgent = create(AgentSchema, {
+  apiVersion: "v1",
+  kind: "agent",
+  metadata: { name: "Code Reviewer", slug: "code-reviewer", org: "stigmer", id: "agt-123" },
+});
+
+let backend: Http2Server;
+let client: Client;
+const openSessions = new Set<ServerHttp2Session>();
+
+beforeAll(async () => {
+  // Real in-process Connect (gRPC-web over h2c) backend serving the controller.
+  const routes = (router: ConnectRouter) =>
+    router.service(AgentQueryController, { getByReference: () => knownAgent });
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  // Track keep-alive sessions so teardown can force them closed (otherwise
+  // backend.close() blocks on the per-call transports' idle connections).
+  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: "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("MCP server integration", () => {
+  it("advertises get_agent", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name)).toContain("get_agent");
+  });
+
+  it("get_agent returns protojson matching the canonical toJson output", async () => {
+    const result = (await client.callTool({
+      name: "get_agent",
+      arguments: { org: "stigmer", slug: "code-reviewer" },
+    })) as { content: Array<{ type: string; text?: string }>; isError?: boolean };
+
+    expect(result.isError).toBeFalsy();
+    const parsed = JSON.parse(result.content[0]?.text ?? "{}");
+    expect(parsed).toEqual(toJson(AgentSchema, knownAgent, { useProtoFieldName: true }));
+  });
+});