@mcpspec/core 1.0.3 → 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.
 
@@ -88,7 +88,7 @@ Evaluated via `TestExecutor` — schema, equals, contains, exists, matches, type
 
 - `SecurityScanner` — Orchestrates security audits
 - `ScanConfig` — Safety controls and mode filtering
-- Rules: `PathTraversalRule`, `InputValidationRule`, `ResourceExhaustionRule`, `AuthBypassRule`, `InjectionRule`, `InformationDisclosureRule`
+- Rules: `PathTraversalRule`, `InputValidationRule`, `ResourceExhaustionRule`, `AuthBypassRule`, `InjectionRule`, `InformationDisclosureRule`, `ToolPoisoningRule`, `ExcessiveAgencyRule`
 - `getSafePayloads`, `getPlatformPayloads`, `getPayloadsForMode` — Payload management
 
 ### Performance
@@ -105,9 +105,21 @@ Evaluated via `TestExecutor` — schema, equals, contains, exists, matches, type
 
 ### Scoring
 
-- `MCPScoreCalculator` — 0–100 quality score across 5 categories
+- `MCPScoreCalculator` — 0–100 quality score across 5 categories; schema quality uses opinionated linting (property types, descriptions, constraints, naming conventions)
 - `BadgeGenerator` — shields.io-style SVG badges
 
+### Recording & Replay
+
+- `RecordingStore` — Save, load, list, and delete session recordings
+- `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

@@ -1,5 +1,5 @@
 import * as _mcpspec_shared from '@mcpspec/shared';
-import { ErrorTemplate, ManagedProcess, ProcessConfig, ServerConfig, ConnectionConfig, ConnectionState, TestResult, TestRunResult, CollectionDefinition, RateLimitConfig, TestDefinition, SecurityScanMode, SeverityLevel, SecurityScanConfig, SecurityFinding, SecurityScanResult, ProfileEntry, BenchmarkStats, BenchmarkResult, BenchmarkConfig, WaterfallEntry, MCPScore } from '@mcpspec/shared';
+import { ErrorTemplate, ManagedProcess, ProcessConfig, ServerConfig, ConnectionConfig, ConnectionState, TestResult, TestRunResult, CollectionDefinition, RateLimitConfig, TestDefinition, SecurityScanMode, SeverityLevel, SecurityScanConfig, SecurityFinding, SecurityScanResult, ProfileEntry, BenchmarkStats, BenchmarkResult, BenchmarkConfig, WaterfallEntry, MCPScore, Recording, RecordingStep, RecordingDiff } from '@mcpspec/shared';
 import { Transport, TransportSendOptions } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { JSONRPCMessage, MessageExtraInfo } from '@modelcontextprotocol/sdk/types.js';
 
@@ -457,6 +457,22 @@ declare class InformationDisclosureRule implements SecurityRule {
     private getFirstParam;
 }
 
+declare class ToolPoisoningRule implements SecurityRule {
+    readonly id = "tool-poisoning";
+    readonly name = "Tool Poisoning";
+    readonly description = "Detects manipulation attempts in tool descriptions that could mislead LLMs";
+    scan(_client: MCPClientInterface, tools: ToolInfo[], _config: ScanConfig): Promise<SecurityFinding[]>;
+}
+
+declare class ExcessiveAgencyRule implements SecurityRule {
+    readonly id = "excessive-agency";
+    readonly name = "Excessive Agency";
+    readonly description = "Detects tools with overly broad permissions or missing safety controls";
+    scan(_client: MCPClientInterface, tools: ToolInfo[], _config: ScanConfig): Promise<SecurityFinding[]>;
+    private getParamNames;
+    private getParamDescriptions;
+}
+
 interface PayloadSet {
     category: string;
     label: string;
@@ -534,6 +550,8 @@ declare class MCPScoreCalculator {
     calculate(client: MCPClientInterface, progress?: ScoreProgress): Promise<MCPScore>;
     private scoreDocumentation;
     private scoreSchemaQuality;
+    /** Score a single tool's schema from 0.0 to 1.0 across 6 weighted criteria. */
+    private scoreToolSchema;
     private scoreErrorHandling;
     private scoreResponsiveness;
     private scoreSecurity;
@@ -544,4 +562,99 @@ declare class BadgeGenerator {
     getColor(score: number): 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, 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, ResourceExhaustionRule, ResultDiffer, type RunDiff, ScanConfig, type ScanProgress, type ScoreProgress, SecretMasker, type SecurityRule, SecurityScanner, type ServerDocData, TapReporter, type TestDiff, TestExecutor, type TestRunReporter, TestRunner, TestScheduler, WaterfallGenerator, YAML_LIMITS, computeStats, formatError, getPayloadsForMode, getPlatformInfo, getPlatformPayloads, getSafePayloads, loadYamlSafely, queryJsonPath, registerCleanupHandlers, resolveVariables };
+declare class RecordingStore {
+    private basePath;
+    constructor(basePath?: string);
+    save(name: string, recording: Recording): string;
+    load(name: string): Recording | null;
+    list(): string[];
+    delete(name: string): boolean;
+    private getFilePath;
+    private ensureDir;
+}
+
+interface ReplayProgress {
+    onStepStart?: (index: number, step: RecordingStep) => void;
+    onStepComplete?: (index: number, replayed: RecordingStep) => void;
+}
+interface ReplayResult {
+    originalRecording: Recording;
+    replayedSteps: RecordingStep[];
+    replayedAt: string;
+}
+declare class RecordingReplayer {
+    replay(recording: Recording, client: MCPClientInterface, progress?: ReplayProgress): Promise<ReplayResult>;
+}
+
+declare class RecordingDiffer {
+    diff(recording: Recording, replayedSteps: RecordingStep[], replayedAt: string): RecordingDiff;
+    private describeChange;
+}
+
+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

@@ -2078,7 +2078,9 @@ var SEVERITY_ORDER = ["info", "low", "medium", "high", "critical"];
 var PASSIVE_RULES = [
   "path-traversal",
   "input-validation",
-  "information-disclosure"
+  "information-disclosure",
+  "tool-poisoning",
+  "excessive-agency"
 ];
 var ACTIVE_RULES = [
   ...PASSIVE_RULES,
@@ -2140,7 +2142,7 @@ var ScanConfig = class {
 };
 
 // src/security/security-scanner.ts
-import { randomUUID as randomUUID9 } from "crypto";
+import { randomUUID as randomUUID11 } from "crypto";
 
 // src/security/rules/path-traversal.ts
 import { randomUUID as randomUUID3 } from "crypto";
@@ -2693,6 +2695,217 @@ var InformationDisclosureRule = class {
   }
 };
 
+// src/security/rules/tool-poisoning.ts
+import { randomUUID as randomUUID9 } from "crypto";
+var SUSPICIOUS_PATTERNS = [
+  /ignore\s+(all\s+)?previous/i,
+  /do\s+not\s+tell\s+the\s+user/i,
+  /override\s+instructions/i,
+  /disregard\s+(all\s+)?previous/i,
+  /pretend\s+(you\s+are|to\s+be)/i,
+  /forget\s+everything/i,
+  /ignore\s+your\s+(instructions|rules)/i,
+  /you\s+must\s+not\s+(reveal|disclose|mention)/i,
+  /system\s+prompt/i,
+  /act\s+as\s+(if|though)/i
+];
+var ZERO_WIDTH_CHARS = /[\u200B-\u200D\uFEFF]/;
+var BIDI_OVERRIDES = /[\u202A-\u202E\u2066-\u2069]/;
+var CROSS_TOOL_PATTERNS = [
+  /when\s+using\s+\w+.*also\s+call/i,
+  /before\s+calling\s+\w+.*first\s+run/i,
+  /after\s+(using|calling)\s+\w+.*invoke/i,
+  /always\s+call\s+\w+\s+(before|after|with)/i
+];
+var EMBEDDED_CODE_PATTERNS = [
+  /```[\s\S]*?```/,
+  /<script[\s>]/i,
+  /eval\s*\(/,
+  /require\s*\(/,
+  /import\s*\(/
+];
+var MAX_DESCRIPTION_LENGTH = 1e3;
+var ToolPoisoningRule = class {
+  id = "tool-poisoning";
+  name = "Tool Poisoning";
+  description = "Detects manipulation attempts in tool descriptions that could mislead LLMs";
+  async scan(_client, tools, _config) {
+    const findings = [];
+    for (const tool of tools) {
+      const desc = tool.description ?? "";
+      for (const pattern of SUSPICIOUS_PATTERNS) {
+        if (pattern.test(desc)) {
+          findings.push({
+            id: randomUUID9(),
+            rule: this.id,
+            severity: "high",
+            title: `Suspicious instruction in tool "${tool.name}"`,
+            description: `Tool description contains prompt injection pattern: ${pattern.source}`,
+            evidence: desc.slice(0, 200),
+            remediation: "Remove manipulative instructions from tool descriptions"
+          });
+          break;
+        }
+      }
+      if (ZERO_WIDTH_CHARS.test(desc) || BIDI_OVERRIDES.test(desc)) {
+        findings.push({
+          id: randomUUID9(),
+          rule: this.id,
+          severity: "high",
+          title: `Hidden Unicode characters in tool "${tool.name}"`,
+          description: "Tool description contains zero-width or bidirectional override characters that can hide malicious content",
+          evidence: `Description length: ${desc.length} characters`,
+          remediation: "Remove invisible Unicode characters from tool descriptions"
+        });
+      }
+      for (const pattern of CROSS_TOOL_PATTERNS) {
+        if (pattern.test(desc)) {
+          findings.push({
+            id: randomUUID9(),
+            rule: this.id,
+            severity: "medium",
+            title: `Cross-tool reference in tool "${tool.name}"`,
+            description: "Tool description instructs the LLM to call other tools, which could be used to chain unauthorized actions",
+            evidence: desc.slice(0, 200),
+            remediation: "Remove cross-tool instructions from descriptions"
+          });
+          break;
+        }
+      }
+      if (desc.length > MAX_DESCRIPTION_LENGTH) {
+        findings.push({
+          id: randomUUID9(),
+          rule: this.id,
+          severity: "low",
+          title: `Overly long description for tool "${tool.name}"`,
+          description: `Tool description is ${desc.length} characters (threshold: ${MAX_DESCRIPTION_LENGTH}). Long descriptions may hide malicious instructions`,
+          remediation: "Keep tool descriptions concise and focused"
+        });
+      }
+      for (const pattern of EMBEDDED_CODE_PATTERNS) {
+        if (pattern.test(desc)) {
+          findings.push({
+            id: randomUUID9(),
+            rule: this.id,
+            severity: "medium",
+            title: `Embedded code in tool "${tool.name}" description`,
+            description: "Tool description contains code blocks or executable patterns",
+            evidence: desc.slice(0, 200),
+            remediation: "Remove code blocks from tool descriptions"
+          });
+          break;
+        }
+      }
+    }
+    return findings;
+  }
+};
+
+// src/security/rules/excessive-agency.ts
+import { randomUUID as randomUUID10 } from "crypto";
+var DESTRUCTIVE_TOOL_PATTERN = /delete|drop|destroy|remove|kill|purge|truncate|wipe|reset|erase|shutdown|terminate/i;
+var CONFIRMATION_PARAMS = ["confirmation", "dryrun", "dry_run", "confirm", "force"];
+var CODE_EXEC_PARAMS = ["code", "script", "command", "query", "sql", "eval", "shell", "exec", "expression", "cmd"];
+var ExcessiveAgencyRule = class {
+  id = "excessive-agency";
+  name = "Excessive Agency";
+  description = "Detects tools with overly broad permissions or missing safety controls";
+  async scan(_client, tools, _config) {
+    const findings = [];
+    for (const tool of tools) {
+      if (DESTRUCTIVE_TOOL_PATTERN.test(tool.name)) {
+        const params2 = this.getParamNames(tool);
+        const hasConfirmation = params2.some((p) => CONFIRMATION_PARAMS.includes(p.toLowerCase()));
+        if (!hasConfirmation) {
+          findings.push({
+            id: randomUUID10(),
+            rule: this.id,
+            severity: "medium",
+            title: `Destructive tool "${tool.name}" lacks confirmation parameter`,
+            description: "Tool with destructive capability does not require confirmation, dryRun, or force parameter",
+            remediation: "Add a confirmation, dryRun, or force parameter to destructive tools"
+          });
+        }
+      }
+      const params = this.getParamNames(tool);
+      for (const param of params) {
+        if (CODE_EXEC_PARAMS.includes(param.toLowerCase())) {
+          findings.push({
+            id: randomUUID10(),
+            rule: this.id,
+            severity: "high",
+            title: `Code execution parameter "${param}" in tool "${tool.name}"`,
+            description: "Tool accepts arbitrary code or command input, which could enable unauthorized actions",
+            remediation: "Use specific, constrained parameters instead of generic code/command inputs"
+          });
+          break;
+        }
+      }
+      const schema = tool.inputSchema;
+      if (schema && typeof schema === "object") {
+        const props = schema.properties;
+        const required = schema.required;
+        if ((!props || Object.keys(props).length === 0) && (!required || required.length === 0)) {
+          findings.push({
+            id: randomUUID10(),
+            rule: this.id,
+            severity: "medium",
+            title: `Overly broad schema for tool "${tool.name}"`,
+            description: "Tool schema has no defined properties or required fields, accepting arbitrary input",
+            remediation: "Define explicit input schema with typed properties and required fields"
+          });
+        }
+      }
+      if (!tool.description || tool.description.trim() === "") {
+        findings.push({
+          id: randomUUID10(),
+          rule: this.id,
+          severity: "low",
+          title: `Missing description for tool "${tool.name}"`,
+          description: "Tool lacks a description, making it difficult to understand its purpose and risks",
+          remediation: "Add a clear, informative description to the tool"
+        });
+      }
+      const paramDescs = this.getParamDescriptions(tool);
+      if (paramDescs.total > 0) {
+        const missingRatio = paramDescs.missing / paramDescs.total;
+        if (missingRatio > 0.5) {
+          findings.push({
+            id: randomUUID10(),
+            rule: this.id,
+            severity: "low",
+            title: `Missing parameter descriptions in tool "${tool.name}"`,
+            description: `${paramDescs.missing} of ${paramDescs.total} parameters lack descriptions`,
+            remediation: "Add descriptions to all parameters to clarify their purpose"
+          });
+        }
+      }
+    }
+    return findings;
+  }
+  getParamNames(tool) {
+    const schema = tool.inputSchema;
+    if (!schema || typeof schema !== "object") return [];
+    const props = schema.properties;
+    if (!props) return [];
+    return Object.keys(props);
+  }
+  getParamDescriptions(tool) {
+    const schema = tool.inputSchema;
+    if (!schema || typeof schema !== "object") return { total: 0, missing: 0 };
+    const props = schema.properties;
+    if (!props) return { total: 0, missing: 0 };
+    const entries = Object.values(props);
+    let missing = 0;
+    for (const prop of entries) {
+      if (!prop || typeof prop !== "object" || !prop.description) {
+        missing++;
+      }
+    }
+    return { total: entries.length, missing };
+  }
+};
+
 // src/security/security-scanner.ts
 var SEVERITY_ORDER2 = ["info", "low", "medium", "high", "critical"];
 var SecurityScanner = class {
@@ -2737,7 +2950,7 @@ var SecurityScanner = class {
     const skippedCount = allTools.length - tools.length;
     if (skippedCount > 0) {
       findings.push({
-        id: randomUUID9(),
+        id: randomUUID11(),
         rule: "safety-filter",
         severity: "info",
         title: `${skippedCount} tool(s) excluded from scan`,
@@ -2757,7 +2970,7 @@ var SecurityScanner = class {
         progress?.onRuleComplete?.(rule.id, ruleFindings.length);
       } catch (err) {
         const errorFinding = {
-          id: randomUUID9(),
+          id: randomUUID11(),
           rule: ruleId,
           severity: "info",
           title: `Rule "${ruleId}" failed to complete`,
@@ -2774,7 +2987,7 @@ var SecurityScanner = class {
     const completedAt = /* @__PURE__ */ new Date();
     const serverInfo = client.getServerInfo();
     return {
-      id: randomUUID9(),
+      id: randomUUID11(),
       serverName: serverInfo?.name ?? "unknown",
       mode: config.mode,
       startedAt,
@@ -2809,6 +3022,8 @@ var SecurityScanner = class {
     this.registerRule(new AuthBypassRule());
     this.registerRule(new InjectionRule());
     this.registerRule(new InformationDisclosureRule());
+    this.registerRule(new ToolPoisoningRule());
+    this.registerRule(new ExcessiveAgencyRule());
   }
 };
 
@@ -3204,16 +3419,50 @@ var MCPScoreCalculator = class {
     if (tools.length === 0) return 0;
     let totalPoints = 0;
     for (const tool of tools) {
-      const schema = tool.inputSchema;
-      if (!schema) continue;
-      let toolPoints = 0;
-      if (schema.type) toolPoints += 1 / 3;
-      if (schema.properties && typeof schema.properties === "object") toolPoints += 1 / 3;
-      if (schema.required && Array.isArray(schema.required)) toolPoints += 1 / 3;
-      totalPoints += toolPoints;
+      totalPoints += this.scoreToolSchema(tool);
     }
     return Math.round(totalPoints / tools.length * 100);
   }
+  /** Score a single tool's schema from 0.0 to 1.0 across 6 weighted criteria. */
+  scoreToolSchema(tool) {
+    const schema = tool.inputSchema;
+    if (!schema) return 0;
+    let score = 0;
+    const hasType = !!schema.type;
+    const properties = schema.properties;
+    const hasProperties = properties && typeof properties === "object" && Object.keys(properties).length > 0;
+    score += (hasType ? 0.1 : 0) + (hasProperties ? 0.1 : 0);
+    if (!hasProperties || !properties) return score;
+    const propEntries = Object.entries(properties);
+    const withType = propEntries.filter(([, prop]) => !!prop.type).length;
+    score += withType / propEntries.length * 0.2;
+    const withDesc = propEntries.filter(([, prop]) => {
+      const desc = prop.description;
+      return typeof desc === "string" && desc.trim().length > 0;
+    }).length;
+    score += withDesc / propEntries.length * 0.2;
+    const required = schema.required;
+    if (Array.isArray(required) && required.length > 0) {
+      score += 0.15;
+    }
+    const constraintKeys = ["enum", "pattern", "minimum", "maximum", "minLength", "maxLength", "minItems", "maxItems", "format", "default"];
+    const withConstraints = propEntries.filter(([, prop]) => {
+      if (constraintKeys.some((k) => prop[k] !== void 0)) return true;
+      if (prop.type === "object" && prop.properties && typeof prop.properties === "object") {
+        const nested = prop.properties;
+        return Object.keys(nested).length > 0 && Object.values(nested).some((np) => !!np.type);
+      }
+      if (prop.type === "array" && prop.items && typeof prop.items === "object") return true;
+      return false;
+    }).length;
+    score += withConstraints / propEntries.length * 0.15;
+    const names = propEntries.map(([name]) => name);
+    const camelCount = names.filter((n) => /^[a-z][a-zA-Z0-9]*$/.test(n)).length;
+    const snakeCount = names.filter((n) => /^[a-z][a-z0-9_]*$/.test(n)).length;
+    const bestConvention = Math.max(camelCount, snakeCount);
+    score += bestConvention / names.length * 0.1;
+    return score;
+  }
   async scoreErrorHandling(client, tools) {
     if (tools.length === 0) return 0;
     const testTools = tools.slice(0, 5);
@@ -3320,6 +3569,425 @@ var BadgeGenerator = class {
     return "#e05d44";
   }
 };
+
+// src/recording/recording-store.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2, existsSync as existsSync2, unlinkSync } from "fs";
+import { join as join4 } from "path";
+var RecordingStore = class {
+  basePath;
+  constructor(basePath) {
+    this.basePath = basePath ?? join4(getPlatformInfo().dataDir, "recordings");
+  }
+  save(name, recording) {
+    this.ensureDir();
+    const filePath = this.getFilePath(name);
+    writeFileSync3(filePath, JSON.stringify(recording, null, 2), "utf-8");
+    return filePath;
+  }
+  load(name) {
+    const filePath = this.getFilePath(name);
+    if (!existsSync2(filePath)) return null;
+    return JSON.parse(readFileSync2(filePath, "utf-8"));
+  }
+  list() {
+    this.ensureDir();
+    return readdirSync2(this.basePath).filter((f) => f.endsWith(".json")).map((f) => f.replace(/\.json$/, ""));
+  }
+  delete(name) {
+    const filePath = this.getFilePath(name);
+    if (!existsSync2(filePath)) return false;
+    unlinkSync(filePath);
+    return true;
+  }
+  getFilePath(name) {
+    const safeName = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return join4(this.basePath, `${safeName}.json`);
+  }
+  ensureDir() {
+    if (!existsSync2(this.basePath)) {
+      mkdirSync3(this.basePath, { recursive: true });
+    }
+  }
+};
+
+// src/recording/recording-replayer.ts
+var RecordingReplayer = class {
+  async replay(recording, client, progress) {
+    const replayedSteps = [];
+    for (let i = 0; i < recording.steps.length; i++) {
+      const step = recording.steps[i];
+      progress?.onStepStart?.(i, step);
+      const start = performance.now();
+      let output = [];
+      let isError = false;
+      try {
+        const result = await client.callTool(step.tool, step.input);
+        output = result.content;
+        isError = result.isError === true;
+      } catch (err) {
+        output = [{ type: "text", text: err instanceof Error ? err.message : String(err) }];
+        isError = true;
+      }
+      const durationMs = Math.round(performance.now() - start);
+      const replayed = {
+        tool: step.tool,
+        input: step.input,
+        output,
+        isError,
+        durationMs
+      };
+      replayedSteps.push(replayed);
+      progress?.onStepComplete?.(i, replayed);
+    }
+    return {
+      originalRecording: recording,
+      replayedSteps,
+      replayedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+};
+
+// src/recording/recording-differ.ts
+var RecordingDiffer = class {
+  diff(recording, replayedSteps, replayedAt) {
+    const steps = [];
+    const maxLen = Math.max(recording.steps.length, replayedSteps.length);
+    for (let i = 0; i < maxLen; i++) {
+      const original = recording.steps[i];
+      const replayed = replayedSteps[i];
+      if (original && replayed) {
+        const outputMatch = JSON.stringify(original.output) === JSON.stringify(replayed.output);
+        const errorMatch = (original.isError ?? false) === (replayed.isError ?? false);
+        const isMatched = outputMatch && errorMatch;
+        steps.push({
+          index: i,
+          tool: original.tool,
+          type: isMatched ? "matched" : "changed",
+          original,
+          replayed,
+          outputDiff: isMatched ? void 0 : this.describeChange(original, replayed)
+        });
+      } else if (original && !replayed) {
+        steps.push({
+          index: i,
+          tool: original.tool,
+          type: "removed",
+          original
+        });
+      } else if (!original && replayed) {
+        steps.push({
+          index: i,
+          tool: replayed.tool,
+          type: "added",
+          replayed
+        });
+      }
+    }
+    const summary = {
+      matched: steps.filter((s) => s.type === "matched").length,
+      changed: steps.filter((s) => s.type === "changed").length,
+      added: steps.filter((s) => s.type === "added").length,
+      removed: steps.filter((s) => s.type === "removed").length
+    };
+    return {
+      recordingId: recording.id,
+      recordingName: recording.name,
+      replayedAt,
+      steps,
+      summary
+    };
+  }
+  describeChange(original, replayed) {
+    const parts = [];
+    if ((original.isError ?? false) !== (replayed.isError ?? false)) {
+      parts.push(`error state: ${original.isError ?? false} \u2192 ${replayed.isError ?? false}`);
+    }
+    if (JSON.stringify(original.output) !== JSON.stringify(replayed.output)) {
+      parts.push("output content changed");
+    }
+    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,
@@ -3331,6 +3999,7 @@ export {
   DocGenerator,
   ERROR_CODE_MAP,
   ERROR_TEMPLATES,
+  ExcessiveAgencyRule,
   HtmlDocGenerator,
   HtmlReporter,
   InformationDisclosureRule,
@@ -3343,13 +4012,19 @@ export {
   MCPScoreCalculator,
   MCPSpecError,
   MarkdownGenerator,
+  MockGenerator,
+  MockMCPServer,
   NotImplementedError,
   PathTraversalRule,
   ProcessManagerImpl,
   ProcessRegistry,
   Profiler,
   RateLimiter,
+  RecordingDiffer,
+  RecordingReplayer,
+  RecordingStore,
   ResourceExhaustionRule,
+  ResponseMatcher,
   ResultDiffer,
   ScanConfig,
   SecretMasker,
@@ -3358,6 +4033,7 @@ export {
   TestExecutor,
   TestRunner,
   TestScheduler,
+  ToolPoisoningRule,
   WaterfallGenerator,
   YAML_LIMITS,
   computeStats,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpspec/core",
-  "version": "1.0.3",
+  "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.0.3"
+    "@mcpspec/shared": "1.2.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",