> ## Documentation Index
> Fetch the complete documentation index at: https://anvil.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Anvil JS: Node.js Backend Framework for AI Developers

> Anvil is a Node.js backend framework with file-based routing, compile-time validation, and a native agentic layer: MCP, tools, tracing, and more.

Anvil is a Node.js backend framework designed for developers building AI-powered and agent-driven applications. It gives you the ergonomics of Express, the structural clarity of Next.js-style file-based routing, and a native agentic layer — MCP auto-exposure, a tool registry, agent orchestration, distributed tracing, durable checkpointing, and more — without requiring a second codebase, a separate config file, or a pile of duplicated schemas.

## The problem Anvil solves

Building a backend for an AI-first product today forces you to maintain parallel worlds: one codebase for your HTTP API, another set of schemas for your MCP tools, manual wiring for tracing and cost observability, and no standard way to resume an agent run after a crash. The result is duplicated logic, schema drift, and brittle glue code that breaks every time a model or SDK changes.

Anvil collapses all of that into a single framework:

* **No duplicate MCP schemas** — mark any route `mcp: { expose: true }` and it becomes an MCP tool automatically. The same handler, the same Zod schema, zero extra code.
* **No manual tracing wiring** — every request, model call, tool invocation, and token cost is captured in the built-in trace store and surfaced through the `/_anvil` dashboard.
* **No crash-resume glue** — durable checkpointing lets agent runs survive restarts; human-in-the-loop gates pause execution until approval arrives.
* **No framework-per-concern** — routing, middleware, CORS, static files, MCP, agent orchestration, evals, and RAG are all first-class citizens in the same package.

## Key features

<CardGroup cols={2}>
  <Card title="File-Based Routing" icon="folder-tree" href="/routing/file-based-routing">
    Drop a `get.ts` in `server/routes/users/` and you have `GET /users`. No config, no decorators, no registration step.
  </Card>

  <Card title="Dynamic Routes" icon="brackets-curly" href="/routing/dynamic-routes">
    Use `[param]` folders for path parameters and `[...param]` for catch-all segments. Validate them with Zod at compile time.
  </Card>

  <Card title="Scoped Middleware" icon="layer-group" href="/routing/middleware">
    Place `_middleware.ts` next to your routes for folder-scoped middleware. Compose multiple middleware functions with the built-in `compose()` helper.
  </Card>

  <Card title="Context API" icon="code" href="/routing/context">
    A single `Context` object replaces Express's `(req, res)` pair — typed params, cached body parsing, and first-class response helpers.
  </Card>

  <Card title="MCP Auto-Exposure" icon="plug" href="/mcp/overview">
    Any route annotated with `meta.mcp.expose` is instantly available as an MCP tool. Run `anvil mcp` to serve tools over Streamable HTTP or `--stdio` for Claude Desktop.
  </Card>

  <Card title="Agent Routes" icon="robot" href="/agents/overview">
    An `agent.ts` file is a streaming agent endpoint. It runs the full model↔tool loop, validates inputs, tracks cost, and aborts cleanly on client disconnect.
  </Card>
</CardGroup>

## Requirements

* **Node.js ≥ 20** (uses the native `Request`/`Response` Web API built into Node 20+)
* **ESM project** — your `package.json` must include `"type": "module"`
* npm, yarn, or pnpm

## CLI overview

Anvil ships with a CLI that handles the full development and deployment lifecycle:

| Command                  | Description                                                               |
| ------------------------ | ------------------------------------------------------------------------- |
| `anvil dev`              | Dev server with watch mode — TypeScript routes are loaded on the fly      |
| `anvil build`            | Generates `.gen/routes.ts` and bundles `dist/server.mjs`                  |
| `anvil start`            | Runs the production bundle                                                |
| `anvil lint`             | Validates routes: checks param schema keys, MCP JSON Schema compatibility |
| `anvil mcp`              | Serves MCP-exposed routes and `server/tools/` over Streamable HTTP        |
| `anvil eval <file>`      | Runs an eval suite against an agent; exits non-zero on failure            |
| `anvil replay <traceId>` | Re-runs a captured trace with mocked responses                            |

## Example apps

Three complete, runnable projects live in the [GitHub repo](https://github.com/subh05sus/anvil-js/tree/main/examples):

<CardGroup cols={3}>
  <Card title="basic-api" icon="folder-tree" href="https://github.com/subh05sus/anvil-js/tree/main/examples/basic-api">
    Express-parity REST API: dynamic routes, scoped middleware, static files, and a route exposed as an MCP tool.
  </Card>

  <Card title="mcp-server" icon="plug" href="https://github.com/subh05sus/anvil-js/tree/main/examples/mcp-server">
    A minimal project demonstrating the zero-extra-code MCP wedge — CRUD routes and a standalone tool, all served by `anvil mcp`.
  </Card>

  <Card title="agent-hitl" icon="user-check" href="https://github.com/subh05sus/anvil-js/tree/main/examples/agent-hitl">
    An agent route with a refund tool gated behind human approval — suspend, approve, and resume, with durable checkpointing.
  </Card>
</CardGroup>

## Next steps

Ready to build? Start with the quickstart to have a working Anvil API in under five minutes.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Install Anvil, create your first route, and run the dev server.
  </Card>

  <Card title="Installation" icon="download" href="/installation">
    Detailed setup: Node version, package managers, ESM config, and optional peer deps.
  </Card>
</CardGroup>