# 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

| 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`

## Add to Claude Code

Published on npm as [`mcp-adonis-docs`](https://www.npmjs.com/package/mcp-adonis-docs) —
runs via npx, nothing to install or build.

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

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

Global level (available in all your projects):

```bash
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):

```bash
claude mcp add adonis-docs --scope user --env GITHUB_TOKEN=ghp_xxxx -- npx -y mcp-adonis-docs
```

Or configure `.mcp.json` manually:

```json
{
  "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

```bash
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](.github/workflows/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" }`