Dependency Context

依存関係のコンテキスト

@darianb 作

MCP サーバーおよびコマンドラインツールです。AI アシスタントがプロジェクトの依存関係に関するドキュメントをコンテキストとして利用できるようにし、コードベースで使用しているライブラリやフレームワークについて、より正確に回答できるようにします。

設定

インデックス化する依存関係を指定するには、プロジェクトのルートにカスタム dependency-context.json ファイルを作成する方法をおすすめします。これにより、次のことができます。

• 現在使用しており、サポートが必要な依存関係だけをインデックス化できます
• 依存関係の数を制限して、インデックス化を高速化できます
• 最も重要なライブラリに検索結果を絞り込めます

次の形式で、プロジェクトのルートに dependency-context.json ファイルを作成します。

{
  "express": "^4.17.1",
  "axios": "1.0.0"
}

dependency-context.json ファイルがない場合、Dependency Context は package.json または requirements.txt をスキャンします。

クイックスタート

オプション 1：AI との連携に MCP を使用する（Cursor ユーザーにおすすめ）

1. エディターに MCP の設定を追加します（Cursor をおすすめします）。

{
  "mcpServers": {
    "dependency-context": {
      "command": "npx",
      "args": ["-y", "--package=dependency-context", "dependency-context"],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN_HERE", // Optional but recommended
        "MODEL_NAME": "Xenova/all-MiniLM-L6-v2", // Optional, default shown
        "DEBUG": "false", // Optional, default shown
        "MIN_CHUNK_SIZE": "800", // Optional, default shown
        "MAX_CHUNK_SIZE": "8000", // Optional, default shown
        "CHUNKS_RETURNED": "5" // Optional, default shown
      }
    }
  }
}

2. エディターで MCP を有効にします。

3. AI に依頼して dependency-context を初期化します。「Agent」モードになっていることを確認してください。

Can you initialize dependency-context?

4. いつもと同じように AI に依頼します。関連する場合、dependency-context が自動的に使用されます。

オプション 2：ドキュメントを直接ダウンロードする（ベクトルデータベースなし）

ベクトル検索を使わず、依存関係のドキュメントをダウンロードして閲覧したい場合は、次の手順に従います。

1. dependency-context をインストールします。

npm install -g dependency-context

2. プロジェクトのドキュメントをダウンロードします。

# From your project directory
dependency-context download

# Or specify a different project path
dependency-context download /path/to/your/project

3. プロジェクト内の dependency-context フォルダーでドキュメントを確認します。

# Explore the documentation
cd dependency-context
ls

各依存関係には専用のフォルダーが作成され、そのリポジトリにあるすべての Markdown ドキュメントが格納されます。

MCP ツール

Dependency Context は、MCP インターフェースを通じて次の 2 つの主要なツールを提供します。

1. InitializeDependencyIndex

プロジェクトの依存関係を分析し、そのドキュメントの検索可能なインデックスを作成します。

{
  "capability": "InitializeDependencyIndex",
  "parameters": {
    "project_path": "/path/to/your/project",
    "env_vars": {
      "GITHUB_TOKEN": "your_github_token", // Optional but recommended
      "MODEL_NAME": "Xenova/all-MiniLM-L6-v2", // Optional, default shown
      "DEBUG": "true", // Optional
      "MIN_CHUNK_SIZE": "800", // Optional, default shown
      "MAX_CHUNK_SIZE": "8000" // Optional, default shown
    }
  }
}

この機能では、次の処理を行います。

• カスタムの dependencies.json ファイルがあるか確認します（推奨）
• カスタムファイルがない場合は、package.json または requirements.txt をスキャンします
• 各依存関係の GitHub リポジトリを特定します
• リポジトリをクローンし、Markdown ドキュメントを抽出します
• セマンティック検索用のベクトル埋め込みを作成します

2. searchDependencyDocs

インデックス化された依存関係のドキュメントをセマンティック検索します。

{
  "capability": "searchDependencyDocs",
  "parameters": {
    "project_path": "/path/to/your/project",
    "query": "How do I handle authentication?",
    "repository_context": "express", // Optional: limit to a specific dependency
    "env_vars": {
      "MODEL_NAME": "Xenova/all-MiniLM-L6-v2",
      "CHUNKS_RETURNED": "5" // Optional, default shown
    }
  }
}

検索結果には、次の情報が含まれます。

• クエリに最も関連するドキュメントのチャンク
• ソース情報（リポジトリ、ファイルパス）
• 各結果の類似度スコア

アーキテクチャ

Dependency Context は、モジュール式の TypeScript アーキテクチャで構築されています。

• コアコンポーネント：

  • パーサー：package.json と requirements.txt から依存関係を抽出します
  • リポジトリの検出：レジストリのメタデータを使用して GitHub リポジトリを特定します
  • ドキュメントの取得：リポジトリをクローンし、ドキュメントを抽出します
  • ベクトルストア：埋め込みを生成し、セマンティック検索を可能にします
  • MCP サーバー：AI ツール向けに標準化されたインターフェースを提供します

• 主要なライブラリ：

  • fastmcp：MCP プロトコルの実装
  • @xenova/transformers：ベクトル作成用のローカル埋め込みモデル
  • simple-git：リポジトリ操作用の Git クライアント
  • axios：API リクエスト用の HTTP クライアント
  • fs-extra：強化されたファイルシステム操作
  • dotenv：環境変数の管理

テスト

単体テスト

次のコマンドでテストスイートを実行します。

npm test

手動テスト

手動でテストするには、次の手順に従います。

1. テストプロジェクトをセットアップする

mkdir test-project
cd test-project

# Create a custom dependencies.json file (recommended approach)
echo '{
  "dependencies": {
    "express": "^4.17.1",
    "axios": "^1.0.0"
  }
}' > dependencies.json

# Alternatively, you can use standard dependency files:

# For Node.js projects
echo '{
  "dependencies": {
    "express": "^4.17.1",
    "axios": "^1.0.0"
  }
}' > package.json

# For Python projects
echo 'requests==2.26.0
numpy>=1.20.0' > requirements.txt

2. fastmcp dev を使用して dependency-context をテストする

# Build and make the CLI executable
cd /path/to/dependency-context
npx fastmcp dev src/index.ts

# Initialize and index dependencies (from your test project directory)
tool(InitializeDependencyIndex)

# Search for information in the indexed dependencies
tool(searchDependencyDocs)


## Troubleshooting

### GitHub API Rate Limits

If you encounter "API rate limit exceeded" errors:

1. Create a GitHub personal access token at https://github.com/settings/tokens
2. Set it as the `GITHUB_TOKEN` environment variable:
   ```bash
   export GITHUB_TOKEN=your_token_here

3. または、.env ファイルに追加します。

   # Optional but recommended for higher API rate limits
   GITHUB_TOKEN=your_token_here
   
   # Optional settings with defaults shown below
   MIN_CHUNK_SIZE=800
   MAX_CHUNK_SIZE=8000
   CHUNKS_RETURNED=5
   

検索結果が空の場合

検索結果が空の場合は、次の点を確認してください。

1. インデックス化が正常に完了したことを確認します
2. コンソール出力にエラーメッセージがないか確認します
3. 検索クエリがインデックス化された依存関係に関連していることを確認します
4. より一般的なクエリを試して、結果が返されるか確認します

権限に関する問題

プロジェクトディレクトリへのアクセス時に権限エラーが発生した場合は、次の点を確認してください。

1. サーバーにプロジェクトディレクトリへの読み取り／書き込みアクセス権があることを確認してください
2. 一時ディレクトリにアクセスできることを確認してください
3. 適切な権限でサーバーを実行してください

開発

# Clone the repository
git clone https://github.com/yourusername/dependency-context.git

# Install dependencies
cd dependency-context
npm install

# Run MCP server locally with fastmcp dev
npx fastmcp dev src/index.ts

# Test CLI download command
node src/index.js download ./test-project

プロジェクトの TODO リスト

優先度：高

• 基本的なプロジェクト構成と依存関係を設定する
• package.json と requirements.txt 用の依存関係パーサーを実装する
• GitHub リポジトリの検出機能を作成する
• ドキュメントの取得と Markdown 処理を構築する
• ベクトルストアの作成とインデックス作成を実装する
• セマンティック検索用の MCP エンドポイントを設定する
• 複数の経路（システム、プロジェクト、MCP パラメーター）を通じた環境変数のサポートを追加する
• 関数にチャンクサイズと top-k の取得件数を指定するパラメーターを追加する
• 生のドキュメントをダウンロードする CLI モードを追加する
• GitHub API 用の適切なエラー処理と再試行の仕組みを追加する

優先度：中

• 追加のパッケージマネージャー（Maven、Go、Rust）をサポートする
• 長時間かかるインデックス作成処理の進捗状況を報告する機能を追加する
• Markdown の構造をより適切に考慮できるよう、チャンク分割アルゴリズムを強化する
• GitHub 以外のリポジトリ（GitLab、Bitbucket）をサポートする

優先度：低

• 包括的なドキュメントを作成する

今後の機能強化

• 追加のパッケージマネージャー：pom.xml、go.mod などの依存関係形式をサポートします（注：推奨される方法として、カスタムの dependencies.json はすでにサポートされています）
• 差分インデックス作成：変更されていないリポジトリの再処理を回避します
• 設定可能なチャンク分割：ドキュメント分割のカスタム戦略を設定できます
• 代替モデル：さまざまな埋め込みモデルをサポートします
• キャッシュレイヤー：頻繁にアクセスされるドキュメントのパフォーマンスを向上させます

ライセンス

Dependency Context は Commons Clause 付きの MIT License の下でライセンスされています。つまり、次のことができます。

✅ 許可される事項：

• Dependency Context をあらゆる目的（個人、商用、学術）で使用する
• コードを変更する
• コピーを配布する
• Dependency Context を使用して構築した製品を作成し、販売する

❌ 許可されない事項：

• Dependency Context 自体を販売する
• Dependency Context をホステッドサービスとして提供する
• Dependency Context に基づいて競合製品を作成する

詳細については、ライセンス全文およびライセンスの詳細が記載された LICENSE ファイルを参照してください。

Copyright © 2024 DarianB