Narsil MCP

🚀 narsil-mcp

高速でプライバシーを重視した、深いコードインテリジェンスのためのMCPサーバー

Rustで構築されたMCP（Model Context Protocol）サーバーで、76種類の特殊ツールを通じてAIアシスタントに深いコード理解能力を提供します。

🚀 クイックスタート

narsil-mcpは、高速でプライバシーを重視したMCPサーバーです。以下の手順で簡単にセットアップできます。

✨ 主な機能

なぜnarsil-mcpを選ぶべきか？

主要な機能

• コードインテリジェンス - シンボル抽出、意味検索、呼び出しグラフ解析
• ニューラル意味検索 - 埋め込みを使用して類似コードを検索（Voyage AI、OpenAI）
• セキュリティ解析 - 汚染解析、脆弱性スキャン、OWASP/CWE対応
• サプライチェーンセキュリティ - SBOM生成、依存関係監査、ライセンス遵守
• 高度な解析 - 制御フローグラフ、データフロー解析、未使用コード検出

なぜnarsil-mcpを選ぶべきか？

• Rustで記述 - 超高速でメモリ安全、単一バイナリ（約30MB）
• Tree-sitter搭載 - 16言語の正確でインクリメンタルな構文解析
• ゼロコンフィグ - リポジトリを指定するだけですぐに使用可能
• MCP準拠 - Claude、Cursor、VS Code Copilot、Zed、およびすべてのMCPクライアントと互換性があります
• プライバシー重視 - 完全にローカルで動作し、データはマシンを離れません
• 並列インデックス作成 - Rayonを使用してすべてのコアを活用
• スマート抜粋 - 完全な構文スコープまで拡張
• セキュリティ重視 - 組み込みの脆弱性検出と汚染解析
• ニューラル埋め込み - Voyage AIまたはOpenAIを使用したオプションの意味検索
• WASMサポート - WebAssemblyビルドでブラウザで実行可能
• リアルタイムストリーミング - 大規模なリポジトリのインデックス作成中に結果をストリーミング

📦 インストール

パッケージマネージャを使用する（推奨）

macOS / Linux (Homebrew):

brew tap postrv/narsil
brew install narsil-mcp

Windows (Scoop):

scoop bucket add narsil https://github.com/postrv/scoop-narsil
scoop install narsil-mcp

Arch Linux (AUR):

yay -S narsil-mcp-bin  # バイナリリリース（高速）
# または
yay -S narsil-mcp      # ソースからビルド

Rust/Cargo (すべてのプラットフォーム):

cargo install narsil-mcp

Node.js/npm (すべてのプラットフォーム):

npm install -g narsil-mcp
# または
yarn global add narsil-mcp
# または
pnpm add -g narsil-mcp

ワンクリックインストールスクリプト

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.ps1 | iex

Windows (Git Bash / MSYS2):

curl -fsSL https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.sh | bash

⚠️ 重要提示

Windowsユーザーへの注意: PowerShellインストーラは、より良いエラーメッセージとWindowsネイティブの統合を提供します。ソースからビルドする場合、自動的にPATHを設定し、必要なビルドツールをチェックします。

ソースからのインストール

前提条件:

• Rust 1.70以上
• Windowsの場合: Visual Studio Build Tools の "Desktop development with C++"

# クローンしてビルド
git clone git@github.com:postrv/narsil-mcp.git
cd narsil-mcp
cargo build --release

# バイナリの場所:
# - macOS/Linux: target/release/narsil-mcp
# - Windows: target/release/narsil-mcp.exe

機能別ビルド

narsil-mcpは、さまざまなユースケースに対応するための機能セットをサポートしています。

# デフォルトビルド - ネイティブMCPサーバー（約30MB）
cargo build --release

# ニューラルベクトル検索付き（約18MB） - TF-IDF類似性を追加
cargo build --release --features neural

# ONNXモデルサポート付き（約50MB） - ローカルニューラル埋め込みを追加
cargo build --release --features neural-onnx

# 埋め込みビジュアライゼーションフロントエンド付き（約31MB）
cargo build --release --features frontend

# ブラウザ/WASMでの使用
cargo build --release --target wasm32-unknown-unknown --features wasm

詳細なインストール手順、トラブルシューティング、およびプラットフォーム固有のガイドについては、docs/INSTALL.md を参照してください。

💻 使用例

基本的な使用法

macOS / Linux:

# 単一のリポジトリをインデックス化
narsil-mcp --repos /path/to/your/project

# 複数のリポジトリをインデックス化
narsil-mcp --repos ~/projects/project1 --repos ~/projects/project2

# 詳細ログを有効にする
narsil-mcp --repos /path/to/project --verbose

# 起動時に強制的に再インデックス化
narsil-mcp --repos /path/to/project --reindex

Windows (PowerShell / CMD):

# 単一のリポジトリをインデックス化
narsil-mcp --repos C:\Users\YourName\Projects\my-project

# 複数のリポジトリをインデックス化
narsil-mcp --repos C:\Projects\project1 --repos C:\Projects\project2

# 詳細ログを有効にする
narsil-mcp --repos C:\Projects\my-project --verbose

# 起動時に強制的に再インデックス化
narsil-mcp --repos C:\Projects\my-project --reindex

全機能セット

narsil-mcp \
  --repos ~/projects/my-app \
  --git \           # git blame、履歴、貢献者を有効にする
  --call-graph \    # 関数呼び出し解析を有効にする
  --persist \       # インデックスをディスクに保存して高速起動を可能にする
  --watch \         # ファイル変更時に自動的に再インデックス化
  --lsp \           # ホバー情報、定義へのジャンプのためのLSPを有効にする
  --streaming \     # 大規模な結果セットをストリーミング
  --remote \        # GitHubリモートリポジトリサポートを有効にする
  --neural \        # ニューラル意味埋め込みを有効にする
  --neural-backend api \  # バックエンド: "api" (Voyage/OpenAI) または "onnx"
  --neural-model voyage-code-2  # 使用するモデル

⚠️ 重要提示

ニューラル埋め込みにはAPIキー（またはカスタムエンドポイント）が必要です。これを設定する最も簡単な方法は、対話型ウィザードを使用することです。

# ニューラルAPIキー設定ウィザードを実行
narsil-mcp config init --neural

ウィザードは以下のことを行います:

• エディタ（Claude Desktop、Claude Code、Zed、VS Code、JetBrains）を検出します
• APIプロバイダ（Voyage AI、OpenAI、またはカスタム）を入力するように促します
• APIキーを検証します
• エディタのMCP設定に自動的に追加します

あるいは、以下の環境変数のいずれかを手動で設定することもできます:

• EMBEDDING_API_KEY - 任意のプロバイダの汎用APIキー
• VOYAGE_API_KEY - Voyage AI専用のAPIキー
• OPENAI_API_KEY - OpenAI専用のAPIキー
• EMBEDDING_SERVER_ENDPOINT - カスタム埋め込みAPIエンドポイントURL（オプション、セルフホストモデルの使用を可能にします）

設定

v1.1.0以降では、ツールとパフォーマンスを細かく制御するためのオプション設定が導入されました。すべての既存の使用法は引き続き機能します - 設定は完全にオプションです！

クイックスタート

# 対話的にデフォルト設定を生成
narsil-mcp config init

# 使用可能なツールをリスト表示
narsil-mcp tools list

# CLIを介してプリセットを適用
narsil-mcp --repos ~/project --preset minimal

自動エディタ検出

narsil-mcpはエディタを検出し、自動的に最適なプリセットを適用します:

トークン節約:

• 最小限のプリセット: フルプリセットと比べて61%少ないトークン
• バランスの良いプリセット: フルプリセットと比べて25%少ないトークン

プリセット

ユースケースに基づいてプリセットを選択します:

# 最小限 - 高速で軽量（Zed、Cursor）
narsil-mcp --repos ~/project --preset minimal

# バランス - 良好なデフォルト設定（VS Code、IntelliJ）
narsil-mcp --repos ~/project --preset balanced --git --call-graph

# フル - すべての機能（Claude Desktop、包括的な解析）
narsil-mcp --repos ~/project --preset full --git --call-graph

# セキュリティ重視 - セキュリティとサプライチェーンツール
narsil-mcp --repos ~/project --preset security-focused

設定ファイル

ユーザー設定 (~/.config/narsil-mcp/config.yaml):

version: "1.0"
preset: "balanced"

tools:
  # 低速なツールを無効にする
  overrides:
    neural_search:
      enabled: false
      reason: "対話的な使用には遅すぎます"

performance:
  max_tool_count: 50  # ツールの総数を制限

プロジェクト設定 (.narsil.yaml in repo root):

version: "1.0"
preset: "security-focused"  # ユーザープリセットを上書き

tools:
  categories:
    Security:
      enabled: true
    SupplyChain:
      enabled: true

優先順位: CLIフラグ > 環境変数 > プロジェクト設定 > ユーザー設定 > デフォルト

環境変数

# プリセットを適用
export NARSIL_PRESET=minimal

# 特定のカテゴリを有効にする
export NARSIL_ENABLED_CATEGORIES=Repository,Symbols,Search

# 特定のツールを無効にする
export NARSIL_DISABLED_TOOLS=neural_search,generate_sbom

CLIコマンド

# 有効な設定を表示
narsil-mcp config show

# 設定ファイルを検証
narsil-mcp config validate ~/.config/narsil-mcp/config.yaml

# カテゴリ別にツールをリスト表示
narsil-mcp tools list --category Search

# ツールを検索
narsil-mcp tools search "git"

# 設定をエクスポート
narsil-mcp config export > my-config.yaml

詳細については、以下を参照してください:

• 設定ガイド - 完全な設定リファレンス
• インストールガイド - プラットフォーム固有のインストール

ビジュアライゼーションフロントエンド

ブラウザで対話的に呼び出しグラフ、インポート、およびコード構造を探索できます。

# 埋め込みフロントエンド付きでビルド
cargo build --release --features frontend

# HTTPサーバーで実行
narsil-mcp --repos ~/project --http --call-graph
# http://localhost:3000 を開く

機能: 対話型グラフ、複雑度オーバーレイ、セキュリティハイライト、複数のレイアウト

セットアップ、APIエンドポイント、および開発モードについては、docs/frontend.md を参照してください。

ニューラル意味検索

ニューラル埋め込みを使用して、変数名や構造が異なる場合でも類似コードを検索できます。

# ウィザードで簡単に設定
narsil-mcp config init --neural

# またはVoyage AIを手動で設定
export VOYAGE_API_KEY="your-key"
narsil-mcp --repos ~/project --neural --neural-model voyage-code-2

Voyage AI、OpenAI、カスタムエンドポイント、およびローカルONNXモデルをサポートしています。

セットアップ、バックエンド、およびユースケースについては、docs/neural-search.md を参照してください。

型推論

Python、JavaScript、およびTypeScriptに組み込みの型推論があり、mypyやtscは必要ありません。

def process(data):
    result = data.split(",")  # result: list[str]
    count = len(result)       # count: int
    return count * 2          # returns: int

MCP設定

構成ファイルを作成することで、narsil-mcpをAIアシスタントに追加できます。以下は推奨される設定です:

Claude Code (.mcp.json in project root - 推奨):

プロジェクトディレクトリに .mcp.json を作成して、プロジェクトごとの設定を行います:

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git", "--call-graph"]
    }
  }
}

次に、プロジェクト内でClaude Codeを起動します:

cd /path/to/project
claude

--repos に . を指定すると、現在のディレクトリが自動的にインデックス化されます。Claudeは現在、76のコードインテリジェンスツールにアクセスできるようになります。

💡 使用建议

後続の実行での起動を高速化するには、--persist --index-path .claude/cache を追加してください。

グローバル設定の場合は、代わりに ~/.claude/settings.json を編集します。詳細な設定については、Claude Code Integration を参照してください。

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git", "--call-graph"]
    }
  }
}

VS Code + GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git", "--call-graph"]
    }
  }
}

⚠️ 重要提示

Copilot Enterpriseの場合、MCPサポートにはVS Code 1.102以上が必要で、組織の管理者によって有効にする必要があります。

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", "/path/to/your/projects", "--git"]
    }
  }
}

Zed (settings.json → Context Servers):

{
  "context_servers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git"]
    }
  }
}

⚠️ 重要提示

Zedの場合、narsil-mcpはすぐに起動し、バックグラウンドでインデックス化を行い、初期化タイムアウトを防ぎます。

Claude Codeプラグイン

Claude Code ユーザー向けに、スラッシュコマンドとスキルを備えたプラグインを提供しています。

マーケットプレイスからインストールする（推奨）:

# narsil-mcpマーケットプレイスを追加
/plugin marketplace add postrv/narsil-mcp

# プラグインをインストール
/plugin install narsil@narsil-mcp

またはGitHubから直接インストールする:

/plugin install github:postrv/narsil-mcp/narsil-plugin

含まれる機能:

詳細なドキュメントについては、narsil-plugin/README.md を参照してください。

実践ガイドとチュートリアル

実践的な使用ガイドについては、docs/playbooks を参照してください:

各ガイドでは、Claudeが質問に答えるために使用する正確なツールチェーンが示されています。

WebAssembly (ブラウザ) での使用

narsil-mcpはWebAssemblyを介してブラウザで完全に実行できます - ブラウザベースのIDE、コードレビューツール、または教育プラットフォームに最適です。

npm install @narsil-mcp/wasm

import { CodeIntelClient } from '@narsil-mcp/wasm';

const client = new CodeIntelClient();
await client.init();
client.indexFile('src/main.rs', rustSourceCode);
const symbols = client.findSymbols('Handler');

ビルド手順、Reactの例、およびAPIリファレンスについては、docs/wasm.md を参照してください。

利用可能なツール (76)

リポジトリとファイル管理

シンボル検索とナビゲーション

コード検索

AST認識チャンク化

ニューラル意味検索 ( --neural が必要)

呼び出しグラフ解析 ( --call-graph が必要)

制御フロー解析

データフロー解析

型推論 (Python/JavaScript/TypeScript)

インポート/依存関係グラフ

セキュリティ解析 - 汚染追跡

セキュリティ解析 - ルールエンジン

サプライチェーンセキュリティ

Git統合 ( --git が必要)

LSP統合 ( --lsp が必要)

リモートリポジトリサポート ( --remote が必要)

メトリクス

セキュリティルール

narsil-mcpには rules/ に組み込みのセキュリティルールが含まれています:

• owasp-top10.yaml - OWASP Top 10 2021の脆弱性パターン
• cwe-top25.yaml - CWE Top 25の最も危険な弱点
• crypto.yaml - 暗号化の問題（弱いアルゴリズム、ハードコードされたキー）
• secrets.yaml - シークレット検出（APIキー、パスワード、トークン）

カスタムルールは scan_security --ruleset /path/to/rules.yaml で読み込むことができます。

アーキテクチャ

+-----------------------------------------------------------------+
|                         MCP Server                               |
|  +-----------------------------------------------------------+  |
|  |                   JSON-RPC over stdio                      |  |
|  +-----------------------------------------------------------+  |
|                              |                                   |
|  +---------------------------v-------------------------------+  |
|  |                   Code Intel Engine                        |  |
|  |  +------------+ +------------+ +------------------------+  |  |
|  |  |  Symbol    | |   File     | |    Search Engine       |  |  |
|  |  |  Index     | |   Cache    | |  (Tantivy + TF-IDF)    |  |  |
|  |  | (DashMap)  | | (DashMap)  | +------------------------+  |  |
|  |  +------------+ +------------+                              |  |
|  |  +------------+ +------------+ +------------------------+  |  |
|  |  | Call Graph | |  Taint     | |   Security Rules       |  |  |
|  |  |  Analysis  | |  Tracker   | |   Engine               |  |  |
|  |  +------------+ +------------+ +------------------------+  |  |
|  +-----------------------------------------------------------+  |
|                              |                                   |
|  +---------------------------v-------------------------------+  |
|  |                Tree-sitter Parser                          |  |
|  |  +------+ +------+ +------+ +------+ +------+             |  |
|  |  | Rust | |Python| |  JS  | |  TS  | | Go   | ...         |  |
|  |  +------+ +------+ +------+ +------+ +------+             |  |
|  +-----------------------------------------------------------+  |
|                              |                                   |
|  +---------------------------v-------------------------------+  |
|  |                Repository Walker                           |  |
|  |           (ignore crate - respects .gitignore)             |  |
|  +-----------------------------------------------------------+  |
+-----------------------------------------------------------------+

パフォーマンス

Apple M1でベンチマークを実行しました（criterion.rs）:

構文解析スループット

検索レイテンシー

エンドツーエンドのインデックス作成

主要なメトリクス:

• Tree-sitter構文解析: ~2 GiB/s の持続的なスループット
• シンボルルックアップ: 完全一致で <1µs
• 全文検索: ほとんどのクエリで <1ms
• ハイブリッド検索はrayonを介してBM25 + TF-IDFを並列実行

開発

# テストを実行（359テスト）
cargo test

# ベンチマークを実行（criterion.rs）
cargo bench

# デバッグログを有効にして実行
RUST_LOG=debug cargo run -- --repos ./test-fixtures

# コードをフォーマット
cargo fmt

# リントを実行
cargo clippy

# MCPインスペクターでテスト
npx @modelcontextprotocol/inspector ./target/release/narsil-mcp --repos ./path/to/repo

トラブルシューティング

Tree-sitterビルドエラー

ビルド中にCコンパイラまたはtree-sitterに関するエラーが表示された場合:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# WASMビルドの場合
brew install emscripten  # macOS

ニューラル検索APIエラー

# APIキーが設定されていることを確認
echo $VOYAGE_API_KEY  # または $OPENAI_API_KEY

# 一般的な問題: キーの形式が間違っている
export VOYAGE_API_KEY="pa-..."  # Voyageのキーは "pa-" で始まります
export OPENAI_API_KEY="sk-..."  # OpenAIのキーは "sk-" で始まります

インデックスがファイルを見つけられない

# .gitignoreがファイルを除外していないことを確認
narsil-mcp --repos /path --verbose  # スキップされたファイルを表示

# 強制的に再インデックス化
narsil-mcp --repos /path --reindex

大規模なリポジトリでのメモリ問題

# 非常に大きなリポジトリ（>50Kファイル）の場合、スタックサイズを増やす
RUST_MIN_STACK=8388608 narsil-mcp --repos /path/to/huge-repo

# または特定のサブディレクトリをインデックス化
narsil-mcp --repos /path/to/repo/src --repos /path/to/repo/lib

ロードマップ

完了済み

• [x] 多言語シンボル抽出（16言語）
• [x] Tantivyを使用した全文検索（BM25ランキング）
• [x] ハイブリッド検索（BM25 + TF-IDFとRRF）
• [x] AST認識コードチャンク化
• [x] Git blame/履歴統合
• [x] 複雑度メトリクス付きの呼び出しグラフ解析
• [x] 制御フローグラフ（CFG）解析
• [x] 到達定義付きのデータフロー解析（DFG）
• [x] 未使用コードと未使用代入の検出
• [x] インジェクション脆弱性のための汚染解析
• [x] セキュリティルールエンジン（OWASP、CWE、暗号化、シークレット）
• [x] SBOM生成（CycloneDX、SPDX）
• [x] 依存関係の脆弱性チェック（OSV）
• [x] ライセンス遵守解析
• [x] 循環依存関係検出付きのインポートグラフ
• [x] クロス言語シンボル解決
• [x] Merkleツリーを使用したインクリメンタルインデックス作成
• [x] インデックスの永続化
• [x] ファイル変更のウォッチモード
• [x] LSP統合
• [x] リモートリポジトリサポート
• [x] ストリーミングレスポンス

新機能

v1.1.x (現在)

• マルチプラットフォーム配布 - Homebrew、Scoop、npm、Cargo、または直接ダウンロードでインストール可能
• 設定可能なツールプリセット - 最小限、バランス、フル、およびセキュリティ重視のプリセット
• 自動エディタ検出 - Zed、VS Code、Claude Desktopに最適なデフォルト設定
• 対話型セットアップウィザード - narsil-mcp config init で簡単に設定可能
• SwiftとVerilogのサポート - 現在16言語をサポート
• パフォーマンスの改善 - バックグラウンドインデックス化による高速起動

v1.0.x

• ニューラル意味検索 - Voyage AIまたはOpenAIの埋め込みを使用して類似コードを検索
• 型推論 - 外部ツールなしでPython/JavaScript/TypeScriptの型を推論
• 多言語汚染解析 - PHP、Java、C#、Ruby、Kotlinのセキュリティスキャン
• WASMビルド - コードプレイグラウンドや教育ツールのためにブラウザで実行可能
• 111のバンドルされたセキュリティルール - OWASP、CWE、暗号化、シークレット検出
• IDE設定が含まれています - Claude Desktop、Cursor、VS Code、Zedのテンプレート

📄 ライセンス

次のいずれかのライセンスの下でライセンスされています:

• Apache License, Version 2.0 (LICENSE-APACHE または http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT または http://opensource.org/licenses/MIT)

あなたの選択です。

クレジット

以下のツールを使用して構築されています:

• tree-sitter - インクリメンタル構文解析
• tantivy - 全文検索
• tokio - 非同期ランタイム
• rayon - データ並列処理
• serde - シリアライゼーション