lightweight-github-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Lightweight GitHub MCP is a proxy server that wraps github/github-mcp-server (GitHub's official MCP server) and exposes only whitelisted tools via YAML configuration. This dramatically reduces context consumption (100+ tools → 10-20 tools).

Prerequisites: Docker must be installed and running.

Build and Run Commands

# Install dependencies
npm install

# Build
npm run build

# Development mode (watch)
npm run dev

# Run the server
npm start

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Architecture

Claude Desktop/Code
        │ MCP Protocol (stdio)
        ▼
┌─────────────────────────────┐
│  lightweight-github-mcp     │
│  ┌─────────┐  ┌──────────┐  │
│  │MCP      │→ │Tool      │→ │ config.yaml (allowedTools)
│  │Server   │  │Filter    │  │
│  └─────────┘  └──────────┘  │
│         ↑          │        │
│         │    ┌─────▼─────┐  │
│         │    │MCP Client │  │
│         │    └─────┬─────┘  │
└─────────┼──────────┼────────┘
          │          │ spawn Docker container
          │          ▼
          │  github/github-mcp-server (Docker, ~100 tools)
          │
    Claude requests

Key Components

• src/index.ts - Entry point, config loading, server initialization
• src/server.ts - MCP server implementation, tool filtering, meta-tool handlers
• src/upstream-client.ts - Child process management for upstream GitHub MCP
• src/config.ts - YAML configuration loading and validation
• config.yaml - Tool whitelist configuration

Meta-Tools (Always Available)

The proxy provides four built-in meta-tools that are always exposed:

• list_all_upstream_tools - List all upstream tools (allowed + blocked)
• list_blocked_tools - List blocked tools by category
• search_upstream_tools - Search upstream tools by keyword
• get_tool_info - Get details about a specific tool