@codewright/mcp

A Model Context Protocol server that exposes Codewright's public, read-only API v1 to any MCP-compatible agent host (Claude Desktop, Claude Code, etc). It never talks to the database directly and never executes any command locally — see "Safety" below.

Configuration

| Env var | Default | Purpose | | --- | --- | --- | | CODEWRIGHT_API_BASE_URL | https://codewright.tools/api/v1 | Base URL of the Codewright public API v1. |

Running

Once published, run it directly with npx:

npx @codewright/mcp

Or add it to a Claude Desktop / Claude Code MCP configuration:

{
  "mcpServers": {
    "codewright": {
      "command": "npx",
      "args": ["-y", "@codewright/mcp"],
      "env": {
        "CODEWRIGHT_API_BASE_URL": "https://codewright.tools/api/v1"
      }
    }
  }
}

During local development in this monorepo, run it from source instead:

pnpm --filter @codewright/mcp build
node packages/mcp-server/dist/cli.js

Tools

• search_recipes — { query: string, limit?: number } → full-text search over the recipe library (GET /api/v1/recipes/search). Returns recipe summaries (id, title, risk, platforms, tags, etc).
• get_recipe — { id: string } → the full recipe document (GET /api/v1/recipes/{id}), including parameters, per-platform steps, verification, and undo.
• render_recipe — { id: string, platform: "macos" | "linux" | "windows", params?: Record<string, string | number | boolean> } → concrete, parameter-substituted commands for the given platform (POST /api/v1/recipes/{id}/render).
• search_workflows — { query: string, category?: string } → full-text search over the workflow library (GET /api/v1/workflows/search). Returns workflow summaries (id, title, description, category, tags). The underlying search endpoint doesn't take a category filter itself, so when category is given this tool applies it client-side over the search results.
• get_workflow — { id: string } → the full workflow document (GET /api/v1/workflows/{id}), including the entry node id and the entire nodes map, so a caller can walk branches itself (matching its own tool-call output against each node's branches) without a round trip per node.

Safety

render_recipe (and this package as a whole) never executes any command. It only relays the JSON returned by the Codewright API verbatim — including risk and requires_confirmation — so the calling agent/host is responsible for deciding whether and how to run the returned commands, and for honoring requires_confirmation: true on destructive recipes by asking the user first (see docs/ARCHITECTURE.md "Security ground rules" and docs/RECIPE_SPEC.md). There is no child_process/exec usage anywhere in this package.

Publishing

This PR does not publish the package to npm. Publishing under the @codewright npm scope is a separate, human-gated step performed outside the agent workflow.