[![Python 3.13+](https://img.shields.io/badge/Python-3.13+-3776AB?style=flat&logo=python&logoColor=white)](https://python.org)
[![MCP 1.0](https://img.shields.io/badge/MCP-1.0-00A67E?style=flat)](https://modelcontextprotocol.io/)
[![ChromaDB](https://img.shields.io/badge/ChromaDB-1.5-FF6F00?style=flat)](https://www.trychroma.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=flat)](LICENSE)

# oarx-docs-mcp

> MCP server for semantic search across the complete ObjectARX 2026 documentation set.
> 89,715 text chunks from 22 guides indexed in ChromaDB with hybrid BM25 + dense retrieval.

## Overview

**oarx-docs-mcp** indexes **89,715 text chunks** from **22 documentation guides**
into a local [ChromaDB](https://www.trychroma.com/) vector database and exposes
them through the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP)
for use with Claude Code, Claude Desktop, or any MCP-compatible client.

## Highlights

- **3 MCP tools** — `search_docs`, `lookup_class`, `list_guides`
- **89,715 indexed chunks** from 22 documentation guides (ObjectARX SDK + Autodesk CloudHelp)
- **Hybrid retrieval** — BM25 sparse + dense vectors + Reciprocal Rank Fusion
- **Cross-encoder reranking** with BAAI/bge-reranker-v2-m3
- **Query optimization** — AutoLISP detection, C++ API expansion, guide-specific boosting
- **Container-ready** — Containerfile + compose.yaml (Podman/Docker)
- **Claude Code plugin** — 4 skills + 2 slash commands for ObjectARX development

### Data Sources

| Source | Guides | Pages | Description |
|--------|--------|-------|-------------|
| ObjectARX SDK (CHM) | 8 | ~45,800 | C++ Reference, .NET Reference, Developer Guides, Migration, Interop |
| Autodesk CloudHelp (web) | 14 | ~5,000 | AutoLISP, ActiveX/VBA, JavaScript, DXF, Customization |

### MCP Tools

| Tool | Description |
|------|-------------|
| `list_guides` | List all 22 available documentation guides |
| `search_docs` | Semantic search with optional guide filter and result limit |
| `lookup_class` | Look up a class or function by name (title match with semantic fallback) |

## Quick Start

```bash
# Clone and install
cd mcp/oarx-docs-mcp
uv sync

# Download web documentation (~5,000 pages)
OARX_DATA_DIR=./data uv run python -m oarx_docs_mcp.scraper

# Index CHM files from ObjectARX SDK (optional, requires 7-Zip)
OARX_DATA_DIR=./data OARX_CHM_DIR=/path/to/sdk/docs uv run python -m oarx_docs_mcp.indexer

# Or index web docs only (no SDK needed)
OARX_DATA_DIR=./data uv run python -m oarx_docs_mcp.indexer
```

## Client Configuration

<details>
<summary><b>Claude Code</b></summary>

Add to `~/.claude.json` (or project-level `.claude.json`):

```json
{
  "mcpServers": {
    "oarx-docs": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/oarx-docs-mcp",
        "python", "-m", "oarx_docs_mcp"
      ],
      "env": {
        "OARX_DATA_DIR": "/path/to/oarx-docs-mcp/data"
      }
    }
  }
}
```

<details>
<summary>Windows example</summary>

```json
{
  "mcpServers": {
    "oarx-docs": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "C:/Users/user/oarx-docs-mcp",
        "python", "-m", "oarx_docs_mcp"
      ],
      "env": {
        "OARX_DATA_DIR": "C:/Users/user/oarx-docs-mcp/data"
      }
    }
  }
}
```

</details>

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Add to Claude Desktop's MCP configuration file:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "oarx-docs": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/oarx-docs-mcp",
        "python", "-m", "oarx_docs_mcp"
      ],
      "env": {
        "OARX_DATA_DIR": "/path/to/oarx-docs-mcp/data"
      }
    }
  }
}
```

Restart Claude Desktop to pick up the new configuration.

</details>

<details>
<summary><b>OpenAI Codex CLI</b></summary>

Add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project):

```toml
[mcp_servers.oarx-docs]
command = "uv"
args = ["run", "--directory", "/path/to/oarx-docs-mcp", "python", "-m", "oarx_docs_mcp"]

[mcp_servers.oarx-docs.env]
OARX_DATA_DIR = "/path/to/oarx-docs-mcp/data"
```

Or via CLI:
```bash
codex mcp add oarx-docs --env OARX_DATA_DIR=/path/to/data -- uv run --directory /path/to/oarx-docs-mcp python -m oarx_docs_mcp
```

</details>

## Container Setup

```bash
# Build image
podman-compose build

# Download web docs
podman-compose --profile scraper run --rm scraper

# Index (requires OARX_CHM_DIR env var for CHM files)
OARX_CHM_DIR=/path/to/sdk/docs podman-compose --profile indexer run --rm indexer

# Run server
podman-compose up server
```

## Configuration

All settings are configurable via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `OARX_CHM_DIR` | `/docs` | Directory containing `.chm` files from ObjectARX SDK |
| `OARX_DATA_DIR` | `/app/data` | Data directory for ChromaDB and extracted HTML |
| `OARX_EMBEDDING_MODEL` | `BAAI/bge-m3` | Sentence-transformers model name |
| `OARX_CHUNK_SIZE` | `800` | Text chunk size in characters |
| `OARX_CHUNK_OVERLAP` | `200` | Overlap between adjacent chunks |
| `OARX_7Z_PATH` | auto-detect | Path to 7z executable |
| `OARX_DB_SOURCE` | `github` | Database source: `github`, `huggingface`, or `local` |
| `OARX_DB_VERSION` | `0.1.0` | Database version to download |
| `OARX_GITHUB_REPO` | `dantte-lp/oarx-docs-mcp` | GitHub repository for release assets |

## Development

```bash
# Install with dev dependencies
uv sync --all-extras

# Run tests
uv run python -m pytest tests/ -v

# Lint
uv run ruff check src/ tests/

# Type check
uv run mypy
```

## Tech Stack

- **Python** 3.13+ with [uv](https://github.com/astral-sh/uv)
- **[MCP SDK](https://github.com/modelcontextprotocol/python-sdk)** (FastMCP, stdio transport)
- **[ChromaDB](https://www.trychroma.com/)** (persistent vector store, HNSW + cosine)
- **[sentence-transformers](https://www.sbert.net/)** (`all-MiniLM-L6-v2`, 384-dim embeddings)
- **[BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/)** + lxml (HTML parsing)
- **[httpx](https://www.python-httpx.org/)** (web documentation scraping)
- **[Podman](https://podman.io/)** / podman-compose (containerization)

## Project Structure

```
oarx-docs-mcp/
├── src/oarx_docs_mcp/
│   ├── __main__.py          # Entry point
│   ├── config.py            # Settings + guide registries
│   ├── data_manager.py      # Database auto-download
│   ├── indexer.py           # CHM/HTML → ChromaDB
│   ├── retriever.py         # BM25 + dense + RRF + reranking
│   ├── scraper.py           # CloudHelp downloader
│   └── server.py            # MCP tools (3 tools)
├── tests/                   # pytest + pytest-asyncio
├── plugin/                  # Claude Code plugin
├── docs/
│   ├── en/                  # English documentation
│   └── ru/                  # Russian documentation
├── Containerfile            # OCI container image
└── compose.yaml             # Podman/Docker services
```

## Documentation

| Document | EN | RU |
|----------|----|----|
| Architecture | [architecture.md](docs/en/architecture.md) | [architecture.md](docs/ru/architecture.md) |
| Installation | [installation.md](docs/en/installation.md) | [installation.md](docs/ru/installation.md) |
| Configuration | [configuration.md](docs/en/configuration.md) | [configuration.md](docs/ru/configuration.md) |
| Usage | [usage.md](docs/en/usage.md) | [usage.md](docs/ru/usage.md) |
| Troubleshooting | [troubleshooting.md](docs/en/troubleshooting.md) | [troubleshooting.md](docs/ru/troubleshooting.md) |
| Changelog | [CHANGELOG.md](CHANGELOG.md) | — |
| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) | [CONTRIBUTING.RU.md](CONTRIBUTING.RU.md) |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) ([RU](CONTRIBUTING.RU.md)).

## License

MIT