# docs-mcp-server

A reusable [Model Context Protocol](https://modelcontextprotocol.io) (MCP)
server that exposes one or more documentation folders — plain `.md`, `.mdx`,
and `.txt` files — to any MCP-compatible AI agent (Claude Desktop, Claude
Code, Cursor, etc).

It's kept as its own package rather than bundled into a specific project so
that any number of repos/services can point at their own docs folder(s) and
share the exact same server binary, instead of every project reimplementing
"list/read/search my markdown docs" from scratch. Real projects also rarely
keep all their docs in one place — e.g. each microservice has its own `docs/`
folder — so this server accepts multiple folders and gives each one a short
label you reference in resource URIs and see in search results.

## ⚙️ Installation

### 🥇 Option 1 — Recommended (npx / direct way)

This is the easiest way. `npx` automatically fetches the repo, installs
dependencies, builds it, and runs the server — no local clone required.

Add this to your MCP settings:

```json
{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": [
        "-y",
        "github:DewminK/docs-mcp-server",
        "--docs-path",
        "/absolute/path/to/your/docs"
      ]
    }
  }
}
```

🚀 What happens with the npx method

- Automatically retrieves the MCP server package from the repository
- Installs the required dependencies in a separate managed environment
- Compiles the TypeScript source code into executable JavaScript
- Starts the MCP server and enables communication with MCP hosts through the stdio transport

Swap `--docs-path` for as many comma-separated folders as you need (see
[Configuring documentation folders](#configuring-documentation-folders)
below).

### 🥈 Option 2 — Clone & build locally

Useful if you want to edit the server itself, or prefer pinning an exact
local build.

```bash
git clone https://github.com/DewminK/docs-mcp-server.git
cd docs-mcp-server
npm install
npm run build
```

This compiles `src/*.ts` to `dist/*.js` (ESM, targeting ES2022). Then point
your MCP host at the built file with absolute paths:

```json
{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": [
        "/absolute/path/to/docs-mcp-server/dist/server.js",
        "--docs-path",
        "/absolute/path/to/service-a/docs,/absolute/path/to/service-b/docs"
      ]
    }
  }
}
```

## Adding it to an MCP host

This section shows how to register the server with each MCP host. Most of
these commands/configs (anything using `npx -y github:DewminK/docs-mcp-server`)
are self-contained and fetch + build + run the server on their own — you
don't need to have done Installation Option 1 or 2 first. Only use a
`node dist/server.js` path (Option 2's build output) if you already cloned
the repo locally.

**Claude Desktop** — edit the config file and restart the app:

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

**Claude Code (terminal or VS Code extension)** — use the CLI instead of
hand-editing JSON, from an integrated or regular terminal. `docs` in the
commands below is just the server name being registered — pick any name
you like, it's not a fixed keyword. The default `local` scope only applies
to the exact project folder you ran the command from; use `--scope project`
or `--scope user` instead if you want it shared or available everywhere
(see below).

**Scope: project** — shared with your team via an `.mcp.json` file created
at the repo root (commit this file so teammates get the same server):

```bash
claude mcp add docs --scope project -- npx -y github:DewminK/docs-mcp-server --docs-path /absolute/path/to/your/docs
```

**Scope: user** — available across all your projects on this machine,
stored in `~/.claude.json`:

```bash
claude mcp add docs --scope user -- npx -y github:DewminK/docs-mcp-server --docs-path /absolute/path/to/your/docs
```

Verify with `claude mcp list`, then **reload the VS Code window**
(Command Palette → "Developer: Reload Window") if you're using the
extension — it only picks up newly registered servers on
startup/reload, not mid-session.

**VS Code (Copilot Chat's MCP support, not the Claude Code extension)** —
add the server to `.vscode/mcp.json` in your workspace, or to your user
`settings.json` under the `mcp.servers` key for a global install:

```json
{
  "servers": {
    "docs": {
      "command": "npx",
      "args": [
        "-y",
        "github:DewminK/docs-mcp-server",
        "--docs-path",
        "/absolute/path/to/your/docs"
      ]
    }
  }
}
```

Then open the Command Palette and run **MCP: List Servers** to start it, or
use the **Start** code lens that appears above the server entry in
`mcp.json`.

**Cursor** — same JSON block as Claude Desktop, placed in `.cursor/mcp.json`
(project-level) or via Cursor's MCP settings UI (global).

## Configuring documentation folders

The server resolves which folders to serve in this order:

1. `--docs-path` CLI flag (comma-separated for multiple folders)
2. `DOCS_PATH` environment variable (comma-separated for multiple folders)
3. Default: `./docs`

Each folder is given a label based on its own directory name. If two folders
share the same directory name, later ones get a numeric suffix (`docs`,
`docs-2`, ...).

Examples:

```bash
# Single folder
node dist/server.js --docs-path ./docs

# Multiple folders, one per microservice
node dist/server.js --docs-path "../service-a/docs,../service-b/docs"

# Same thing via environment variable
DOCS_PATH="../service-a/docs,../service-b/docs" node dist/server.js
```

Passing `DOCS_PATH` via the MCP config's `env` field works just as well as
`--docs-path`, e.g.:

```json
{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "github:DewminK/docs-mcp-server"],
      "env": {
        "DOCS_PATH": "/absolute/path/to/service-a/docs,/absolute/path/to/service-b/docs"
      }
    }
  }
}
```

If a configured path doesn't exist or isn't a directory, the server prints a
clear error to stderr and exits instead of starting.

## What it exposes

| Type              | Name                          | Description                                                                                   |
| ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------- |
| Resource           | `docs://list`                  | Lists every doc file across all configured folders, one `{label}/{relativePath}` per line.       |
| Resource template  | `docs://{label}/{relativePath}` | Reads a single doc file's contents, given its folder label and path relative to that folder.     |
| Tool               | `search_docs`                  | Case-insensitive keyword search across all folders. Input: `{ query: string }`.                  |

## Project layout

```
docs-mcp-server/
  src/lib.ts       # pure logic: resolve paths, list/read/search files (no MCP imports)
  src/server.ts    # thin MCP wiring around lib.ts, connected over stdio
```