anvil

The universal tool compiler for AI agents.
One YAML definition. Ten compilation targets. Zero drift.

The Problem

Every agent runtime has its own tool format. You end up maintaining:

• An MCP schema for Claude Desktop
• An OpenAPI spec for your REST API
• TypeScript types for your SDK
• Hand-written docs that drift out of sync
• No eval coverage, no permission model, no agent-specific descriptions

Anvil replaces all of them with a single source of truth.

Quick Start

npm install -g @anvil-tools/cli
anvil init my-tools && cd my-tools
anvil validate
anvil compile

Define Once

anvil: "1.0"

service:
  name: github-tools
  version: "1.0.0"

tools:
  create_issue:
    description: Create a new GitHub issue
    agent:
      description: |
        Create a GitHub issue in a repository.
        Use when the user wants to file a bug or feature request.
      when_to_use:
        - User wants to create a bug report
        - User wants to file a feature request
      when_not_to_use:
        - User wants to comment on existing issue (use add_comment)
      tips:
        - Always include a clear title
        - Use markdown in the body
    parameters:
      owner:
        type: string
        required: true
        description: Repository owner
      repo:
        type: string
        required: true
      title:
        type: string
        required: true
      body:
        type: string
    permissions:
      - type: network
        target: api.github.com
        methods: [POST]
    side_effects: write
    cost: free
    examples:
      - name: bug_report
        input:
          owner: anthropics
          repo: claude-code
          title: "Bug: timeout on large files"
          body: "Completions time out after 30s on files >10MB."
        prompt: "Create a bug report for timeout issues"

Compile Everywhere

anvil compile   # → MCP server, OpenAPI spec, TypeScript SDK, docs, eval tests, agent schema, CLI...

What Makes Anvil Different

Agent-first semantics. Tools declare when_to_use, when_not_to_use, tips, cost, side_effects, and agent_description — information agents need to make good tool selection decisions.

Permissions as first-class. Every tool declares what it needs. The runtime enforces it.

Built-in eval. Examples in your definition become test cases automatically. Schema validation, contract testing, and agent tool selection eval from one source.

Compiler architecture. Parse → IR → Target plugins. Like protobuf for tools. Adding a new target is implementing one interface.

Schema Semantics

Registry

Anvil includes a self-hosted registry. Start it locally or deploy to any server:

# Start the registry (seeds with example packages)
cd packages/hub && SEED=true npm run dev

Then publish, search, and install:

anvil login --token <token> --registry http://localhost:4400/api/v1
anvil publish tools.anvil.yaml
anvil search "github"
anvil install github-tools

Runtime Middleware

import { compose, validationMiddleware, rateLimitMiddleware } from '@anvil-tools/runtime';

const handler = compose(
  validationMiddleware(ir),   // validates input/output
  rateLimitMiddleware(ir),    // enforces rate limits
  cachingMiddleware(ir),      // caches by tool config
  circuitBreakerMiddleware(), // prevents cascading failures
)(myToolHandler);

CLI Commands

Examples

See examples/ for complete definitions:

• GitHub — 5 tools: issues, search, PRs, comments, repo files
• PostgreSQL — queries, table schemas, guarded mutations
• Browser — navigate, screenshot, extract links
• Weather — current conditions, forecasts
• Linear — issue tracking
• Filesystem — read, write, list with permissions

Architecture

packages/
  schema/              Core types, parser, validation, IR
  compiler/            Compilation pipeline + plugin interface
  cli/                 10 CLI commands
  runtime/             Middleware, validation, telemetry
  registry/            Registry client
  hub/                 Self-hosted registry server (SQLite)
  target-mcp/          MCP server generator
  target-openapi/      OpenAPI spec generator
  target-docs/         Markdown docs generator
  target-agent-schema/ LLM-optimized schema generator
  target-eval/         Test harness generator
  target-sdk-ts/       TypeScript SDK generator
  target-cli-gen/      CLI app generator
  target-anthropic/    Claude API tool format
  target-openai/       OpenAI function calling format
  target-vercel-ai/    Vercel AI SDK format

Contributing

See CONTRIBUTING.md. Clone, pnpm install, pnpm run build, pnpm run test.

License

Apache 2.0