mcp-devtools

A small, production-quality Model Context Protocol (MCP) server exposing credential-free developer utilities. Built as a reference/demo of clean MCP server engineering: typed tool schemas, structured output, a resource, a prompt, unit tests, and an end-to-end protocol smoke test.

Zero credentials, zero network. Clone it, install, and it runs — nothing to configure, nothing to leak.

CI (.github/workflows/ci.yml) runs typecheck + unit tests + build + the wire-protocol smoke test on every push. Licensed MIT (see LICENSE).

Provenance: designed and reviewed by a human engineer (architecture, the decode-only security framing, the wire-protocol test strategy); implementation is AI-assisted. What's being sold is the engineering judgment, not the typing.

What it exposes

Tools (6):

Resource: devtools://reference/http-status-codes — common HTTP status codes as JSON. Prompt: code_review — a parameterized code-review request.

Related MCP server: mcp-dev-utils

Install & run

npm install
npm run build        # compile to dist/
npm start            # run the server on stdio

Development (no build step, via tsx):

npm run dev

Verify it works

npm test             # unit tests for all tool logic (node:test)
npm run smoke        # end-to-end: spawns the server, drives it with a real MCP client

npm run smoke connects an actual MCP client over stdio, lists the tools/resource/prompt, and calls each tool — proving the wire protocol, not just the functions. Expected tail:

ALL CHECKS PASSED

Add it to an MCP client

Claude Code

claude mcp add devtools -- node /absolute/path/to/mcp-devtools/dist/server.js

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "devtools": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-devtools/dist/server.js"]
    }
  }
}

Then ask the assistant things like "sort the keys in this JSON", "sha256 this string", or "decode this JWT" and it will call the tools.

Design notes (why it's built this way)

• Tool logic is separated from transport (src/logic.ts vs src/server.ts) so every tool is unit-testable in isolation and the MCP layer stays thin.

• Deterministic + self-contained — no network calls, no API keys, no live services. Errors are returned as isError tool results, not thrown, so the client sees a clean message.

• jwt_inspect decodes only. Signature verification needs key material and a stated algorithm policy; conflating "decode" with "verify" is a common security mistake, so this tool is explicit about not verifying.

• Structured output on regex_test returns a typed object (validated against the tool's outputSchema) alongside the human-readable text.

Stack

TypeScript · @modelcontextprotocol/sdk · zod · Node ≥ 20 · tests on node:test.

MIT-licensed engineering sample; provided as-is. Provenance note at the top.