Metadata-Version: 2.4
Name: adonis-docs-mcp
Version: 0.9.0
Summary: MCP server for AdonisJS documentation (v5, v6, v7) — gives AI agents quick access to AdonisJS docs
Project-URL: Homepage, https://github.com/pimentelleo/adonis-docs-mcp
Project-URL: Repository, https://github.com/pimentelleo/adonis-docs-mcp
Project-URL: Issues, https://github.com/pimentelleo/adonis-docs-mcp/issues
Author: pimen
License-Expression: MIT
License-File: LICENSE
Keywords: adonisjs,ai,documentation,llm,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.0
Requires-Dist: mcp[cli]>=1.9.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# 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

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

## Integration

### Claude Desktop / Claude Code

Add to your MCP settings:

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

### VS Code / GitHub Copilot

Add to `.vscode/mcp.json`:

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

### Cursor

Add to your MCP config:

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

<details>
<summary>Click to expand AGENTS.md template</summary>

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

</details>

## 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](https://github.com/adonisjs/v7-docs) | Latest (default) |
| v6 | [adonisjs/v6-docs](https://github.com/adonisjs/v6-docs) | Stable |
| v5 | [adonisjs/v5-docs](https://github.com/adonisjs/v5-docs) | Legacy |
| Edge.js | [edge-js/edgejs.dev](https://github.com/edge-js/edgejs.dev) | Template engine |
| Lucid ORM | [adonisjs/lucid.adonisjs.com](https://github.com/adonisjs/lucid.adonisjs.com) | SQL ORM |
| Packages | [adonisjs-community/adonis-packages](https://github.com/adonisjs-community/adonis-packages) | Community registry |

## Development

```bash
# 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](https://docs.pypi.org/trusted-publishers/) 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
