# lightweight-github-mcp

A lightweight proxy server that wraps [github/github-mcp-server](https://github.com/github/github-mcp-server) (GitHub's official MCP server) and exposes only whitelisted tools via YAML configuration. This dramatically reduces context consumption.

## Prerequisites

- Node.js >= 18.0.0
- **Docker** (required for running upstream GitHub MCP server)

## Installation

```bash
# Install dependencies
npm install

# Build
npm run build
```

## Usage

```bash
# Run the server
npm start

# Development mode (watch)
npm run dev

# 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

These help Claude discover tools and guide users to add needed tools to the whitelist.

## Configuration

### config.yaml

```yaml
allowedTools:
  - get_file_contents
  - create_issue
  # ... only listed tools are exposed

# Using github/github-mcp-server via Docker
upstream:
  command: docker
  args:
    - "run"
    - "-i"
    - "--rm"
    - "-e"
    - "GITHUB_PERSONAL_ACCESS_TOKEN"
    - "ghcr.io/github/github-mcp-server"
```

### Config File Lookup Order

1. `CONFIG_PATH` environment variable
2. `./config.yaml` (current directory)
3. Project root `config.yaml`

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GITHUB_PERSONAL_ACCESS_TOKEN` | Yes | GitHub Personal Access Token |
| `CONFIG_PATH` | No | Path to config.yaml |

## Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

```json
{
  "mcpServers": {
    "github-lite": {
      "command": "node",
      "args": ["/path/to/lightweight-github-mcp/dist/index.js"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}
```

## License

MIT