MCP Docs Server

A Model Context Protocol (MCP) server that exposes documentation from GitHub as resources and provides search tools.

Features

• Resources: Exposes documentation files as MCP resources that can be read by LLMs
• Tools: Provides search_docs and list_docs tools for finding information
• GitHub Integration: Fetches documentation directly from GitHub repositories
• Caching: In-memory caching (5 min TTL) to reduce API calls
• Node.js Based: Works with standard Node.js runtime

Installation

For Development

Clone the repository and install dependencies:

git clone https://github.com/homebase-id/mcp-docs.git
cd mcp-docs
npm install

From GitHub Packages

To install from GitHub Packages, first configure npm to use GitHub registry for @homebase-id scope:

echo "@homebase-id:registry=https://npm.pkg.github.com" >> ~/.npmrc

Then authenticate (requires a GitHub personal access token with read:packages scope):

npm login --scope=@homebase-id --registry=https://npm.pkg.github.com

Install the package:

npm install -g @homebase-id/mcp-docs-server

Usage

In Claude Desktop

Add to your claude_desktop_config.json (location varies by OS):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "docs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-docs/src/index.js"],
      "env": {
        "GITHUB_OWNER": "homebase-id",
        "GITHUB_REPO": "odin-js",
        "GITHUB_BRANCH": "main"
      }
    }
  }
}

After adding, restart Claude Desktop. You'll see the docs server in the 🔌 icon.

In VS Code with GitHub Copilot

Add to your VS Code settings (settings.json):

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Search for "Preferences: Open User Settings (JSON)"
3. Add the MCP server configuration:

{
  "github.copilot.chat.mcp.servers": {
    "docs": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-docs/src/index.js"],
      "env": {
        "GITHUB_OWNER": "homebase-id",
        "GITHUB_REPO": "odin-js",
        "GITHUB_BRANCH": "main"
      }
    }
  }
}

Note: Replace /absolute/path/to/mcp-docs with the actual path to your installation.

Reload VS Code after adding. The MCP server will be available in Copilot Chat.

In Cline (VS Code Extension)

Add to Cline's MCP settings:

1. Open Cline settings in VS Code
2. Navigate to MCP Servers section
3. Add server configuration:

{
  "mcpServers": {
    "docs": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-docs/src/index.js"],
      "env": {
        "GITHUB_OWNER": "homebase-id",
        "GITHUB_REPO": "odin-js",
        "GITHUB_BRANCH": "main"
      }
    }
  }
}

Running Standalone

npm start

The server uses stdio transport and communicates via JSON-RPC.

Configuration

Set environment variables to customize:

• GITHUB_OWNER - Repository owner (default: homebase-id)
• GITHUB_REPO - Repository name (default: odin-js)
• GITHUB_BRANCH - Branch name (default: main)

Available Resources

The server exposes documentation files as MCP resources with URIs like:

github://homebase-id/odin-js/main/docs/llm/WORKSPACE_INSTRUCTIONS.md
github://homebase-id/odin-js/main/docs/llm/ARCHITECTURE.md
github://homebase-id/odin-js/main/docs/llm/modules/CORE_MODULE.md

LLMs can directly read these resources without needing to call tools. This provides instant access to documentation context.

Available Tools

list_docs

Lists all available documentation files with their URIs.

search_docs

Search through all documentation for a specific term or topic.

Parameters:

• query (string): The search term to look for

Example:

{
  "name": "search_docs",
  "arguments": {
    "query": "authentication"
  }
}

How It Works

1. Resources: LLMs can list and read documentation files as MCP resources for instant context
2. Tools: LLMs can use search_docs to find specific information or list_docs to see all available documentation
3. Caching: Content is cached in-memory for 5 minutes to minimize GitHub API calls and improve performance
4. GitHub Integration: Fetches content on-demand from GitHub raw URLs (works with public repositories)

Troubleshooting

Server Not Showing Up

• Claude Desktop: Check the 🔌 icon in the bottom right. If not visible, check the config file path is correct.
• VS Code Copilot: Reload VS Code window (Cmd+Shift+P → "Developer: Reload Window")
• Verify Node.js: Run node --version to ensure Node.js is installed and in PATH

"Document not found" Errors

• Ensure the files exist in the GitHub repository at the specified branch
• Check that GITHUB_OWNER, GITHUB_REPO, and GITHUB_BRANCH are correctly set
• Verify the repository is public (or you have access)
• Files must be in the docs/llm/ directory of the repository

Permission Errors

• Make sure the script is executable: chmod +x /path/to/mcp-docs/src/index.js
• Use absolute paths in configuration files
• Check Node.js is installed and accessible from the terminal

Development

Run in development mode:

node src/index.js

The server logs to stderr (console.error) so it doesn't interfere with stdio transport.

Publishing

This package is published to GitHub Packages. The workflow automatically:

1. Bumps version on changes to src/ or package.json
2. Publishes to @homebase-id/mcp-docs-server
3. Creates a PR with the version bump

License

MIT