Semantic Context MCP

🚀 エンタープライズコード検索MCPサーバー

共有ベクトルデータベースを用いた強力なモデルコンテキストプロトコル（MCP） サーバーで、セマンティックコード検索を実現します。埋め込みにはOpenAIとOllamaの両方をサポートし、ローカルプロジェクトまたはGitリポジトリをインデックス化できます。

🚀 クイックスタート

1. リポジトリをクローンする

git clone https://github.com/your-username/semantic-context-mcp.git
cd semantic-context-mcp

2. 依存関係をインストールする

npm install

3. 環境を設定する

cp .env.example .env
# .envを自分の設定で編集する

4. サービスを起動する

# ChromaDBとOllamaを起動する
docker-compose up -d

# Ollamaがモデルをダウンロードするのを待つ
docker-compose logs -f ollama-setup

5. ビルドして実行する

npm run build
npm start

✨ 主な機能

• AI埋め込みを使用したセマンティックコード検索
• 2つのプロバイダーサポート：OpenAIまたはOllama（ローカル、プライベート）
• 柔軟なインデックス化：ローカルプロジェクトまたはGitリポジトリ
• ChromaDBによる共有ベクトルデータベース
• 複数プロジェクト管理：複数のプロジェクトを同時に扱う
• 自動プロジェクト構造分析
• コードスニペットに基づく類似コード検索
• エンタープライズ対応：プライベート、セキュア、セルフホスト

📦 インストール

📋 必要条件

• Node.js 18+
• DockerとDocker Compose
• Git（リポジトリインデックス化用）

💻 使用例

基本的な使用法

1. ローカルプロジェクトをインデックス化する

Index my local project at /home/user/my-app with the name "frontend-app"

2. コード内を検索する

Search for "main application function" in all indexed projects

3. 類似コードを検索する

def authenticate_user(username, password):
    return check_credentials(username, password)

4. プロジェクト構造を分析する

Analyze the structure of project "frontend-app"

高度な使用法

利用可能なツール

例クエリ

機能検索

• "Where is the authentication logic?"
• "Functions that handle database operations"
• "Environment variable configuration"
• "Unit tests for the API"

コード分析

• "What design patterns are used?"
• "Most complex functions in the project"
• "Error handling in the code"

技術固有の検索

• "Code using React hooks"
• "PostgreSQL queries"
• "Docker configuration"

📚 ドキュメント

⚙️ 設定

Ollamaを使用する（エンタープライズ向けに推奨）

# .env
EMBEDDING_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=nomic-embed-text
CHROMA_HOST=localhost
CHROMA_PORT=8000

OpenAIを使用する

# .env
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=your-api-key
OPENAI_MODEL=text-embedding-3-small

🔧 Claude Desktopとの統合

このMCPサーバーをClaude Desktopと一緒に使用するには、claude_desktop_config.jsonに以下を追加します。

{
  "mcpServers": {
    "enterprise-code-search": {
      "command": "node",
      "args": ["/path/to/semantic-context-mcp/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "nomic-embed-text",
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000",
        "COMPANY_NAME": "YourCompany"
      }
    }
  }
}

🔧 高度な設定

推奨Ollamaモデル

# コード埋め込み用
ollama pull nomic-embed-text    # コードに最適 (384次元)
ollama pull all-minilm         # 軽量な代替案 (384次元)
ollama pull mxbai-embed-large  # 高精度 (1024次元)

ファイルパターン

サーバーは以下を含む広範なファイルタイプ認識をサポートしています。

• プログラミング言語：Python、JavaScript/TypeScript、Java、C/C++、Go、Rust、PHP、Ruby、Swift、Kotlin、Scalaなど
• Web技術：HTML、CSS、SCSS、Vue、Svelte
• 設定：JSON、YAML、TOML、Docker、Terraform
• ドキュメント：Markdown、reStructuredText、AsciiDoc
• データベース：SQLファイル

パフォーマンスチューニング

# 最大チャンクサイズ（文字数）
MAX_CHUNK_SIZE=1500

# 最大ファイルサイズ（KB）
MAX_FILE_SIZE=500

# インデックス化のバッチサイズ
BATCH_SIZE=100

🏢 エンタープライズデプロイメント

オプション1: 専用サーバー

# エンタープライズサーバー上で
docker-compose up -d

オプション2: ネットワークデプロイメント

# ネットワークアクセス用に設定
CHROMA_HOST=192.168.1.100
OLLAMA_HOST=http://192.168.1.100:11434

🔒 セキュリティに関する考慮事項

主な利点

1. プライベートデータ：Ollamaはすべてをローカルに保持します。
2. 外部APIなし：Ollamaを使用する場合、データはネットワークを離れません。
3. セルフホスト：コードと埋め込みに完全なコントロールがあります。
4. 分離環境：Dockerコンテナが分離を提供します。

セキュリティのベストプラクティス

# ChromaDBのアクセスを制限する
CHROMA_SERVER_HOST=127.0.0.1  # ローカルホストのみ

# 本番環境ではHTTPSを使用する
OLLAMA_HOST=https://ollama.company.com

📈 モニタリングとトラブルシューティング

有用なログ

# インデックス化のログを表示する
docker-compose logs -f enterprise-mcp-server

# ChromaDBのパフォーマンス
docker-compose logs -f chromadb

# Ollamaをモニタリングする
curl http://localhost:11434/api/tags

一般的な問題

• Ollamaが応答しない場合

curl http://localhost:11434/api/tags
# 失敗した場合: docker-compose restart ollama

• ChromaDBが遅い場合

# ディスク容量を確認する
docker system df
# 必要に応じてクリーンアップする
docker system prune

• 埋め込み品質が低い場合
  • 異なるモデルを試す: all-minilm 対 nomic-embed-text
  • チャンクサイズを調整する
  • ソースファイルの品質を確認する

🤝 協調ワークフロー

典型的なエンタープライズワークフロー

1. DevOpsが メインプロジェクトをインデックス化する
2. 開発者が Claudeを使用してコードを検索する
3. CI/CDによる自動更新
4. コードレビューのためのコード分析

ベストプラクティス

• 重要なマージの後にインデックス化する
• 分かりやすいプロジェクト名を使用する
• プロジェクト固有の検索フィルターを維持する
• 命名規則を文書化する

🛠️ 開発

プロジェクト構造

src/
├── index.ts          # メインのMCPサーバー
└── http-server.ts    # HTTPサーバーバリアント

scripts/              # セットアップとユーティリティスクリプト
docker-compose.yml    # サービスオーケストレーション
package.json         # 依存関係とスクリプト

利用可能なスクリプト

npm run build        # TypeScriptをコンパイルする
npm run dev          # 開発モード
npm run start        # 本番モード
npm run clean        # ビルドディレクトリをクリーンする

📚 APIリファレンス

MCPサーバーは、以下の特定のツールを備えた標準のモデルコンテキストプロトコルを実装しています。

• index_local_project：構成可能なファイルパターンでローカルディレクトリをインデックス化する
• search_codebase：プロジェクトフィルタリングと類似度スコアリングによるセマンティック検索
• list_indexed_projects：メタデータ付きですべてのインデックス化されたプロジェクトを列挙する
• get_embedding_provider_info：現在のプロバイダーの状態と設定を取得する

各ツールには、例と検証を含む詳細なJSONスキーマが含まれています。

🤖 推奨AIモデル

埋め込み用（Ollama）

• nomic-embed-text：コード用に最適化されています。
• all-minilm：バランスが良く、高速です。
• mxbai-embed-large：高精度です。

埋め込み用（OpenAI）

• text-embedding-3-small：コスト効率が良いです。
• text-embedding-3-large：高精度です。

🐳 Dockerサポート

このプロジェクトには完全なDockerセットアップが含まれています。

• ChromaDB：埋め込み用のベクトルデータベース
• Ollama：ローカル埋め込み生成
• PostgreSQL：オプションのメタデータストレージ

すべてのサービスはDocker Composeで調整され、簡単にデプロイできます。

☕ サポート

このプロジェクトがあなたの開発ワークフローに役立った場合は、サポートを検討してください。

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

🤝 貢献

貢献は大歓迎です！プルリクエストを送信してください。

1. プロジェクトをフォークする
2. あなたの機能ブランチを作成する (git checkout -b feature/AmazingFeature)
3. 変更をコミットする (git commit -m 'Add some AmazingFeature')
4. ブランチにプッシュする (git push origin feature/AmazingFeature)
5. プルリクエストを開く

📞 サポートと問題報告

• 📧 問題報告：GitHub Issues
• 💬 ディスカッション：GitHub Discussions
• ☕ サポート：Buy Me a Coffee