@cyanheads/mcp-ts-core 0.1.29 → 0.2.0

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # Agent Protocol
 
-**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.1.29
+**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.2.0
 **npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) · **Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
 
 > **Developer note:** Never assume. Read related files and docs before making changes. Read full file content for context. Never edit a file before reading it.
@@ -38,6 +38,7 @@
 | `/services` | `OpenRouterProvider`, `SpeechService`, `createSpeechProvider`, `ElevenLabsProvider`, `WhisperProvider`, `GraphService`, provider interfaces and types | LLM, Speech (TTS/STT), Graph services |
 | `/linter` | `validateDefinitions`, `LintReport`, `LintDiagnostic`, `LintInput`, `LintSeverity` | Definition validation |
 | `/testing` | `createMockContext` | Test helpers |
+| `/testing/fuzz` | `fuzzTool`, `fuzzResource`, `fuzzPrompt`, `zodToArbitrary`, `adversarialArbitrary`, `ADVERSARIAL_STRINGS` | Fuzz testing |
 
 All subpaths prefixed with `@cyanheads/mcp-ts-core`. **†Tier 3 modules** require optional peer dependencies — see `package.json` `peerDependencies`. Tier 3 methods that lazy-load deps are **async**.
 
@@ -383,6 +384,21 @@ describe('myTool', () => {
 
 **`createMockContext` options:** `createMockContext()` (minimal), `{ tenantId: 'test-tenant' }` (enables state), `{ sample: vi.fn() }`, `{ elicit: vi.fn() }`, `{ progress: true }` (task progress).
 
+**Fuzz testing:** `fuzzTool`/`fuzzResource`/`fuzzPrompt` from `/testing/fuzz` generate valid and adversarial inputs from Zod schemas via `fast-check`, then assert handler invariants (no crashes, no prototype pollution, no stack trace leaks). Returns a `FuzzReport` for custom assertions.
+
+```ts
+import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';
+
+it('survives fuzz testing', async () => {
+  const report = await fuzzTool(myTool, { numRuns: 100 });
+  expect(report.crashes).toHaveLength(0);
+  expect(report.leaks).toHaveLength(0);
+  expect(report.prototypePollution).toBe(false);
+});
+```
+
+Options: `numRuns` (valid inputs, default 50), `numAdversarial` (adversarial inputs, default 30), `seed` (reproducibility), `timeout` (per-call ms, default 5000), `ctx` (`MockContextOptions` for stateful handlers). Also exports `zodToArbitrary(schema)` for custom property-based tests and `ADVERSARIAL_STRINGS` for targeted injection testing.
+
 **Vitest config:** Extend core config, add `@/` alias: `resolve: { alias: { '@/': new URL('./src/', import.meta.url).pathname } }`. Construct deps in `beforeEach`. Re-init services per suite.
 
 ---
@@ -413,6 +429,8 @@ Detailed method signatures, options, and examples live in skill files. Read the
 | `setup` | `skills/setup/SKILL.md` | Initialize a new consumer server from the template |
 | `devcheck` | `skills/devcheck/SKILL.md` | Run lint, format, typecheck, security checks |
 | `polish-docs-meta` | `skills/polish-docs-meta/SKILL.md` | Finalize docs, README, metadata, and agent protocol for shipping |
+| `report-issue-framework` | `skills/report-issue-framework/SKILL.md` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
+| `report-issue-local` | `skills/report-issue-local/SKILL.md` | File a bug or feature request against this server's own repo via `gh` CLI |
 | `release` | `skills/release/SKILL.md` | Version bump, changelog, publish workflow |
 | `maintenance` | `skills/maintenance/SKILL.md` | Dependency updates, housekeeping tasks |
 | `migrate-mcp-ts-template` | `skills/migrate-mcp-ts-template/SKILL.md` | Migrate legacy template fork to package dependency |

package/README.md

@@ -5,7 +5,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.29-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
+[![Version](https://img.shields.io/badge/Version-0.2.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![MCP Spec](https://img.shields.io/badge/MCP%20Spec-2025--11--25-8A2BE2.svg?style=flat-square)](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE)
 
 [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
@@ -191,6 +191,7 @@ import { markdown, fetchWithTimeout } from '@cyanheads/mcp-ts-core/utils';
 import { OpenRouterProvider, GraphService } from '@cyanheads/mcp-ts-core/services';
 import { validateDefinitions } from '@cyanheads/mcp-ts-core/linter';
 import { createMockContext } from '@cyanheads/mcp-ts-core/testing';
+import { fuzzTool, fuzzResource, fuzzPrompt } from '@cyanheads/mcp-ts-core/testing/fuzz';
 ```
 
 See [CLAUDE.md](CLAUDE.md) for the complete exports reference.
@@ -222,6 +223,21 @@ const result = await myTool.handler(input, ctx);
 
 `createMockContext()` provides stubbed `log`, `state`, and `signal`. Pass `{ tenantId }` for state operations, `{ sample }` for LLM mocking, `{ elicit }` for elicitation mocking, `{ progress: true }` for task tools.
 
+### Fuzz testing
+
+Schema-aware fuzz testing via `fast-check`. Generates valid inputs from Zod schemas and adversarial payloads (prototype pollution, injection strings, type confusion) to verify handler invariants.
+
+```ts
+import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';
+
+const report = await fuzzTool(myTool, { numRuns: 100 });
+expect(report.crashes).toHaveLength(0);
+expect(report.leaks).toHaveLength(0);
+expect(report.prototypePollution).toBe(false);
+```
+
+Also exports `fuzzResource`, `fuzzPrompt`, `zodToArbitrary`, and `ADVERSARIAL_STRINGS` for custom property-based tests.
+
 ## Documentation
 
 - **[CLAUDE.md](CLAUDE.md)** — Complete API reference: exports catalog, patterns, Context interface, error codes, auth, config, testing. Ships in the npm package.
@@ -232,6 +248,7 @@ const result = await myTool.handler(input, ctx);
 ```bash
 bun run build          # tsc && tsc-alias
 bun run devcheck       # lint, format, typecheck, security
+bun run lint:mcp       # validate MCP definitions against spec
 bun run test           # vitest
 bun run dev:stdio      # dev mode (stdio)
 bun run dev:http       # dev mode (HTTP)

package/biome.json

@@ -81,6 +81,16 @@
         }
       }
     },
+    {
+      "includes": ["src/testing/**"],
+      "linter": {
+        "rules": {
+          "suspicious": {
+            "noExplicitAny": "off"
+          }
+        }
+      }
+    },
     {
       "includes": ["scripts/**"],
       "linter": {

package/dist/testing/fuzz.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @fileoverview Schema-aware fuzz testing utilities for MCP definitions.
+ * Generates valid, near-miss, and adversarial inputs from Zod schemas,
+ * then asserts handler invariants (no crashes, well-formed errors, etc.).
+ *
+ * Uses `fast-check` for property-based generation. Consumers use
+ * `fuzzTool()`, `fuzzResource()`, and `fuzzPrompt()` in their Vitest suites.
+ *
+ * @module src/testing/fuzz
+ */
+import fc from 'fast-check';
+import type { ZodObject, ZodRawShape } from 'zod';
+import type { AnyPromptDefinition } from '../mcp-server/prompts/utils/promptDefinition.js';
+import type { AnyResourceDefinition } from '../mcp-server/resources/utils/resourceDefinition.js';
+import type { AnyToolDefinition } from '../mcp-server/tools/utils/toolDefinition.js';
+import { type MockContextOptions } from './index.js';
+/** Options for fuzz test runners. */
+export interface FuzzOptions {
+    /** Mock context options passed to `createMockContext()`. */
+    ctx?: MockContextOptions;
+    /** Number of adversarial-input runs. @default 30 */
+    numAdversarial?: number;
+    /** Number of valid-input runs. @default 50 */
+    numRuns?: number;
+    /** fast-check seed for reproducibility. */
+    seed?: number;
+    /** Timeout per individual handler call in ms. @default 5000 */
+    timeout?: number;
+}
+/**
+ * Converts a Zod schema to a fast-check `Arbitrary` that produces valid values.
+ * Supports the JSON-Schema-serializable subset used by MCP tool/resource schemas.
+ */
+export declare function zodToArbitrary(schema: unknown): fc.Arbitrary<unknown>;
+/** Strings designed to trigger injection, encoding, or parsing vulnerabilities. */
+export declare const ADVERSARIAL_STRINGS: readonly string[];
+/** Generates adversarial values for object fields based on expected type. */
+export declare function adversarialArbitrary(): fc.Arbitrary<unknown>;
+/**
+ * Generates an adversarial variant of a Zod object schema's input.
+ * Produces objects that match the key structure but have wrong-type values.
+ */
+export declare function adversarialObjectArbitrary(schema: ZodObject<ZodRawShape>): fc.Arbitrary<Record<string, unknown>>;
+/** Result of a fuzz run, useful for custom assertions. */
+export interface FuzzReport {
+    /** Inputs that caused the handler to crash (unhandled throw past framework). */
+    crashes: Array<{
+        input: unknown;
+        error: unknown;
+    }>;
+    /** Responses that leaked stack traces or internal paths. */
+    leaks: Array<{
+        input: unknown;
+        errorText: string;
+    }>;
+    /** Prototype pollution detected on global objects. */
+    prototypePollution: boolean;
+    /** Total inputs tested. */
+    totalRuns: number;
+}
+/**
+ * Fuzz-tests a tool definition's handler with valid and adversarial inputs.
+ * Designed to be called inside a `describe()` / `it()` block.
+ *
+ * Checks:
+ * 1. Valid inputs -> handler runs without crash, output matches schema
+ * 2. Adversarial inputs -> Zod rejects or handler errors gracefully
+ * 3. No prototype pollution on Object.prototype
+ * 4. No stack trace / path leaks in error messages
+ * 5. Aborted signals -> handler doesn't hang
+ *
+ * @returns FuzzReport for additional custom assertions.
+ *
+ * @example
+ * ```ts
+ * import { fuzzTool } from '@cyanheads/mcp-ts-core/testing/fuzz';
+ *
+ * describe('myTool fuzz', () => {
+ *   it('survives fuzz testing', async () => {
+ *     const report = await fuzzTool(myTool, { numRuns: 100 });
+ *     expect(report.crashes).toHaveLength(0);
+ *     expect(report.leaks).toHaveLength(0);
+ *     expect(report.prototypePollution).toBe(false);
+ *   });
+ * });
+ * ```
+ */
+export declare function fuzzTool(def: AnyToolDefinition, options?: FuzzOptions): Promise<FuzzReport>;
+/**
+ * Fuzz-tests a resource definition's handler with valid and adversarial params.
+ *
+ * @example
+ * ```ts
+ * const report = await fuzzResource(myResource, { numRuns: 50 });
+ * expect(report.crashes).toHaveLength(0);
+ * ```
+ */
+export declare function fuzzResource(def: AnyResourceDefinition, options?: FuzzOptions): Promise<FuzzReport>;
+/**
+ * Fuzz-tests a prompt definition's `generate()` with valid and adversarial args.
+ *
+ * @example
+ * ```ts
+ * const report = await fuzzPrompt(myPrompt, { numRuns: 50 });
+ * expect(report.crashes).toHaveLength(0);
+ * ```
+ */
+export declare function fuzzPrompt(def: AnyPromptDefinition, options?: FuzzOptions): Promise<FuzzReport>;
+//# sourceMappingURL=fuzz.d.ts.map

package/dist/testing/fuzz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzz.d.ts","sourceRoot":"","sources":["../../src/testing/fuzz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAalD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AAC1F,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oDAAoD,CAAC;AAChG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4CAA4C,CAAC;AACpF,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAMxE,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,GAAG,CAAC,EAAE,kBAAkB,CAAC;IACzB,oDAAoD;IACpD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAErE;AAmHD,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAwDvC,CAAC;AAEX,6EAA6E;AAC7E,wBAAgB,oBAAoB,IAAI,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CA4B5D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,CAAC,WAAW,CAAC,GAC7B,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CASvC;AA2DD,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,gFAAgF;IAChF,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACnD,4DAA4D;IAC5D,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpD,sDAAsD;IACtD,kBAAkB,EAAE,OAAO,CAAC;IAC5B,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,iBAAiB,EACtB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CA8FrB;AAMD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,qBAAqB,EAC1B,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CA4ErB;AAMD;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,mBAAmB,EACxB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,UAAU,CAAC,CAmErB"}