adonis-docs-mcp 0.9.0

MCP server for AdonisJS documentation (v5, v6, v7) — gives AI agents quick access to AdonisJS docs

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:

Click to expand AGENTS.md template

# 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

Tool	Description
list_versions	List all available AdonisJS doc versions (v5, v6, v7)
list_sections	Browse the documentation structure for a version
get_doc	Fetch the full markdown content of a specific page
search_docs	Search docs by keyword across titles and content
clear_cache	Clear the local documentation cache

Edge.js Templates

Tool	Description
edge_list_sections	Browse the Edge.js documentation structure
edge_get_doc	Fetch the full markdown content of an Edge.js doc page
edge_search_docs	Search Edge.js docs by keyword

Lucid ORM

Tool	Description
lucid_list_sections	Browse the Lucid ORM documentation structure
lucid_get_doc	Fetch the full markdown content of a Lucid ORM doc page
lucid_search_docs	Search Lucid ORM docs by keyword

Packages Registry

Tool	Description
packages_list	List all AdonisJS packages, optionally filtered by category
packages_search	Search packages by keyword (name, description, category)
packages_get	Get full details and README for a specific package

Development Guidelines

Tool	Description
get_backend_guidelines	AdonisJS v7 backend rules: architecture, Edge templates, controllers, forms, models, assets
get_frontend_guidelines	Frontend anti-slop rules: semantic HTML, typography, color, layout, spacing, accessibility
get_code_quality_guidelines	Code quality anti-slop rules: surgical changes, no comment spam, no bloat, domain naming
get_agents_md	Generate an AGENTS.md file template for your AdonisJS project

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

Environment Variable	Default	Description
ADONIS_DOCS_CACHE_TTL	3600	Cache TTL in seconds (default: 1 hour)
ADONIS_DOCS_CACHE_DIR	~/.cache/adonis-docs-mcp	Cache directory path

Documentation Sources

Version	GitHub Repo	Status
v7	adonisjs/v7-docs	Latest (default)
v6	adonisjs/v6-docs	Stable
v5	adonisjs/v5-docs	Legacy
Edge.js	edge-js/edgejs.dev	Template engine
Lucid ORM	adonisjs/lucid.adonisjs.com	SQL ORM
Packages	adonisjs-community/adonis-packages	Community registry

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