# Yandex Cloud Docs MCP

Offline, read-only full-text search for a local checkout of the
[Yandex Cloud documentation](https://github.com/yandex-cloud/docs), exposed as
a Model Context Protocol (MCP) server.

The server is designed for local use with Claude Code, Claude Desktop, Codex,
and other MCP clients that support the stdio transport. It does not call a
remote documentation service, require authentication, or send documentation
content over the network.

> [!NOTE]
> The prebuilt Yandex Cloud Markdown corpus is primarily in Russian. The server
> instructs MCP clients to translate core technical search terms to Russian
> when the user's question is in another language.

## Features

- Local SQLite FTS5 index with ranked full-text search.
- Line-numbered excerpts and document reads for precise citations.
- Incremental refresh after upstream Git updates.
- Explicit status reporting for the docs revision, index revision, file count,
  dirty working tree, and stale index state.
- Read-only MCP tool annotations.
- Path traversal and symlink-escape protection.
- Atomic full-index rebuilds.
- No remote fallback and no runtime network access.

## MCP tools

| Tool | Purpose |
| --- | --- |
| `search_yandex_cloud_docs` | Search the local index and return ranked paths, excerpts, and line ranges. |
| `read_yandex_cloud_doc` | Read up to 400 numbered lines from a document returned by search. |
| `yandex_cloud_docs_status` | Compare the indexed revision with the current documentation checkout. |

## Requirements

- Git.
- Node.js 25.7 or newer.
- An MCP client with local stdio support.
- A local checkout of `yandex-cloud/docs` containing `md-docs/`.

The commands below use a POSIX shell on macOS or Linux. Windows users can use
the same directory layout with absolute Windows paths in the client
configuration.

## Quick start

The recommended layout keeps the upstream documentation and this MCP server in
one parent directory:

```text
yc-docs/
├── docs/    # yandex-cloud/docs
└── mcp/     # this repository
```

Choose an absolute installation directory and clone both repositories:

```bash
export YC_DOCS_HOME="${YC_DOCS_HOME:-$HOME/src/yc-docs}"

mkdir -p "$YC_DOCS_HOME"
git clone https://github.com/yandex-cloud/docs.git "$YC_DOCS_HOME/docs"
git clone https://github.com/selivanov-tech/yandex-cloud-docs-mcp.git \
  "$YC_DOCS_HOME/mcp"
```

Install dependencies and compile the server:

```bash
cd "$YC_DOCS_HOME/mcp"
npm ci
npm run build
```

Build the local index:

```bash
npm run index -- \
  --docs-root "$YC_DOCS_HOME/docs/md-docs" \
  --index "$YC_DOCS_HOME/mcp/var/yandex-cloud-docs.sqlite"
```

The first build is a full scan. Later builds use the Git history to update
changed Markdown files incrementally. The generated `dist/`, `node_modules/`,
and `var/` directories are intentionally excluded from Git.

## Prepare absolute client paths

All runtime paths must be absolute. These shell variables make the rollout
commands easier to copy:

```bash
export NODE_BIN="$(command -v node)"
export MCP_SERVER="$YC_DOCS_HOME/mcp/dist/src/server.js"
export DOCS_ROOT="$YC_DOCS_HOME/docs/md-docs"
export DOCS_INDEX="$YC_DOCS_HOME/mcp/var/yandex-cloud-docs.sqlite"
```

Confirm that every path exists before configuring a client:

```bash
test -x "$NODE_BIN"
test -f "$MCP_SERVER"
test -d "$DOCS_ROOT"
test -f "$DOCS_INDEX"
```

## Roll out to Claude Code

### User scope

User scope makes the server available in every Claude Code project on the
machine:

```bash
claude mcp add \
  --transport stdio \
  --scope user \
  yandex-cloud-documentation \
  -- "$NODE_BIN" "$MCP_SERVER" \
  --docs-root "$DOCS_ROOT" \
  --index "$DOCS_INDEX"
```

Verify the connection:

```bash
claude mcp get yandex-cloud-documentation
```

### Project scope

To share the server definition through a project's `.mcp.json`, run the same
command from that project with `--scope project`:

```bash
claude mcp add \
  --transport stdio \
  --scope project \
  yandex-cloud-documentation \
  -- "$NODE_BIN" "$MCP_SERVER" \
  --docs-root "$DOCS_ROOT" \
  --index "$DOCS_INDEX"
```

Claude Code asks each user to approve project-scoped MCP servers. Start an
interactive `claude` session in the project to review the prompt. Because the
generated paths are machine-specific, do not commit that `.mcp.json` for a
team unless you replace them with shared environment-variable conventions.

## Roll out to Claude Desktop

This repository currently ships as a developer-installed stdio server rather
than a packaged `.mcpb` desktop extension.

Open the Claude Desktop configuration file:

| Platform | Configuration path |
| --- | --- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

Merge the following entry into the existing `mcpServers` object. Replace every
placeholder with an absolute path; JSON configuration does not run the shell
variables from the previous section.

```json
{
  "mcpServers": {
    "yandex-cloud-documentation": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/yc-docs/mcp/dist/src/server.js",
        "--docs-root",
        "/absolute/path/to/yc-docs/docs/md-docs",
        "--index",
        "/absolute/path/to/yc-docs/mcp/var/yandex-cloud-docs.sqlite"
      ]
    }
  }
}
```

Fully quit and reopen Claude Desktop. Use **+ → Connectors** in the composer,
or open the desktop developer settings, to confirm that
`yandex-cloud-documentation` is connected and exposes three tools.

## Roll out to Codex

The Codex CLI command installs the server in the user's Codex configuration:

```bash
codex mcp add yandex-cloud-documentation \
  -- "$NODE_BIN" "$MCP_SERVER" \
  --docs-root "$DOCS_ROOT" \
  --index "$DOCS_INDEX"
```

Verify the stored configuration:

```bash
codex mcp get yandex-cloud-documentation --json
```

Alternatively, add the server directly to `~/.codex/config.toml`:

```toml
[mcp_servers.yandex-cloud-documentation]
command = "/absolute/path/to/node"
args = [
  "/absolute/path/to/yc-docs/mcp/dist/src/server.js",
  "--docs-root",
  "/absolute/path/to/yc-docs/docs/md-docs",
  "--index",
  "/absolute/path/to/yc-docs/mcp/var/yandex-cloud-docs.sqlite",
]
```

For project-only access, put the same table in `.codex/config.toml` inside a
trusted project. Start a new Codex session after changing MCP configuration.

## Smoke test

Ask the client:

```text
Use yandex-cloud-documentation to find the documentation for creating a
service account. Cite the local document path and line numbers, then report
whether the local index is stale.
```

A successful response should use the search, read, and status tools; cite a
path such as `iam/operations/sa/create.md`; and report `stale: false`.

## Update the documentation and index

Pull upstream documentation changes:

```bash
git -C "$YC_DOCS_HOME/docs" pull --ff-only
```

Refresh the index:

```bash
cd "$YC_DOCS_HOME/mcp"
npm run index -- \
  --docs-root "$YC_DOCS_HOME/docs/md-docs" \
  --index "$YC_DOCS_HOME/mcp/var/yandex-cloud-docs.sqlite"
```

Use `--rebuild` to force an atomic full rebuild:

```bash
npm run index -- \
  --docs-root "$YC_DOCS_HOME/docs/md-docs" \
  --index "$YC_DOCS_HOME/mcp/var/yandex-cloud-docs.sqlite" \
  --rebuild
```

The MCP runtime never updates the checkout or index automatically. This keeps
runtime tool calls read-only and makes documentation updates explicit.

## Update the MCP server

```bash
cd "$YC_DOCS_HOME/mcp"
git pull --ff-only
npm ci
npm run build
```

Restart Claude Desktop and begin new Claude Code or Codex sessions if the
server process was already running.

## Run directly

The server communicates over stdio:

```bash
"$NODE_BIN" "$MCP_SERVER" \
  --docs-root "$DOCS_ROOT" \
  --index "$DOCS_INDEX"
```

Protocol messages are written to stdout. Startup and fatal errors are written
to stderr.

## Development

Install and test:

```bash
npm ci
npm test
```

The test suite covers:

- Full and incremental indexing.
- Search, numbered reads, and index status.
- Additions, modifications, and deletions.
- Path traversal and symlink escapes.
- MCP tool discovery and calls over an in-memory transport.

## Troubleshooting

### `Both --docs-root <path> and --index <path> are required`

Both arguments must be present in the client configuration.

### `--docs-root and --index must be absolute paths`

Resolve shell variables before saving client configuration. Claude Desktop JSON
and Codex TOML examples must contain literal absolute paths.

### `spawn node ENOENT` or `Server disconnected`

GUI applications often have a smaller `PATH` than an interactive shell. Use
the absolute path returned by `command -v node` as the MCP `command`.

### The index is missing or stale

Run the index refresh command, then call `yandex_cloud_docs_status` again. A
dirty documentation checkout triggers a safe full rebuild.

### Claude Code shows `Pending approval`

Open an interactive Claude Code session in the project and approve the
project-scoped `.mcp.json` entry.

### Claude Desktop does not show the tools

Validate the JSON, confirm all paths exist, fully restart Claude Desktop, and
check the MCP server logs from the desktop developer settings.

## Security model

- MCP runtime tools are local and read-only.
- The runtime makes no network requests.
- The index command writes only to the configured SQLite path.
- Document reads are confined to the configured docs root.
- Generated data and the upstream documentation checkout are not bundled in
  this repository.

Review any local MCP server before enabling it, especially when using a
project-scoped configuration from a repository you do not control.

## Upstream documentation

- [Yandex Cloud documentation repository](https://github.com/yandex-cloud/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
- [Claude Desktop local MCP servers](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)
- [Codex MCP documentation](https://developers.openai.com/codex/mcp/)

## License

Copyright 2026 Sergey Selivanov.

The MCP server and its documentation are licensed under the
[Apache License 2.0](LICENSE). The separately cloned Yandex Cloud
documentation remains subject to its upstream license.

## Disclaimer

This is an unofficial community project. It is not affiliated with or endorsed
by Yandex, Anthropic, or OpenAI. Yandex Cloud documentation and trademarks
remain the property of their respective owners and are subject to the upstream
repository's terms.