mcp-test-kits 0.0.0

package/src/capabilities/prompts.ts

@@ -0,0 +1,108 @@
+/**
+ * Prompt implementations for MCP Test Kits
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+/**
+ * Register all prompts with the MCP server
+ */
+export function registerPrompts(server: McpServer): void {
+  // Simple prompt
+  server.prompt(
+    "simple_prompt",
+    "A basic prompt with no arguments",
+    async () => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: "You are a helpful assistant. Please respond concisely and accurately.",
+          },
+        },
+      ],
+    }),
+  );
+
+  // Greeting prompt
+  server.prompt(
+    "greeting_prompt",
+    "Generate a greeting message",
+    {
+      name: z.string().describe("Name of the person to greet"),
+      style: z
+        .string()
+        .optional()
+        .describe("Greeting style (formal, casual, friendly)"),
+    },
+    async ({ name, style }: { name: string; style?: string }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Generate a ${style ?? "friendly"} greeting for ${name}.`,
+          },
+        },
+      ],
+    }),
+  );
+
+  // Template prompt
+  server.prompt(
+    "template_prompt",
+    "A template with multiple arguments",
+    {
+      topic: z.string().describe("Main topic"),
+      context: z.string().optional().describe("Additional context"),
+      length: z
+        .string()
+        .optional()
+        .describe("Desired length (short, medium, long)"),
+    },
+    async ({
+      topic,
+      context,
+      length,
+    }: {
+      topic: string;
+      context?: string;
+      length?: string;
+    }) => {
+      let text = `Write a ${length ?? "medium"} explanation about ${topic}.`;
+      if (context) {
+        text += ` Context: ${context}`;
+      }
+      return {
+        messages: [
+          {
+            role: "user",
+            content: { type: "text", text },
+          },
+        ],
+      };
+    },
+  );
+
+  // Multi-message prompt
+  server.prompt(
+    "multi_message_prompt",
+    "Prompt that returns multiple messages",
+    {
+      count: z.string().describe("Number of messages to generate"),
+    },
+    async ({ count }: { count: string }) => {
+      const numMessages = Math.max(1, Math.min(parseInt(count, 10) || 1, 10));
+      const messages = Array.from({ length: numMessages }, (_, i) => ({
+        role: "user" as const,
+        content: {
+          type: "text" as const,
+          text: `Message ${i + 1} of ${numMessages}: Generate a helpful response.`,
+        },
+      }));
+      return { messages };
+    },
+  );
+}

package/src/capabilities/resources.ts

@@ -0,0 +1,108 @@
+/**
+ * Resource implementations for MCP Test Kits
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// Large text content for testing
+const LARGE_TEXT_CONTENT = `
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
+incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
+fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+culpa qui officia deserunt mollit anim id est laborum.
+
+`.repeat(100);
+
+/**
+ * Register all resources with the MCP server
+ */
+export function registerResources(server: McpServer): void {
+  // Static greeting resource
+  server.registerResource(
+    "static-greeting",
+    "test://static/greeting",
+    { title: "Static Greeting", mimeType: "text/plain" },
+    async () => ({
+      contents: [
+        {
+          uri: "test://static/greeting",
+          mimeType: "text/plain",
+          text: "Hello from mcp-test-kits!",
+        },
+      ],
+    }),
+  );
+
+  // Static numbers resource
+  server.registerResource(
+    "static-numbers",
+    "test://static/numbers",
+    { title: "Number List", mimeType: "application/json" },
+    async () => ({
+      contents: [
+        {
+          uri: "test://static/numbers",
+          mimeType: "application/json",
+          text: JSON.stringify({ numbers: [1, 2, 3, 4, 5] }),
+        },
+      ],
+    }),
+  );
+
+  // Dynamic timestamp resource
+  server.registerResource(
+    "dynamic-timestamp",
+    "test://dynamic/timestamp",
+    { title: "Current Timestamp", mimeType: "application/json" },
+    async () => {
+      const now = new Date();
+      return {
+        contents: [
+          {
+            uri: "test://dynamic/timestamp",
+            mimeType: "application/json",
+            text: JSON.stringify({
+              timestamp: now.toISOString(),
+              unix: Math.floor(now.getTime() / 1000),
+            }),
+          },
+        ],
+      };
+    },
+  );
+
+  // Dynamic random resource
+  server.registerResource(
+    "dynamic-random",
+    "test://dynamic/random",
+    { title: "Random Number", mimeType: "application/json" },
+    async () => ({
+      contents: [
+        {
+          uri: "test://dynamic/random",
+          mimeType: "application/json",
+          text: JSON.stringify({ random: Math.floor(Math.random() * 101) }),
+        },
+      ],
+    }),
+  );
+
+  // Large text resource
+  server.registerResource(
+    "large-text",
+    "test://large-text",
+    { title: "Large Text Resource", mimeType: "text/plain" },
+    async () => ({
+      contents: [
+        {
+          uri: "test://large-text",
+          mimeType: "text/plain",
+          text: LARGE_TEXT_CONTENT,
+        },
+      ],
+    }),
+  );
+}

package/src/capabilities/tools.ts

@@ -0,0 +1,124 @@
+/**
+ * Tool implementations for MCP Test Kits
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+/**
+ * Register all tools with the MCP server
+ */
+export function registerTools(server: McpServer): void {
+  // echo tool
+  server.tool(
+    "echo",
+    "Returns the input message unchanged",
+    { message: z.string().describe("The message to echo") },
+    async ({ message }: { message: string }) => ({
+      content: [{ type: "text", text: message }],
+    }),
+  );
+
+  // add tool
+  server.tool(
+    "add",
+    "Adds two numbers together",
+    {
+      a: z.number().describe("First number"),
+      b: z.number().describe("Second number"),
+    },
+    async ({ a, b }: { a: number; b: number }) => ({
+      content: [{ type: "text", text: String(a + b) }],
+    }),
+  );
+
+  // multiply tool
+  server.tool(
+    "multiply",
+    "Multiplies two numbers",
+    {
+      x: z.number().describe("First number"),
+      y: z.number().describe("Second number"),
+    },
+    async ({ x, y }: { x: number; y: number }) => ({
+      content: [{ type: "text", text: String(x * y) }],
+    }),
+  );
+
+  // reverse_string tool
+  server.tool(
+    "reverse_string",
+    "Reverses a string",
+    { text: z.string().describe("Text to reverse") },
+    async ({ text }: { text: string }) => ({
+      content: [{ type: "text", text: text.split("").reverse().join("") }],
+    }),
+  );
+
+  // generate_uuid tool
+  server.tool("generate_uuid", "Generates a random UUID", {}, async () => ({
+    content: [{ type: "text", text: crypto.randomUUID() }],
+  }));
+
+  // get_timestamp tool
+  server.tool(
+    "get_timestamp",
+    "Returns the current timestamp",
+    {
+      format: z
+        .enum(["unix", "iso"])
+        .default("iso")
+        .describe("Format: 'unix' or 'iso'"),
+    },
+    async ({ format }: { format: string }) => {
+      const now = new Date();
+      const result =
+        format === "unix"
+          ? String(Math.floor(now.getTime() / 1000))
+          : now.toISOString();
+      return { content: [{ type: "text", text: result }] };
+    },
+  );
+
+  // sample_error tool
+  server.tool(
+    "sample_error",
+    "Always throws an error (for testing error handling)",
+    {
+      error_message: z
+        .string()
+        .default("This is a test error")
+        .describe("Custom error message"),
+    },
+    async ({ error_message }: { error_message: string }) => {
+      throw new Error(error_message);
+    },
+  );
+
+  // long_running_task tool
+  server.tool(
+    "long_running_task",
+    "Simulates a long-running operation",
+    {
+      duration: z
+        .number()
+        .min(0)
+        .max(10)
+        .describe("Duration in seconds (max 10)"),
+    },
+    async ({ duration }: { duration: number }) => {
+      const actualDuration = Math.min(Math.max(duration, 0), 10);
+      await new Promise((resolve) =>
+        setTimeout(resolve, actualDuration * 1000),
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Task completed after ${actualDuration} seconds`,
+          },
+        ],
+      };
+    },
+  );
+}

package/src/config.ts

@@ -0,0 +1,60 @@
+/**
+ * Configuration types for MCP Test Kits
+ */
+
+export interface ServerConfig {
+  name: string;
+  version: string;
+}
+
+export interface NetworkConfig {
+  host: string;
+  port: number;
+}
+
+export interface TransportConfig {
+  type: "stdio" | "http" | "sse";
+  network: NetworkConfig;
+}
+
+export interface CapabilitiesConfig {
+  tools: boolean;
+  resources: boolean;
+  prompts: boolean;
+}
+
+export interface ConfigOptions {
+  server: ServerConfig;
+  transport: TransportConfig;
+  capabilities: CapabilitiesConfig;
+}
+
+/**
+ * Configuration class with default values
+ */
+export class Config implements ConfigOptions {
+  server: ServerConfig;
+  transport: TransportConfig;
+  capabilities: CapabilitiesConfig;
+
+  constructor(options?: Partial<ConfigOptions>) {
+    this.server = {
+      name: options?.server?.name ?? "mcp-test-kits",
+      version: options?.server?.version ?? "1.0.0",
+    };
+
+    this.transport = {
+      type: options?.transport?.type ?? "stdio",
+      network: {
+        host: options?.transport?.network?.host ?? "127.0.0.1",
+        port: options?.transport?.network?.port ?? 3000,
+      },
+    };
+
+    this.capabilities = {
+      tools: options?.capabilities?.tools ?? true,
+      resources: options?.capabilities?.resources ?? true,
+      prompts: options?.capabilities?.prompts ?? true,
+    };
+  }
+}

package/src/extract-spec.ts

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * Extract specification from MCP Test Kits server.
+ *
+ * This script extracts the tools, resources, and prompts specification
+ * from the TypeScript implementation and outputs JSON that can be compared
+ * against the shared specification.
+ *
+ * Usage:
+ *   node dist/extract-spec.js > extracted_spec.json
+ *   node dist/extract-spec.js --compare
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { Config } from "./config.js";
+import { createServer } from "./server.js";
+import { extractSpec } from "./introspection.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+interface ToolSpec {
+  name: string;
+  description: string;
+}
+
+interface ResourceSpec {
+  name: string;
+  uri: string;
+  description?: string;
+  mimeType?: string;
+}
+
+interface PromptSpec {
+  name: string;
+  description: string;
+  arguments?: Array<{ name: string; description?: string; required?: boolean }>;
+}
+
+interface Spec {
+  tools: ToolSpec[];
+  resources: ResourceSpec[];
+  prompts: PromptSpec[];
+}
+
+/**
+ * Load shared specification from JSON files
+ */
+function loadSharedSpec(): Spec {
+  // Navigate from dist/ to project root, then to shared/
+  const projectRoot = join(__dirname, "..", "..");
+  const sharedDir = join(projectRoot, "shared", "test-data");
+
+  const tools: ToolSpec[] = [];
+  const resources: ResourceSpec[] = [];
+  const prompts: PromptSpec[] = [];
+
+  const toolsFile = join(sharedDir, "tools.json");
+  if (existsSync(toolsFile)) {
+    const data = JSON.parse(readFileSync(toolsFile, "utf-8"));
+    tools.push(...(data.tools || []));
+  }
+
+  const resourcesFile = join(sharedDir, "resources.json");
+  if (existsSync(resourcesFile)) {
+    const data = JSON.parse(readFileSync(resourcesFile, "utf-8"));
+    resources.push(...(data.resources || []));
+  }
+
+  const promptsFile = join(sharedDir, "prompts.json");
+  if (existsSync(promptsFile)) {
+    const data = JSON.parse(readFileSync(promptsFile, "utf-8"));
+    prompts.push(...(data.prompts || []));
+  }
+
+  return {
+    tools: tools.sort((a, b) => a.name.localeCompare(b.name)),
+    resources: resources.sort((a, b) => a.uri.localeCompare(b.uri)),
+    prompts: prompts.sort((a, b) => a.name.localeCompare(b.name)),
+  };
+}
+
+interface ComparisonResult {
+  match: boolean;
+  missing: string[];
+  extra: string[];
+}
+
+/**
+ * Compare extracted spec against shared spec
+ */
+function compareSpecs(
+  extracted: Spec,
+  shared: Spec,
+): {
+  tools: ComparisonResult;
+  resources: ComparisonResult;
+  prompts: ComparisonResult;
+} {
+  const results = {
+    tools: { match: true, missing: [] as string[], extra: [] as string[] },
+    resources: { match: true, missing: [] as string[], extra: [] as string[] },
+    prompts: { match: true, missing: [] as string[], extra: [] as string[] },
+  };
+
+  // Compare tools by name
+  const extractedToolNames = new Set(extracted.tools.map((t) => t.name));
+  const sharedToolNames = new Set(shared.tools.map((t) => t.name));
+
+  results.tools.missing = [...sharedToolNames].filter(
+    (n) => !extractedToolNames.has(n),
+  );
+  results.tools.extra = [...extractedToolNames].filter(
+    (n) => !sharedToolNames.has(n),
+  );
+  results.tools.match =
+    results.tools.missing.length === 0 && results.tools.extra.length === 0;
+
+  // Compare resources by URI
+  const extractedResourceUris = new Set(extracted.resources.map((r) => r.uri));
+  const sharedResourceUris = new Set(shared.resources.map((r) => r.uri));
+
+  results.resources.missing = [...sharedResourceUris].filter(
+    (u) => !extractedResourceUris.has(u),
+  );
+  results.resources.extra = [...extractedResourceUris].filter(
+    (u) => !sharedResourceUris.has(u),
+  );
+  results.resources.match =
+    results.resources.missing.length === 0 &&
+    results.resources.extra.length === 0;
+
+  // Compare prompts by name
+  const extractedPromptNames = new Set(extracted.prompts.map((p) => p.name));
+  const sharedPromptNames = new Set(shared.prompts.map((p) => p.name));
+
+  results.prompts.missing = [...sharedPromptNames].filter(
+    (n) => !extractedPromptNames.has(n),
+  );
+  results.prompts.extra = [...extractedPromptNames].filter(
+    (n) => !sharedPromptNames.has(n),
+  );
+  results.prompts.match =
+    results.prompts.missing.length === 0 && results.prompts.extra.length === 0;
+
+  return results;
+}
+
+async function main(): Promise<void> {
+  const { values } = parseArgs({
+    options: {
+      compare: { type: "boolean" },
+      output: { type: "string", short: "o" },
+    },
+    allowPositionals: true,
+  });
+
+  // Create server instance with default config
+  const config = new Config();
+  const server = createServer(config);
+
+  // Extract specifications automatically via introspection
+  const extracted = extractSpec(server);
+
+  if (values.compare) {
+    const shared = loadSharedSpec();
+    const results = compareSpecs(extracted, shared);
+
+    const allMatch =
+      results.tools.match && results.resources.match && results.prompts.match;
+
+    const output = {
+      status: allMatch ? "pass" : "fail",
+      comparison: results,
+    };
+
+    console.log(JSON.stringify(output, null, 2));
+    process.exit(allMatch ? 0 : 1);
+  } else {
+    console.log(JSON.stringify(extracted, null, 2));
+  }
+}
+
+main().catch((error) => {
+  console.error("Error:", error);
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * Entry point for MCP Test Kits server (TypeScript)
+ */
+
+import { parseArgs } from "node:util";
+import { Config } from "./config.js";
+import { createServer } from "./server.js";
+import {
+  runStdioServer,
+  runHttpServer,
+  runSseServer,
+} from "./transports/index.js";
+
+function printHelp(): void {
+  console.log(`
+MCP Test Kits - A comprehensive MCP testing server
+
+Usage:
+  mcp-test-kits [options]
+
+Options:
+  -t, --transport <type>  Transport type: stdio, http, sse (default: stdio)
+      --host <host>       Host to bind to (default: localhost)
+  -p, --port <port>       Port to listen on (default: 3000)
+  -l, --log-level <level> Log level: debug, info, warn, error (default: info)
+      --no-tools          Disable tools capability
+      --no-resources      Disable resources capability
+      --no-prompts        Disable prompts capability
+  -v, --version           Show version
+  -h, --help              Show this help
+
+Examples:
+  # Run with stdio (default)
+  mcp-test-kits
+
+  # Run with HTTP transport
+  mcp-test-kits --transport http --port 3000
+
+  # Run with only tools (no resources or prompts)
+  mcp-test-kits --no-resources --no-prompts
+`);
+}
+
+async function main(): Promise<void> {
+  // Parse command line arguments
+  const { values } = parseArgs({
+    options: {
+      transport: { type: "string", short: "t", default: "stdio" },
+      host: { type: "string", default: "localhost" },
+      port: { type: "string", short: "p", default: "3000" },
+      "log-level": { type: "string", short: "l", default: "info" },
+      "no-tools": { type: "boolean", default: false },
+      "no-resources": { type: "boolean", default: false },
+      "no-prompts": { type: "boolean", default: false },
+      version: { type: "boolean", short: "v" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+  });
+
+  if (values.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (values.version) {
+    console.log("mcp-test-kits 1.0.0");
+    process.exit(0);
+  }
+
+  // Build config from CLI args
+  const transport = values.transport as "stdio" | "http" | "sse";
+  const host = values.host as string;
+  const port = parseInt(values.port as string, 10);
+
+  const config = new Config({
+    server: { name: "mcp-test-kits", version: "1.0.0" },
+    transport: { type: transport, network: { host, port } },
+    capabilities: {
+      tools: !values["no-tools"],
+      resources: !values["no-resources"],
+      prompts: !values["no-prompts"],
+    },
+  });
+
+  // Create server
+  const server = createServer(config);
+
+  // Run with appropriate transport
+  switch (transport) {
+    case "stdio":
+      await runStdioServer(server, config);
+      break;
+    case "http":
+      await runHttpServer(server, config);
+      break;
+    case "sse":
+      await runSseServer(server, config);
+      break;
+    default:
+      console.error(`Unknown transport type: ${transport}`);
+      process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});