# Shelby docs MCP

A lightweight, read-only MCP server that exposes Shelby documentation as searchable tools for MCP-compatible clients like Claude Code, Codex, Cursor, VS Code, and Gemini CLI.

This project is a docs-only server. It does not write data, talk to Shelby RPC endpoints, or modify anything in the network.

## Docs source

The server loads the full Shelby LLM docs bundle:

- [https://docs.shelby.xyz/llms-full.txt](https://docs.shelby.xyz/llms-full.txt)

It parses that bundle into page-level chunks using the native Shelby format:

```text
# Page Title (/path)
Page content...
# Next Page (/next-path)
Next page content...
```

## Quickstart for Claude Code

Add the MCP server with `npx`:

```bash
claude mcp add --transport stdio shelby-docs -- npx -y github:Jr-kenny/shelby-mcp
```

Then start Claude Code:

```bash
claude
```

Inside Claude Code, run:

```bash
/mcp
```

You should see the `shelby-docs` server and its tool endpoints listed.

## Quickstart for Cursor (per-project)

Create `.cursor/mcp.json` and add:

```json
{
  "mcpServers": {
    "shelby-docs": {
      "command": "npx",
      "args": ["-y", "github:Jr-kenny/shelby-mcp"]
    }
  }
}
```

> [!TIP]
> If Cursor does not recognize `mcpServers` in your version, try `mcp_servers` as the top-level key instead.

## Quickstart for VS Code (per-workspace)

Add this to `.vscode/mcp.json`:

```json
{
  "servers": {
    "shelby-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:Jr-kenny/shelby-mcp"]
    }
  },
  "inputs": []
}
```

## Quickstart for Gemini CLI

Add the MCP server globally:

```bash
gemini mcp add --scope user shelby-docs npx -y github:Jr-kenny/shelby-mcp
```

Confirm it is registered:

```bash
gemini mcp list
```

## Quickstart for Codex

Add the MCP server with the Codex CLI:

```bash
codex mcp add shelby-docs -- npx -y github:Jr-kenny/shelby-mcp
```

Confirm it is registered:

```bash
codex mcp list
```

Alternatively, add this to your Codex MCP config:

```toml
[mcp_servers.shelby-docs]
command = "npx"
args = ["-y", "github:Jr-kenny/shelby-mcp"]
```

Then restart Codex if needed so it reloads the MCP config.

## Quickstart from source

If you want to run the repository locally from source:

1. Clone the repo:

   ```bash
   git clone https://github.com/Jr-kenny/shelby-mcp
   cd shelby-mcp
   ```

2. Install dependencies and build:

   ```bash
   npm install
   npm run build
   ```

3. Run the local entrypoint:

   ```bash
   node /absolute/path/to/shelby-mcp/dist/cli.js
   ```

Then substitute that `node .../dist/cli.js` command in any MCP client config if you prefer source-based usage over `npx`.

## Repository

GitHub repository:

- [https://github.com/Jr-kenny/shelby-mcp](https://github.com/Jr-kenny/shelby-mcp)

## Tool endpoints

1. `search_shelby_docs`
   Searches the Shelby documentation bundle and returns ranked matches with IDs and snippets.

2. `read_shelby_doc`
   Reads a page by exact path, title, URL, page ID, or fuzzy query.

3. `get_shelby_doc_chunk`
   Reads a specific page by the exact chunk ID returned from search results.

4. `list_shelby_doc_pages`
   Lists available parsed pages and supports filtering by path or title text.

## Project structure

| File/Folder | Purpose |
| --- | --- |
| `src/index.ts` | MCP server setup, tool registration, and stdio startup |
| `src/cli.ts` | CLI entry point that starts the server |
| `src/shelbyDocs.ts` | Shelby docs loading, parsing, search, and formatting helpers |
| `dist/` | Compiled JavaScript output generated by `npm run build` |
| `package.json` | Dependencies, scripts, package metadata, and CLI registration |
| `tsconfig.json` | TypeScript compiler settings |
| `README.md` | Usage and setup instructions |

## How it's built

This MCP server is a lightweight TypeScript implementation built on the official MCP SDK.

### Core components

- Built on [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)
- Uses `StdioServerTransport` for local MCP clients
- Uses `zod` to validate tool inputs
- Fetches Shelby docs from the official `llms-full.txt` bundle at startup
- Parses the bundle into page chunks using Shelby's `# Title (/path)` format
- Uses deterministic keyword scoring over titles, paths, URLs, and body text

## Configuration

Optional environment variables:

- `SHELBY_DOCS_URL`: alternate docs bundle URL
- `SHELBY_DOCS_TIMEOUT_MS`: HTTP timeout in milliseconds, default `15000`

## Fork this for your own docs

This repo is a good base if you want to publish other docs-only MCP servers backed by a single `llms-full.txt` style bundle.

1. Update `package.json`:

   ```json
   {
     "name": "your-docs-mcp",
     "description": "Docs-only MCP server for YourProduct documentation"
   }
   ```

2. Update the docs URL in `src/shelbyDocs.ts`:

   ```ts
   const DEFAULT_DOCS_URL = "https://your-domain.com/llms-full.txt";
   ```

3. Update the server name in `src/index.ts`:

   ```ts
   name: "your-docs-mcp"
   ```

4. Build and publish:

   ```bash
   npm install
   npm run build
   ```

## Local development

This section is only for working on the MCP server itself.

```bash
npm install
npm run build
npm run check
npm start
```

`npm run check` verifies that the server can fetch and parse the live Shelby docs bundle.