adonis-docs-mcp

MCP server for version-aware AdonisJS documentation. It reads your project's package.json, detects which AdonisJS major version you are on (v4, v5, v6, or v7), and searches the documentation that matches — so you never get v7 answers for a v5 app.

Also covers Lucid ORM, Edge templates, VineJS validation, and Japa testing docs.

Documentation sources

| Source | Where it reads from | |--------|---------------------| | v7 (core) | docs.adonisjs.com/llms.txt index + raw markdown pages | | v6 (core) | github.com/adonisjs/v6-docs (markdown) | | v5 (core) | github.com/adonisjs/v5-docs (markdown) | | v4 (core) | github.com/adonisjs/legacy-docs branch 4.1 (asciidoc) | | Lucid ORM | github.com/adonisjs/lucid.adonisjs.com (markdown) | | Edge | github.com/edge-js/edgejs.dev (markdown) | | VineJS | github.com/vinejs/vinejs.dev (markdown) | | Japa | github.com/japa/japa.dev branch 3.x (markdown) |

Indexes and pages are cached in memory for 15 minutes.

Version detection

From dependencies + devDependencies in the project's package.json:

• @adonisjs/core major 7 → v7
• @adonisjs/core major 6 → v6
• @adonisjs/core major 5 → v5
• @adonisjs/framework → v4

Tools

detect_version

Reads package.json and reports the AdonisJS version, related packages (@adonisjs/lucid, edge.js, ...), and the matching docs site.

• projectPath — project root or path to package.json

search_docs

Keyword search over the docs index. Output is a compact ranked list (title + doc id) designed to stay small in context.

• query — keywords, e.g. "auth middleware", "lucid relationships"
• library — core (default), lucid, edge, vine, or japa
• version — v4 | v5 | v6 | v7 (optional)
• projectPath — auto-detect the version from this project (optional)
• limit — max results, default 8

When neither version nor projectPath is given, defaults to v7.

get_doc

Fetches one doc page as plain markdown/asciidoc — no HTML, no boilerplate.

• id — doc id from search_docs
• section — keyword; returns only the matching heading section (much cheaper than the full page)
• maxLength — character cap, default 8000 (truncates at a line boundary)
• library / version / projectPath — same as search_docs

Install

No clone or build needed — install straight from GitHub (builds automatically on install, no auth required):

npm install -g github:fdciabdul/mcp-adonis-docs

This gives you the adonis-docs-mcp command.

Pin a version via package.json if you prefer:

"@fdciabdul/mcp-adonis-docs": "github:fdciabdul/mcp-adonis-docs#main"

The package is also published to GitHub Packages as @fdciabdul/[email protected]. Note that GitHub Packages requires a personal access token with the read:packages scope even for public packages (gh auth token does NOT have it by default). Add to ~/.npmrc:

@fdciabdul:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=TOKEN_WITH_READ_PACKAGES

then npm install -g @fdciabdul/mcp-adonis-docs.

Add to Claude Code

Project level (writes .mcp.json, shared with your team):

claude mcp add adonis-docs --scope project -- adonis-docs-mcp

Global level (available in all your projects):

claude mcp add adonis-docs --scope user -- adonis-docs-mcp

With a GitHub token (recommended — raises the docs-index rate limit from 60 to 5000 requests/hour; both GITHUB_TOKEN and GH_TOKEN are accepted):

claude mcp add adonis-docs --scope user --env GITHUB_TOKEN=ghp_xxxx -- adonis-docs-mcp

Without a global install, run it through npx instead:

claude mcp add adonis-docs --scope user -- npx -y github:fdciabdul/mcp-adonis-docs

Or configure .mcp.json manually:

{
  "mcpServers": {
    "adonis-docs": {
      "command": "adonis-docs-mcp",
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Claude Code expands ${VAR} in .mcp.json, so no hardcoded token needed.

Development

git clone https://github.com/fdciabdul/mcp-adonis-docs.git
npm install
npm run build   # or npm run dev for watch mode

Publishing happens via GitHub Actions (publish.yml) — runs on every GitHub release or manual gh workflow run publish.yml.

Example flow

1. detect_version { projectPath: "./my-app" } → AdonisJS v5 (@adonisjs/core@^5.9.0)
2. search_docs { query: "file upload", projectPath: "./my-app" } → ranked ids from v5 docs
3. get_doc { id: "content/guides/http/file-uploads.md", version: "v5", section: "validating" }