@mcpspec/core 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @mcpspec/core
 
-Core engine for [MCPSpec](https://www.npmjs.com/package/mcpspec) — MCP client, test runner, security scanner, performance profiler, documentation generator, and quality scorer.
+Core engine for [MCPSpec](https://www.npmjs.com/package/mcpspec) — MCP client, test runner, security scanner, performance profiler, documentation generator, quality scorer, and mock server generator.
 
 > **For CLI usage, install [`mcpspec`](https://www.npmjs.com/package/mcpspec) instead.** This package is for programmatic use — embedding MCPSpec capabilities in your own tools.
 
@@ -114,6 +114,12 @@ Evaluated via `TestExecutor` — schema, equals, contains, exists, matches, type
 - `RecordingReplayer` — Replay recorded steps against a live server
 - `RecordingDiffer` — Diff original recording vs replayed results (matched/changed/added/removed)
 
+### Mock Server
+
+- `MockMCPServer` — Start a mock MCP server from a recording (stdio transport, drop-in replacement)
+- `ResponseMatcher` — Match incoming tool calls to recorded responses (`match` or `sequential` mode)
+- `MockGenerator` — Generate standalone `.js` mock server files (only requires `@modelcontextprotocol/sdk`)
+
 ### Utilities
 
 - `loadYamlSafely` — FAILSAFE_SCHEMA YAML parsing

package/dist/index.d.ts

@@ -591,4 +591,70 @@ declare class RecordingDiffer {
     private describeChange;
 }
 
-export { AuthBypassRule, BadgeGenerator, BaselineStore, type BenchmarkProgress, BenchmarkRunner, ConnectionManager, ConsoleReporter, DANGEROUS_TOOL_PATTERNS, DocGenerator, type DocGeneratorOptions, type DryRunResult, ERROR_CODE_MAP, ERROR_TEMPLATES, type ErrorCode, ExcessiveAgencyRule, HtmlDocGenerator, HtmlReporter, InformationDisclosureRule, InjectionRule, InputValidationRule, JsonReporter, JunitReporter, LoggingTransport, MCPClient, type MCPClientInterface, MCPScoreCalculator, MCPSpecError, MarkdownGenerator, NotImplementedError, type OnProtocolMessage, PathTraversalRule, type PayloadSet, type PlatformPayload, ProcessManagerImpl, ProcessRegistry, Profiler, RateLimiter, RecordingDiffer, RecordingReplayer, RecordingStore, type ReplayProgress, type ReplayResult, ResourceExhaustionRule, ResultDiffer, type RunDiff, ScanConfig, type ScanProgress, type ScoreProgress, SecretMasker, type SecurityRule, SecurityScanner, type ServerDocData, TapReporter, type TestDiff, TestExecutor, type TestRunReporter, TestRunner, TestScheduler, ToolPoisoningRule, WaterfallGenerator, YAML_LIMITS, computeStats, formatError, getPayloadsForMode, getPlatformInfo, getPlatformPayloads, getSafePayloads, loadYamlSafely, queryJsonPath, registerCleanupHandlers, resolveVariables };
+type MatchMode = 'match' | 'sequential';
+type OnMissingBehavior = 'error' | 'empty';
+interface ResponseMatcherConfig {
+    mode: MatchMode;
+    onMissing: OnMissingBehavior;
+}
+interface MatchResult {
+    output: unknown[];
+    isError: boolean;
+    durationMs: number;
+}
+interface MatcherStats {
+    totalSteps: number;
+    servedCount: number;
+    remainingCount: number;
+}
+/**
+ * Matches incoming tool calls to recorded responses.
+ *
+ * - `match` mode: tries exact input match first, then falls back to next queued response for that tool.
+ * - `sequential` mode: serves responses in recorded order regardless of tool name/input.
+ */
+declare class ResponseMatcher {
+    private readonly config;
+    private readonly steps;
+    private servedCount;
+    private toolQueues;
+    private sequentialCursor;
+    constructor(steps: RecordingStep[], config: ResponseMatcherConfig);
+    match(toolName: string, input: Record<string, unknown>): MatchResult | null;
+    getStats(): MatcherStats;
+    private matchSequential;
+    private matchByTool;
+    private normalizeInput;
+    private stepToResult;
+}
+
+interface MockServerConfig {
+    recording: Recording;
+    mode: MatchMode;
+    latency: number | 'original';
+    onMissing: OnMissingBehavior;
+}
+interface MockServerStats extends MatcherStats {
+    toolCount: number;
+}
+declare class MockMCPServer {
+    private readonly config;
+    private readonly matcher;
+    private readonly server;
+    constructor(config: MockServerConfig);
+    start(transport?: Transport): Promise<void>;
+    getStats(): MockServerStats;
+    private registerHandlers;
+}
+
+interface MockGeneratorOptions {
+    recording: Recording;
+    mode: MatchMode;
+    latency: number | 'original';
+    onMissing: OnMissingBehavior;
+}
+declare class MockGenerator {
+    generate(options: MockGeneratorOptions): string;
+}
+
+export { AuthBypassRule, BadgeGenerator, BaselineStore, type BenchmarkProgress, BenchmarkRunner, ConnectionManager, ConsoleReporter, DANGEROUS_TOOL_PATTERNS, DocGenerator, type DocGeneratorOptions, type DryRunResult, ERROR_CODE_MAP, ERROR_TEMPLATES, type ErrorCode, ExcessiveAgencyRule, HtmlDocGenerator, HtmlReporter, InformationDisclosureRule, InjectionRule, InputValidationRule, JsonReporter, JunitReporter, LoggingTransport, MCPClient, type MCPClientInterface, MCPScoreCalculator, MCPSpecError, MarkdownGenerator, type MatchMode, type MatchResult, type MatcherStats, MockGenerator, type MockGeneratorOptions, MockMCPServer, type MockServerConfig, type MockServerStats, NotImplementedError, type OnMissingBehavior, type OnProtocolMessage, PathTraversalRule, type PayloadSet, type PlatformPayload, ProcessManagerImpl, ProcessRegistry, Profiler, RateLimiter, RecordingDiffer, RecordingReplayer, RecordingStore, type ReplayProgress, type ReplayResult, ResourceExhaustionRule, ResponseMatcher, type ResponseMatcherConfig, ResultDiffer, type RunDiff, ScanConfig, type ScanProgress, type ScoreProgress, SecretMasker, type SecurityRule, SecurityScanner, type ServerDocData, TapReporter, type TestDiff, TestExecutor, type TestRunReporter, TestRunner, TestScheduler, ToolPoisoningRule, WaterfallGenerator, YAML_LIMITS, computeStats, formatError, getPayloadsForMode, getPlatformInfo, getPlatformPayloads, getSafePayloads, loadYamlSafely, queryJsonPath, registerCleanupHandlers, resolveVariables };

package/dist/index.js

@@ -3708,6 +3708,286 @@ var RecordingDiffer = class {
     return parts.join("; ");
   }
 };
+
+// src/mock/mock-server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+// src/mock/response-matcher.ts
+var ResponseMatcher = class {
+  config;
+  steps;
+  servedCount = 0;
+  // match mode: per-tool queues
+  toolQueues = /* @__PURE__ */ new Map();
+  // sequential mode: single cursor
+  sequentialCursor = 0;
+  constructor(steps, config) {
+    this.steps = steps;
+    this.config = config;
+    if (config.mode === "match") {
+      for (const step of steps) {
+        const queue = this.toolQueues.get(step.tool);
+        if (queue) {
+          queue.push(step);
+        } else {
+          this.toolQueues.set(step.tool, [step]);
+        }
+      }
+    }
+  }
+  match(toolName, input) {
+    if (this.config.mode === "sequential") {
+      return this.matchSequential();
+    }
+    return this.matchByTool(toolName, input);
+  }
+  getStats() {
+    return {
+      totalSteps: this.steps.length,
+      servedCount: this.servedCount,
+      remainingCount: this.steps.length - this.servedCount
+    };
+  }
+  matchSequential() {
+    if (this.sequentialCursor >= this.steps.length) {
+      return null;
+    }
+    const step = this.steps[this.sequentialCursor];
+    this.sequentialCursor++;
+    this.servedCount++;
+    return this.stepToResult(step);
+  }
+  matchByTool(toolName, input) {
+    const queue = this.toolQueues.get(toolName);
+    if (!queue || queue.length === 0) {
+      return null;
+    }
+    const inputKey = this.normalizeInput(input);
+    const exactIndex = queue.findIndex((s) => this.normalizeInput(s.input) === inputKey);
+    if (exactIndex !== -1) {
+      const step2 = queue.splice(exactIndex, 1)[0];
+      this.servedCount++;
+      return this.stepToResult(step2);
+    }
+    const step = queue.shift();
+    this.servedCount++;
+    return this.stepToResult(step);
+  }
+  normalizeInput(input) {
+    return JSON.stringify(input, Object.keys(input).sort());
+  }
+  stepToResult(step) {
+    return {
+      output: step.output,
+      isError: step.isError === true,
+      durationMs: step.durationMs ?? 0
+    };
+  }
+};
+
+// src/mock/mock-server.ts
+var MockMCPServer = class {
+  config;
+  matcher;
+  server;
+  constructor(config) {
+    this.config = config;
+    this.matcher = new ResponseMatcher(config.recording.steps, {
+      mode: config.mode,
+      onMissing: config.onMissing
+    });
+    this.server = new Server(
+      {
+        name: config.recording.serverName ?? config.recording.name,
+        version: "1.0.0-mock"
+      },
+      {
+        capabilities: {
+          tools: {}
+        }
+      }
+    );
+    this.registerHandlers();
+  }
+  async start(transport) {
+    const t = transport ?? new StdioServerTransport();
+    await this.server.connect(t);
+    process.stderr.write(`Mock server started (${this.config.recording.steps.length} recorded steps)
+`);
+  }
+  getStats() {
+    return {
+      ...this.matcher.getStats(),
+      toolCount: this.config.recording.tools.length
+    };
+  }
+  registerHandlers() {
+    const tools = this.config.recording.tools;
+    const matcher = this.matcher;
+    const config = this.config;
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: tools.map((t) => ({
+          name: t.name,
+          description: t.description ?? "",
+          inputSchema: { type: "object", properties: {} }
+        }))
+      };
+    });
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const toolName = request.params.name;
+      const input = request.params.arguments ?? {};
+      const result = matcher.match(toolName, input);
+      if (!result) {
+        if (config.onMissing === "empty") {
+          return {
+            content: [{ type: "text", text: "" }],
+            isError: false
+          };
+        }
+        return {
+          content: [{ type: "text", text: `No recorded response for tool "${toolName}"` }],
+          isError: true
+        };
+      }
+      const delay = config.latency === "original" ? result.durationMs : config.latency;
+      if (delay > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+      return {
+        content: result.output,
+        isError: result.isError
+      };
+    });
+  }
+};
+
+// src/mock/mock-generator.ts
+var MockGenerator = class {
+  generate(options) {
+    const recordingJson = JSON.stringify(options.recording, null, 2);
+    const latencyValue = options.latency === "original" ? `'original'` : String(options.latency);
+    return `#!/usr/bin/env node
+// Auto-generated mock MCP server by mcpspec
+// Recording: ${options.recording.name}
+// Generated: ${(/* @__PURE__ */ new Date()).toISOString()}
+//
+// Dependencies: @modelcontextprotocol/sdk
+// Install: npm install @modelcontextprotocol/sdk
+// Run: node ${options.recording.name}-mock.js
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const RECORDING = ${recordingJson};
+
+const MODE = '${options.mode}';
+const LATENCY = ${latencyValue};
+const ON_MISSING = '${options.onMissing}';
+
+// --- ResponseMatcher (inlined) ---
+
+class ResponseMatcher {
+  constructor(steps, config) {
+    this.config = config;
+    this.steps = steps;
+    this.servedCount = 0;
+    this.toolQueues = new Map();
+    this.sequentialCursor = 0;
+
+    if (config.mode === 'match') {
+      for (const step of steps) {
+        const queue = this.toolQueues.get(step.tool);
+        if (queue) {
+          queue.push(step);
+        } else {
+          this.toolQueues.set(step.tool, [step]);
+        }
+      }
+    }
+  }
+
+  match(toolName, input) {
+    if (this.config.mode === 'sequential') {
+      return this._matchSequential();
+    }
+    return this._matchByTool(toolName, input);
+  }
+
+  _matchSequential() {
+    if (this.sequentialCursor >= this.steps.length) return null;
+    const step = this.steps[this.sequentialCursor];
+    this.sequentialCursor++;
+    this.servedCount++;
+    return { output: step.output, isError: step.isError === true, durationMs: step.durationMs || 0 };
+  }
+
+  _matchByTool(toolName, input) {
+    const queue = this.toolQueues.get(toolName);
+    if (!queue || queue.length === 0) return null;
+
+    const inputKey = JSON.stringify(input, Object.keys(input).sort());
+    const exactIndex = queue.findIndex(
+      (s) => JSON.stringify(s.input, Object.keys(s.input).sort()) === inputKey
+    );
+
+    let step;
+    if (exactIndex !== -1) {
+      step = queue.splice(exactIndex, 1)[0];
+    } else {
+      step = queue.shift();
+    }
+    this.servedCount++;
+    return { output: step.output, isError: step.isError === true, durationMs: step.durationMs || 0 };
+  }
+}
+
+// --- Server setup ---
+
+const matcher = new ResponseMatcher(RECORDING.steps, { mode: MODE, onMissing: ON_MISSING });
+
+const server = new Server(
+  { name: RECORDING.serverName || RECORDING.name, version: '1.0.0-mock' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: RECORDING.tools.map((t) => ({
+    name: t.name,
+    description: t.description || '',
+    inputSchema: { type: 'object', properties: {} },
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const toolName = request.params.name;
+  const input = request.params.arguments || {};
+  const result = matcher.match(toolName, input);
+
+  if (!result) {
+    if (ON_MISSING === 'empty') {
+      return { content: [{ type: 'text', text: '' }], isError: false };
+    }
+    return { content: [{ type: 'text', text: \`No recorded response for tool "\${toolName}"\` }], isError: true };
+  }
+
+  const delay = LATENCY === 'original' ? result.durationMs : LATENCY;
+  if (delay > 0) {
+    await new Promise((resolve) => setTimeout(resolve, delay));
+  }
+
+  return { content: result.output, isError: result.isError };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(\`Mock server started (\${RECORDING.steps.length} recorded steps)\\n\`);
+`;
+  }
+};
 export {
   AuthBypassRule,
   BadgeGenerator,
@@ -3732,6 +4012,8 @@ export {
   MCPScoreCalculator,
   MCPSpecError,
   MarkdownGenerator,
+  MockGenerator,
+  MockMCPServer,
   NotImplementedError,
   PathTraversalRule,
   ProcessManagerImpl,
@@ -3742,6 +4024,7 @@ export {
   RecordingReplayer,
   RecordingStore,
   ResourceExhaustionRule,
+  ResponseMatcher,
   ResultDiffer,
   ScanConfig,
   SecretMasker,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpspec/core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,7 +31,7 @@
     "expr-eval": "^2.0.2",
     "handlebars": "^4.7.8",
     "zod": "^3.22.0",
-    "@mcpspec/shared": "1.1.0"
+    "@mcpspec/shared": "1.2.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",