ghrepo-mcp

GitHub repository analyzer with Model Context Protocol (MCP) server for AI agents

ghrepo-mcp is a powerful tool that enables AI agents like Claude Code to efficiently analyze and reference public GitHub repositories. It clones repositories, generates structured summaries and dependency maps, and provides high-speed full-text search capabilities through DuckDB.

日本語ドキュメント | English

English

Features

• 🔍 Full-Text Search: Lightning-fast code search powered by DuckDB with BM25 ranking
• 📊 Code Analysis: Automatic extraction of functions, classes, imports, and exports
• 🗺️ Dependency Mapping: Generate comprehensive codebase dependency graphs
• 📝 Smart Summaries: AI-friendly structured summaries of files and directories
• 🤖 MCP Server: Native integration with Claude Code and other MCP-compatible AI agents
• 🌐 Multi-Language: Support for TypeScript, JavaScript, Python, Go, and Rust
• ⚡ Incremental Updates: Efficient updates that only process changed files
• 📈 Monitoring: Built-in health checks, metrics, and performance monitoring

Installation

NPX (Recommended)

No installation required! Run directly with NPX:

npx ghrepo-mcp init github.com/owner/repo

Global Installation

npm install -g ghrepo-mcp

Quick Start

1. Initialize a Repository

# Initialize latest version
npx ghrepo-mcp init github.com/expressjs/express

# Initialize specific version
npx ghrepo-mcp init github.com/expressjs/[email protected]

2. Search Code

# Simple search
npx ghrepo-mcp search "middleware" --repository github.com/expressjs/express

# Search with filters
npx ghrepo-mcp search "router" --file-type js --path "lib/**"

3. Update Repository

# Update to latest
npx ghrepo-mcp update github.com/expressjs/express

# Update to specific version
npx ghrepo-mcp update github.com/expressjs/[email protected]

CLI Commands

# Initialize repository
ghrepo-mcp init <github-url> [options]

# Update repository
ghrepo-mcp update <github-url> [options]

# Search code
ghrepo-mcp search <query> [options]
  --repository <url>     Filter by repository
  --file-type <ext>      Filter by file extension
  --path <pattern>       Filter by file path pattern
  --case-sensitive       Case-sensitive search
  --output <format>      Output format (json|text|pretty)

# View repository summary
ghrepo-mcp summary <github-url> [path]

# Get dependency information
ghrepo-mcp dependencies <github-url>

# Configuration management
ghrepo-mcp config <get|set|reset> [key] [value]

# Start MCP server
ghrepo-mcp serve [options]
  --transport <type>     Transport type (stdio|sse)
  --port <number>        Port for SSE transport (default: 3000)

# Clean up repositories
ghrepo-mcp clean [repository] [options]
  --all                  Remove all repositories
  --yes                  Skip confirmation

# Display version
ghrepo-mcp --version

# Show help
ghrepo-mcp --help

MCP Server Integration

ghrepo-mcp can run as an MCP server, allowing AI agents to analyze repositories directly.

Claude Code Integration

1. Create or edit your Claude Code MCP configuration file:

   • macOS/Linux: ~/.config/claude-code/mcp.json
   • Windows: %APPDATA%\claude-code\mcp.json

2. Add ghrepo-mcp server:

{
  "mcpServers": {
    "ghrepo-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ghrepo-mcp",
        "serve",
        "--transport",
        "stdio"
      ],
      "env": {
        "GHREPO_STORAGE_PATH": "${HOME}/.ghrepo-mcp",
        "GHREPO_LOG_LEVEL": "info"
      }
    }
  }
}

3. Restart Claude Code

4. The ghrepo-mcp server will now be available to Claude!

Available MCP Tools

• init_repository: Initialize and analyze a GitHub repository
• update_repository: Update repository to latest or specific version
• search_code: Search code across analyzed repositories
• get_summary: Get implementation summary for files or directories
• get_dependencies: Get dependency mapping for a repository

Available MCP Resources

• summary://github.com/owner/repo/path/to/file: File summaries
• mapping://github.com/owner/repo: Dependency maps
• metadata://github.com/owner/repo: Repository metadata

For detailed integration instructions, see Integration Guide.

Configuration

ghrepo-mcp can be configured via environment variables:

| Variable | Description | Default | |----------|-------------|---------| | GHREPO_STORAGE_PATH | Storage directory for repositories and database | ~/.ghrepo-mcp | | GHREPO_DB_PATH | DuckDB database path | ${STORAGE_PATH}/ghrepo.db | | GHREPO_LOG_LEVEL | Logging level (debug, info, warn, error) | info | | GHREPO_DUCKDB_MEMORY_LIMIT | DuckDB memory limit | 1GB |

Architecture

┌─────────────────────────────────────────────────────────┐
│                     CLI / MCP Server                     │
├─────────────────────────────────────────────────────────┤
│  Repository Manager  │  Code Analyzer  │  Search Engine │
├─────────────────────────────────────────────────────────┤
│         Git Client        │      Tree-sitter Parser     │
├─────────────────────────────────────────────────────────┤
│                  DuckDB (FTS + Storage)                  │
└─────────────────────────────────────────────────────────┘

Performance

• Repository Analysis: <5 min for 100MB, <15 min for 500MB
• Search Queries: <1 second for 90% of queries
• Incremental Updates: Only processes changed files
• Memory Usage: Stays under 1GB during analysis

Development

Prerequisites

• Node.js 18 or higher
• Git
• NPM

Setup

# Clone repository
git clone https://github.com/timakin/ghrepo-mcp.git
cd ghrepo-mcp

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Watch tests
npm run test:watch

# Type checking
npm run typecheck

# Linting
npm run lint

# Formatting
npm run format

Project Structure

ghrepo-mcp/
├── src/
│   ├── cli/              # CLI commands
│   ├── mcp/              # MCP server implementation
│   ├── git/              # Git operations
│   ├── analysis/         # Code analysis with tree-sitter
│   ├── search/           # Search engine
│   ├── database/         # DuckDB integration
│   ├── monitoring/       # Health checks and metrics
│   └── __tests__/        # Test files
├── docs/                 # Documentation
├── mcp-config.example.json  # Example MCP configuration
└── package.json

Publishing to NPM

To publish this package to NPM (for maintainers):

# 1. Ensure all tests pass
npm test

# 2. Build the project
npm run build

# 3. Update version (choose one)
npm version patch  # Bug fixes (1.0.0 -> 1.0.1)
npm version minor  # New features (1.0.0 -> 1.1.0)
npm version major  # Breaking changes (1.0.0 -> 2.0.0)

# 4. Publish to NPM
npm publish

# 5. Push changes and tags to GitHub
git push && git push --tags

Important Notes:

• The dist/ directory is included in the NPM package (see .npmignore)
• Source files and tests are excluded from the package
• Ensure you're logged in to NPM: npm login
• Check what will be published: npm pack --dry-run

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript strict mode conventions
• Write tests for new features
• Update documentation as needed
• Follow conventional commit messages
• Ensure all tests pass before submitting PR

Troubleshooting

Common issues and solutions are documented in the Troubleshooting Guide.

License

MIT © Seiji Takahashi

Acknowledgments

• Built with Model Context Protocol SDK
• Powered by DuckDB
• Code parsing with Tree-sitter

日本語

概要

ghrepo-mcpは、AIエージェント（Claude Codeなど）が公開GitHubリポジトリを効率的に分析・参照できるようにするツールです。リポジトリをクローンし、構造化されたサマリーや依存関係マップを生成し、DuckDBによる高速全文検索機能を提供します。

主な機能

• 🔍 全文検索: DuckDBによるBM25ランキングを使用した超高速コード検索
• 📊 コード分析: 関数、クラス、インポート、エクスポートの自動抽出
• 🗺️ 依存関係マッピング: 包括的なコードベース依存関係グラフの生成
• 📝 スマートサマリー: ファイルとディレクトリのAIフレンドリーな構造化サマリー
• 🤖 MCPサーバー: Claude Codeや他のMCP互換AIエージェントとのネイティブ統合
• 🌐 多言語対応: TypeScript、JavaScript、Python、Go、Rustをサポート
• ⚡ 増分更新: 変更されたファイルのみを処理する効率的な更新
• 📈 モニタリング: 組み込みのヘルスチェック、メトリクス、パフォーマンス監視

インストール

NPX（推奨）

インストール不要！NPXで直接実行：

npx ghrepo-mcp init github.com/owner/repo

グローバルインストール

npm install -g ghrepo-mcp

クイックスタート

1. リポジトリを初期化

# 最新版を初期化
npx ghrepo-mcp init github.com/expressjs/express

# 特定バージョンを初期化
npx ghrepo-mcp init github.com/expressjs/[email protected]

2. コードを検索

# シンプルな検索
npx ghrepo-mcp search "middleware" --repository github.com/expressjs/express

# フィルター付き検索
npx ghrepo-mcp search "router" --file-type js --path "lib/**"

3. リポジトリを更新

# 最新版に更新
npx ghrepo-mcp update github.com/expressjs/express

# 特定バージョンに更新
npx ghrepo-mcp update github.com/expressjs/[email protected]

CLIコマンド

# リポジトリの初期化
ghrepo-mcp init <github-url> [オプション]

# リポジトリの更新
ghrepo-mcp update <github-url> [オプション]

# コード検索
ghrepo-mcp search <クエリ> [オプション]
  --repository <url>     リポジトリでフィルター
  --file-type <拡張子>   ファイル拡張子でフィルター
  --path <パターン>      ファイルパスパターンでフィルター
  --case-sensitive       大文字小文字を区別
  --output <形式>        出力形式 (json|text|pretty)

# リポジトリサマリーを表示
ghrepo-mcp summary <github-url> [パス]

# 依存関係情報を取得
ghrepo-mcp dependencies <github-url>

# 設定管理
ghrepo-mcp config <get|set|reset> [キー] [値]

# MCPサーバーを起動
ghrepo-mcp serve [オプション]
  --transport <タイプ>   トランスポートタイプ (stdio|sse)
  --port <番号>          SSEトランスポートのポート (デフォルト: 3000)

# リポジトリのクリーンアップ
ghrepo-mcp clean [リポジトリ] [オプション]
  --all                  全リポジトリを削除
  --yes                  確認をスキップ

# バージョン表示
ghrepo-mcp --version

# ヘルプ表示
ghrepo-mcp --help

MCP統合

ghrepo-mcpはMCPサーバーとして実行でき、AIエージェントが直接リポジトリを分析できます。

Claude Code統合

1. Claude CodeのMCP設定ファイルを作成または編集：

   • macOS/Linux: ~/.config/claude-code/mcp.json
   • Windows: %APPDATA%\claude-code\mcp.json

2. ghrepo-mcpサーバーを追加：

{
  "mcpServers": {
    "ghrepo-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ghrepo-mcp",
        "serve",
        "--transport",
        "stdio"
      ],
      "env": {
        "GHREPO_STORAGE_PATH": "${HOME}/.ghrepo-mcp",
        "GHREPO_LOG_LEVEL": "info"
      }
    }
  }
}

3. Claude Codeを再起動

4. ghrepo-mcpサーバーがClaudeで利用可能になります！

利用可能なMCPツール

• init_repository: GitHubリポジトリを初期化・分析
• update_repository: リポジトリを最新版または特定バージョンに更新
• search_code: 分析済みリポジトリ全体でコード検索
• get_summary: ファイルやディレクトリの実装サマリーを取得
• get_dependencies: リポジトリの依存関係マッピングを取得

利用可能なMCPリソース

• summary://github.com/owner/repo/path/to/file: ファイルサマリー
• mapping://github.com/owner/repo: 依存関係マップ
• metadata://github.com/owner/repo: リポジトリメタデータ

詳細な統合手順は統合ガイドを参照してください。

設定

環境変数で設定可能：

| 変数 | 説明 | デフォルト | |------|------|-----------| | GHREPO_STORAGE_PATH | リポジトリとデータベースの保存ディレクトリ | ~/.ghrepo-mcp | | GHREPO_DB_PATH | DuckDBデータベースパス | ${STORAGE_PATH}/ghrepo.db | | GHREPO_LOG_LEVEL | ログレベル (debug, info, warn, error) | info | | GHREPO_DUCKDB_MEMORY_LIMIT | DuckDBメモリ制限 | 1GB |

パフォーマンス

• リポジトリ分析: 100MBで5分未満、500MBで15分未満
• 検索クエリ: 90%のクエリで1秒未満
• 増分更新: 変更されたファイルのみを処理
• メモリ使用量: 分析中も1GB未満を維持

開発

必要な環境

• Node.js 18以上
• Git
• NPM

セットアップ

# リポジトリをクローン
git clone https://github.com/timakin/ghrepo-mcp.git
cd ghrepo-mcp

# 依存関係をインストール
npm install

# プロジェクトをビルド
npm run build

# テストを実行
npm test

# テストを監視
npm run test:watch

# 型チェック
npm run typecheck

# リント
npm run lint

# フォーマット
npm run format

NPMへの公開

NPMにパッケージを公開する手順（メンテナー向け）：

# 1. 全テストが通ることを確認
npm test

# 2. プロジェクトをビルド
npm run build

# 3. バージョンを更新（いずれかを選択）
npm version patch  # バグ修正 (1.0.0 -> 1.0.1)
npm version minor  # 新機能 (1.0.0 -> 1.1.0)
npm version major  # 破壊的変更 (1.0.0 -> 2.0.0)

# 4. NPMに公開
npm publish

# 5. 変更とタグをGitHubにプッシュ
git push && git push --tags

重要な注意事項：

• dist/ ディレクトリはNPMパッケージに含まれます（.npmignore参照）
• ソースファイルとテストはパッケージから除外されます
• NPMにログインしていることを確認：npm login
• 公開内容の確認：npm pack --dry-run

コントリビューション

コントリビューションを歓迎します！以下の手順に従ってください：

1. リポジトリをフォーク
2. フィーチャーブランチを作成 (git checkout -b feature/amazing-feature)
3. 変更をコミット (git commit -m 'feat: add amazing feature')
4. ブランチにプッシュ (git push origin feature/amazing-feature)
5. プルリクエストを開く

開発ガイドライン

• TypeScriptのstrictモード規則に従う
• 新機能にはテストを書く
• 必要に応じてドキュメントを更新
• 従来型のコミットメッセージに従う
• PR提出前に全テストが通過することを確認

トラブルシューティング

よくある問題と解決策はトラブルシューティングガイドに記載されています。

ライセンス

MIT © Seiji Takahashi

謝辞

• Model Context Protocol SDKで構築
• DuckDBを使用
• Tree-sitterでコード解析