mcp-adonis-docs

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

Indexes and pages are cached in memory for 15 minutes.

Related MCP server: scoutdocs-mcp

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

Add to Claude Code

Published on npm as mcp-adonis-docs — runs via npx, nothing to install or build.

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

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

Global level (available in all your projects):

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

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 -- npx -y mcp-adonis-docs

Or configure .mcp.json manually:

{
  "mcpServers": {
    "adonis-docs": {
      "command": "npx",
      "args": ["-y", "mcp-adonis-docs"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

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

Prefer a global install? npm install -g mcp-adonis-docs gives you the adonis-docs-mcp command — use it in place of npx -y mcp-adonis-docs.

Development

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

Publishing to npm happens via GitHub Actions (publish.yml) — runs on every GitHub release or manual gh workflow run publish.yml. Requires an NPM_TOKEN repository secret (npm automation token).

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" }