Metadata-Version: 2.4
Name: adonis-docs-mcp
Version: 0.1.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
Description-Content-Type: text/markdown

# adonis-docs-mcp

MCP server that gives AI agents fast access to **AdonisJS documentation** (v5, v6, v7).

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

## Available Tools

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

## 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")
```

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

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