DevDox MCP Server

A Model Context Protocol (MCP) server that serves developer documentation from GitHub repositories.

Overview

This MCP server loads and indexes markdown documentation files from a GitHub repository with a specific directory structure, allowing AI assistants to access and retrieve documentation content through standardized tools.

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Git (if using clone mode)

Quick Start

To use the MCP server with Claude Code add the following to your Claude Code MCP configuration (eg in .mcp.json):

{
  "mcpServers": {
    "devdox": {
      "command": "npx",
      "args": ["-y", "devdox-mcp-server"],
      "env": {
        "DEVDOX_GITHUB_REPO_URL": "https://github.com/owner/repo",
        "DEVDOX_PROJECT_HANDLE": "my-project"
      }
    }
  }
}

If your using cursor, windsurf etc. then use the equivalent mcp installation workflow.

Configuration

The server takes the following environment variables:

• DEVDOX_GITHUB_REPO_URL (required): The URL of your GitHub repository containing the documentation/rules for your AI agents
• DEVDOX_PROJECT_HANDLE (required): The project handle/directory name within the repository
• DEVDOX_USE_GITHUB_API (optional): Set to true to use GitHub API instead of cloning (default: false)
• DEVDOX_GITHUB_TOKEN (optional): GitHub personal access token for API requests (recommended when using API mode)

Your Dev Docs/Rules Repository Structure

The server expects your Docs repository to follow this structure:

projects/
  project1-handle/
    devdocs/
      doc1.md
      doc2.md
      subfolder/
        doc3.md
  project2-handle/
    devdocs/
      anotherdoc.md

Running the Server

Development Mode

DEVDOX_GITHUB_REPO_URL=https://github.com/owner/repo DEVDOX_PROJECT_HANDLE=my-project npm run dev

Production Mode

DEVDOX_GITHUB_REPO_URL=https://github.com/owner/repo DEVDOX_PROJECT_HANDLE=my-project npm start

Using GitHub API Mode

DEVDOX_GITHUB_REPO_URL=https://github.com/owner/repo DEVDOX_PROJECT_HANDLE=my-project DEVDOX_USE_GITHUB_API=true DEVDOX_GITHUB_TOKEN=your-token npm start

Claude Code Configuration

To use this server with Claude Code, add the following to your MCP settings:

Using npm (recommended)

{
  "mcpServers": {
    "devdox": {
      "command": "npx",
      "args": ["-y", "devdox-mcp-server"],
      "env": {
        "DEVDOX_GITHUB_REPO_URL": "https://github.com/owner/repo",
        "DEVDOX_PROJECT_HANDLE": "my-project"
      }
    }
  }
}

Available Tools

The server provides two tools:

1. listDocs: Returns a list of all available documentation titles

   • No parameters required
   • Returns: Array of document titles

2. getDoc: Retrieves a specific document by its title

   • Parameters:
     • title (string, required): The title of the document to retrieve
   • Returns: The markdown content of the document

Document Title Resolution

Documents are indexed by title, which is determined in the following order:

1. Front matter title field (if using YAML front matter)
2. First H1 heading in the markdown content
3. Filename (converted from kebab-case to Title Case)

Development

Scripts

• npm run build: Build the TypeScript code
• npm run dev: Run in development mode with hot reload
• npm run lint: Run ESLint
• npm run typecheck: Run TypeScript type checking

Project Structure

src/
  index.ts       # Main entry point
  server.ts      # MCP server implementation
  github.ts      # GitHub loading functionality
  indexer.ts     # Document indexing logic
  types.ts       # TypeScript type definitions

Troubleshooting

1. Repository not found: Ensure the DEVDOX_GITHUB_REPO_URL is correct and accessible
2. Project not found: Verify that DEVDOX_PROJECT_HANDLE matches a directory in the projects/ folder
3. API rate limits: When using GitHub API mode, provide a DEVDOX_GITHUB_TOKEN to increase rate limits
4. Permission denied: Ensure you have access to clone the repository (for clone mode) or API access (for API mode)

License

MIT