adonis-docs-mcp

MCP server that gives AI agents fast access to AdonisJS documentation (v5, v6, v7) and Edge.js template engine documentation.

Fetches raw markdown directly from the official GitHub repos and caches locally for speed.

Quick Start

# Run with uvx (no install needed)
uvx adonis-docs-mcp

Integration

Claude Desktop / Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "adonis-docs": {
      "command": "uvx",
      "args": ["adonis-docs-mcp"]
    }
  }
}

VS Code / GitHub Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "adonis-docs": {
      "command": "uvx",
      "args": ["adonis-docs-mcp"]
    }
  }
}

Cursor

Add to your MCP config:

{
  "mcpServers": {
    "adonis-docs": {
      "command": "uvx",
      "args": ["adonis-docs-mcp"]
    }
  }
}

AGENTS.md for Your Project

To make sure AI agents always use this MCP when working on your AdonisJS project, add an AGENTS.md file to your project root. You can generate one by calling the get_agents_md tool, or copy the template below:

# AGENTS.md

This project is built with **AdonisJS v7** and **Edge.js** templates
(server-rendered monolith). An MCP server is available with documentation
and development guidelines — **use it before guessing**.

## Before You Start

1. Call `get_backend_guidelines` — architecture rules, Edge template
   conventions, controller patterns, forms, models, and assets.
2. Call `get_frontend_guidelines` — anti-slop rules for HTML, CSS, and UI
   development in Edge templates.
3. Call `get_code_quality_guidelines` — anti-slop rules for code changes
   (surgical edits, no bloat, no filler, domain naming).

## When You Need Documentation

- **AdonisJS v7 docs:** `search_docs(query="...", version="v7")` or
  `get_doc(permalink="...", version="v7")`. Use `list_sections(version="v7")`
  to browse available pages.
- **Edge.js templates:** `edge_search_docs(query="...")` or
  `edge_get_doc(permalink="...")`. Use `edge_list_sections()` to browse.
- **Lucid ORM (models, queries, migrations):**
  `lucid_search_docs(query="...")` or `lucid_get_doc(permalink="...")`.
  Use `lucid_list_sections()` to browse.
- **Community packages:** `packages_search(query="...")` to find packages,
  `packages_get(name="...")` to read full README with install/usage docs.

## Key Rules

- This is a **server-rendered app**, not a SPA. Do not introduce React, Vue,
  Svelte, or any frontend framework.
- Controllers render Edge views directly. No REST API for frontend consumption.
- Use Edge layouts, partials, and components — do not duplicate HTML structure.
- Validate with VineJS validators, not manually in controllers.
- Use Lucid ORM models with migrations. Never modify the database directly.
- Follow the existing project structure. Do not invent new directories or
  patterns.
- Do not add npm packages unless explicitly asked. Work with what is already
  in `package.json`.
- Keep changes surgical — only touch files related to the task.
- Read existing code before adding new code. Match naming conventions.

## Stack Reference

| Layer | Technology | Docs Tool |
|-------|-----------|-----------|
| Framework | AdonisJS v7 | `search_docs`, `get_doc` |
| Templates | Edge.js | `edge_search_docs`, `edge_get_doc` |
| ORM | Lucid | `lucid_search_docs`, `lucid_get_doc` |
| Validation | VineJS | `search_docs(query="validation")` |
| Auth | @adonisjs/auth | `search_docs(query="auth")` |
| Packages | Community registry | `packages_search`, `packages_get` |

Available Tools

AdonisJS

Edge.js Templates

Lucid ORM

Packages Registry

Development Guidelines

Examples

# List what's available
list_versions()

# Browse v7 docs structure
list_sections(version="v7")

# Read the routing guide
get_doc(permalink="guides/basics/routing", version="v7")

# Search for authentication docs
search_docs(query="authentication", version="v7")

# Search across all versions
search_docs(query="middleware", version="all")

# Browse Edge.js template docs
edge_list_sections()

# Read Edge.js components docs
edge_get_doc(permalink="components/introduction")

# Search Edge.js docs
edge_search_docs(query="slots")

# Browse Lucid ORM docs
lucid_list_sections()

# Read Lucid relationships docs
lucid_get_doc(permalink="relationships")

# Search Lucid ORM docs
lucid_search_docs(query="migrations")

# List all packages
packages_list()

# List authentication packages
packages_list(category="Authentication")

# Search for a package
packages_search(query="jwt")

# Get full details and README for a package
packages_get(name="adonisjs-jwt")

# Load guidelines before working on a project
get_backend_guidelines()
get_frontend_guidelines()
get_code_quality_guidelines()

Configuration

Documentation Sources

Development

# Clone and install
git clone https://github.com/pimentelleo/adonis-docs-mcp.git
cd adonis-docs-mcp
uv sync

# Run locally
uv run adonis-docs-mcp

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run adonis-docs-mcp

Publishing (maintainers)

This project uses PyPI Trusted Publishing via GitHub Actions.

One-time setup

1. Go to https://pypi.org/manage/account/publishing/
2. Add a new pending publisher:
   • Project name: adonis-docs-mcp
   • Owner: pimentelleo
   • Repository: adonis-docs-mcp
   • Workflow name: publish.yml
   • Environment name: pypi
3. Save

Releasing a new version

1. Update version in pyproject.toml and src/adonis_docs_mcp/__init__.py
2. Commit and push
3. Create a GitHub release (tag format: v0.1.0)
4. The publish workflow will automatically build and upload to PyPI

License

MIT