@langwatch/mcp-server 1.0.0 → 2.1.0

package/src/__tests__/docker.integration.test.ts

@@ -4,7 +4,16 @@ import { execSync } from "child_process";
 const IMAGE_NAME = "langwatch-mcp-server-test";
 const CONTAINER_NAME = "langwatch-mcp-server-test-container";
 const HOST_PORT = 13099; // unlikely to conflict
-const BEARER_TOKEN = "test-docker-api-key";
+
+/**
+ * HTTP mode verifies the bearer against the LangWatch API before creating a
+ * session, so the authenticated paths need a key the API actually accepts.
+ * Without one, this file still covers startup, CORS, and rejection.
+ */
+const BEARER_TOKEN = process.env.LANGWATCH_API_KEY;
+
+/** A syntactically fine token that the LangWatch API does not know. */
+const BOGUS_TOKEN = "totally-not-a-real-key";
 
 /** Standard headers required by the MCP Streamable HTTP protocol */
 const MCP_POST_HEADERS = {
@@ -20,7 +29,7 @@ describe("Docker container", () => {
       // Build from repo root (mcp-server needs langevals/ for build)
       const repoRoot = process.cwd().replace(/\/mcp-server.*$/, "");
       execSync(
-        `docker build -t ${IMAGE_NAME} -f mcp-server/Dockerfile .`,
+        `docker build -t ${IMAGE_NAME} -f mcp/typescript/Dockerfile .`,
         {
           cwd: repoRoot,
           stdio: "pipe",
@@ -85,11 +94,86 @@ describe("Docker container", () => {
     expect(body.status).toBe("ok");
   });
 
-  it("CORS headers are present", async () => {
+  it("does not answer with a wildcard CORS origin", async () => {
     if (!containerRunning) return;
 
     const res = await fetch(`http://localhost:${HOST_PORT}/health`);
-    expect(res.headers.get("access-control-allow-origin")).toBe("*");
+    expect(res.headers.get("access-control-allow-origin")).not.toBe("*");
+  });
+
+  it("reflects an allowed origin and rejects an unlisted one", async () => {
+    if (!containerRunning) return;
+
+    const allowed = await fetch(`http://localhost:${HOST_PORT}/health`, {
+      headers: { Origin: "http://localhost:5173" },
+    });
+    expect(allowed.status).toBe(200);
+    expect(allowed.headers.get("access-control-allow-origin")).toBe(
+      "http://localhost:5173"
+    );
+
+    const rejected = await fetch(`http://localhost:${HOST_PORT}/health`, {
+      headers: { Origin: "https://attacker.example" },
+    });
+    expect(rejected.status).toBe(403);
+  });
+
+  it("rejects a bearer the LangWatch API does not recognise", async () => {
+    if (!containerRunning) return;
+
+    const res = await fetch(`http://localhost:${HOST_PORT}/mcp`, {
+      method: "POST",
+      headers: {
+        ...MCP_POST_HEADERS,
+        Authorization: `Bearer ${BOGUS_TOKEN}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2025-03-26",
+          capabilities: {},
+          clientInfo: { name: "docker-test", version: "1.0.0" },
+        },
+      }),
+    });
+
+    expect(res.status).toBe(401);
+    expect(res.headers.get("mcp-session-id")).toBeNull();
+  });
+
+  it("rejects a session id presented without a bearer token", async () => {
+    if (!containerRunning || !BEARER_TOKEN) return;
+
+    const initRes = await fetch(`http://localhost:${HOST_PORT}/mcp`, {
+      method: "POST",
+      headers: {
+        ...MCP_POST_HEADERS,
+        Authorization: `Bearer ${BEARER_TOKEN}`,
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+          protocolVersion: "2025-03-26",
+          capabilities: {},
+          clientInfo: { name: "docker-test", version: "1.0.0" },
+        },
+      }),
+    });
+    const sessionId = initRes.headers.get("mcp-session-id");
+    expect(sessionId).toBeTruthy();
+    await initRes.text();
+
+    const res = await fetch(`http://localhost:${HOST_PORT}/mcp`, {
+      method: "POST",
+      headers: { ...MCP_POST_HEADERS, "mcp-session-id": sessionId! },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" }),
+    });
+
+    expect(res.status).toBe(401);
   });
 
   it("returns 401 on initialize without Bearer token", async () => {
@@ -116,7 +200,7 @@ describe("Docker container", () => {
   });
 
   it("MCP initialize works with Bearer token", async () => {
-    if (!containerRunning) return;
+    if (!containerRunning || !BEARER_TOKEN) return;
 
     const res = await fetch(`http://localhost:${HOST_PORT}/mcp`, {
       method: "POST",
@@ -146,7 +230,7 @@ describe("Docker container", () => {
   });
 
   it("lists tools after initialization with Bearer token", async () => {
-    if (!containerRunning) return;
+    if (!containerRunning || !BEARER_TOKEN) return;
 
     // Initialize a session
     const initRes = await fetch(`http://localhost:${HOST_PORT}/mcp`, {
@@ -205,7 +289,7 @@ describe("Docker container", () => {
   });
 
   it("legacy SSE endpoint responds with Bearer token", async () => {
-    if (!containerRunning) return;
+    if (!containerRunning || !BEARER_TOKEN) return;
 
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 5000);

package/src/__tests__/documentation-fetch-security.integration.test.ts

@@ -3,10 +3,13 @@ import { afterAll, beforeAll, describe, expect, it } from "vitest";
 
 import { initConfig } from "../config.js";
 import { fetchDocumentation, resolveDocumentationUrl } from "../documentation-fetch.js";
+import { countingVerifier } from "./support/http-server-harness.js";
+
+const TEST_API_KEY = "security-regression-test";
 
 const MCP_HEADERS = {
   Accept: "application/json, text/event-stream",
-  Authorization: "Bearer security-regression-test",
+  Authorization: `Bearer ${TEST_API_KEY}`,
   "Content-Type": "application/json",
 };
 
@@ -95,7 +98,10 @@ describe("MCP documentation fetch security", () => {
 
       initConfig({ endpoint: "https://app.langwatch.ai" });
       const { startHttpServer } = await import("../http-server.js");
-      const started = await startHttpServer({ port: 0 });
+      // These cases are about SSRF in the documentation tools, so the key check
+      // is stubbed to keep the test on its own subject.
+      const { verifier } = countingVerifier([TEST_API_KEY]);
+      const started = await startHttpServer({ port: 0, apiKeyVerifier: verifier });
       mcpServer = started.server;
       mcpPort = started.port;
 

package/src/__tests__/feature-map-tool-drift.unit.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Drift guard between the MCP tools this server registers and the names
+ * `feature-map.json` tells agents to call.
+ *
+ * The feature map is the canonical information architecture: it is embedded
+ * into the CLI at codegen time and shipped inside the npx server package, so a
+ * name in it is a name an agent will try. Two entries pointed at
+ * `platform_run_evaluation` and `platform_evaluation_status`, which have never
+ * existed — the tools are `platform_run_experiment` and
+ * `platform_experiment_status`. An agent following the map for the experiments
+ * feature called two tools that were not there.
+ *
+ * Nothing compared the two lists, which is why it went unnoticed. This does.
+ *
+ * @see .claude/skills/feature-map/SKILL.md
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const REPO_ROOT = join(__dirname, "../../../..");
+
+/**
+ * Every tool name the feature map hands to an agent, from any depth: `mcp`
+ * arrays hang off surfaces nested several levels into the tree.
+ */
+function toolNamesInFeatureMap(): Set<string> {
+  const map: unknown = JSON.parse(
+    readFileSync(join(REPO_ROOT, "feature-map.json"), "utf-8")
+  );
+  const names = new Set<string>();
+
+  const walk = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item);
+      return;
+    }
+    if (node === null || typeof node !== "object") return;
+
+    const entry = node as Record<string, unknown>;
+    if (Array.isArray(entry.mcp)) {
+      for (const name of entry.mcp) {
+        if (typeof name === "string") names.add(name);
+      }
+    }
+    for (const value of Object.values(entry)) walk(value);
+  };
+
+  walk(map);
+  return names;
+}
+
+/**
+ * Every name passed as the first argument of a `server.tool(` registration.
+ *
+ * Read from the source rather than by constructing a server: building one
+ * needs config and credentials this test has no business holding, and the
+ * registration is a string literal in every case.
+ */
+function registeredToolNames(): Set<string> {
+  const source = readFileSync(
+    join(__dirname, "../create-mcp-server.ts"),
+    "utf-8"
+  );
+  const names = new Set<string>();
+  for (const match of source.matchAll(/server\.tool\(\s*"([^"]+)"/g)) {
+    names.add(match[1]!);
+  }
+  return names;
+}
+
+describe("feature map MCP tool names", () => {
+  describe("given the tools this server registers", () => {
+    it("names only tools that exist", () => {
+      const registered = registeredToolNames();
+      const missing = [...toolNamesInFeatureMap()]
+        .filter((name) => !registered.has(name))
+        .sort();
+
+      // Listed, not registered: an agent following the map calls a tool that
+      // is not there. Either rename the entry, or register the tool.
+      expect(missing).toEqual([]);
+    });
+
+    it("finds the registrations it is reading", () => {
+      // A regex that silently matched nothing would make the check above pass
+      // for the wrong reason.
+      const registered = registeredToolNames();
+      expect(registered.size).toBeGreaterThan(50);
+      expect(registered).toContain("platform_run_experiment");
+    });
+  });
+});

package/src/__tests__/http-security-origin.unit.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_BIND_HOST,
+  isLoopbackHost,
+  isOriginAllowed,
+  parseAllowedOrigins,
+} from "../http-security.js";
+
+describe("bind host", () => {
+  it("defaults to loopback", () => {
+    expect(DEFAULT_BIND_HOST).toBe("127.0.0.1");
+    expect(isLoopbackHost(DEFAULT_BIND_HOST)).toBe(true);
+  });
+
+  it.each(["127.0.0.1", "localhost", "::1", "[::1]", " LOCALHOST "])(
+    "recognises %s as loopback",
+    (host) => {
+      expect(isLoopbackHost(host)).toBe(true);
+    }
+  );
+
+  it.each(["0.0.0.0", "::", "192.168.1.10", "10.0.0.1", "example.com"])(
+    "does not treat %s as loopback",
+    (host) => {
+      expect(isLoopbackHost(host)).toBe(false);
+    }
+  );
+});
+
+describe("parseAllowedOrigins", () => {
+  it("returns an empty list when nothing is configured", () => {
+    expect(parseAllowedOrigins(undefined)).toEqual([]);
+    expect(parseAllowedOrigins("")).toEqual([]);
+  });
+
+  it("splits, trims, and normalizes entries", () => {
+    expect(
+      parseAllowedOrigins(" https://Example.com/ , https://app.test:8443 ")
+    ).toEqual(["https://example.com", "https://app.test:8443"]);
+  });
+
+  it("drops entries that are not usable origins", () => {
+    expect(parseAllowedOrigins("not-an-origin, https://ok.test")).toEqual([
+      "https://ok.test",
+    ]);
+  });
+
+  it("deduplicates equivalent origins", () => {
+    expect(parseAllowedOrigins("https://a.test,https://a.test/")).toEqual([
+      "https://a.test",
+    ]);
+  });
+});
+
+describe("isOriginAllowed", () => {
+  it.each([
+    "http://localhost:5173",
+    "http://127.0.0.1:3000",
+    "http://[::1]:3000",
+    "https://localhost",
+  ])("always allows the loopback origin %s", (origin) => {
+    expect(isOriginAllowed({ origin, allowedOrigins: [] })).toBe(true);
+  });
+
+  it("rejects an unlisted remote origin", () => {
+    expect(isOriginAllowed({ origin: "https://evil.test", allowedOrigins: [] })).toBe(false);
+  });
+
+  it("allows a configured remote origin", () => {
+    expect(isOriginAllowed({ origin: "https://app.test", allowedOrigins: ["https://app.test"] })).toBe(
+      true
+    );
+  });
+
+  it("matches on scheme, host and port together", () => {
+    const allowlist = ["https://app.test"];
+    expect(isOriginAllowed({ origin: "http://app.test", allowedOrigins: allowlist })).toBe(false);
+    expect(isOriginAllowed({ origin: "https://app.test:8443", allowedOrigins: allowlist })).toBe(false);
+    expect(isOriginAllowed({ origin: "https://other.test", allowedOrigins: allowlist })).toBe(false);
+  });
+
+  it("does not let a hostname that merely ends in localhost through", () => {
+    expect(isOriginAllowed({ origin: "https://notlocalhost", allowedOrigins: [] })).toBe(false);
+    expect(isOriginAllowed({ origin: "https://evil-localhost.test", allowedOrigins: [] })).toBe(false);
+  });
+
+  it("rejects the opaque null origin", () => {
+    expect(isOriginAllowed({ origin: "null", allowedOrigins: [] })).toBe(false);
+  });
+
+  it("treats a rebound attacker hostname as unlisted", () => {
+    // DNS rebinding points an attacker hostname at loopback, but the browser
+    // still sends the attacker hostname as the origin.
+    expect(isOriginAllowed({ origin: "http://rebind.attacker.test", allowedOrigins: [] })).toBe(false);
+  });
+});

package/src/__tests__/http-security-sessions.unit.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { admitOAuthToken, createSessionStore } from "../http-security.js";
+
+describe("createSessionStore", () => {
+  function makeStore(maxAgeMs = 60_000) {
+    const closed: string[] = [];
+    const store = createSessionStore<{ id: string }>({
+      maxAgeMs,
+      closeTransport: (transport) => closed.push(transport.id),
+    });
+    return { store, closed };
+  }
+
+  it("stores and returns sessions bound to their key", () => {
+    const { store } = makeStore();
+    store.add({ sessionId: "s1", transport: { id: "s1" }, apiKey: "sk-a" });
+
+    expect(store.get("s1")?.apiKey).toBe("sk-a");
+    expect(store.size).toBe(1);
+  });
+
+  it("counts live sessions per key without holding the raw key", () => {
+    const { store } = makeStore();
+    store.add({ sessionId: "s1", transport: { id: "s1" }, apiKey: "sk-a" });
+    store.add({ sessionId: "s2", transport: { id: "s2" }, apiKey: "sk-a" });
+    store.add({ sessionId: "s3", transport: { id: "s3" }, apiKey: "sk-b" });
+
+    expect(store.countForKey("sk-a")).toBe(2);
+    expect(store.countForKey("sk-b")).toBe(1);
+    expect(store.countForKey("sk-unknown")).toBe(0);
+  });
+
+  it("decrements the per-key count when a session is removed", () => {
+    const { store } = makeStore();
+    store.add({ sessionId: "s1", transport: { id: "s1" }, apiKey: "sk-a" });
+    store.add({ sessionId: "s2", transport: { id: "s2" }, apiKey: "sk-a" });
+
+    store.remove("s1");
+    expect(store.countForKey("sk-a")).toBe(1);
+
+    store.remove("s2");
+    expect(store.countForKey("sk-a")).toBe(0);
+  });
+
+  it("ignores removal of a session it does not hold", () => {
+    const { store } = makeStore();
+    store.add({ sessionId: "s1", transport: { id: "s1" }, apiKey: "sk-a" });
+
+    store.remove("never-existed");
+    store.remove("never-existed");
+
+    expect(store.countForKey("sk-a")).toBe(1);
+  });
+
+  it("closes and forgets sessions that have gone idle", () => {
+    vi.useFakeTimers();
+    try {
+      const { store, closed } = makeStore(1_000);
+      store.add({ sessionId: "idle", transport: { id: "idle" }, apiKey: "sk-a" });
+      store.add({ sessionId: "busy", transport: { id: "busy" }, apiKey: "sk-a" });
+
+      vi.advanceTimersByTime(900);
+      store.touch("busy");
+      vi.advanceTimersByTime(900);
+      store.sweep();
+
+      expect(closed).toEqual(["idle"]);
+      expect(store.get("idle")).toBeUndefined();
+      expect(store.get("busy")).toBeDefined();
+      expect(store.countForKey("sk-a")).toBe(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("closes everything on shutdown", () => {
+    const { store, closed } = makeStore();
+    store.add({ sessionId: "s1", transport: { id: "s1" }, apiKey: "sk-a" });
+    store.add({ sessionId: "s2", transport: { id: "s2" }, apiKey: "sk-b" });
+
+    store.closeAll();
+
+    expect(closed.sort()).toEqual(["s1", "s2"]);
+    expect(store.size).toBe(0);
+    expect(store.countForKey("sk-a")).toBe(0);
+  });
+
+  it("does not let a prototype-shaped session id reach the prototype chain", () => {
+    const { store } = makeStore();
+
+    expect(store.get("__proto__")).toBeUndefined();
+    expect(store.get("constructor")).toBeUndefined();
+
+    store.add({ sessionId: "__proto__", transport: { id: "weird" }, apiKey: "sk-a" });
+    expect(store.get("__proto__")?.transport.id).toBe("weird");
+    expect(store.size).toBe(1);
+  });
+});
+
+describe("session reservations", () => {
+  function makeStore() {
+    return createSessionStore<{ id: string }>({
+      maxAgeMs: 60_000,
+      closeTransport: () => undefined,
+    });
+  }
+
+  it("counts a reserved slot before any session exists", () => {
+    const store = makeStore();
+    store.reserve("sk-a");
+
+    // The point of the reservation: the cap sees the slot while the session is
+    // still being set up.
+    expect(store.countForKey("sk-a")).toBe(1);
+    expect(store.size).toBe(0);
+  });
+
+  it("hands the reserved slot to the session rather than counting twice", () => {
+    const store = makeStore();
+    store.reserve("sk-a").commit({ sessionId: "s1", transport: { id: "s1" } });
+
+    expect(store.countForKey("sk-a")).toBe(1);
+    expect(store.get("s1")?.apiKey).toBe("sk-a");
+  });
+
+  it("returns the slot when the session never came up", () => {
+    const store = makeStore();
+    const reservation = store.reserve("sk-a");
+    reservation.release();
+
+    expect(store.countForKey("sk-a")).toBe(0);
+  });
+
+  it("ignores a release once the slot was committed", () => {
+    const store = makeStore();
+    const reservation = store.reserve("sk-a");
+    reservation.commit({ sessionId: "s1", transport: { id: "s1" } });
+    reservation.release();
+
+    expect(store.countForKey("sk-a")).toBe(1);
+    expect(store.get("s1")).toBeDefined();
+  });
+
+  it("frees the slot when the committed session is removed", () => {
+    const store = makeStore();
+    store.reserve("sk-a").commit({ sessionId: "s1", transport: { id: "s1" } });
+    store.remove("s1");
+
+    expect(store.countForKey("sk-a")).toBe(0);
+  });
+});
+
+describe("admitOAuthToken", () => {
+  function entry(apiKey: string, expiresAt: number) {
+    return { apiKey, expiresAt };
+  }
+
+  it("evicts the oldest token for a key that is at the cap", () => {
+    const tokens = new Map([
+      ["t1", entry("sk-a", Date.now() + 1_000)],
+      ["t2", entry("sk-a", Date.now() + 2_000)],
+      ["t3", entry("sk-a", Date.now() + 3_000)],
+    ]);
+
+    admitOAuthToken({ apiKey: "sk-a", tokens, maxPerKey: 3 });
+
+    // Room for the caller's new token, and the longest-standing one went.
+    expect(tokens.has("t1")).toBe(false);
+    expect([...tokens.keys()]).toEqual(["t2", "t3"]);
+  });
+
+  it("leaves other keys alone", () => {
+    const tokens = new Map([
+      ["t1", entry("sk-a", Date.now() + 1_000)],
+      ["t2", entry("sk-b", Date.now() + 1_000)],
+      ["t3", entry("sk-b", Date.now() + 2_000)],
+    ]);
+
+    admitOAuthToken({ apiKey: "sk-a", tokens, maxPerKey: 1 });
+
+    expect(tokens.has("t1")).toBe(false);
+    expect(tokens.has("t2")).toBe(true);
+    expect(tokens.has("t3")).toBe(true);
+  });
+
+  it("keeps a key from growing the map without bound", () => {
+    const tokens = new Map<string, { apiKey: string; expiresAt: number }>();
+
+    for (let i = 0; i < 50; i += 1) {
+      admitOAuthToken({ apiKey: "sk-a", tokens, maxPerKey: 10 });
+      tokens.set(`t${i}`, entry("sk-a", Date.now() + 60_000 + i));
+    }
+
+    expect(tokens.size).toBe(10);
+  });
+
+  it("drops expired tokens for any key on the way past", () => {
+    const tokens = new Map([
+      ["stale", entry("sk-b", Date.now() - 1)],
+      ["live", entry("sk-b", Date.now() + 60_000)],
+    ]);
+
+    admitOAuthToken({ apiKey: "sk-a", tokens, maxPerKey: 10 });
+
+    expect(tokens.has("stale")).toBe(false);
+    expect(tokens.has("live")).toBe(true);
+  });
+});