mcp-works

Mock, contract-test, validate and guard MCP (Model Context Protocol) tool servers in Vitest with zero hassle.

📚 Full docs: https://ravandevil25.github.io/mcp-works/ — guides, API reference, migration, FAQ.

The official MCP SDK ships transport but no testing story. mcp-works fills that gap with four small tools: an in-process mock server, a contract checker, an arg validator, and a safety guard.

Install in 15 seconds

npm install mcp-works

import { contractTest, createMockServer, guard, validateArgs } from 'mcp-works';

const mock = createMockServer(
  {
    tools: [
      {
        name: 'get_time',
        description: 'Returns the current time.',
        inputSchema: { type: 'object', properties: {} },
      },
    ],
  },
  { get_time: () => new Date().toISOString() },
);

const report = await contractTest(mock.definition);
console.log(report.passed); // true

const safe = guard(mock, { timeoutMs: 5000, allowTools: ['get_time'] });
const res = await safe.callTool('get_time', {});
console.log(res.content[0]?.text);

Before / after

| Hand-rolled | With mcp-works | |---|---| | Spin up a real server per test (slow, flaky) | createMockServer in-process, 2 lines | | Wrong input crashes the agent at runtime | contractTest catches missing description/schema upfront | | Agent calls the wrong tool or hangs | guard allowlists tools, enforces timeout + output cap |

API

createMockServer(definition, handlers, options?)

In-process mock. callTool returns { content, isError } — unknown tools and thrown handler errors come back as isError: true instead of crashing. options.latencyMs simulates slow tools. Respects AbortSignal.

contractTest(definition)

Returns { passed, failures[] }. Checks: tools array shape, non-empty name/description, inputSchema object with type: 'object', unique names.

validateArgs(tool, args)

Zero-dependency runtime check of args against the tool's inputSchema. Returns { valid, failures[] } with dotted paths (filter.tag, tags[1]). Checks: required, type (string/number/integer/boolean/array/object), enum, string constraints (minLength, maxLength, pattern), number constraints (minimum, maximum), arrays (items type, minItems, maxItems), and nested objects.

const check = validateArgs(tool, { id: '42' });
if (!check.valid) console.log(check.failures);

guard(server, options?)

Wraps any server with a callTool method (mocks, SDK adapters — not just createMockServer output).

| Option | Default | Meaning | |---|---|---| | timeoutMs | 5000 | Abort slow calls; throws TIMEOUT | | allowTools | all | Deny-list everything else; throws TOOL_DENIED | | maxBytes | 1048576 (1MB) | Cap output size; throws OUTPUT_TOO_LARGE | | redact | off | true = redact emails, API keys, card-like numbers; RegExp[] = custom patterns (replaced with [redacted]) |

All errors are McpWorksError with a .code (TOOL_DENIED, TIMEOUT, OUTPUT_TOO_LARGE, ABORTED, INVALID_TOOL). McpTestkitError remains as a deprecated alias.

Migrating from @sauravsk2507/mcp-testkit

npm uninstall @sauravsk2507/mcp-testkit && npm install mcp-works

Then replace the import specifier: @sauravsk2507/mcp-testkit → mcp-works. API is identical; optionally rename McpTestkitError → McpWorksError.

Examples

node examples/vitest-mock.mjs
node examples/guard-express.mjs
node examples/sdk-compat.mjs

Roadmap

• v0.3: PII-redact guard option, richer validateArgs (arrays, string/number constraints), McpWorksError branding
• v0.4: npm create scaffolder, OTel tracing, registry audit metadata

FAQ

Does this replace the official MCP SDK? No. The SDK owns transport (stdio/SSE, protocol messages). This package owns the testing layer: mock, contract checks, arg validation, guard.

How do I use it with a real SDK server? Pull the tool definitions out of your SDK Server and feed them to contractTest / validateArgs. See examples/sdk-compat.mjs.

Does it work with plain Node test runner or Jest? Yes. Only the docs use Vitest. createMockServer, contractTest, validateArgs and guard are plain async functions with zero runtime deps.

How do I import from CommonJS? const { createMockServer } = require('mcp-works'); — dual ESM+CJS, verified by attw and a CJS smoke test in CI.

How do I catch guard errors? All guard errors are McpTestkitError with a .code: TOOL_DENIED, TIMEOUT, OUTPUT_TOO_LARGE. Switch on code for retries.

Troubleshooting

| Symptom | Cause | Fix | |---|---|---| | contractTest passes but bad args crash at runtime | Contract checks shape, not values | Add validateArgs(tool, args) before callTool | | TIMEOUT on every call | timeoutMs lower than handler latency | Raise timeoutMs or pass an AbortSignal with a longer deadline | | OUTPUT_TOO_LARGE | Default 1MB cap exceeded | Set maxBytes explicitly | | Types resolve to ESM under require | Stale 0.1.0 install | Upgrade to latest; require types ship as .d.cts |

License

MIT