Claude Code Integration

d1-eloquent ships with first-class Claude Code support through two complementary tools: a skill that teaches Claude how to write correct d1-eloquent code, and an MCP server that gives Claude live access to your D1 database.

Skill

The d1-eloquent skill is a set of reference documents that Claude Code loads automatically when it detects you're working with d1-eloquent. It covers model definitions, migrations, query building, relationships, hooks, casting, seeders, factories, and every CLI command.

When the skill is active, Claude will:

• Generate models with correct BaseModel<TAttrs> patterns, TEXT primary keys, and proper casts
• Write migrations using the schema builder (not raw SQL)
• Use declarative static relations instead of legacy helpers
• Apply configure(env) auto-wiring or explicit db arguments consistently
• Follow all d1-eloquent conventions (soft deletes, revision tracking, mass assignment, etc.)

Install the Skill

# Clone into your Claude Code skills directory
git clone https://github.com/Orphnet/d1-eloquent-skill.git ~/.claude/skills/d1-eloquent-skill

That's it. Claude Code discovers skills from ~/.claude/skills/ automatically. The skill activates whenever you mention d1-eloquent, Cloudflare D1, or ask Claude to scaffold a Workers + D1 project.

No configuration needed

The skill has no dependencies or build step. It's a set of markdown reference files that Claude reads on demand.

MCP Server

The MCP server (@orphnet/d1-eloquent-mcp) gives Claude — and any Model Context Protocol–compatible client (Claude Desktop, Cursor, Windsurf, JetBrains) — live, context-aware access to your project:

• Introspect your models, migrations, seeders, factories, and the actual D1 schema
• Generate new resources via your existing bunx d1-eloquent make:* CLI
• Execute migrate / rollback / fresh / seed against your local D1
• Query the local D1 with read-only SQL (SELECT / WITH / EXPLAIN / PRAGMA)

Status

@orphnet/d1-eloquent-mcp@0.1.0-alpha.0 — works against any local d1-eloquent project. Remote D1 access is planned for a future release.

Install in Claude Code

claude mcp add d1-eloquent -- bunx @orphnet/d1-eloquent-mcp

Install in Claude Desktop

Add to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "d1-eloquent": {
      "command": "bunx",
      "args": ["@orphnet/d1-eloquent-mcp"]
    }
  }
}

Per-project (Claude Code)

Drop a .claude/mcp.json in your project so the server scopes to that codebase. To target a different directory, pass --project:

{
  "mcpServers": {
    "d1-eloquent": {
      "command": "bunx",
      "args": ["@orphnet/d1-eloquent-mcp", "--project", "/path/to/your/project"]
    }
  }
}

What gets discovered

On startup the server scans for wrangler.jsonc / wrangler.toml, classes that extends BaseModel, and the migrations / seeders / factories directories. Static parsing — never imports your code, so it works without your build chain.

Available Tools

Introspection (read-only)

• list_models, read_model — model classes + parsed metadata (relations, casts, soft deletes, revisions)
• list_migrations, read_migration, migration_status
• inspect_schema — what's actually in your D1 (sqlite_master)
• query_d1 — read-only SQL against the local D1
• list_seeders, list_factories, read_file, refresh_project

Generation (delegates to your existing CLI)

• make_model, make_migration, make_seeder, make_factory, make_resource, make_pivot

Execution (local D1)

• run_migrate, run_rollback, run_fresh, run_seed

Resources

Claude can pull these in as background context:

• d1-eloquent://project/summary — your project's discovered state
• d1-eloquent://docs/api/base-model
• d1-eloquent://docs/api/query-builder
• d1-eloquent://docs/api/relationships
• d1-eloquent://docs/guide/quick-start

Prompts

Pre-built multi-step workflow templates:

• create-model — scaffold + migrate + verify in one chat
• audit-schema — compare every model against the actual D1 schema, report drift

Safety

• query_d1 rejects anything other than SELECT / WITH / EXPLAIN / PRAGMA, and rejects multi-statement payloads.
• read_file refuses paths containing .. or starting with /.
• Shell-outs use spawnSync with arg arrays — no shell-injection vectors.
• Execution tools (run_migrate / run_rollback / run_fresh / run_seed) only operate on the local D1.

Resources

• d1-eloquent-skill on GitHub -- skill source and reference docs
• d1-eloquent-mcp on GitHub -- MCP server source + release notes
• Claude Code documentation -- skills, MCP servers, and configuration