Vetwerk

vetwerk

Vet your MCP server before Claude does.

Your MCP server passes the spec validator and still dies the moment a real client talks to it. vetwerk finds why. It spawns your server over stdio, runs the handshake, lists the tools, throws bad input at it, and watches how it shuts down — then grades the things that actually kill servers in the field but slip past schema-level validators:

• Stdout hygiene — a stray log line, a startup banner, or a UTF-8 BOM on stdout corrupts the JSON-RPC stream. The #1 field failure, and the one lenient parsers hide.
• Handshake conformance — initialize returns a well-formed result with a protocol version, capabilities, and server info.
• Tool catalog & schemas — every advertised tool has a name, a description (the model picks tools by description), and a valid JSON Schema for its input.
• Error-envelope discipline — an unknown tool name or type-violating arguments come back as a clean JSON-RPC error, not a crash, a hang, or transport garbage. vetwerk checks the process is still alive afterward.
• Startup latency — how long initialize and tools/list really take.
• Shutdown — the server exits when its client closes stdin, instead of lingering as an orphan that holds file locks and ports.

vetwerk is not another spec validator. Tools like the official MCP Inspector, mcp-validator, and mcp-halflist check protocol conformance; vetwerk assumes you pass those and probes the operational failures that happen anyway.

Install

pip install vetwerk

Use

# Everything after -- is your server command, run however you'd run it.
vetwerk -- node server.js
vetwerk -- python -m my_server
vetwerk -- dotnet run --project src/MyMcp
vetwerk -- C:\tools\my-mcp\MyMcp.exe

# CI gate: write a JSON report and treat warnings as failures.
vetwerk --strict --json report.json -- node server.js

Exit codes: 0 pass (or warnings without --strict), 2 at least one check failed, 3 the server could not be spawned, 1 usage error.

Example

vetwerk :: KbSearchMcp 1.0.0.0
command: C:\tools\kb-search-mcp\KbSearchMcp.exe

  [ok] Initialize handshake         KbSearchMcp 1.0.0.0 speaks protocol 2025-06-18
  [ok] Tool catalog and schemas     8 tool(s); 0 schema fail(s), 0 warning(s)
  [ok] Error envelope discipline    bad input comes back as clean errors, server stays alive
         - unknown tool name -> clean error envelope
         - kb_get_page with type-violating args -> clean error envelope
  [ok] Startup latency              initialize 330 ms, tools/list 9 ms
  [ok] Exit on stdin EOF            exited in 0.0s with code 0
  [ok] Stdout hygiene               4440 bytes captured, every line is clean JSON-RPC

verdict: PASS

How it works

vetwerk drives a real spawn → initialize → notifications/initialized → tools/list → tools/call → stdin-EOF sequence against your server. It keeps every byte the server writes to stdout, parsed or not, and runs the hygiene check last against that complete capture — so it catches pollution the transport layer would otherwise swallow. The error-envelope probe builds type-violating arguments from your own tool schemas, so it adapts to whatever you advertise.

Scope (v0.1)

Targets stdio servers (the dominant local transport). HTTP/SSE transports, OAuth flows, and resource/prompt conformance are out of scope for now. Requires Python 3.10+.

License

MIT — see LICENSE.txt.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: draakaap
• Source: draakaap/vetwerk
• License: MIT

Install and usage instructions live in the source repository linked above.