Greptile

🚀 Greptile MCP サーバー - TypeScript 版

Greptile API を通じて、AI を活用したコード検索とクエリ機能を提供する、最新の TypeScript 製 MCP（Model Context Protocol）サーバーです。公式 MCP SDK を使用して構築されており、Claude Desktop、Continue、その他の MCP 対応クライアントなどの AI ツールとシームレスに連携できるよう設計されています。

✨ 特長

🔥 インストール不要ですぐに利用可能

# Start immediately with npx - no setup required!
npx greptile-mcp-server --api-key=xxx --github-token=yyy

🧠 AI を活用したコード理解

• 自然言語でのクエリ：コードベースについて、平易な英語で質問できます
• 詳細なコード分析：アーキテクチャ、パターン、実装の詳細を把握できます
• リポジトリ横断の分析：複数のコードベースにわたってパターンやアプローチを比較できます
• セッションの継続性：会話を通じて段階的に理解を深められます

⚡ モダンなアーキテクチャ

• 公式 MCP SDK：TypeScript MCP SDK で構築され、プロトコルに完全準拠しています
• ストリーミング対応：Server-Sent Events によるリアルタイム応答
• 型安全性：包括的な型定義を備えた、完全な TypeScript 統合
• プラグインアーキテクチャ：カスタムツールや統合に対応する拡張可能な設計

🛠️ 開発者エクスペリエンス

• NPX 対応：1 つのコマンドでインストールして実行できます
• 自動設定：設定をインテリジェントに検出し、検証します
• 対話型セットアップ：初回利用者向けのガイド付きセットアップウィザード
• 充実したヘルプ：ドキュメントと使用例を内蔵しています

🚀 クイックスタート

前提条件

• Node.js 18+（最適なパフォーマンスを得るため）
• Greptile API キー：app.greptile.com で取得できます
• GitHub トークン：repo 権限を付与して github.com/settings/tokens で生成します

すぐに開始

# Start immediately (will prompt for credentials if not set)
npx greptile-mcp-server

# With inline credentials
npx greptile-mcp-server --api-key=your_key --github-token=your_token

# Interactive setup wizard
npx greptile-mcp-server init

# Test connectivity
npx greptile-mcp-server test

環境設定

オプション 1：.env ファイル（ローカル開発におすすめ）

プロジェクトのルートに .env ファイルを作成します：

GREPTILE_API_KEY=your_greptile_api_key_here
GITHUB_TOKEN=your_github_personal_access_token_here
GREPTILE_BASE_URL=https://api.greptile.com/v2  # Optional

オプション 2：システム環境変数

Linux/macOS（Bash/Zsh）：

# Current session
export GREPTILE_API_KEY="your_api_key_here"
export GITHUB_TOKEN="your_github_token_here"

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export GREPTILE_API_KEY="your_api_key_here"' >> ~/.bashrc
echo 'export GITHUB_TOKEN="your_github_token_here"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell：

# Current session
$env:GREPTILE_API_KEY="your_api_key_here"
$env:GITHUB_TOKEN="your_github_token_here"

# Permanent
setx GREPTILE_API_KEY "your_api_key_here"
setx GITHUB_TOKEN "your_github_token_here"
# Note: Restart terminal after using setx

Windows コマンドプロンプト：

# Current session
set GREPTILE_API_KEY=your_api_key_here
set GITHUB_TOKEN=your_github_token_here

# Permanent
setx GREPTILE_API_KEY "your_api_key_here"
setx GITHUB_TOKEN "your_github_token_here"

API キーとトークンの設定

Greptile API キー：

1. Greptile の設定にアクセスします
2. 新しい API キーを生成します
3. キーを環境変数に設定します

GitHub トークン：

1. GitHub の設定 > Personal Access Tokensにアクセスします
2. セキュリティを強化するため、「Fine-grained personal access token」を作成します
3. インデックスを作成するリポジトリに repo 権限を付与します
4. トークンを環境変数に設定します

🔧 MCP クライアントとの連携

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "greptile": {
      "command": "npx",
      "args": ["greptile-mcp-server"],
      "env": {
        "GREPTILE_API_KEY": "your_api_key",
        "GITHUB_TOKEN": "your_github_token"
      }
    }
  }
}

Continue IDE 拡張機能

Continue の設定に追加します：

{
  "contextProviders": [
    {
      "name": "greptile-mcp",
      "type": "mcp",
      "serverName": "greptile",
      "command": ["npx", "greptile-mcp-server"]
    }
  ]
}

その他の MCP クライアント

このサーバーは標準の MCP プロトコルを使用しており、MCP 対応のあらゆるクライアントで動作します：

# Generic MCP client connection
your-mcp-client connect --command "npx greptile-mcp-server"

🛠️ 利用可能なツール

1. greptile_help

詳細なドキュメントと使用例を取得します。

{
  "name": "greptile_help"
}

2. index_repository

リポジトリにインデックスを作成し、検索できるようにします。

{
  "name": "index_repository",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main",
    "reload": true
  }
}

3. query_repository

自然言語でリポジトリにクエリを実行します。

{
  "name": "query_repository",
  "arguments": {
    "query": "How is authentication implemented in this codebase?",
    "repositories": [
      {
        "remote": "github",
        "repository": "microsoft/vscode", 
        "branch": "main"
      }
    ],
    "stream": false,
    "session_id": "optional-session-id"
  }
}

4. get_repository_info

インデックス作成済みのリポジトリに関する情報を取得します。

{
  "name": "get_repository_info",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main"
  }
}

📖 使用例

基本的なワークフロー

# 1. Start the server
npx greptile-mcp-server

# 2. In your MCP client, index a repository
{
  "tool": "index_repository",
  "arguments": {
    "remote": "github",
    "repository": "microsoft/vscode",
    "branch": "main"
  }
}

# 3. Query the codebase
{
  "tool": "query_repository", 
  "arguments": {
    "query": "How does VS Code handle file watching?",
    "repositories": [{"remote": "github", "repository": "microsoft/vscode", "branch": "main"}]
  }
}

セッションを使った高度な探索

// Start with architecture overview
const session = "exploration-session-1";

// Query 1: High-level understanding
{
  "tool": "query_repository",
  "arguments": {
    "query": "What is the overall architecture of this codebase?",
    "session_id": session,
    "repositories": [...]
  }
}

// Query 2: Deep dive (builds on previous context)
{
  "tool": "query_repository", 
  "arguments": {
    "query": "How do the main components we just discussed interact with each other?",
    "session_id": session  // Same session for continuity
  }
}

// Query 3: Implementation details
{
  "tool": "query_repository",
  "arguments": {
    "query": "Show me the specific implementation of the component interaction patterns",
    "session_id": session
  }
}

🔀 Python 版からの移行

TypeScript 版は Python 実装との完全な互換性を維持しながら、大幅な改善を加えています：

新着情報

• ✅ 公式 MCP SDK：標準に準拠した実装
• ✅ NPX による配布：インストール不要ですぐに利用可能
• ✅ パフォーマンスの向上：I/O 操作における V8 エンジンの利点
• ✅ 型安全性：TypeScript を全面的に統合
• ✅ 最新のツール群：ESLint、Prettier、包括的なテスト
• ✅ CLI の強化：対話形式のセットアップと優れた UX

移行手順

# Old Python usage
python -m src.main

# New TypeScript usage  
npx greptile-mcp-server

# Same MCP tools and API compatibility
# No changes needed in MCP client configurations

🚨 トラブルシューティング

セットアップのテスト

セットアップ後は、必ず設定をテストしてください。

npx greptile-mcp-server test

よくある問題

❌ 「環境変数が見つかりません」

問題： サーバーが API キーを見つけられません 解決策：

• 環境変数を永続的に設定した後、ターミナルを再起動します
• 環境変数が設定されていることを確認します。

  # Linux/macOS
  echo $GREPTILE_API_KEY
  echo $GITHUB_TOKEN
  
  # Windows PowerShell
  echo $env:GREPTILE_API_KEY
  echo $env:GITHUB_TOKEN
  

• 認証情報を直接指定してみます。

  GREPTILE_API_KEY="your_key" GITHUB_TOKEN="your_token" npx greptile-mcp-server
  

❌ 「GitHub トークンの検証に失敗しました」

問題： GitHub トークンが無効か、権限が不足しています 解決策：

• トークンに repo 権限があることを確認します
• GitHub Settings で新しいトークンを生成します
• セキュリティを高めるには、「Fine-grained personal access tokens」を使用します
• トークンの有効期限が切れていないことを確認します

❌ 「Greptile API の認証に失敗しました」

問題： Greptile API キーが無効か、有効期限が切れています 解決策：

• Greptile Settings から新しい API キーを取得します
• キーが正しくコピーされていることを確認します（余分なスペースがないこと）
• API キーの有効期限が切れていないか確認します

❌ 「モジュールが見つかりません」またはインポートエラー

問題： NPX キャッシュの問題、またはインストールが不完全です 解決策：

• NPX キャッシュを消去します：npx clear-npx-cache
• 最新版を強制的にインストールします：npx greptile-mcp-server@latest
• Node.js のバージョンを確認します（Node 18 以降が必要です）

❌ MCP クライアントの接続に関する問題

問題： Claude Desktop またはその他の MCP クライアントが接続できません 解決策：

• MCP サーバーの設定構文を確認します
• Claude Desktop のログを確認して、詳細なエラーメッセージを調べます
• MCP クライアントから環境変数にアクセスできることを確認します
• まずサーバーを手動で実行し、正常に動作することを確認します

サポートを受ける

• 対話形式でセットアップするには、npx greptile-mcp-server init を実行します
• 詳細な診断を行うには、npx greptile-mcp-server test を実行します
• API 固有の問題については、Greptile Documentation を確認します
• クライアント連携に関するサポートは、MCP Documentation をご覧ください

❓ よくある質問

Q: これを使うために、ローカルに何かをインストールする必要がありますか？

A: いいえ！サーバーはインストール不要で NPX 経由で実行されます。npx greptile-mcp-server を実行するだけで、自動的にダウンロードされて実行されます。

Q: MCP 互換のクライアントならどれでも使えますか？

A: はい！このサーバーは標準の Model Context Protocol を実装しており、Claude Desktop、MCP CLI ツール、その他すべての MCP 互換クライアントで動作します。

Q: プライベートリポジトリをインデックス化するにはどうすればよいですか？

A: GitHub トークンに、プライベートリポジトリ用の repo 権限があることを確認してください。トークンには、インデックス化するリポジトリを読み取るためのアクセス権が必要です。

Q: .env ファイルと環境変数の違いは何ですか？

A:

• .env ファイルはローカル開発に適しています。ファイルが存在するディレクトリ内でのみ機能します
• 環境変数はシステム全体で有効になり、どこでも使えるため、npx でのグローバルな利用に適しています

Q: Greptile の利用料金はいくらですか？

A: Greptile の料金は利用状況によって異なります。最新の料金については、Greptile's pricing page をご確認ください。この MCP サーバー自体は無料のオープンソースソフトウェアです。

Q: 複数のリポジトリで使えますか？

A: はい！複数のリポジトリをインデックス化して、それらすべてを対象にクエリを実行できます。追加するリポジトリごとに index_repository ツールを使用してください。

Q: リポジトリのインデックス化にはどのくらい時間がかかりますか？

A: インデックス化にかかる時間はリポジトリのサイズによって異なります。小規模なリポジトリ（ファイル数 1000 未満）は通常 1～2 分、大規模なリポジトリは 10～15 分かかる場合があります。get_repository_info ツールでステータスを確認できます。

Q: コードデータは安全ですか？

A: コードは、Greptile のセキュリティおよびプライバシーポリシーに従って、Greptile の API で処理されます。データの取り扱いと保持については、Greptile のセキュリティドキュメントをご確認ください。

Q: これを Windows で実行できますか？

A: はい！サーバーは Windows、macOS、Linux で動作します。上記のプラットフォーム固有の環境変数の設定手順を使用してください。

Q: 「command not found」エラーが表示されるのはなぜですか？

A: 通常、次のいずれかが原因です。

• NPX がインストールされていない（NPX を含む Node.js をインストールしてください）
• PATH に Node.js のバイナリが含まれていない
• コマンドにタイプミスがある（コマンドは npx @greptile/mcp-server ではなく npx greptile-mcp-server です）

🏗️ 開発

ローカル開発

# Clone and setup
git clone https://github.com/greptile/mcp-server.git
cd mcp-server
npm install

# Development with hot reload
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting and formatting
npm run lint
npm run format

プロジェクト構成

src/
├── cli.ts              # NPX CLI interface
├── server.ts           # Core MCP server implementation  
├── index.ts            # Module exports
├── clients/
│   └── greptile.ts     # Greptile API client
├── types/
│   └── index.ts        # TypeScript type definitions
└── utils/
    └── index.ts        # Utility functions

tests/
├── unit/               # Unit tests
└── integration/        # Integration tests

ビルド設定

• TypeScript：厳格モードで ES2022 をターゲット
• ビルドツール：ESM/CJS の両方の出力に tsup を使用
• テスト：TypeScript をサポートする Mocha + Chai
• コード品質：TypeScript ルールを適用した ESLint + Prettier

🔧 設定オプション

CLI 引数

npx greptile-mcp-server \
  --api-key="your_key" \
  --github-token="your_token" \
  --base-url="https://api.greptile.com/v2" \
  --repositories='[{"remote":"github","repository":"owner/repo","branch":"main"}]' \
  --stream=true \
  --timeout=60000 \
  --verbose

環境変数

変数	説明	デフォルト
GREPTILE_API_KEY	Greptile API キー	必須
GITHUB_TOKEN	GitHub 個人アクセストークン	必須
GREPTILE_BASE_URL	API ベース URL	https://api.greptile.com/v2

設定ファイル（任意）

greptile.config.js を作成します。

export default {
  apiKey: process.env.GREPTILE_API_KEY,
  githubToken: process.env.GITHUB_TOKEN,
  repositories: [
    { remote: 'github', repository: 'owner/repo', branch: 'main' }
  ],
  features: {
    streaming: true,
    orchestration: true,
    flowEnhancement: true
  }
};

🚀 デプロイ

Smithery Cloud へのデプロイ

設定不要で、すぐに Smithery にデプロイできます。

# Install Smithery CLI
npm install -g smithery

# Deploy from repository
smithery deploy

# Or deploy with custom configuration
smithery deploy --config smithery.yaml

# Monitor deployment
smithery status
smithery logs

Docker へのデプロイ

# Build Docker image
docker build -t greptile-mcp .

# Run with environment variables
docker run -e GREPTILE_API_KEY=your_key \
           -e GITHUB_TOKEN=your_token \
           -p 8080:8080 \
           greptile-mcp

# Or build Smithery-optimized image
npm run smithery:build

デプロイ用環境変数

# Required
GREPTILE_API_KEY=your_greptile_api_key
GITHUB_TOKEN=your_github_token

# Optional
GREPTILE_BASE_URL=https://api.greptile.com/v2
TRANSPORT=stdio
HOST=0.0.0.0
PORT=8080

クラウドプラットフォーム

• Smithery：smithery deploy によるワンクリックデプロイ
• Railway：GitHub リポジトリを接続し、環境変数を設定します
• Render：起動コマンドに npm start を使用します
• Heroku：標準的な Node.js デプロイ
• DigitalOcean App Platform：Docker またはビルドパックによるデプロイ

🚦 パフォーマンスとベンチマーク

起動パフォーマンス

• コールドスタート：2 秒未満
• メモリ使用量：ベースで約 50MB
• 同時リクエスト：100 件以上の同時 MCP ツール呼び出しを処理

API パフォーマンス

• クエリ応答：通常 1～3 秒
• ストリーミング：リアルタイムでチャンクを配信
• リポジトリのインデックス作成：リポジトリのサイズによって異なります（通常 30 秒～5 分）

Python 版との比較

• 起動が 40% 高速 - V8 と Python ランタイムの比較
• コンテナーが 60% 小型 - Node.js と Python のベースイメージの比較
• メモリ効率が 30% 向上 - V8 のガベージコレクション
• ネイティブストリーミング - SSE のパフォーマンスが向上

🛡️ セキュリティとベストプラクティス

トークンのセキュリティ

• 環境変数：トークンはコードではなく、環境変数に保存します
• 最小限の権限：必要な repo 権限のみを持つ GitHub トークンを使用します
• トークンのローテーション：API キーとトークンを定期的にローテーションします
• ローカルストレージ：トークンをバージョン管理に絶対にコミットしないでください

ネットワークセキュリティ

• HTTPS のみ：すべての API 通信で HTTPS を使用します
• リクエストの検証：入力を検証し、サニタイズします
• レート制限：指数バックオフを用いた再試行ロジックを組み込み済みです
• エラー処理：トークンを漏えいさせずに包括的なエラー処理を行います

🤝 コントリビューション

コントリビューションを歓迎します！詳細については、コントリビューションガイドをご覧ください。

開発ワークフロー

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. テストを追加して変更を加えます
4. テストスイートを実行します（npm test）
5. コード品質を確認します（npm run lint）
6. 変更をコミットします（git commit -m 'Add amazing feature'）
7. ブランチにプッシュします（git push origin feature/amazing-feature）
8. プルリクエストを作成します

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

🙏 謝辞

• Anthropic：Model Context Protocol の仕様を提供していただきました
• Greptile：強力なコード分析 API を提供していただきました
• TypeScript Community：優れたツールとエコシステムを提供していただきました
• MCP Community：プロトコルの開発とフィードバックにご協力いただきました

📞 サポート

• ドキュメント：docs.greptile.com
• 課題：GitHub Issues
• ディスカッション：GitHub Discussions
• Discord：MCP Community Discord

---

Greptile チームが ❤️ を込めて開発 • TypeScript と Model Context Protocol を活用