Coding Guides MCP server

Coding Guides MCP Server

A Model Context Protocol (MCP) server that provides access to coding guides and best practices for AI assistants like Claude and GitHub Copilot.

What is this?

This MCP server exposes coding guidelines and style guides as resources that can be accessed by MCP clients. It's designed to extend or replace AGENTS.md files by providing a structured way to serve coding practices and guidelines to AI assistants during development.

Features

• Resource-based API: Exposes coding guides through MCP resources
• GitHub integration: Loads guides from GitHub repositories over the web
• Automatic caching: Caches downloaded guides locally for offline access
• Fallback support: Uses local cache or directory when network is unavailable
• Simple file-based storage: Guides can be stored as Markdown files locally
• Official MCP SDK: Built on the Python mcp SDK (MCPServer, formerly FastMCP)
• Easy integration: Works with any MCP-compatible client (Claude Desktop, Cline, etc.)

Available Resources

• guides://list - Lists all available coding guides
• guides://{guide_name} - Retrieves the content of a specific guide (e.g., guides://python.md)

Installation

From Source

# Clone the repository
git clone https://github.com/delian/codeguide-mcp.git
cd codeguide-mcp

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

With Docker

docker build -t codeguide-mcp .
docker run -i codeguide-mcp

In VS Code

Or search for codeguide-mcp in the Extensions view MCP servers list (type @mcp in the Extensions search bar), or add it manually to .vscode/mcp.json:

{
  "servers": {
    "codeguide-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "delian/codeguide-mcp"]
    }
  }
}

Configuration

Configure the server by creating a config.toml file or setting environment variables:

GitHub Configuration (Recommended)

To load guides from a GitHub repository:

github_repo = "owner/repository"  # e.g., "delian/codeguide-mcp"
github_path = "guides"            # Path to guides directory in repo
github_branch = "main"            # Branch to fetch from
  cache_dir = ".guides-cache"       # Local cache directory
log_level = "INFO"

Local Directory Configuration

To use local guides only:

guides_dir = "guides"
log_level = "INFO"

Environment Variables

• GUIDESGITHUBREPO - GitHub repository (format: owner/repo)
• GUIDESGITHUBPATH - Path to guides directory in repository (default: guides)
• GUIDESGITHUBBRANCH - Branch to fetch from (default: main)
• GUIDESCACHEDIR - Local cache directory (default: .guides-cache)
• GUIDES_DIR - Local directory containing guide files (default: guides)
• GUIDESLOGLEVEL - Logging level (default: INFO)

Transport (see Remote deployment):

• GUIDES_TRANSPORT - stdio, streamable-http, or auto (default: auto — HTTP when a PORT env var is present, stdio otherwise)
• PORT - Port to listen on in HTTP mode; takes precedence over GUIDES_PORT (Cloud Run injects this)
• GUIDES_HOST - Bind address in HTTP mode (default: 0.0.0.0)
• GUIDESHTTPPATH - MCP endpoint path (default: /mcp)
• GUIDESSTATELESSHTTP - Handle each request independently (default: true; required when replicas autoscale)
• GUIDESALLOWEDHOSTS - Host header allowlist enabling DNS-rebinding protection (default: empty = no Host validation)

Behavior

Shortened. The full README is on GitHub.