# Atelier Busco GitHub MCP Server (`atelier-busco-github-mcp`)

A lightweight, robust Model Context Protocol (MCP) server built with Node.js and TypeScript to seamlessly connect LLMs and AI agents (Claude Desktop, Cursor, Antigravity, Cline) directly to GitHub repositories (public and private).

---

## Key Features

- **Repository Inspection:** List repositories for any user or organization, get repository metadata, statistics, and branch details.
- **File & Tree Exploration:** Read and automatically decode file contents (base64 to UTF-8 text), browse directory trees, and fetch recursive Git trees.
- **Global & Local Search:** Search repositories and code across GitHub or within specific repositories by language, file path, or query strings.
- **Git Tracking & History:** Retrieve commit histories, detailed commit diffs/patches, issues, pull requests, and releases.
- **Hybrid Authentication Support:**
  - **Public Unauthenticated Mode:** Out-of-the-box support without a token (standard GitHub rate limit: 60 requests/hour).
  - **Authenticated Mode:** Seamlessly activates when `GITHUB_TOKEN` or `GH_TOKEN` is present (increases limit to 5,000 requests/hour and unlocks private repositories).

---

## Available MCP Tools

| Tool Name | Description | Key Parameters |
| :--- | :--- | :--- |
| `list_repositories` | List repositories for an owner/organization or default `GITHUB_OWNER` | `owner`, `type`, `sort`, `direction`, `per_page`, `page` |
| `get_repository_details` | Retrieve comprehensive metadata and statistics for a repository | `owner`, `repo` |
| `list_branches` | List branches for a given repository | `owner`, `repo`, `protected`, `per_page`, `page` |
| `get_file_contents` | Read and decode file contents in UTF-8 format | `owner`, `repo`, `path`, `ref` |
| `list_directory_contents` | List files and subdirectories at a specific repository path | `owner`, `repo`, `path`, `ref` |
| `get_repository_tree` | Get the full Git tree structure (supports recursive trees) | `owner`, `repo`, `tree_sha`, `recursive` |
| `search_repositories` | Search GitHub repositories using query qualifiers | `query`, `sort`, `order`, `per_page`, `page` |
| `search_code` | Search for code snippets, symbols, or files | `query`, `owner`, `repo`, `path`, `language` |
| `list_commits` | Fetch commit history for a repository or branch | `owner`, `repo`, `sha`, `path`, `author`, `since`, `until` |
| `get_commit_details` | Get commit details including modified files and patches | `owner`, `repo`, `ref` |
| `list_issues_and_prs` | List issues and pull requests by status and labels | `owner`, `repo`, `state`, `sort`, `direction`, `labels` |
| `get_issue_or_pr` | Retrieve details for a specific issue or PR by number | `owner`, `repo`, `issue_number` |
| `list_releases` | List published releases for a repository | `owner`, `repo`, `per_page`, `page` |

---

## Environment Variables

| Variable | Description | Required |
| :--- | :--- | :--- |
| `GITHUB_OWNER` | Default GitHub user or organization name for queries | Optional (can be passed in tool calls) |
| `GITHUB_TOKEN` / `GH_TOKEN` | GitHub Personal Access Token (for 5,000 req/hr and private repos) | Optional |
| `GITHUB_API_URL` | Base URL for GitHub API (defaults to `https://api.github.com`) | Optional |

---

## Client Configuration

### 1. Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "atelier-busco-github-mcp": {
      "command": "node",
      "args": [
        "/path/to/atelier-busco-github-mcp/dist/index.js"
      ],
      "env": {
        "GITHUB_OWNER": "Atelier-Busco"
      }
    }
  }
}
```

*Or running via `tsx` in development mode:*

```json
{
  "mcpServers": {
    "atelier-busco-github-mcp": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/atelier-busco-github-mcp/src/index.ts"
      ],
      "env": {
        "GITHUB_OWNER": "Atelier-Busco"
      }
    }
  }
}
```

### 2. Antigravity (`~/.gemini/config/mcp_config.json`)

```json
{
  "mcpServers": {
    "atelier-busco-github-mcp": {
      "command": "node",
      "args": [
        "/path/to/atelier-busco-github-mcp/dist/index.js"
      ],
      "env": {
        "GITHUB_OWNER": "Atelier-Busco"
      }
    }
  }
}
```

---

## Development & Build

```bash
# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Start the compiled production server
npm run start

# Run with auto-reloading (development mode)
npm run dev
```

---

## License

[MIT](LICENSE) © [Atelier Busco](https://atelierbusco.com)