> ## 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 JS is a Node.js backend framework with file-based routing, compile-time validation, and a native agentic layer — MCP, tools, tracing, and agents built in.

Anvil JS is a Node.js backend framework built for AI and GenAI developers. It gives you Express-level flexibility and Next.js-style file-based routing, with a native agentic layer — MCP auto-exposure, a tool registry, agent orchestration, observability, and durability — built directly into the framework core. No second MCP codebase. No hand-wired tool schemas. No separate tracing infra.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build your first Anvil app with file-based routes and an agent endpoint in under 5 minutes.
  </Card>

  <Card title="File-Based Routing" icon="folder-tree" href="/routing/file-based-routing">
    Learn how Anvil maps your folder structure to HTTP routes — dynamic params, catch-alls, and middleware scoping.
  </Card>

  <Card title="MCP & Tools" icon="plug" href="/mcp/overview">
    Expose any route as an MCP tool with a single annotation — no separate MCP server required.
  </Card>

  <Card title="Agent Routes" icon="robot" href="/agents/overview">
    Define streaming agent endpoints with built-in LLM clients, tool calling, and abort propagation.
  </Card>

  <Card title="Observability" icon="chart-line" href="/observability/tracing">
    Trace every agent run, track token usage and cost, and replay past runs without live model calls.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Reference for all Anvil CLI commands: dev, build, start, mcp, lint, eval, and replay.
  </Card>
</CardGroup>

## Why Anvil?

Today, building an AI product on Node requires stitching together Express for HTTP, a hand-written MCP server, OpenAI/Anthropic SDK calls scattered across routes, and no standard way to trace a multi-step agent run. Anvil solves this once at the framework layer:

* **One route, three protocols.** Any Anvil route automatically speaks REST, MCP, and A2A — same handler, no duplicated schemas.
* **Compile-time safety.** The `anvil build` step validates param names, schema compatibility, and MCP serializability before you ship.
* **Agent-native primitives.** `defineAgent`, `LlmClient`, guardrails, durable checkpointing, and human-in-the-loop are framework features, not application code you write per project.
* **Built-in observability.** Every agent run is traced to a local SQLite store and viewable at `/_anvil`. OTel export ships out of the box.

<Steps>
  <Step title="Install Anvil">
    Add the `anvil` package to your Node.js project (requires Node ≥ 20).

    ```bash theme={null}
    npm install anvil
    ```
  </Step>

  <Step title="Create your first route">
    Add `server/routes/get.ts` — the file name and location define the HTTP method and path.

    ```ts server/routes/get.ts theme={null}
    import type { Context } from 'anvil';

    export default async function handler(ctx: Context) {
      return { message: 'Hello from Anvil!' };
    }
    ```
  </Step>

  <Step title="Start the dev server">
    Run `anvil dev` to start a live-reload server. TypeScript routes load on the fly.

    ```bash theme={null}
    anvil dev
    # [anvil] dev server listening on http://localhost:3000
    ```
  </Step>

  <Step title="Expose a route as an MCP tool">
    Add `meta` and a `paramsSchema` to turn any route into an MCP tool with `anvil mcp`.

    ```ts server/routes/users/[id]/get.ts theme={null}
    import { z } from 'zod';
    import type { Context } from 'anvil';

    export const meta = { mcp: { expose: true, description: 'Fetch a user by ID' } };
    export const paramsSchema = z.object({ id: z.string() });

    export default async function handler(ctx: Context) {
      return findUser(ctx.params.id);
    }
    ```
  </Step>
</Steps>

<Note>
  Anvil is currently **pre-alpha**. The core framework (routing, MCP, agents, observability, durability, RAG, A2A) is fully implemented. The public release (docs, examples, marketing) is the final milestone.
</Note>