Skip to main content
Glama
wthek-mcp
by Skillnter

Official @wthek Extension – MCP Server for HTTP Error Diagnostics & Framework Recipes

Local Model Context Protocol (MCP) server providing AI coding agents with error diagnostics, HTTP standards, and verified framework recipes.

A lightweight, production-grade MCP server built for AI coding agents (Claude Desktop, Cursor, Antigravity, etc.). Empowers agents to audit source code for error anti-patterns, resolve exact RFC status codes and headers, and generate verified @wthek error-handling setups for Express, Fastify, Hono, Koa, NestJS, and Restify.

💡 What the HEK?! AI agents hallucinating error-handling packages or writing manual res.status(500).json() calls? wthek-mcp runs locally alongside your AI editor over standard input/output (stdio), giving models deterministic tools to look up HTTP standards, generate copy-paste framework recipes, and audit source code before deploying to production.

GitHub Workflow Status npm version GitHub license GitHub Issues Codacy Badge Codacy Badge Socket Badge npm NPM Type Definitions Bundle Size Github Sponsors Open Collective Buy Me A Coffee Patreon PayPal


Features

  • Automated Anti-Pattern Auditing (audit_error_handling) – Detects manual status mutations, swallowed exceptions, missing headersSent guards, and generic throw new Error() in routes.

  • RFC Standards & Header Lookup (lookup_http_status) – Resolves exact RFC status code numbers, names, descriptions, standard headers (WWW-Authenticate, Allow, Retry-After), and import statements.

  • Hallucination-Free Recipes (get_framework_recipe) – Supplies agents with verified, copy-paste error handling recipes for Express, Fastify, Hono, Koa, NestJS, and Restify paired with validation companion libraries (Zod, TypeBox, Valibot).

  • Zero Configuration via npx – Ready to run out of the box via npx -y wthek-mcp in any MCP-compliant editor.

  • Standard Protocol Compliance – Built on @modelcontextprotocol/sdk utilizing standard input/output (stdio) transport.

  • Standalone Programmatic Tools – Tools can be consumed as an MCP server or imported directly as pure utility functions in custom Node.js agent pipelines.

  • 100% Test Coverage & TypeScript-First – Guaranteed reliability with strict typing, zero runtime exceptions, and full test coverage.


Related MCP server: API Debugger MCP

Table of Contents


Quick Start: Configuring Your AI Agent

No installation is necessary. Configure your agent to launch wthek-mcp via npx:

Claude Desktop Configuration

Add to claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wthek": {
      "command": "npx",
      "args": ["-y", "wthek-mcp"]
    }
  }
}

Cursor Configuration

Add to your project's .cursor/mcp.json or global Cursor settings:

{
  "mcpServers": {
    "wthek": {
      "command": "npx",
      "args": ["-y", "wthek-mcp"]
    }
  }
}

Antigravity Configuration

Add to your workspace or user MCP configuration file:

{
  "mcpServers": {
    "wthek": {
      "command": "npx",
      "args": ["-y", "wthek-mcp"]
    }
  }
}

Available MCP Tools

Once connected, your AI coding agent has direct access to the following 3 diagnostic tools:

1. lookup_http_status

Provides RFC metadata, recommended headers, and exact http-error-kit class imports for any HTTP status code or name.

Input Arguments:

  • query (string, required): Status code number (e.g. "404") or name (e.g. "NOT_FOUND", "too many requests").

Example Agent Output:

{
  "className": "NotFoundError",
  "code": 404,
  "description": "Not Found",
  "exampleSnippet": "import { NotFoundError } from \"http-error-kit\";\n\nthrow new NotFoundError(\"Not Found\");",
  "isClientError": true,
  "isServerError": false,
  "name": "NOT_FOUND",
  "recommendedHeaders": [],
  "rfcStandardUrl": "https://httpstatuses.com/404"
}

2. get_framework_recipe

Retrieves a verified, production-ready @wthek error handling recipe for a specific web framework and optional validator.

Input Arguments:

  • framework (string, required): Web framework name ("express", "fastify", "hono", "koa", "nestjs", "restify").

  • validator (string, optional): Schema validation library ("zod", "typebox", "valibot").

Example Agent Output:

{
  "framework": "express",
  "validator": "zod",
  "packages": [
    "@wthek/express-middleware",
    "@wthek/zod-express-interceptor",
    "http-error-kit",
    "zod"
  ],
  "code": "import express from \"express\";\nimport { KitExpressMiddleware } from \"@wthek/express-middleware\";\nimport { KitZodExpressInterceptor } from \"@wthek/zod-express-interceptor\";\n\nconst app = express();\napp.use(express.json());\n\n// 1. Define application routes before error middleware\napp.get(\"/api/example\", (req, res) => {\n  res.json({ status: \"ok\" });\n});\n\n// 2. Intercept Zod validation errors and convert them to KitHttpErrors\napp.use(KitZodExpressInterceptor());\n\n// 3. Centralized error-handling middleware (must be registered last)\napp.use(KitExpressMiddleware({ handleUnknownErrors: true, log: true }));",
  "instructions": [
    "1. Install dependencies: npm install @wthek/express-middleware @wthek/zod-express-interceptor http-error-kit zod",
    "2. Copy and adapt the recipe code into your application entrypoint.",
    "3. Throw named error classes (e.g. NotFoundError, BadRequestError) inside route handlers."
  ]
}

3. audit_error_handling

Audits source code snippets for common error-handling anti-patterns and suggests @wthek best practices.

ℹ️ About the Heuristic Audit: audit_error_handling is a fast, pattern-based heuristic diagnostic check designed to catch common pitfalls (such as manual status/json mutations, missing res.headersSent checks, and swallowed error logs). It is intentionally lightweight and non-intrusive—not a full AST-based static compiler or replacement for developer review or AI contextual reasoning.

Input Arguments:

  • code (string, required): Source code snippet to audit.

Example Agent Output:

{
  "codeSnippetLength": 72,
  "hasIssues": true,
  "issuesCount": 1,
  "summary": "Found 1 error-handling anti-pattern(s). Review suggestions to adopt @wthek best practices.",
  "issues": [
    {
      "description": "Direct manual response status and JSON payload mutation detected in route handler.",
      "rule": "no-manual-status-json",
      "severity": "high",
      "suggestion": "Throw structured http-error-kit classes (e.g. NotFoundError, BadRequestError) and delegate serialization to @wthek middleware."
    }
  ]
}

Programmatic Usage

Starting the MCP Server in Code

You can embed the server into custom Node.js agents, test suites, or orchestrators:

import { createWthekMcpServer } from "wthek-mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = createWthekMcpServer();
const transport = new StdioServerTransport();
await server.connect(transport);

Direct Tool Execution

Consume the diagnostic helpers directly in your Node.js application without starting an MCP server:

import {
  lookupHttpStatus,
  getFrameworkRecipe,
  auditErrorHandling,
} from "wthek-mcp";

// Look up status metadata
const statusInfo = lookupHttpStatus(401);
console.log(statusInfo.recommendedHeaders); // ["WWW-Authenticate"]

// Generate framework recipe
const recipe = getFrameworkRecipe("fastify", "zod");
console.log(recipe.packages); // ["@wthek/fastify-middleware", "http-error-kit", "@wthek/zod-transformer"]

// Audit source code
const report = auditErrorHandling(`
  app.get("/user", (req, res) => {
    res.status(500).json({ error: "Something broke" });
  });
`);
console.log(report.hasIssues); // true
console.log(report.issues[0].suggestion);

API Reference

API Overview

Export

Kind

Description

Returns

createWthekMcpServer()

Function

Creates and configures the McpServer instance

McpServer

lookupHttpStatus(query)

Function

Looks up HTTP status code metadata, RFC links, and snippets

IHttpStatusLookupResult

getFrameworkRecipe(framework, validator?)

Function

Generates verified framework error-handling recipes

IFrameworkRecipeResult

auditErrorHandling(code)

Function

Scans code snippets for error anti-patterns

IAuditResult

STATUS_CLASS_MAP

Constant

Maps numeric status codes to http-error-kit class names

Record<number, string>

STATUS_HEADERS_MAP

Constant

Maps status codes to recommended protocol headers

Record<number, string[]>

AUDIT_RULES

Constant

Active rule definitions and regular expression patterns

IAuditRuleDefinition[]

COMPANION_TRANSFORMERS

Constant

Validation companion package mapping dictionary

Record<string, string>


Exported Constants & Interfaces

import type {
  AuditSeverity,
  IAuditIssue,
  IAuditResult,
  IAuditRuleDefinition,
  IFrameworkRecipeResult,
  IHttpStatusLookupResult,
  SupportedFramework,
  SupportedValidator,
} from "wthek-mcp";

import {
  AUDIT_RULES,
  COMPANION_TRANSFORMERS,
  STATUS_CLASS_MAP,
  STATUS_HEADERS_MAP,
} from "wthek-mcp";

Architecture Diagram


Security Considerations

  1. Sandboxed Code Execution: audit_error_handling operates purely via static regular expression matching on provided code strings. It never evaluates (eval), executes, or loads external code.

  2. Safe Transports: wthek-mcp connects via local standard input/output (stdio), ensuring tools run locally on the developer's machine without exposing network ports or listening sockets.

  3. Defensive Input Validation: Status code lookups and recipe parameters are normalized to prevent prototype pollution or unhandled runtime exceptions.


Explore More WTHek Extensions

The WTHek ecosystem continues to grow with new extensions to simplify error handling across frameworks and AI pipelines. Stay updated with the latest tools that integrate seamlessly with http-error-kit:

Check out the official list of extensions: Official Extensions List


People

The original author of the project is Himanshu Bansal


Donations

This is all voluntary work, so if you want to support my efforts you can:

You can also use the following cryptocurrency addresses:

BTC: bc1p22h4nsad5d8ketyhuvf0vyva6unttxwzzqvkty5r839as0mlclgs72d3mf

ETH: 0x1D59a291391a3CE17C63D5dC50F258Dc0Ab62889

BNB: 0x1D59a291391a3CE17C63D5dC50F258Dc0Ab62889


License

wthek-mcp is open-sourced software licensed under the MIT license by Himanshu Bansal.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An HTTP MCP server providing AI agents with real-time access to all VS Code diagnostics (TypeScript, ESLint, Prettier, etc.) via 5 powerful tools including workspace health scoring.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to inspect, test, validate, compare, and debug HTTP APIs through a structured toolkit, with features such as secret redaction, response contract validation, regression comparison, health checks, and incident investigation workflows.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Verifies environment variable reads, Python/Node imports, and FastAPI/Starlette route handlers against a repository's indexed contracts so coding agents can catch broken references before changes ship. Exposes tools such as check_change, check_claim, audit, suggest, index_status, and index locally, with no API key, runtime dependencies, or network calls on the default path.
      4
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Exposes six security tools (scan_repo, scan_diff, list_findings, get_finding, verify_finding, list_detectors) over stdio or HTTP so AI coding agents can run SAST/SCA/secrets/IaC scans and inspect prioritized findings without writing to the repository. It also lets agents verify a finding by re-running its generated proof-of-concept in an isolated sandbox, returning a confirmed or unavailable verdict.
      17
      Apache 2.0