Narsil MCP

公式

Rustで実装された超高速🔥最高クラスのMCPサーバー。ニューラルエンジン、セキュリティプロファイリング、オプションのグラフフロントエンドを搭載

GitHub
185

Narsil MCPで何ができますか？

  • コードベースの探索 — アシスタントに馴染みのないプロジェクトのマッピング、シンボルの検索、32言語にわたる参照の追跡を依頼します。find_symbols と find_references を使用します。

  • セキュリティ脆弱性の分析 — 汚染解析、OWASP Top 10スキャン、CWEチェックを依頼して、インジェクションポイントを特定し、scan_security と suggest_fix による修正アドバイスを得ます。

  • 関数関係の追跡 — コールグラフの可視化、呼び出し元・呼び出し先の検索、関数間のパスの特定を行い、get_call_graph と find_call_path で実行フローを理解します。

  • サプライチェーンリスクの監査 — SBOMの生成、OSVに対する依存関係のチェック、generate_sbom、check_dependencies、check_licenses を使用したライセンス準拠の検証を行います。

  • コード品質の問題の検出 — Python、JavaScript、TypeScript全体で、デッドコード、未初期化変数、型不一致を find_dead_code と check_type_errors で特定します。

ドキュメント

narsil-mcp

高速かつプライバシー最優先の、ディープなコードインテリジェンスのためのMCPサーバー

License Rust Tests MCP

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

narsil-mcpを選ぶ理由

機能narsil-mcpXRAYSerenaGitHub MCP
言語32430+ (LSP)N/A
ニューラル検索ありなしなしなし
汚染解析ありなしなしなし
SBOM/ライセンスありなしなし一部
オフライン/ローカルありありありなし
WASM/ブラウザありなしなしなし
コールグラフあり一部なしなし
型推論ありなしなしなし

主な機能

  • コードインテリジェンス - シンボル抽出、セマンティック検索、コールグラフ解析
  • ニューラルセマンティック検索 - 埋め込みを使用した類似コードの検索（Voyage AI、OpenAI）
  • セキュリティ解析 - 汚染解析、脆弱性スキャン、OWASP/CWEカバレッジ
  • サプライチェーンセキュリティ - SBOM生成、依存関係監査、ライセンス準拠
  • 高度な解析 - 制御フローグラフ、データフロー解析、デッドコード検出

narsil-mcpを選ぶ理由

  • Rustで記述 - 驚異的に高速、メモリ安全、単一バイナリ（約30MB）
  • Tree-sitter搭載 - 32言語に対応した正確なインクリメンタル解析
  • 設定不要 - リポジトリを指定するだけですぐに使用可能
  • MCP準拠 - Claude、Cursor、VS Code Copilot、Zed、および任意のMCPクライアントで動作
  • プライバシー最優先 - 完全にローカルで動作し、データがマシンの外に出ることはありません
  • 並列インデックス - Rayonを介して全コアを使用
  • スマートな抜粋 - 完全な構文スコープに展開
  • セキュリティ最優先 - 組み込みの脆弱性検出と汚染解析
  • ニューラル埋め込み - Voyage AIまたはOpenAIによるオプションのセマンティック検索
  • WASMサポート - WebAssemblyビルドでブラウザ内で実行可能
  • リアルタイムストリーミング - 大規模リポジトリでもインデックス進行に応じて結果を表示

対応言語

言語拡張子抽出されるシンボル
Rust.rs関数、構造体、列挙型、トレイト、impl、モジュール
Python.py、.pyi関数、クラス
JavaScript.js、.jsx、.mjs関数、クラス、メソッド、変数
TypeScript.ts、.tsx関数、クラス、インターフェース、型、列挙型
Go.go関数、メソッド、型
C.c、.h関数、構造体、列挙型、typedef
C++.cpp、.cc、.hpp関数、クラス、構造体、名前空間
Java.javaメソッド、クラス、インターフェース、列挙型
C#.csメソッド、クラス、インターフェース、構造体、列挙型、デリゲート、名前空間
Bash.sh、.bash、.zsh関数、変数
Ruby.rb、.rake、.gemspecメソッド、クラス、モジュール
Kotlin.kt、.kts関数、クラス、オブジェクト、インターフェース
PHP.php、.phtml関数、メソッド、クラス、インターフェース、トレイト
Swift.swiftクラス、構造体、列挙型、プロトコル、関数
Verilog/SystemVerilog.v、.vh、.sv、.svhモジュール、タスク、関数、インターフェース、クラス
Scala.scala、.scクラス、オブジェクト、トレイト、関数、val
Lua.lua関数、メソッド
Haskell.hs、.lhs関数、データ型、型クラス
Elixir.ex、.exsモジュール、関数
Clojure.clj、.cljs、.cljc、.ednリスト（基本AST）
Dart.dart関数、クラス、メソッド
Julia.jl関数、モジュール、構造体
R.R、.r、.Rmd関数
Perl.pl、.pm、.t関数、パッケージ
Zig.zig関数、変数
Erlang.erl、.hrl関数、モジュール、レコード
Elm.elm関数、型
Fortran.f90、.f95、.f03、.f08、.f、.for、.fppプログラム、サブルーチン、関数、モジュール
PowerShell.ps1、.psm1、.psd1関数、クラス、列挙型
Nix.nixバインディング
Groovy.groovy、.gradleメソッド、クラス、インターフェース、列挙型、関数

インストール

パッケージマネージャー経由（推奨）

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

Rust/Cargo（全プラットフォーム）:

cargo install narsil-mcp

Node.js/npm（全プラットフォーム）:

npm install -g narsil-mcp
# or
yarn global add narsil-mcp
# or
pnpm add -g narsil-mcp

Nix:

# Run directly without installing
nix run github:postrv/narsil-mcp -- --repos ./my-project

# Install to profile
nix profile install github:postrv/narsil-mcp

# With web visualization frontend
nix profile install github:postrv/narsil-mcp#with-frontend

# Development shell
nix develop github:postrv/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（このリリースはRust 1.98および1.99で検証済み）
  • Windowsの場合: Visual Studio Build Tools の「C++によるデスクトップ開発」
# Clone and build
git clone git@github.com:postrv/narsil-mcp.git
cd narsil-mcp
cargo build --release

# Binary will be at:
# - macOS/Linux: target/release/narsil-mcp
# - Windows: target/release/narsil-mcp.exe

機能ビルド

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

# Default build - native MCP server (~30MB)
cargo build --release

# With RDF knowledge graph and CCG tools (~35MB) - SPARQL queries, Code Context Graph
cargo build --release --features graph

# With neural vector search (~32MB) - adds TF-IDF similarity
cargo build --release --features neural

# With ONNX model support (~50MB) - adds local neural embeddings
cargo build --release --features neural-onnx

# With embedded visualization frontend (~31MB)
cargo build --release --features frontend

# Full-featured build with graph + frontend (~40MB)
cargo build --release --features graph,frontend

# Experimental browser/WASM source build (not release-qualified)
cargo build --release --target wasm32-unknown-unknown --no-default-features --features wasm
機能説明サイズ
native（デフォルト）全ツールを備えた完全なMCPサーバー約30MB
graph+ RDFナレッジグラフ、SPARQL、CCGツール約35MB
frontend+ 組み込みの可視化Web UI約31MB
neural+ TF-IDFベクトル検索、API埋め込み約32MB
neural-onnx+ ローカルONNXモデル推論約50MB
wasm実験的なブラウザソースビルド（ファイルシステム、gitなし）リリース認定外

重要: --graph CLIフラグを使用するには、バイナリが--features graphでビルドされている必要があります。この機能なしでビルドされたバイナリに--graphを渡すと、警告が表示され、SPARQL/CCGツールは利用できません。詳細は以下のトラブルシューティングを参照してください。

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

使用方法

基本的な使用方法

macOS / Linux:

# Index a single repository
narsil-mcp --repos /path/to/your/project

# Index multiple repositories
narsil-mcp --repos ~/projects/project1 --repos ~/projects/project2

# Enable verbose logging
narsil-mcp --repos /path/to/project --verbose

# Force re-index on startup
narsil-mcp --repos /path/to/project --reindex

Windows（PowerShell / CMD）:

# Index a single repository
narsil-mcp --repos C:\Users\YourName\Projects\my-project

# Index multiple repositories
narsil-mcp --repos C:\Projects\project1 --repos C:\Projects\project2

# Enable verbose logging
narsil-mcp --repos C:\Projects\my-project --verbose

# Force re-index on startup
narsil-mcp --repos C:\Projects\my-project --reindex

全機能セット

narsil-mcp \
  --repos ~/projects/my-app \
  --git \           # Enable git blame, history, contributors
  --call-graph \    # Enable function call analysis
  --persist \       # Save index to disk for fast startup
  --watch \         # Auto-reindex on file changes
  --lsp \           # Enable LSP for hover, go-to-definition
  --streaming \     # Stream large result sets
  --remote \        # Enable GitHub remote repo support
  --neural \        # Enable neural semantic embeddings
  --neural-backend api \  # Backend: "api" (Voyage/OpenAI) or "onnx"
  --neural-model voyage-code-2 \  # Model to use
  --neural-dimension 3072 \  # Override embedding dimensions (auto-detected per model)
  --graph           # Enable SPARQL/RDF knowledge graph and CCG tools (requires --features graph build)

--graphに関する注意: このフラグはSPARQLクエリとCode Context Graph（CCG）ツールを有効にしますが、バイナリが--features graphでビルドされている場合に限ります。デフォルトのバイナリにはこの機能は含まれていません。SPARQL/CCG機能が必要な場合は、ソースからビルドしてください:

cargo build --release --features graph

この機能なしのバイナリに--graphを渡すと、起動時に警告が表示され、サーバーはSPARQL/CCGツールなしで動作を継続します。

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

# Run the neural API key setup wizard
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以降では、ツールとパフォーマンスを細かく制御するためのオプション設定が導入されています。 既存の使用方法はすべて引き続き機能します - 設定は完全にオプションです！

クイックスタート

# Generate default config interactively
narsil-mcp config init

# List available tools
narsil-mcp tools list

# Apply a preset via CLI
narsil-mcp --repos ~/project --preset minimal

自動エディター検出

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

エディタープリセットツールコンテキストトークン理由
Zed最小26約4,686高速起動、最小コンテキスト
VS Codeバランス51約8,948優れた機能バランス
Claude Desktopフル90約12,001最大機能

トークン節約:

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

プリセット

ユースケースに基づいてプリセットを選択してください:

# Minimal - Fast, lightweight (Zed, Cursor)
narsil-mcp --repos ~/project --preset minimal

# Balanced - Good defaults (VS Code, IntelliJ)
narsil-mcp --repos ~/project --preset balanced --git --call-graph

# Full - All features (Claude Desktop, comprehensive analysis)
narsil-mcp --repos ~/project --preset full --git --call-graph

# Security-focused - Security and supply chain tools
narsil-mcp --repos ~/project --preset security-focused

設定ファイル

ユーザー設定（~/.config/narsil-mcp/config.yaml）:

version: "1.0"
preset: "balanced"

tools:
  # Disable slow tools
  overrides:
    neural_search:
      enabled: false
      reason: "Too slow for interactive use"

performance:
  max_tool_count: 50  # Limit total tools

プロジェクト設定（リポジトリルートの.narsil.yaml）:

version: "1.0"
preset: "security-focused"  # Override user preset

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

名前付きリポジトリプロファイルは、マルチリポジトリワークスペースに便利です:

version: "1.0"
profiles:
  platform:
    repos:
      - ~/src/api
      - ~/src/web
    git: true
    call_graph: true
    persist: true
    preset: balanced

narsil-mcp --profile platform
narsil-mcp config profiles

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

環境変数

# Select repos/profile
export NARSIL_REPOS=~/src/api,~/src/web
export NARSIL_PROFILE=platform

# Apply preset
export NARSIL_PRESET=minimal

# Enable specific categories
export NARSIL_ENABLED_CATEGORIES=Repository,Symbols,Search

# Disable specific tools
export NARSIL_DISABLED_TOOLS=neural_search,generate_sbom

CLIコマンド

# View effective config
narsil-mcp config show

# Validate config file
narsil-mcp config validate ~/.config/narsil-mcp/config.yaml

# List tools by category
narsil-mcp tools list --category Search

# Search for tools
narsil-mcp tools search "git"

# Export config
narsil-mcp config export > my-config.yaml

# List named repository profiles
narsil-mcp config profiles

詳細情報:

可視化フロントエンド

コールグラフ、インポート、シンボル参照、制御フローをブラウザでインタラクティブに探索できます。

# Build with embedded frontend
cargo build --release --features frontend

# Run with HTTP server
narsil-mcp --repos ~/project --http --call-graph
# Open http://localhost:3000

5つのグラフビュー:

ビュー説明
コールグラフ深さ制御と方向フィルタリングを備えた関数呼び出し関係
インポートグラフコードベース全体のファイルレベルのインポート依存関係
シンボルグラフシンボルへのすべての参照（ファイルクラスタリング付き）
ハイブリッド分割予算付きのコール+インポートグラフの組み合わせ
制御フロー基本ブロック、分岐、ループバックエッジを備えた実際のCFG

機能:

  • ドラッグ、ズーム、ダブルクリックによるドリルダウンを備えたインタラクティブなCytoscape.jsグラフ
  • 色分け（緑/黄/オレンジ/赤）による複雑度メトリクスのオーバーレイ
  • 汚染ソースとシンクを強調表示するセキュリティ脆弱性オーバーレイ
  • 6つのレイアウトアルゴリズム（dagre、force-directed、breadthfirst、concentric、circle、grid）
  • 構文ハイライト付きコードビューアーを備えたファイルツリーサイドバー
  • URL駆動の状態（共有可能なリンク、ブラウザの戻る/進む）
  • ダークモードサポート
  • コード抜粋とソースへのナビゲーションを備えたノード詳細パネル

完全なドキュメント: セットアップ、APIエンドポイント、開発モードについてはdocs/frontend.mdを参照してください。

ニューラルセマンティック検索

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

# Quick setup with wizard
narsil-mcp config init --neural

# Or manually with 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は不要です。

ツール説明
infer_types関数内のすべての変数の推論型を取得
check_type_errors潜在的な型不一致を検出
get_typed_taint_flow型情報による強化されたセキュリティ解析
def process(data):
    result = data.split(",")  # result: list[str]
    count = len(result)       # count: int
    return count * 2          # returns: int

Forgemax統合（実験的）

大規模なエージェントワークフローのために、narsil-mcpはForgemaxを通じて使用できます。Forgemaxは、90のツールすべてをわずか2つ（search + execute）に集約するCode Mode MCPゲートウェイで、ツールスキーマのオーバーヘッドを約12,000トークンから約1,000トークンに削減します。

# Install Forgemax
cargo install forgemax

# Run narsil-mcp through Forgemax (uses forge.toml in repo root)
forgemax

同梱のforge.tomlは、narsil-mcpを適切なデフォルトで設定します:

[servers.narsil]
command = "narsil-mcp"
args = ["--repos", ".", "--git", "--call-graph", "--persist", "--watch"]
transport = "stdio"

[sandbox]
timeout_secs = 10
max_heap_mb = 64
max_concurrent = 8

LLMは、サンドボックス化されたV8アイソレート内の型付きプロキシオブジェクトを通じて呼び出しを行うJavaScriptを記述します。認証情報、ファイルパス、内部状態がホストから流出することはありません。このアプローチは、複数のMCPサーバーを同時に使用する場合に特に有用で、ツール全体のコンテキストを小さく予測可能に保ちます。

MCP設定

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

Claude Code（プロジェクトルートの.mcp.json - 推奨）:

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

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

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

cd /path/to/project
claude

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

ヒント: 以降の起動を高速化するには、--persist --index-path .claude/cacheを追加します。

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

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": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git"]
    }
  }
}

Zed向け注意: narsil-mcpは即座に起動し、バックグラウンドでインデックス化を行うため、初期化タイムアウトを防ぎます。

Claude Codeプラグイン

Claude Codeユーザー向けに、スラッシュコマンドとスキルを備えたプラグインを提供し、ツールを効果的に使用できるようにします。

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

# Add the narsil-mcp marketplace
/plugin marketplace add postrv/narsil-mcp

# Install the plugin
/plugin install narsil@narsil-mcp

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

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

含まれるもの:

コンポーネント説明
/narsil:security-scan包括的なセキュリティ監査を実行
/narsil:explore馴染みのないコードベースを探索
/narsil:analyze-function特定の関数を詳細に調査
/narsil:find-feature機能が実装されている場所を特定
/narsil:supply-chainサプライチェーンセキュリティを分析
スキル90のツールを効果的に使用する方法をClaudeにガイド
MCP設定適切なデフォルト設定でnarsil-mcpを自動起動

完全なドキュメントはnarsil-plugin/README.mdを参照してください。

Ralph自動化統合

Ralphは、自律的なコード開発のためのClaude Code自動化スイートです。narsil-mcpが利用可能な場合、Ralphは拡張されたコードインテリジェンス機能を獲得します:

機能narsil-mcpなしnarsil-mcpあり
セキュリティスキャン基本（clippy）OWASP/CWE脆弱性検出
コード理解ファイルベースコールグラフ、シンボル参照
アーキテクチャ分析手動CCG L0/L1/L2自動レイヤー
依存関係分析cargo treeインポートグラフ、循環検出

セットアップ:

# Install narsil-mcp (Ralph auto-detects it)
cargo install narsil-mcp

# Ralph's quality gates use these tools:
narsil-mcp scan_security --repo <name>
narsil-mcp check_type_errors --repo <name> --path src
narsil-mcp find_injection_vulnerabilities --repo <name>

Ralphはnarsil-mcpが利用できない場合でもグレースフルに機能を縮小します。すべてのコア自動化機能はnarsil-mcpなしでも動作します。

ドキュメント: 完全な統合の詳細はRalph READMEを参照してください。

プレイブックとチュートリアル

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

ガイド説明
はじめにクイックセットアップと最初のツール呼び出し
コードベースを理解する馴染みのないプロジェクトを探索
バグを修正するコールグラフと汚染解析でデバッグ
セキュリティ監査OWASP/CWEスキャンで脆弱性を発見
コードレビュー変更を効果的にレビュー

各プレイブックは、Claudeが質問に答えるために使用する正確なツールチェーンを示しています。

WebAssembly（ブラウザ）での使用

リポジトリには実験的なWebAssemblyソースとローカルビルドスクリプトが含まれています。 @narsil-mcp/wasmはnpmに公開されておらず、1.7.1 CLIリリースの配布チャネルではありません。 WASMビルドと例は、そのリリースの認定範囲に含まれていません。実験的なソースワークフローについてはdocs/wasm.mdを参照してください。

利用可能なツール（93）

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

ツール説明
list_reposメタデータ付きでインデックス化されたすべてのリポジトリを一覧表示
get_project_structureファイルアイコンとサイズ付きのディレクトリツリーを取得
get_fileオプションの行範囲付きでファイル内容を取得
get_excerptコンテキスト付きで特定の行の周囲のコードを抽出
reindexリポジトリの再インデックス化をトリガー
discover_reposディレクトリ内のリポジトリを自動検出
validate_repoパスが有効なリポジトリかどうかを確認
get_index_statusインデックス統計と有効な機能を表示

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

ツール説明
find_symbols型/パターンで構造体、クラス、関数を検索
get_symbol_definition周囲のコンテキスト付きでシンボルソースを取得
find_referencesシンボルへのすべての参照を検索
get_dependenciesインポートと依存先を分析
workspace_symbol_searchワークスペース全体でシンボルをファジー検索
find_symbol_usagesインポート付きのクロスファイルシンボル使用法
get_export_mapファイル/モジュールからエクスポートされたシンボルを取得

コード検索

ツール説明
search_code関連性ランキング付きのキーワード検索
semantic_searchBM25ランク付けされたセマンティック検索
hybrid_searchランクフュージョン付きのBM25 + TF-IDFの組み合わせ
search_chunksAST対応コードチャンクの検索
find_similar_codeスニペットに類似したコードを検索（TF-IDF）
find_similar_to_symbolシンボルに類似したコードを検索

AST対応チャンキング

ツール説明
get_chunksファイルのAST対応チャンクを取得
get_chunk_statsコードチャンクに関する統計
get_embedding_stats埋め込みインデックス統計

ニューラルセマンティック検索（--neuralが必要）

ツール説明
neural_searchニューラル埋め込みを使用したセマンティック検索（異なる名前でも類似コードを検出）
find_semantic_clones関数のType-3/4セマンティッククローンを検索
get_neural_statsニューラル埋め込みインデックス統計

コールグラフ分析（--call-graphが必要）

ツール説明
get_call_graphリポジトリ/関数のコールグラフを取得
get_callers関数を呼び出す関数を検索
get_callees関数によって呼び出される関数を検索
find_call_path2つの関数間のパスを検索
get_complexityサイクロマティック/認知的複雑度を取得
get_function_hotspots高度に接続された関数を検索

制御フロー分析

ツール説明
get_control_flow基本ブロックと分岐を示すCFGを取得
find_dead_code到達不能なコードブロックを検索

データフロー分析

ツール説明
get_data_flow変数の定義と使用
get_reaching_definitions各ポイントに到達する代入
find_uninitialized初期化前に使用される変数
find_dead_stores読み取られない代入

型推論（Python/JavaScript/TypeScript）

ツール説明
infer_types外部型チェッカーなしで関数内の変数の型を推論
check_type_errorsmypy/tscを実行せずに潜在的な型エラーを検出
get_typed_taint_flowデータフローと型推論を組み合わせた拡張汚染解析

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

ツール説明
get_import_graphインポートグラフを構築および分析
find_circular_imports循環依存関係を検出
get_incremental_statusマークルツリーと変更統計

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

ツール説明
find_injection_vulnerabilitiesSQLインジェクション、XSS、コマンドインジェクション、パストラバーサルを検出
trace_taintソースからの汚染データフローをトレース
get_taint_sources汚染ソースを一覧表示（ユーザー入力、ファイル、ネットワーク）
get_security_summary包括的なセキュリティリスク評価

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

ツール説明
scan_securityセキュリティルールでスキャン（OWASP、CWE、暗号、シークレット）
check_owasp_top10OWASP Top 10 2021の脆弱性をスキャン
check_cwe_top25CWE Top 25の弱点をスキャン
explain_vulnerability詳細な脆弱性の説明を取得
suggest_fix検出結果の修正提案を取得

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

ツール説明
generate_sbomSBOMを生成（CycloneDX/SPDX/JSON）
check_dependencies既知の脆弱性をチェック（OSVデータベース）
check_licensesコンプライアンス問題のライセンスを分析
find_upgrade_path脆弱な依存関係の安全なアップグレードパスを検索

Git統合（--gitが必要）

ツール説明
get_blameファイルのGit blame
get_file_historyファイルのコミット履歴
get_recent_changesリポジトリの最近のコミット
get_hotspots変更頻度と複雑度が高いファイル
get_contributorsリポジトリ/ファイルのコントリビューター
get_commit_diff特定のコミットの差分
get_symbol_historyシンボルを変更したコミット
get_branch_info現在のブランチとステータス
get_modified_files作業ツリーの変更

LSP統合（--lspが必要）

ツール説明
get_hover_info型情報とドキュメント
get_type_info正確な型情報
go_to_definition定義の場所を検索

リモートリポジトリサポート（--remoteが必要）

ツール説明
add_remote_repoGitHubリポジトリをクローンしてインデックス化
list_remote_filesGitHub API経由でファイルを一覧表示
get_remote_fileGitHub API経由でファイルを取得

メトリクス

ツール説明
get_metricsパフォーマンス統計とタイミング

SPARQL / ナレッジグラフ（--graphが必要）

ツール説明
sparql_queryRDFナレッジグラフに対してSPARQLクエリを実行
list_sparql_templates利用可能なSPARQLクエリテンプレートを一覧表示
run_sparql_templateパラメータ付きで定義済みSPARQLテンプレートを実行

コードコンテキストグラフ（CCG）（--graphが必要）

CCGは、コードベースの標準化されたAI消費可能な表現を階層化レイヤーで提供します。

ツール説明
get_ccg_manifestレイヤー0マニフェスト（約1-2KB JSON-LD）- リポジトリID、カウント
export_ccg_manifestレイヤー0マニフェストをファイルにエクスポート
export_ccg_architectureレイヤー1アーキテクチャ（約10-50KB JSON-LD）- モジュール、API
export_ccg_indexレイヤー2シンボルインデックス（約100-500KB N-Quads gzip圧縮）
export_ccg_fullレイヤー3完全詳細（約1-20MB N-Quads gzip圧縮）
export_ccgすべてのCCGレイヤーをバンドルとしてエクスポート
query_ccgSPARQLを使用してCCGをクエリ
get_ccg_aclCCGレイヤー用のWebACLアクセス制御を生成
get_ccg_access_infoCCGアクセス層情報を取得
import_ccgURLまたはファイルからCCGレイヤーをインポート
import_ccg_from_registrycodecontextgraph.comレジストリからCCGをインポート

セキュリティルール

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

コアルールセット:

  • owasp-top10.yaml - OWASP Top 10 2021の脆弱性パターン
  • cwe-top25.yaml - CWE Top 25の最も危険な弱点
  • crypto.yaml - 暗号化の問題（弱いアルゴリズム、ハードコードされたキー）
  • secrets.yaml - シークレット検出（APIキー、パスワード、トークン） 言語別ルール:
  • rust.yaml - Rustセキュリティパターン（unsafe transmute、FFI境界、コマンドインジェクション、TOCTOU）
  • elixir.yaml - Elixir/BEAMパターン（アトム枯渇、binary_to_term、Code.eval、Ecto SQLインジェクション）
  • go.yaml - Goセキュリティパターン（SQLインジェクション、TLS、コマンドインジェクション）
  • java.yaml - Javaの脆弱性（XXE、デシリアライゼーション、LDAPインジェクション）
  • csharp.yaml - C#のセキュリティ問題（デシリアライゼーション、XSS、パストラバーサル）
  • kotlin.yaml - Kotlin/Androidパターン（WebView、インテント、シークレット）
  • bash.yaml - シェルスクリプトの脆弱性（コマンドインジェクション、eval）

インフラストラクチャと設定:

  • iac.yaml - Infrastructure as Code（Terraform、CloudFormation、Kubernetes）
  • config.yaml - 設定ファイルのセキュリティ（ハードコードされた認証情報、安全でない設定）

カスタムルールは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）でベンチマーク:

パーススループット

言語入力サイズ時間スループット
Rust（大規模ファイル）278 KB131 µs1.98 GiB/s
Rust（中規模ファイル）27 KB13.5 µs1.89 GiB/s
Python~4 KB16.7 µs-
TypeScript~5 KB13.9 µs-
混合（5ファイル）~15 KB57 µs-

検索レイテンシ

操作コーパスサイズ時間
シンボル完全一致1,000シンボル483 ns
シンボル前方一致1,000シンボル2.7 µs
シンボルあいまい一致1,000シンボル16.5 µs
BM25全文検索1,000ドキュメント80 µs
TF-IDF類似度1,000ドキュメント130 µs
ハイブリッド（BM25+TF-IDF）1,000ドキュメント151 µs

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

リポジトリファイル数シンボル数時間メモリ
narsil-mcp（このリポジトリ）531,733220 ms~50 MB
rust-analyzer2,847~50K2.1s89 MB
linux kernel78,000+~500K45s2.1 GB

主要メトリクス:

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

開発

# Run the full test suite
cargo test

# Run benchmarks (criterion.rs)
cargo bench

# Run with debug logging
RUST_LOG=debug cargo run -- --repos ./test-fixtures

# Format code
cargo fmt

# Lint
cargo clippy

# Test with MCP Inspector
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

# For WASM builds
brew install emscripten  # macOS

ニューラル検索APIエラー

# Check your API key is set
echo $VOYAGE_API_KEY  # or $OPENAI_API_KEY

# Common issue: wrong key format
export VOYAGE_API_KEY="pa-..."  # Voyage keys start with "pa-"
export OPENAI_API_KEY="sk-..."  # OpenAI keys start with "sk-"

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

# Check .gitignore isn't excluding files
narsil-mcp --repos /path --verbose  # Shows skipped files

# Force reindex
narsil-mcp --repos /path --reindex

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

# For very large repos (>50K files), increase stack size
RUST_MIN_STACK=8388608 narsil-mcp --repos /path/to/huge-repo

# Or index specific subdirectories
narsil-mcp --repos /path/to/repo/src --repos /path/to/repo/lib

グラフ機能が動作しない

--graphを渡して次のような警告が表示される場合:

WARN: --graph flag was passed but the binary was built without the 'graph' feature.
SPARQL and CCG tools will not be available.

これは、graph機能を有効にしてコンパイルされていないバイナリを使用していることを意味します。修正するには:

# Build from source with the graph feature
cargo build --release --features graph

# Or with multiple features
cargo build --release --features graph,frontend

# Then run with --graph
./target/release/narsil-mcp --repos ~/project --graph

なぜ別の機能なのか? graph機能はOxigraph RDFデータベース（バイナリサイズが約5MB増加）を追加しますが、これはほとんどのユースケースでは必要ありません。デフォルトのバイナリを小さく保つためにオプションとして維持されています。

グラフが有効かどうかを確認する方法: 起動ログを確認してください:

  • graph=trueは機能がコンパイルされ、かつ有効になっていることを意味します
  • graph=falseは機能がコンパイルされていないか、--graphが渡されていないことを意味します

ロードマップ

完了済み

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

新機能

v1.6.x（現在）

  • クラッシュプルーフチャンキング - chunk_file()およびextract_signature()における安全でないバイトレベル文字列スライシングを修正。これにより、マルチバイトUTF-8文字（絵文字、CJK、アクセント付き文字）を含むファイルを処理する際にhybrid_search、search_chunks、get_chunk_statsがクラッシュしていました。すべてのバイトスライシングは、フォールバック付きの安全なcontent.get()を使用するようになりました。
  • NaN安全なソート操作 - 検索、埋め込み、git、インデックス、抽出モジュールの5箇所で、NaN浮動小数点値に対してpartial_cmp().unwrap()がパニックを引き起こす問題を修正。すべてのソートはunwrap_or(Ordering::Equal)を使用するようになりました。
  • 多層防御チャンキング - リポジトリ全体のchunk_file()ループの周りにcatch_unwindラッパーを追加。1つのファイルでのパニックは、MCPサーバー全体をクラッシュさせる代わりにスキップされます。
  • ビジュアライゼーションフロントエンドの刷新 - HashRouterルーティング、ファイルツリーサイドバー、シンタックスハイライト付きコードビューアー、ダッシュボード、リポジトリ別概要ページを備えた完全なSPA
  • グラフビューのパフォーマンス - インポートグラフはファイルシステムウォークの代わりにキャッシュされたインデックスデータを使用。シンボルグラフはマークダウンラウンドトリップの代わりにファイルキャッシュを直接反復。すべてのビューは早期終了のためにmax_nodesを尊重
  • 実際の制御フローグラフ - フロービューは、単一ブロックのスタブの代わりに、適切な基本ブロック、分岐条件、ループバックエッジを持つ実際のCFGビルダー（cfg::analyze_function）を使用
  • ハイブリッドグラフ予算分割 - ハイブリッドビューは、バランスの取れた結果のためにコールグラフとインポートグラフの間で60/40のノード予算を割り当て
  • 修正#14: 設定可能な埋め込み次元 - --neural-dimensionCLI引数とdefault_dimension_for_model()ルックアップを追加。text-embedding-3-largeなどのモデルがハードコードされた1536の代わりに正しい次元（3072）を使用するように
  • 修正#13: Nixフロントエンドビルド - flake.nixにfrontendDist導出を追加し、buildNpmPackageを使用してnix profile install github:postrv/narsil-mcp#with-frontendが動作するように
  • Rustセキュリティルール - コマンドインジェクション、transmute、FFI境界、TOCTOU、ReDoS、static mut、SSRFなどをカバーする18の新しいルール（RUST-004からRUST-021）
  • Elixirセキュリティルール - アトム枯渇、binary_to_termデシリアライゼーション、Code.evalインジェクション、Ecto SQLインジェクション、Phoenix XSS、Erlang分散セキュリティをカバーする18の新しいルール（EX-001からEX-018）
  • serde_yamlからserde-saphyrへ移行 - 非推奨のserde_yamlを、積極的にメンテナンスされパニックフリーのYAMLライブラリに置き換え
  • カスタムファビコン - フロントエンドはデフォルトのViteロゴの代わりにnarsil-mcpブランディングアイコンを使用
  • 依存関係のセキュリティ - timeを0.3.47（RUSTSEC-2026-0009）に、bytesを1.11.1（RUSTSEC-2026-0007）に更新
  • テスト数が1,611から1,763に増加（+152テスト）

v1.5.x

  • 決定論的コールグラフ解決 - スコープヒント伝播により、被呼び出し側の解決があいまいさなく行われます（例: App::run()はsrc/app/mod.rs::runに正しく解決されます）
  • 8つのグラフ解析修正 - 修飾ノードキー、ホットスポットフィルタリング、CFG式処理、インポートパス解析
  • Nixフレークの改善 - DRYなmkPkgヘルパー、不要なmacOSフレームワークの削除、サンドボックスビルドのための--libテスト戦略

v1.4.x

  • SPARQL / RDFナレッジグラフ - Oxigraphを介したSPARQLでコードインテリジェンスデータをクエリ
  • コードコンテキストグラフ（CCG） - 階層化レイヤー（L0-L3）を持つ、標準化されたAI消費可能なコードベース表現のための12のツール
  • 型認識セキュリティ解析 - 型推論とトレイト実装による強化されたテイントトラッキング
  • 多言語CFG/DFG - 制御フローおよびデータフロー解析をGo、Java、C#、Kotlinに拡張
  • Infrastructure as Codeスキャン - Terraform、CloudFormation、Kubernetesのための新しいiac.yamlルール
  • 言語別セキュリティルール - Go、Java、C#、Kotlin、Bashのための新しいルール
  • 6つの新しい言語 - Erlang、Elm、Fortran、PowerShell、Nix、Groovy
  • 合計90ツール - 新しいSPARQL、CCG、解析機能により79から増加

v1.2.x

  • exclude_testsパラメータ - 22のツールがテストファイルのフィルタリングをサポート
  • npmパッケージ - npm install -g narsil-mcpでインストール

v1.1.x

  • マルチプラットフォーム配布 - Homebrew、Scoop、npm、Cargo、または直接ダウンロードでインストール
  • 設定可能なツールプリセット - 最小、バランス、フル、セキュリティ重視のプリセット
  • 自動エディタ検出 - Zed、VS Code、Claude Desktopの最適なデフォルト
  • 対話型セットアップウィザード - 簡単な設定のためのnarsil-mcp config init
  • 32言語サポート - Dart、Julia、R、Perl、Zigなどを追加
  • パフォーマンス向上 - バックグラウンドインデックス作成による高速起動

v1.0.x

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

ライセンス

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

お客様の選択により。

クレジット

以下を使用して構築:

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