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

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

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

Quickstart for Claude Code

Add the MCP server with npx:

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

Then start Claude Code:

claude

Inside Claude Code, run:

/mcp

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

Quickstart for Cursor (per-project)

Create .cursor/mcp.json and add:

{
  "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:

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

Quickstart for Gemini CLI

Add the MCP server globally:

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

Confirm it is registered:

gemini mcp list

Quickstart for Codex

Add the MCP server with the Codex CLI:

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

Confirm it is registered:

codex mcp list

Alternatively, add this to your Codex MCP config:

[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:

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

2. Install dependencies and build:

   npm install
   npm run build
   

3. Run the local entrypoint:

   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

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
• 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:

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

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

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

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

   name: "your-docs-mcp"
   

4. Build and publish:

   npm install
   npm run build
   

Local development

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

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.