Kontxt MCP Server

マーケットプレイスのバッジ

Kontxt MCP Server

エージェントが対応できるようになるまで、コードベースのインデックス作成の課題解決を試みる Model Context Protocol（MCP）サーバーです。

機能

• ユーザーが指定したローカルコードリポジトリに接続します。
• AI クライアント（Cursor、Claude Desktop など）向けに、（get_codebase_context）ツールを提供します。
• Gemini 2.0 Flash の 100 万トークンの入力ウィンドウを内部で使用してコードベースを分析し、ユーザーのクライアントからのクエリに基づいてコンテキストを生成します。
• Flash は内部ツール（list_repository_structure、read_files、grep_codebase）を使用してコードを理解できます。
• SSE（推奨）と stdio の両方のトランスポートプロトコルに対応しています。
• より的を絞った分析のために、クライアントからのクエリにユーザーが添付したファイル／ドキュメント／コンテキストを利用できます。
• トークン使用量を追跡し、API 消費量の詳細な分析を提供します。
• コンテキスト生成のトークン上限をユーザーが設定できます（選択肢：50 万、80 万、または 100 万トークン。デフォルト：80 万）。

セットアップ

1. クローン／ダウンロード： サーバーのコードを取得します。
2. 環境の作成：

   python -m venv venv
   source venv/bin/activate  # Windows の場合：venv\Scripts\activate
   

3. 依存関係のインストール：

   pip install -r requirements.txt
   

4. tree のインストール： システムで tree コマンドを使用できることを確認します。
   • macOS：brew install tree
   • Debian/Ubuntu：sudo apt update && sudo apt install tree
   • Windows：移植版をインストールするか、WSL を使用する必要があります。
5. API キーの設定：
   • .env.example を .env にコピーします。
   • .env を編集し、Google Gemini API キーを追加します。

     GEMINI_API_KEY="YOUR_ACTUAL_API_KEY"
     

   • または、コマンドライン引数 --gemini-api-key でキーを指定できます。

スタンドアロンサーバーとして実行する（推奨）

デフォルトでは、サーバーは SSE モードで実行されます。このモードでは、次のことができます。

• サーバーを単独で起動する
• 複数のクライアントから接続する
• クライアントを再起動してもサーバーを稼働させ続ける

サーバーを実行します。

python kontxt_server.py --repo-path /path/to/your/codebase

追記：pwd を使用すると、プロジェクトのパスを表示できます。

デフォルトでは、サーバーは http://127.0.0.1:8080/sse で起動します。

その他のオプションについては、次を参照してください。

python kontxt_server.py --repo-path /path/to/your/codebase --host 0.0.0.0 --port 6900

サーバーのシャットダウン

実行中のターミナルで Ctrl+C を押すと、サーバーを停止できます。サーバーは 3 秒のタイムアウト内に正常終了を試みます。

クライアントからサーバーに接続する（Cursor の例）

サーバーの起動後、~/.cursor/mcp.json ファイルを編集して Cursor を接続できます。

{
  "mcpServers": {
    "kontxt-server": {
      "serverType": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

追記：SSE 経由で MCP に接続するには、Cursor の設定または他のクライアントで、MCP サーバーを必ず更新してください。

別の方法：stdio トランスポートで実行する

クライアントからサーバープロセスを起動して管理する場合は、次の方法を使用してください。

python kontxt_server.py --repo-path /path/to/your/codebase --transport stdio

このモードでは、~/.cursor/mcp.json ファイルを次のように設定します。

{
  "mcpServers": {
    "kontxt-server": {
      "serverType": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/kontxt_server.py", "--repo-path", "/absolute/path/to/your/codebase", "--transport", "stdio"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

コマンドライン引数

• --repo-path PATH：必須。分析するローカルコードリポジトリの絶対パスです。
• --gemini-api-key KEY：Google Gemini API キーです（指定すると .env の値を上書きします）。
• --token-threshold NUM：コンテキストの目標最大トークン数です。指定できる値は次のとおりです。
  • 500000
  • 800000（デフォルト）
  • 1000000
• --gemini-model NAME：使用する Gemini モデルです（デフォルト：models/gemini-2.5-flash-preview-04-17）。
• --tokenizer-model NAME：トークン数の推定に使用する Hugging Face トークナイザー ID です（デフォルト：google/gemma-7b。KONTXT_TOKENIZER_MODEL で上書きできます）。
• --transport {stdio,sse}：使用するトランスポートプロトコルです（デフォルト：sse）。
• --host HOST：SSE サーバーのホストアドレスです（デフォルト：127.0.0.1）。
• --port PORT：SSE サーバーのポートです（デフォルト：8080）。
• --cors-origins ORIGINS：許可する CORS オリジンをカンマ区切りで指定します。省略した場合、デフォルトではループバックのみが許可されます。
• --cors-credentials：CORS の認証情報を許可します（デフォルトでは無効）。

CORS の設定

セキュリティ上の理由から、ワイルドカード CORS は使用しません。デフォルトでは、ループバックオリジンのみが許可されます。

• http://127.0.0.1、http://localhost、およびバインドされた host:port。

開発中に特定のウェブクライアントを許可するには、明示的にオリジンを指定するか、環境変数を使用してください。

python kontxt_server.py \
  --repo-path /path/to/your/codebase \
  --cors-origins http://localhost:3000,http://127.0.0.1:5173

# or via environment variable
KONTXT_CORS_ORIGINS="http://localhost:3000,http://127.0.0.1:5173" \
python kontxt_server.py --repo-path /path/to/your/codebase

注意：

• 許可されるメソッド：GET、OPTIONS。ヘッダー：すべて。認証情報：--cors-credentials が設定されていない限り無効です。

トークナイザー（Gemma）へのアクセスと自動復旧

このサーバーは、トークン数を推定するために google/gemma-7b トークナイザーを使用します。このモデルは、Hugging Face 上で Google によってアクセス制限されています。

まだアクセス権がない場合の動作：

• 起動時にトークナイザーをダウンロードできないと、サーバーは明確なメッセージをログに記録し、自動的に https://huggingface.co/google/gemma-7b を開きます。
• サーバーはヒューリスティックなトークン推定器を使用して動作を続けます（クラッシュしません）。
• トークナイザーの読み込みを定期的に再試行します。アクセス権を取得すると、自動的に切り替わります（再起動は不要です）。

アクセス権の取得方法（無料、約2分）：

1. https://huggingface.co/google/gemma-7b にアクセスしてログインします（必要に応じてアカウントを作成します）。
2. モデルページで Google の利用規約に同意します。
3. ヘッドレス環境／CI またはコンテナで実行している場合は、環境を認証します：huggingface-cli login（または HF_TOKEN を設定します）。

設定：

• --tokenizer-model または KONTXT_TOKENIZER_MODEL：必要に応じて、別の HF トークナイザー ID を使用します。
• KONTXT_TOKENIZER_RELOAD_INTERVAL（秒、デフォルトは 60）：サーバーがトークナイザーの読み込みを再試行する間隔です。

基本的な使い方

クエリの例：

• 「このコードベースについて教えてください」
• 「認証システムはどのように機能しますか？」
• 「アプリケーション内のデータフローを説明してください」

追記：エージェントが MCP ツールを使用しない場合は、使用するように指定できます：「auth ファイルの 3 番目のコードブロックの最後の単語は何ですか？利用可能な MCP ツールを使用してください。」

コンテキストの添付

クエリで参照したファイル／コンテキストは、分析用のコンテキストとして含まれます。

• 「このファイルの仕組みを説明してください：@kontxt_server.py」
• 「@user_model.py とやり取りするすべてのファイルを見つけてください」
• 「@file1.js と @file2.js の実装を比較してください」

サーバーは Gemini にこれらのファイルについて伝えますが、ファイルの内容を自動的に読み取ったり含めたりすることはありません。代わりに、Gemini がクエリのコンテキストに基づいて、ツールを使って読み取るファイルを決定します。

この方法により、Gemini は実際に必要なファイルだけを読み取り、無関係なファイルの内容でコンテキストが肥大化するのを防げます。

トークン使用量の追跡

サーバーは、さまざまな操作におけるトークン使用量を追跡します。

• リポジトリ構造の一覧表示
• ファイルの読み取り
• Grep 検索
• ユーザークエリに添付されたファイル
• 生成された回答

この情報は動作中にログに記録されるため、API の使用状況を監視し、クエリを最適化できます。

追伸：このツールを改善したいですか？PR をお待ちしています。