Narsil MCP

公式

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

GitHub

168

Narsil MCPで何ができますか？

Find symbols across 32 languages — Search for functions, classes, or interfaces by name or pattern using find_symbols or workspace_symbol_search.
Trace tainted data for security audits — Follow user input through the codebase with trace_taint and detect injection vulnerabilities like SQLi or XSS.
Analyze function call relationships — Map callers, callees, and paths between functions with get_call_graph, get_callers, and find_call_path.
Generate a software bill of materials — Export a CycloneDX or SPDX SBOM and check dependencies against the OSV database with generate_sbom and check_dependencies.
Infer types without external checkers — Get inferred types for Python, JavaScript, or TypeScript variables using infer_types and find potential type errors.
Query the codebase as a knowledge graph — Run SPARQL queries against the RDF graph or export tiered CCG layers for AI consumption with sparql_query and export_ccg.

ドキュメント

narsil-mcp

深いコードインテリジェンスのための、超高速でプライバシーを最優先するMCPサーバー

90の専用ツールを通じて、AIアシスタントに深いコード理解を提供する、Rust製のMCP（モデルコンテキストプロトコル）サーバーです。

なぜnarsil-mcpなのか？

機能	narsil-mcp	XRAY	Serena	GitHub MCP
言語	32	4	30以上 (LSP)	該当なし
ニューラル検索	あり	なし	なし	なし
テイント解析	あり	なし	なし	なし
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`	関数、構造体、列挙型、トレイト、実装、モジュール
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`	クラス、オブジェクト、トレイト、関数、vals
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 1.70以降
Windowsの場合: Visual Studio Build Tools の「C++によるデスクトップ開発」

# Clone and build
git clone [email protected]: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

# For browser/WASM usage
cargo build --release --target wasm32-unknown-unknown --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なし）	~3MB

重要: --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クエリとコードコンテキストグラフ（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	Minimal	26	~4,686	高速起動、最小限のコンテキスト
VS Code	Balanced	51	~8,948	機能のバランスが良好
Claude Desktop	Full	90	~12,001	最大限の機能

トークン節約:

Minimalプリセット: Full比で61%少ないトークン
Balancedプリセット: Full比で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、フォースディレクテッド、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を通じて使用できます。これは、90のツールすべてをわずか2つ（search + execute）に集約し、ツールスキーマのオーバーヘッドを約12,000トークンから約1,000トークンに削減するCode Mode MCPゲートウェイです。

# 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が利用できない場合でも適切に機能を低下させ、コアの自動化機能はすべて動作します。

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

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

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

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

各プレイブックは、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を参照してください。

利用可能なツール (90)

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

ツール	説明
`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_search`	BM25ランク付けされたセマンティック検索
`hybrid_search`	ランク融合によるBM25 + TF-IDFの組み合わせ
`search_chunks`	AST認識コードチャンクの検索
`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_path`	2つの関数間のパスを検索
`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_errors`	mypy/tscを実行せずに潜在的な型エラーを検索
`get_typed_taint_flow`	データフローと型推論を組み合わせた強化されたテイント分析

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

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

セキュリティ分析 - テイントトラッキング

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

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

ツール	説明
`scan_security`	セキュリティルールでスキャン (OWASP、CWE、暗号、シークレット)
`check_owasp_top10`	OWASP Top 10 2021の脆弱性をスキャン
`check_cwe_top25`	CWE Top 25の弱点をスキャン
`explain_vulnerability`	詳細な脆弱性の説明を取得
`suggest_fix`	検出結果に対する修復提案を取得

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

ツール	説明
`generate_sbom`	SBOMを生成 (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_repo`	GitHubリポジトリをクローンしてインデックス化
`list_remote_files`	GitHub API経由でファイルを一覧表示
`get_remote_file`	GitHub API経由でファイルを取得

メトリクス

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

SPARQL / ナレッジグラフ (`--graph`が必要)

ツール	説明
`sparql_query`	RDFナレッジグラフに対して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_ccg`	SPARQLを使用してCCGをクエリ
`get_ccg_acl`	CCGレイヤーのWebACLアクセス制御を生成
`get_ccg_access_info`	CCGアクセス層情報を取得
`import_ccg`	URLまたはファイルからCCGレイヤーをインポート
`import_ccg_from_registry`	codecontextgraph.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 KB	131 µs	1.98 GiB/s
Rust (中規模ファイル)	27 KB	13.5 µs	1.89 GiB/s
Python	~4 KB	16.7 µs	-
TypeScript	~5 KB	13.9 µs	-
混合 (5ファイル)	~15 KB	57 µ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 (このリポジトリ)	53	1,733	220 ms	~50 MB
rust-analyzer	2,847	~50K	2.1s	89 MB
Linux カーネル	78,000+	~500K	45s	2.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 が渡されなかったことを意味します

ロードマップ

完了

ライセンス

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

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 - シリアライゼーション