Smart Coding MCP

🚀 Smart Coding MCP

Smart Coding MCPは、AIアシスタントに対してインテリジェントなセマンティックコード検索を提供する拡張可能なモデルコンテキストプロトコル（MCP）サーバーです。Matryoshka Representation Learning（MRL）を用いたローカルAIモデルで構築され、柔軟な埋め込み次元（64 - 768d）をサポートします。

🚀 クイックスタート

AIコーディングアシスタントは、関連するコードを迅速に見つけることができる場合、より良い性能を発揮します。従来のキーワード検索では、例えば「認証はどこで処理されているか」と問い合わせた場合、コード内で「login」や「session」が使用されていると、キーワード検索では見つけることができません。Smart Coding MCPサーバーは、AI埋め込みを使用してコードベースをインデックス化することで、この問題を解決します。AIアシスタントは、正確なキーワードではなく、意味に基づいてコードを検索することができ、用語が異なる場合でも関連するコードを見つけることができます。

✨ 主な機能

🔍 a_semantic_search - 意味に基づくコード検索

コードベースを探索するための主要なツールです。AI埋め込みを使用して、あなたが探しているものを理解し、キーワードの一致だけでなく、意味を考慮してコードを検索します。

• 動作原理: 自然言語のクエリをベクトルに変換し、コサイン類似度と完全一致のブーストを使用して、類似した意味を持つコードチャンクを見つけます。
• 最適な使用シナリオ:
  • 不慣れなコードベースの探索: "認証はどのように機能するか？"
  • 関連するコードの検索: "ユーザー入力の検証はどこで行われているか？"
  • 概念的な検索: "エラーハンドリングパターン"
  • タイプミスがある場合でも動作: "embeding modle initializashun" でも埋め込みコードを見つけることができます。
• クエリの例:

"キャッシュの永続化はどこで処理されているか？"
"データベース接続はどのように管理されているか？"
"すべてのAPIエンドポイントの定義を見つける"

📦 d_check_last_version - パッケージバージョンの検索

公式レジストリから任意のパッケージの最新バージョンを取得します。20以上のエコシステムをサポートしています。

• 動作原理: 公式パッケージレジストリ（npm、PyPI、Crates.ioなど）にリアルタイムで問い合わせます。推測や古いトレーニングデータを使用しません。
• サポートされるエコシステム: npm、PyPI、Crates.io、Maven、Go、RubyGems、NuGet、Packagist、Hex、pub.dev、Homebrew、Condaなど。
• 最適な使用シナリオ:
  • 依存関係を追加する前: "express" → 4.18.2
  • 更新の確認: "pip:requests" → 2.31.0
  • 複数のエコシステムのプロジェクト: "npm:react", "go:github.com/gin-gonic/gin"
• 使用例:

"lodashの最新バージョンは何ですか？"
"axiosに新しいバージョンがあるか確認する"

🔄 b_index_codebase - 手動による再インデックス化

コードベースの完全な再インデックス化をトリガーします。通常、インデックス化は自動的かつ増分的に行われるため、必要ありません。

• 動作原理: すべてのファイルをスキャンし、新しい埋め込みを生成し、SQLiteキャッシュを更新します。進行中のインデックス化中にも検索が可能なように、段階的なインデックス化を使用します。
• 使用タイミング:
  • 大規模なリファクタリングまたはブランチ切り替え後
  • リモートから大規模な変更を取得した後
  • 検索結果が古いまたは不完全な場合
  • 埋め込み構成（次元、モデル）を変更した後

🗑️ c_clear_cache - キャッシュのリセット

埋め込みキャッシュを完全に削除し、次回の検索時に完全な再インデックス化を強制します。

• 動作原理: .smart-coding-cache/ ディレクトリを削除します。次回の検索またはインデックス操作は、最初から開始されます。
• 使用タイミング:
  • キャッシュの破損（稀だが可能）
  • 埋め込みモデルまたは次元の切り替え
  • 大規模なコードベースの再構築後に最初から始める場合
  • 検索問題のトラブルシューティング

📂 e_set_workspace - プロジェクトの切り替え

サーバーを再起動することなく、実行時にワークスペースパスを変更します。

• 動作原理: 内部のワークスペース参照を更新し、新しいパスのキャッシュフォルダを作成し、必要に応じて再インデックス化をトリガーします。
• 使用タイミング:
  • 1つのセッションで複数のプロジェクトに取り組む場合
  • モノレポ内のパッケージ間を移動する場合
  • 関連するリポジトリ間を切り替える場合

ℹ️ f_get_status - サーバーのヘルスチェック

MCPサーバーに関する包括的なステータス情報を返します。

• 表示内容:
  • サーバーのバージョンと稼働時間
  • ワークスペースパスとキャッシュの場所
  • インデックス化のステータス（準備完了、インデックス化中、完了率）
  • インデックス化されたファイルとチャンク数
  • モデルの構成（名前、次元、デバイス）
  • キャッシュのサイズとタイプ
• 使用タイミング:
  • セッション開始時にすべてが正常に動作していることを確認する場合
  • 接続またはインデックス化の問題をデバッグする場合
  • 大規模なコードベースのインデックス化の進行状況を確認する場合

📦 インストール

npm install -g smart-coding-mcp

更新するには：

npm update -g smart-coding-mcp

💻 IDE統合

好みの環境の詳細なセットアップ手順：

クイックセットアップ

MCP設定ファイルに追加：

{
  "mcpServers": {
    "smart-coding-mcp": {
      "command": "smart-coding-mcp",
      "args": ["--workspace", "/absolute/path/to/your/project"]
    }
  }
}

設定ファイルの場所

複数プロジェクトのセットアップ

{
  "mcpServers": {
    "smart-coding-frontend": {
      "command": "smart-coding-mcp",
      "args": ["--workspace", "/path/to/frontend"]
    },
    "smart-coding-backend": {
      "command": "smart-coding-mcp",
      "args": ["--workspace", "/path/to/backend"]
    }
  }
}

🔧 環境変数

環境変数を使用して動作をカスタマイズできます。

環境変数を使用した例:

{
  "mcpServers": {
    "smart-coding-mcp": {
      "command": "smart-coding-mcp",
      "args": ["--workspace", "/path/to/project"],
      "env": {
        "SMART_CODING_VERBOSE": "true",
        "SMART_CODING_MAX_RESULTS": "10",
        "SMART_CODING_EMBEDDING_DIMENSION": "256"
      }
    }
  }
}

🔧 技術詳細

パフォーマンス

• 段階的なインデックス化 - インデックス化がバックグラウンドで続行されている間も、すぐに検索が可能です。大規模なコードベースでも待機する必要がありません。
• リソース制限 - デフォルトでCPU使用率が50%に制限されています。インデックス化中もマシンは応答性を維持します。
• SQLiteキャッシュ - JSONよりも5 - 10倍高速です。古いJSONキャッシュからの自動移行もサポートしています。
• 増分更新 - 変更されたファイルのみが再インデックス化されます。5バッチごとに保存されるため、中断されてもデータが失われることはありません。
• 最適化されたデフォルト設定 - 128dの埋め込み（256dよりも2倍高速で、品質の損失は最小限）、スマートなバッチサイジング、並列処理。

動作原理

flowchart TB
    subgraph IDE["IDE / AI Assistant"]
        Agent["AI Agent<br/>(Claude, GPT, Gemini)"]
    end

    subgraph MCP["Smart Coding MCP Server"]
        direction TB
        Protocol["Model Context Protocol<br/>JSON-RPC over stdio"]
        Tools["MCP Tools<br/>semantic_search | index_codebase | set_workspace | get_status"]

        subgraph Indexing["Indexing Pipeline"]
            Discovery["File Discovery<br/>glob patterns + smart ignore"]
            Chunking["Code Chunking<br/>Smart (regex) / AST (Tree-sitter)"]
            Embedding["AI Embedding<br/>transformers.js + ONNX Runtime"]
        end

        subgraph AI["AI Model"]
            Model["nomic-embed-text-v1.5<br/>Matryoshka Representation Learning"]
            Dimensions["Flexible Dimensions<br/>64 | 128 | 256 | 512 | 768"]
            Normalize["Layer Norm → Slice → L2 Normalize"]
        end

        subgraph Search["Search"]
            QueryEmbed["Query → Vector"]
            Cosine["Cosine Similarity"]
            Hybrid["Hybrid Search<br/>Semantic + Exact Match Boost"]
        end
    end

    subgraph Storage["Cache"]
        Vectors["SQLite Database<br/>embeddings.db (WAL mode)"]
        Hashes["File Hashes<br/>Incremental updates"]
        Progressive["Progressive Indexing<br/>Search works during indexing"]
    end

    Agent <-->|"MCP Protocol"| Protocol
    Protocol --> Tools

    Tools --> Discovery
    Discovery --> Chunking
    Chunking --> Embedding
    Embedding --> Model
    Model --> Dimensions
    Dimensions --> Normalize
    Normalize --> Vectors

    Tools --> QueryEmbed
    QueryEmbed --> Model
    Cosine --> Hybrid
    Vectors --> Cosine
    Hybrid --> Agent

技術スタック

プライバシー

すべてが100%ローカルで実行されます。

• AIモデルはあなたのマシン上で実行されます（API呼び出しはありません）
• コードはあなたのシステムから離れることはありません
• テレメトリや分析は行われません
• キャッシュは .smart-coding-cache/ に保存されます。

研究背景

このプロジェクトは、Cursorの研究に基づいて構築されています。この研究によると、セマンティック検索により、AIコーディングエージェントのパフォーマンスが平均12.5%向上することが示されています。重要な洞察は、AIアシスタントは、大量のコンテキストよりも、関連するコンテキストからより多くの恩恵を受けるということです。

📄 ライセンス

MITライセンス - Copyright (c) 2025 Omar Haris 詳細は LICENSE を参照してください。