OpenGradient Docs

A lightweight, read-only MCP server that exposes OpenGradient 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 OpenGradient RPC endpoints, or modify anything on the network.

Docs source

The server indexes the public docs site:

• https://docs.opengradient.ai/

Unlike the Shelby docs server, OpenGradient does not currently publish a public llms-full.txt bundle. This MCP instead reads the VitePress page hash map from the docs homepage, downloads each docs page asset, extracts rendered content, and caches the parsed snapshot locally.

Quickstart for Claude Code

Add the MCP server with npx:

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

Then start Claude Code:

claude

Inside Claude Code, run:

/mcp

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

Quickstart for Cursor (per-project)

Create .cursor/mcp.json and add:

{
  "mcpServers": {
    "opengradient-docs": {
      "command": "npx",
      "args": ["-y", "github:Jr-kenny/opengradient-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": {
    "opengradient-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:Jr-kenny/opengradient-mcp"]
    }
  },
  "inputs": []
}

Quickstart for Gemini CLI

Add the MCP server globally:

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

Confirm it is registered:

gemini mcp list

Quickstart for Codex

Add the MCP server with the Codex CLI:

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

Confirm it is registered:

codex mcp list

Alternatively, add this to your Codex MCP config:

[mcp_servers.opengradient-docs]
command = "npx"
args = ["-y", "github:Jr-kenny/opengradient-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/opengradient-mcp
   cd opengradient-mcp
   

2. Install dependencies and build:

   npm install
   npm run build
   

3. Run the local entrypoint:

   node /absolute/path/to/opengradient-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/opengradient-mcp

Tool endpoints

1. opengradient_search_docs Searches the OpenGradient documentation and returns ranked matches with snippets.

2. opengradient_read_doc Reads a page by exact slug, path, title, URL, or fuzzy query.

3. opengradient_get_doc_by_slug Reads a page by exact slug, URL, path, or resource URI.

4. opengradient_list_pages Lists available parsed pages and supports filtering by path, title, or slug.

5. opengradient_list_developer_pages Lists the developer-doc subset only, covering developers/, api_reference/, and tutorials/.

6. opengradient_search_examples Searches example-heavy pages with code blocks, commands, API usage, or configuration examples.

7. opengradient_get_related_docs Finds related pages by path structure and title overlap.

8. opengradient_list_topics Lists top-level topic groups with page counts and example pages.

Resources

• opengradient://docs/index JSON index of the parsed docs snapshot.

• opengradient://docs/page/{slug} Individual page resources.

CLI helpers

These are useful when you want to inspect what the parser actually indexed without connecting an MCP client.

Dump every indexed page:

npm run dump:pages

Dump only developer docs:

npm run dump:developer-pages

You can also call the built CLI directly:

node dist/cli.js --dump-pages
node dist/cli.js --dump-developer-pages

Project structure

File/Folder	Purpose
src/index.ts	MCP server setup, tool registration, CLI helpers, and stdio startup
src/cli.ts	CLI entry point that starts the server
src/opengradientDocs.ts	OpenGradient docs loading, VitePress scraping, parsing, search, and formatting helpers
.cache/	Cached parsed docs snapshot
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 the OpenGradient docs homepage and page assets at startup
• Parses VitePress docs assets into page-level records
• Uses deterministic keyword scoring over titles, slugs, paths, and body text
• Caches the parsed snapshot locally to avoid re-scraping the site on every launch

Configuration

Optional environment variables:

• OPENGRADIENT_DOCS_URL: alternate docs site URL
• OPENGRADIENT_DOCS_CACHE_FILE: alternate cache path
• OPENGRADIENT_DOCS_REFRESH_HOURS: cache freshness window, default 24
• OPENGRADIENT_DOCS_TIMEOUT_MS: HTTP timeout in milliseconds, default 20000
• OPENGRADIENT_DOCS_CONCURRENCY: concurrent page fetches during indexing, default 6

Local development

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

npm install
npm run build
npm run check
npm run dump:developer-pages
npm start

npm run check verifies that the server can fetch and parse the live OpenGradient docs site.