# mcp-devtools

[![CI](https://github.com/VBSage/mcp-devtools/actions/workflows/ci.yml/badge.svg)](https://github.com/VBSage/mcp-devtools/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

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):
| Tool | Does |
|---|---|
| `json_tools` | Validate + format / minify / recursively sort-keys a JSON string |
| `regex_test` | Run a regex against a subject; returns every match, index, and capture group (**structured output**) |
| `hash_text` | MD5 / SHA-1 / SHA-256 / SHA-512 hex digest of text |
| `uuid_generate` | Generate 1–100 RFC-4122 v4 UUIDs |
| `base64_transform` | Base64 encode/decode, with an optional URL-safe alphabet |
| `jwt_inspect` | Decode a JWT's header/payload + expiry (decode only — does **not** verify the signature) |

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

## Install & run

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

Development (no build step, via tsx):

```bash
npm run dev
```

## Verify it works

```bash
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**
```bash
claude mcp add devtools -- node /absolute/path/to/mcp-devtools/dist/server.js
```

**Claude Desktop** — add to `claude_desktop_config.json`:
```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._