mcp-test-kits 0.0.0

package/src/introspection.ts

@@ -0,0 +1,216 @@
+/**
+ * Introspection utilities for extracting specifications from MCP Server
+ */
+
+import {
+  McpServer,
+  RegisteredTool,
+  RegisteredResource,
+  RegisteredResourceTemplate,
+  RegisteredPrompt,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+
+/**
+ * Type representing the internal structure of McpServer with private fields exposed
+ */
+interface McpServerInternal {
+  _registeredTools: Record<string, RegisteredTool>;
+  _registeredResources: Record<string, RegisteredResource>;
+  _registeredResourceTemplates: Record<string, RegisteredResourceTemplate>;
+  _registeredPrompts: Record<string, RegisteredPrompt>;
+}
+
+/**
+ * Extended McpServer with introspection capabilities.
+ * Provides access to registered tools, resources, and prompts for spec extraction.
+ */
+export class IntrospectableMcpServer extends McpServer {
+  /**
+   * Get all registered tools with their metadata
+   */
+  getRegisteredTools(): Record<string, RegisteredTool> {
+    // Access the private _registeredTools field (it's an object, not a Map)
+    return (this as unknown as McpServerInternal)._registeredTools;
+  }
+
+  /**
+   * Get all registered resources with their metadata
+   */
+  getRegisteredResources(): Record<string, RegisteredResource> {
+    // Access the private _registeredResources field (it's an object, not a Map)
+    return (this as unknown as McpServerInternal)._registeredResources;
+  }
+
+  /**
+   * Get all registered resource templates with their metadata
+   */
+  getRegisteredResourceTemplates(): Record<string, RegisteredResourceTemplate> {
+    // Access the private _registeredResourceTemplates field (it's an object, not a Map)
+    return (this as unknown as McpServerInternal)._registeredResourceTemplates;
+  }
+
+  /**
+   * Get all registered prompts with their metadata
+   */
+  getRegisteredPrompts(): Record<string, RegisteredPrompt> {
+    // Access the private _registeredPrompts field (it's an object, not a Map)
+    return (this as unknown as McpServerInternal)._registeredPrompts;
+  }
+}
+
+interface ToolSpec {
+  name: string;
+  description: string;
+}
+
+interface ResourceSpec {
+  name: string;
+  uri: string;
+  description?: string;
+  mimeType?: string;
+}
+
+interface PromptArgSpec {
+  name: string;
+  description?: string;
+  required?: boolean;
+}
+
+interface PromptSpec {
+  name: string;
+  description: string;
+  arguments?: PromptArgSpec[];
+}
+
+/**
+ * Extract tool specifications from an introspectable server
+ */
+export function extractToolsSpec(server: IntrospectableMcpServer): ToolSpec[] {
+  const tools: ToolSpec[] = [];
+  const registeredTools = server.getRegisteredTools();
+
+  for (const [name, tool] of Object.entries(registeredTools)) {
+    if (tool.enabled) {
+      tools.push({
+        name,
+        description: tool.description || "",
+      });
+    }
+  }
+
+  return tools.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Extract resource specifications from an introspectable server
+ */
+export function extractResourcesSpec(
+  server: IntrospectableMcpServer,
+): ResourceSpec[] {
+  const resources: ResourceSpec[] = [];
+  const registeredResources = server.getRegisteredResources();
+
+  for (const [uri, resource] of Object.entries(registeredResources)) {
+    if (resource.enabled) {
+      resources.push({
+        name: resource.name,
+        uri,
+        mimeType: resource.metadata?.mimeType || "text/plain",
+      });
+    }
+  }
+
+  // Note: Resource templates are not included in static spec extraction
+  // as they represent dynamic URI patterns
+
+  return resources.sort((a, b) => a.uri.localeCompare(b.uri));
+}
+
+/**
+ * Type representing Zod schema internal structure
+ */
+interface ZodSchemaDef {
+  typeName?: string;
+  shape?: () => Record<string, ZodSchemaInternal>;
+  innerType?: ZodSchemaInternal;
+  description?: string;
+}
+
+interface ZodSchemaInternal {
+  _def: ZodSchemaDef;
+}
+
+/**
+ * Extract argument specifications from Zod schema
+ */
+function extractPromptArgs(argsSchema: ZodSchemaInternal): PromptArgSpec[] {
+  if (!argsSchema || !argsSchema._def) {
+    return [];
+  }
+
+  const args: PromptArgSpec[] = [];
+
+  // Handle Zod object schema
+  if (argsSchema._def.typeName === "ZodObject") {
+    const shape = argsSchema._def.shape?.();
+
+    if (shape) {
+      for (const [argName, argSchema] of Object.entries(shape)) {
+        // Check if the argument is optional
+        const isOptional = argSchema._def.typeName === "ZodOptional";
+        const innerSchema = isOptional ? argSchema._def.innerType : argSchema;
+
+        // Extract description from the schema
+        let description = "";
+        if (innerSchema?._def.description) {
+          description = innerSchema._def.description;
+        }
+
+        args.push({
+          name: argName,
+          description,
+          required: !isOptional,
+        });
+      }
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Extract prompt specifications from an introspectable server
+ */
+export function extractPromptsSpec(
+  server: IntrospectableMcpServer,
+): PromptSpec[] {
+  const prompts: PromptSpec[] = [];
+  const registeredPrompts = server.getRegisteredPrompts();
+
+  for (const [name, prompt] of Object.entries(registeredPrompts)) {
+    if (prompt.enabled) {
+      const args = prompt.argsSchema
+        ? extractPromptArgs(prompt.argsSchema as ZodSchemaInternal)
+        : [];
+
+      prompts.push({
+        name,
+        description: prompt.description || "",
+        arguments: args,
+      });
+    }
+  }
+
+  return prompts.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Extract full specification from an introspectable server
+ */
+export function extractSpec(server: IntrospectableMcpServer) {
+  return {
+    tools: extractToolsSpec(server),
+    resources: extractResourcesSpec(server),
+    prompts: extractPromptsSpec(server),
+  };
+}

package/src/server.ts

@@ -0,0 +1,34 @@
+/**
+ * MCP Server setup for MCP Test Kits
+ */
+
+import { Config } from "./config.js";
+import { IntrospectableMcpServer } from "./introspection.js";
+import { registerTools } from "./capabilities/tools.js";
+import { registerResources } from "./capabilities/resources.js";
+import { registerPrompts } from "./capabilities/prompts.js";
+
+/**
+ * Create and configure the MCP server
+ */
+export function createServer(config: Config): IntrospectableMcpServer {
+  const server = new IntrospectableMcpServer({
+    name: config.server.name,
+    version: config.server.version,
+  });
+
+  // Register capabilities based on config
+  if (config.capabilities.tools) {
+    registerTools(server);
+  }
+
+  if (config.capabilities.resources) {
+    registerResources(server);
+  }
+
+  if (config.capabilities.prompts) {
+    registerPrompts(server);
+  }
+
+  return server;
+}

package/src/transports/http.ts

@@ -0,0 +1,42 @@
+/**
+ * HTTP transport for MCP Test Kits (Streamable HTTP)
+ */
+
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Config } from "../config.js";
+
+/**
+ * Run the MCP server over HTTP transport (Streamable HTTP)
+ */
+export async function runHttpServer(
+  server: McpServer,
+  config: Config,
+): Promise<void> {
+  const { host, port } = config.transport.network;
+
+  const app = express();
+  app.use(express.json());
+
+  // MCP endpoint - handle all HTTP methods
+  app.all("/mcp", async (req, res) => {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true,
+    });
+
+    res.on("close", () => transport.close());
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+
+  // Start server
+  console.error(`Starting MCP HTTP server at http://${host}:${port}/mcp`);
+  app.listen(port, host, () => {
+    console.error(`MCP HTTP server listening on http://${host}:${port}`);
+  });
+
+  // Keep the process running
+  await new Promise(() => {});
+}

package/src/transports/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Transport modules for MCP Test Kits
+ */
+
+export { runStdioServer } from "./stdio.js";
+export { runHttpServer } from "./http.js";
+export { runSseServer } from "./sse.js";

package/src/transports/sse.ts

@@ -0,0 +1,60 @@
+/**
+ * SSE transport for MCP Test Kits
+ */
+
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import type { Config } from "../config.js";
+
+/**
+ * Run the MCP server over SSE transport
+ */
+export async function runSseServer(
+  server: McpServer,
+  config: Config,
+): Promise<void> {
+  const { host, port } = config.transport.network;
+
+  const app = express();
+  app.use(express.json());
+
+  // Store active transports for session management
+  const transports = new Map<string, SSEServerTransport>();
+
+  // SSE endpoint for server->client messages
+  app.get("/sse", async (req, res) => {
+    const transport = new SSEServerTransport("/sse", res);
+    const sessionId = transport.sessionId;
+    transports.set(sessionId, transport);
+
+    // Cleanup on close
+    transport.onclose = () => {
+      transports.delete(sessionId);
+    };
+
+    await server.connect(transport);
+  });
+
+  // POST endpoint for client->server messages
+  app.post("/sse", async (req, res) => {
+    const sessionId = req.query.sessionId as string | undefined;
+
+    if (!sessionId || !transports.has(sessionId)) {
+      res.status(400).json({ error: "Invalid or missing session ID" });
+      return;
+    }
+
+    const transport = transports.get(sessionId)!;
+    await transport.handlePostMessage(req, res, req.body);
+  });
+
+  // Start server
+  console.error(`Starting MCP SSE server at http://${host}:${port}/sse`);
+  app.listen(port, host, () => {
+    console.error(`MCP SSE server listening on http://${host}:${port}`);
+  });
+
+  // Keep the process running
+  await new Promise(() => {});
+}

package/src/transports/stdio.ts

@@ -0,0 +1,21 @@
+/**
+ * Stdio transport for MCP Test Kits
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { Config } from "../config.js";
+
+/**
+ * Run the MCP server over stdio transport
+ */
+export async function runStdioServer(
+  server: McpServer,
+  _config: Config,
+): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Keep the process running
+  await new Promise(() => {});
+}

package/tests/fixtures.ts

@@ -0,0 +1,146 @@
+/**
+ * Shared test fixtures for integration tests.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+/**
+ * Create an MCP client connected via stdio transport.
+ */
+export async function createStdioClient(): Promise<{
+    client: Client;
+    close: () => Promise<void>;
+}> {
+    const transport = new StdioClientTransport({
+        command: "npx",
+        args: ["tsx", "src/index.ts"],
+    });
+
+    const client = new Client({
+        name: "test-client",
+        version: "1.0.0",
+    });
+
+    await client.connect(transport);
+
+    return {
+        client,
+        close: async () => {
+            await client.close();
+        },
+    };
+}
+
+/**
+ * Start an HTTP server and return the base URL.
+ */
+export async function startHttpServer(port: number = 3001): Promise<{
+    url: string;
+    stop: () => void;
+}> {
+    const proc = spawn("npx", ["tsx", "src/index.ts", "--transport", "http", "--port", String(port)], {
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    // Wait for server to start
+    await new Promise<void>((resolve, reject) => {
+        const timeout = setTimeout(() => resolve(), 3000);
+        proc.stderr?.on("data", (data: Buffer) => {
+            if (data.toString().includes("listening")) {
+                clearTimeout(timeout);
+                resolve();
+            }
+        });
+        proc.on("error", reject);
+    });
+
+    return {
+        url: `http://localhost:${port}`,
+        stop: () => {
+            proc.kill();
+        },
+    };
+}
+
+/**
+ * Start an SSE server and return the base URL.
+ */
+export async function startSseServer(port: number = 3002): Promise<{
+    url: string;
+    stop: () => void;
+}> {
+    const proc = spawn("npx", ["tsx", "src/index.ts", "--transport", "sse", "--port", String(port)], {
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    // Wait for server to start
+    await new Promise<void>((resolve, reject) => {
+        const timeout = setTimeout(() => resolve(), 3000);
+        proc.stderr?.on("data", (data: Buffer) => {
+            if (data.toString().includes("listening")) {
+                clearTimeout(timeout);
+                resolve();
+            }
+        });
+        proc.on("error", reject);
+    });
+
+    return {
+        url: `http://localhost:${port}`,
+        stop: () => {
+            proc.kill();
+        },
+    };
+}
+
+/**
+ * Create an MCP client connected via HTTP transport.
+ */
+export async function createHttpClient(serverUrl: string): Promise<{
+    client: Client;
+    close: () => Promise<void>;
+}> {
+    const transport = new StreamableHTTPClientTransport(new URL(`${serverUrl}/mcp`));
+
+    const client = new Client({
+        name: "test-client",
+        version: "1.0.0",
+    });
+
+    await client.connect(transport);
+
+    return {
+        client,
+        close: async () => {
+            await client.close();
+        },
+    };
+}
+
+/**
+ * Create an MCP client connected via SSE transport.
+ */
+export async function createSseClient(serverUrl: string): Promise<{
+    client: Client;
+    close: () => Promise<void>;
+}> {
+    const transport = new SSEClientTransport(new URL(`${serverUrl}/sse`));
+
+    const client = new Client({
+        name: "test-client",
+        version: "1.0.0",
+    });
+
+    await client.connect(transport);
+
+    return {
+        client,
+        close: async () => {
+            await client.close();
+        },
+    };
+}

package/tests/http.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration tests via HTTP transport.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { startHttpServer, createHttpClient } from "./fixtures.js";
+
+describe("HTTP Transport", () => {
+    let serverUrl: string;
+    let stopServer: () => void;
+    let client: Client;
+    let closeClient: () => Promise<void>;
+
+    beforeAll(async () => {
+        const server = await startHttpServer(3001);
+        serverUrl = server.url;
+        stopServer = server.stop;
+
+        const conn = await createHttpClient(serverUrl);
+        client = conn.client;
+        closeClient = conn.close;
+    });
+
+    afterAll(async () => {
+        await closeClient();
+        stopServer();
+    });
+
+    it("should connect and call echo tool", async () => {
+        const result = await client.callTool({ name: "echo", arguments: { message: "test" } });
+        expect((result.content as Array<{ type: string; text: string }>)[0].text).toBe("test");
+    });
+});

package/tests/sse.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Integration tests via SSE transport - smoke test only.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { startSseServer, createSseClient } from "./fixtures.js";
+
+describe("SSE Transport", () => {
+    let serverUrl: string;
+    let stopServer: () => void;
+    let client: Client;
+    let closeClient: () => Promise<void>;
+
+    beforeAll(async () => {
+        const server = await startSseServer(3002);
+        serverUrl = server.url;
+        stopServer = server.stop;
+
+        const conn = await createSseClient(serverUrl);
+        client = conn.client;
+        closeClient = conn.close;
+    });
+
+    afterAll(async () => {
+        await closeClient();
+        stopServer();
+    });
+
+    it("should connect and call echo tool", async () => {
+        const result = await client.callTool({ name: "echo", arguments: { message: "test" } });
+        expect((result.content as Array<{ type: string; text: string }>)[0].text).toBe("test");
+    });
+});

package/tests/stdio.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Integration tests via stdio transport.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { createStdioClient } from "./fixtures.js";
+
+describe("Stdio Transport", () => {
+    let client: Client;
+    let close: () => Promise<void>;
+
+    beforeAll(async () => {
+        const conn = await createStdioClient();
+        client = conn.client;
+        close = conn.close;
+    });
+
+    afterAll(async () => {
+        await close();
+    });
+
+    describe("Tools", () => {
+        it("should echo message", async () => {
+            const result = await client.callTool({ name: "echo", arguments: { message: "hello" } });
+            expect((result.content as Array<{ type: string; text: string }>)[0].text).toBe("hello");
+        });
+
+        it("should add numbers", async () => {
+            const result = await client.callTool({ name: "add", arguments: { a: 5, b: 3 } });
+            expect(Number((result.content as Array<{ type: string; text: string }>)[0].text)).toBe(8);
+        });
+
+        it("should multiply numbers", async () => {
+            const result = await client.callTool({ name: "multiply", arguments: { x: 4, y: 7 } });
+            expect(Number((result.content as Array<{ type: string; text: string }>)[0].text)).toBe(28);
+        });
+
+        it("should reverse string", async () => {
+            const result = await client.callTool({ name: "reverse_string", arguments: { text: "hello" } });
+            expect((result.content as Array<{ type: string; text: string }>)[0].text).toBe("olleh");
+        });
+
+        it("should generate valid UUID", async () => {
+            const result = await client.callTool({ name: "generate_uuid", arguments: {} });
+            const uuid = (result.content as Array<{ type: string; text: string }>)[0].text;
+            // UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+            expect(uuid).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+        });
+
+        it("should get timestamp", async () => {
+            const result = await client.callTool({ name: "get_timestamp", arguments: { format: "iso" } });
+            const timestamp = (result.content as Array<{ type: string; text: string }>)[0].text;
+            expect(timestamp).toContain("T");
+        });
+
+        it("should return error for sample_error tool", async () => {
+            const result = await client.callTool({ name: "sample_error", arguments: {} });
+            expect(result.isError).toBe(true);
+        });
+    });
+
+    describe("Resources", () => {
+        it("should list resources", async () => {
+            const result = await client.listResources();
+            const uris = result.resources.map((r) => r.uri);
+            expect(uris).toContain("test://static/greeting");
+        });
+
+        it("should read static greeting", async () => {
+            const result = await client.readResource({ uri: "test://static/greeting" });
+            expect((result.contents[0] as { text: string }).text).toContain("Hello");
+        });
+
+        it("should read dynamic timestamp", async () => {
+            const result = await client.readResource({ uri: "test://dynamic/timestamp" });
+            expect((result.contents[0] as { text: string }).text).toContain("T");
+        });
+    });
+
+    describe("Prompts", () => {
+        it("should list prompts", async () => {
+            const result = await client.listPrompts();
+            const names = result.prompts.map((p) => p.name);
+            expect(names).toContain("simple_prompt");
+        });
+
+        it("should get simple prompt", async () => {
+            const result = await client.getPrompt({ name: "simple_prompt" });
+            expect(result.messages.length).toBeGreaterThanOrEqual(1);
+        });
+
+        it("should get greeting prompt with argument", async () => {
+            const result = await client.getPrompt({ name: "greeting_prompt", arguments: { name: "Alice" } });
+            expect((result.messages[0].content as { type: string; text: string }).text).toContain("Alice");
+        });
+    });
+});