# @devista/docs-mcp

A generic MCP server that gives AI agents (Claude Code, Cursor, etc.) full-text search over any Markdown/MDX documentation folder. Point it at your docs and your AI assistant can search, browse, and read your project documentation during development.

## How It Works

The server runs as a local process communicating over stdio (the standard MCP transport). When it starts:

1. **Freshness check** — compares modification times of your doc files against the last-built index
2. **Auto-rebuild** — if any file changed (or the index doesn't exist yet), it parses all Markdown/MDX files, strips MDX syntax (imports, JSX component tags), extracts frontmatter, and builds a [Flexsearch](https://github.com/nextapps-de/flexsearch) full-text search index
3. **Serve** — exposes three MCP tools (`search_docs`, `get_page`, `list_sections`) that agents can call to query your documentation
4. **Cached** — the index is stored in `.docs-mcp/` in your working directory, so subsequent startups are instant if nothing changed

The server understands standard Markdown frontmatter (`title`, `description`) and organizes pages into sections based on directory structure (e.g. `backend/payments.md` belongs to the `backend` section).

## Quick Start

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs"]
    }
  }
}
```

That's it. Restart your AI tool and the docs are queryable.

## Usage Examples

### Relative path — docs inside your project

When your documentation lives alongside your code:

```
my-project/
├── src/
├── docs/           <-- your markdown docs
├── .mcp.json
└── package.json
```

```json
{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs"]
    }
  }
}
```

### Relative path — Astro/Starlight project

For documentation sites using Astro Starlight:

```json
{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp", "--docs", "./src/content/docs"]
    }
  }
}
```

### Absolute path — docs in a separate repo or folder

When your docs live outside the current project (e.g. a monorepo or a separate docs repo):

```json
{
  "mcpServers": {
    "project-docs": {
      "command": "npx",
      "args": [
        "-y", "@devista/docs-mcp",
        "--docs", "/Users/me/projects/my-docs/src/content/docs",
        "--name", "project-docs"
      ]
    }
  }
}
```

### Multiple documentation sources

You can register multiple instances for different doc folders:

```json
{
  "mcpServers": {
    "api-docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs/api", "--name", "api-docs"]
    },
    "architecture-docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp", "--docs", "./docs/architecture", "--name", "architecture-docs"]
    }
  }
}
```

### Using a config file instead of CLI args

Create `.docs-mcp.json` in your project root:

```json
{
  "docs": "./src/content/docs",
  "include": ["**/*.md", "**/*.mdx"],
  "exclude": ["**/drafts/**"],
  "name": "my-project-docs"
}
```

Then your `.mcp.json` simplifies to:

```json
{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@devista/docs-mcp"]
    }
  }
}
```

## Configuration

### CLI Args

| Arg | Description |
|-----|-------------|
| `--docs <path>` | Path to documentation folder (required unless set in config file) |
| `--name <name>` | Server name shown in MCP clients (default: `docs-mcp`) |
| `--reindex` | Force a full rebuild of the search index on startup |

### Config File (`.docs-mcp.json`)

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `docs` | string | — | Path to documentation folder (required) |
| `include` | string[] | `["**/*.md", "**/*.mdx"]` | Glob patterns for files to index |
| `exclude` | string[] | `["**/node_modules/**"]` | Glob patterns for files to skip |
| `name` | string | `docs-mcp` | Server name shown in MCP clients |

CLI args override config file values. Paths are resolved relative to the working directory.

## Tools

### `search_docs`

Full-text search across all documentation pages. Returns ranked results with text excerpts.

- **query** (string, required) — The search query
- **limit** (number, optional, default: 5) — Max results to return

### `get_page`

Retrieve the full Markdown content of a specific page, including frontmatter metadata.

- **path** (string, required) — Page path relative to docs root, without extension (e.g. `backend/payments`)

### `list_sections`

List all documentation sections and their pages. Returns a structured table of contents. No parameters.

## Add to .gitignore

The search index is cached locally. Add this to your `.gitignore`:

```
.docs-mcp/
```

## License

MIT