Narsil MCP

ทางการ

เซิร์ฟเวอร์ MCP ที่เร็วที่สุด 🔥 ระดับแนวหน้าใน Rust 🦀 พร้อมนิวรัลเอนจิน การวิเคราะห์ความปลอดภัย และส่วนหน้าสำหรับกราฟแบบเลือกใช้ได้

GitHub
185

คุณทำอะไรได้บ้างด้วย Narsil MCP?

  • สำรวจโค้ดเบส — ให้ผู้ช่วยของคุณแมปโปรเจกต์ที่ไม่คุ้นเคย ค้นหาสัญลักษณ์ และติดตามการอ้างอิงใน 32 ภาษาโดยใช้ find_symbols และ find_references

  • วิเคราะห์ช่องโหว่ด้านความปลอดภัย — ขอการวิเคราะห์ taint, การสแกน OWASP Top 10 หรือการตรวจสอบ CWE เพื่อระบุจุดที่อาจถูกโจมตีและรับคำแนะนำในการแก้ไขผ่าน scan_security และ suggest_fix

  • ติดตามความสัมพันธ์ของฟังก์ชัน — แสดงภาพ call graphs ค้นหา callers/callees หรือค้นหาเส้นทางระหว่างฟังก์ชันเพื่อทำความเข้าใจการไหลของการทำงานด้วย get_call_graph และ find_call_path

  • ตรวจสอบความเสี่ยงในซัพพลายเชน — สร้าง SBOM ตรวจสอบ dependencies กับ OSV และยืนยันการปฏิบัติตามข้อกำหนดด้านลิขสิทธิ์โดยใช้ generate_sbom, check_dependencies และ check_licenses

  • ตรวจจับปัญหาคุณภาพโค้ด — ระบุ dead code, ตัวแปรที่ไม่ได้รับการกำหนดค่า หรือ type mismatches ใน Python, JavaScript และ TypeScript ด้วย find_dead_code และ check_type_errors

เอกสาร

narsil-mcp

เซิร์ฟเวอร์ MCP ที่รวดเร็วเป็นพิเศษและให้ความสำคัญกับความเป็นส่วนตัว สำหรับการวิเคราะห์โค้ดเชิงลึก

License Rust Tests MCP

เซิร์ฟเวอร์ MCP (Model Context Protocol) ที่พัฒนาด้วย Rust ซึ่งมอบความเข้าใจโค้ดเชิงลึกให้กับผู้ช่วย AI ผ่านเครื่องมือเฉพาะทาง 90 รายการ

ทำไมต้อง narsil-mcp?

คุณสมบัติnarsil-mcpXRAYSerenaGitHub MCP
ภาษา32430+ (LSP)N/A
การค้นหาแบบ Neuralมีไม่มีไม่มีไม่มี
การวิเคราะห์ Taintมีไม่มีไม่มีไม่มี
SBOM/ใบอนุญาตมีไม่มีไม่มีบางส่วน
ออฟไลน์/ภายในเครื่องมีมีมีไม่มี
WASM/เบราว์เซอร์มีไม่มีไม่มีไม่มี
กราฟการเรียกใช้มีบางส่วนไม่มีไม่มี
การอนุมานชนิดข้อมูลมีไม่มีไม่มีไม่มี

คุณสมบัติหลัก

  • ความฉลาดด้านโค้ด - การแยกสัญลักษณ์, การค้นหาเชิงความหมาย, การวิเคราะห์กราฟการเรียกใช้
  • การค้นหาเชิงความหมายแบบ Neural - ค้นหาโค้ดที่คล้ายกันโดยใช้ embeddings (Voyage AI, OpenAI)
  • การวิเคราะห์ความปลอดภัย - การวิเคราะห์ Taint, การสแกนหาช่องโหว่, ความครอบคลุม OWASP/CWE
  • ความปลอดภัยของซัพพลายเชน - การสร้าง SBOM, การตรวจสอบ dependencies, การปฏิบัติตามใบอนุญาต
  • การวิเคราะห์ขั้นสูง - กราฟควบคุมการไหล, การวิเคราะห์การไหลของข้อมูล, การตรวจจับโค้ดที่ตายแล้ว

ทำไมต้องเลือก narsil-mcp?

  • เขียนด้วย Rust - รวดเร็วเป็นพิเศษ, ปลอดภัยด้านหน่วยความจำ, ไบนารีไฟล์เดียว (~30MB)
  • ขับเคลื่อนด้วย Tree-sitter - การแยกวิเคราะห์แบบเพิ่มหน่วยที่แม่นยำสำหรับ 32 ภาษา
  • ไม่ต้องตั้งค่า - ชี้ไปที่ repositories แล้วเริ่มใช้งานได้เลย
  • รองรับ MCP - ทำงานร่วมกับ Claude, Cursor, VS Code Copilot, Zed และไคลเอนต์ MCP ใดๆ
  • ให้ความสำคัญกับความเป็นส่วนตัว - ทำงานภายในเครื่องทั้งหมด ไม่มีข้อมูลใดออกจากเครื่องของคุณ
  • การจัดทำดัชนีแบบขนาน - ใช้ทุกคอร์ผ่าน Rayon
  • ข้อความตัวอย่างอัจฉริยะ - ขยายไปยังขอบเขตไวยากรณ์ที่สมบูรณ์
  • ความปลอดภัยเป็นอันดับแรก - การตรวจจับช่องโหว่และการวิเคราะห์ Taint ในตัว
  • Neural embeddings - การค้นหาเชิงความหมายเสริมด้วย Voyage AI หรือ OpenAI
  • รองรับ WASM - ทำงานในเบราว์เซอร์ด้วยบิลด์ WebAssembly
  • สตรีมมิ่งแบบเรียลไทม์ - ผลลัพธ์แสดงขณะจัดทำดัชนีสำหรับ repositories ขนาดใหญ่

ภาษาที่รองรับ

ภาษานามสกุลไฟล์สัญลักษณ์ที่แยก
Rust.rsfunctions, structs, enums, traits, impls, mods
Python.py, .pyifunctions, classes
JavaScript.js, .jsx, .mjsfunctions, classes, methods, variables
TypeScript.ts, .tsxfunctions, classes, interfaces, types, enums
Go.gofunctions, methods, types
C.c, .hfunctions, structs, enums, typedefs
C++.cpp, .cc, .hppfunctions, classes, structs, namespaces
Java.javamethods, classes, interfaces, enums
C#.csmethods, classes, interfaces, structs, enums, delegates, namespaces
Bash.sh, .bash, .zshfunctions, variables
Ruby.rb, .rake, .gemspecmethods, classes, modules
Kotlin.kt, .ktsfunctions, classes, objects, interfaces
PHP.php, .phtmlfunctions, methods, classes, interfaces, traits
Swift.swiftclasses, structs, enums, protocols, functions
Verilog/SystemVerilog.v, .vh, .sv, .svhmodules, tasks, functions, interfaces, classes
Scala.scala, .scclasses, objects, traits, functions, vals
Lua.luafunctions, methods
Haskell.hs, .lhsfunctions, data types, type classes
Elixir.ex, .exsmodules, functions
Clojure.clj, .cljs, .cljc, .ednlists (basic AST)
Dart.dartfunctions, classes, methods
Julia.jlfunctions, modules, structs
R.R, .r, .Rmdfunctions
Perl.pl, .pm, .tfunctions, packages
Zig.zigfunctions, variables
Erlang.erl, .hrlfunctions, modules, records
Elm.elmfunctions, types
Fortran.f90, .f95, .f03, .f08, .f, .for, .fppprograms, subroutines, functions, modules
PowerShell.ps1, .psm1, .psd1functions, classes, enums
Nix.nixbindings
Groovy.groovy, .gradlemethods, classes, interfaces, enums, functions

การติดตั้ง

ผ่านตัวจัดการแพ็กเกจ (แนะนำ)

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 ให้อัตโนมัติและตรวจสอบเครื่องมือ build ที่จำเป็นหากต้องการ build จากซอร์สโค้ด

จากซอร์สโค้ด

ข้อกำหนดเบื้องต้น:

  • Rust เวอร์ชันเสถียรปัจจุบัน (รีลีสนี้ตรวจสอบกับ Rust 1.98 และ 1.99)
  • บน Windows: Visual Studio Build Tools พร้อม "Desktop development with 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+ UI เว็บการแสดงภาพในตัว~31MB
neural+ การค้นหาเวกเตอร์ TF-IDF, API embeddings~32MB
neural-onnx+ การอนุมานโมเดล ONNX ในเครื่อง~50MB
wasmบิลด์ซอร์สเบราว์เซอร์ทดลอง (ไม่มีระบบไฟล์, git)ยังไม่ผ่านการรับรองสำหรับรีลีส

สำคัญ: แฟล็ก CLI --graph ต้องใช้ไบนารีที่ build ด้วย --features graph หากคุณส่ง --graph ให้กับไบนารีที่ build โดยไม่มีคุณสมบัตินี้ คุณจะเห็นคำเตือนและเครื่องมือ 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) แต่ เฉพาะเมื่อไบนารีถูก build ด้วย --features graph เท่านั้น ไบนารีค่าเริ่มต้นไม่รวมคุณสมบัตินี้ หากคุณต้องการความสามารถ SPARQL/CCG ให้ build จากซอร์สโค้ดด้วย:

cargo build --release --features graph

หากคุณส่ง --graph ให้กับไบนารีที่ไม่มีคุณสมบัตินี้ คุณจะเห็นคำเตือนเมื่อเริ่มต้นและเซิร์ฟเวอร์จะทำงานต่อไปโดยไม่มีเครื่องมือ SPARQL/CCG

หมายเหตุ: Neural embeddings ต้องใช้คีย์ API (หรือ endpoint ที่กำหนดเอง) วิธีที่ง่ายที่สุดในการตั้งค่าคือใช้วิซาร์ดแบบโต้ตอบ:

# 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 - คีย์ API เฉพาะ Voyage AI
  • OPENAI_API_KEY - คีย์ API เฉพาะ OpenAI
  • EMBEDDING_SERVER_ENDPOINT - URL endpoint embedding แบบกำหนดเอง (ไม่บังคับ อนุญาตให้ใช้โมเดลที่โฮสต์เอง)

การกำหนดค่า

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 ตรวจจับโปรแกรมแก้ไขของคุณและใช้ค่าที่ตั้งไว้ล่วงหน้าที่เหมาะสมที่สุดโดยอัตโนมัติ:

โปรแกรมแก้ไขค่าที่ตั้งไว้เครื่องมือContext Tokensเหตุผล
ZedMinimal26~4,686เริ่มต้นเร็ว, ใช้ context น้อยที่สุด
VS CodeBalanced51~8,948ความสมดุลของคุณสมบัติที่ดี
Claude DesktopFull90~12,001ความสามารถสูงสุด

การประหยัด Token:

  • ค่าที่ตั้งไว้ Minimal: ประหยัด token 61% เทียบกับ Full
  • ค่าที่ตั้งไว้ Balanced: ประหยัด token 25% เทียบกับ Full

ค่าที่ตั้งไว้ล่วงหน้า

เลือกค่าที่ตั้งไว้ตามกรณีการใช้งานของคุณ:

# 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 ในรากของ repo):

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

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

โปรไฟล์ repository ที่มีชื่อ มีประโยชน์สำหรับเวิร์กสเปซหลาย repo:

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

เรียนรู้เพิ่มเติม:

ส่วนติดต่อผู้ใช้การแสดงภาพ

สำรวจกราฟการเรียกใช้, imports, การอ้างอิงสัญลักษณ์ และการควบคุมการไหลแบบโต้ตอบในเบราว์เซอร์ของคุณ

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

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

มุมมองกราฟห้าแบบ:

มุมมองคำอธิบาย
Call Graphความสัมพันธ์การเรียกใช้ฟังก์ชันพร้อมการควบคุมความลึกและการกรองทิศทาง
Import Graphการพึ่งพา import ระดับไฟล์ทั่วทั้งโค้ดเบส
Symbol Graphการอ้างอิงทั้งหมดของสัญลักษณ์ พร้อมการจัดกลุ่มไฟล์
Hybridกราฟการเรียกใช้ + import รวมกันพร้อมงบประมาณแบบแยก
Control FlowCFG จริงพร้อมบล็อกพื้นฐาน, สาขา และ back-edges ของลูป

คุณสมบัติ:

  • กราฟ Cytoscape.js แบบโต้ตอบพร้อมการลาก, ซูม และการเจาะลึกด้วยการดับเบิลคลิก
  • การแสดงความซับซ้อนซ้อนทับพร้อมรหัสสี (เขียว/เหลือง/ส้ม/แดง)
  • การแสดงช่องโหว่ความปลอดภัยซ้อนทับที่เน้น taint sources และ sinks
  • อัลกอริทึมการจัดวางหกแบบ (dagre, force-directed, breadthfirst, concentric, circle, grid)
  • แถบด้านข้างแผนผังไฟล์พร้อมตัวแสดงโค้ดที่เน้นไวยากรณ์
  • สถานะที่ขับเคลื่อนด้วย URL (ลิงก์ที่แชร์ได้, ปุ่มย้อนกลับ/ไปข้างหน้าของเบราว์เซอร์)
  • รองรับโหมดมืด
  • แผงรายละเอียดโหนดพร้อมตัวอย่างโค้ดและการนำทางไปยังซอร์ส

เอกสารเต็มรูปแบบ: ดู docs/frontend.md สำหรับการตั้งค่า, API endpoints และโหมดการพัฒนา

การค้นหาเชิงความหมายแบบ Neural

ค้นหาโค้ดที่คล้ายกันโดยใช้ neural embeddings - แม้ว่าชื่อตัวแปรและโครงสร้างจะแตกต่างกัน

# 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, endpoints แบบกำหนดเอง และโมเดล ONNX ในเครื่อง

เอกสารเต็มรูปแบบ: ดู docs/neural-search.md สำหรับการตั้งค่า, backends และกรณีการใช้งาน

การอนุมานชนิดข้อมูล

การอนุมานชนิดข้อมูลในตัวสำหรับ 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 (ทดลอง)

สำหรับเวิร์กโฟลว์ agentic ขนาดใหญ่ narsil-mcp สามารถใช้งานผ่าน Forgemax — เกตเวย์ MCP โหมด Code ที่รวมเครื่องมือทั้งหมด 90 รายการเป็นเพียง 2 รายการ (search + execute) ลดค่าใช้จ่าย schema เครื่องมือจาก ~12,000 token เป็น ~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 เขียน JavaScript ที่เรียกผ่านออบเจกต์พร็อกซีแบบมีชนิดภายใน V8 isolate ที่อยู่ในแซนด์บ็อกซ์ — ข้อมูลประจำตัว เส้นทางไฟล์ และสถานะภายในไม่เคยออกจากโฮสต์ แนวทางนี้มีประโยชน์อย่างยิ่งเมื่อทำงานกับเซิร์ฟเวอร์ MCP หลายตัวพร้อมกัน เนื่องจากช่วยให้บริบทเครื่องมือทั้งหมดมีขนาดเล็กและคาดเดาได้

การกำหนดค่า MCP

เพิ่ม narsil-mcp ให้กับผู้ช่วย AI ของคุณโดยสร้างไฟล์กำหนดค่า นี่คือการตั้งค่าที่แนะนำ:

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 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 เรามีปลั๊กอินพร้อมคำสั่งสแลชและทักษะสำหรับการใช้เครื่องมืออย่างมีประสิทธิภาพ

ติดตั้งผ่าน Marketplace (แนะนำ):

# 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วิเคราะห์ความปลอดภัยของซัพพลายเชน
ทักษะแนะนำ Claude ในการใช้เครื่องมือ 90 รายการอย่างมีประสิทธิภาพ
การกำหนดค่า MCPเริ่ม narsil-mcp อัตโนมัติพร้อมค่าเริ่มต้นที่เหมาะสม

ดู narsil-plugin/README.md สำหรับเอกสารฉบับเต็ม

การผสานรวม Ralph Automation

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 สำหรับคู่มือการใช้งานจริง:

คู่มือคำอธิบาย
Getting Startedการตั้งค่าด่วนและการเรียกเครื่องมือครั้งแรก
Understand a Codebaseสำรวจโปรเจกต์ที่ไม่คุ้นเคย
Fix a Bugแก้จุดบกพร่องด้วยกราฟการเรียกและการวิเคราะห์ taint
Security Auditค้นหาช่องโหว่ด้วยการสแกน OWASP/CWE
Code Reviewตรวจสอบการเปลี่ยนแปลงอย่างมีประสิทธิภาพ

เพลย์บุ๊กแต่ละรายการแสดงห่วงโซ่เครื่องมือที่แน่นอนที่ Claude ใช้เพื่อตอบคำถามของคุณ

การใช้งาน WebAssembly (เบราว์เซอร์)

พื้นที่เก็บข้อมูลมีซอร์ส WebAssembly ทดลองและสคริปต์สร้างในเครื่อง @narsil-mcp/wasm ไม่ได้เผยแพร่บน npm และไม่ใช่ช่องทางการเผยแพร่สำหรับ เวอร์ชัน CLI 1.7.1 การสร้าง WASM และตัวอย่างไม่ครอบคลุมในการรับรองคุณภาพการเผยแพร่ ดู docs/wasm.md สำหรับขั้นตอนการทำงานซอร์สทดลอง

เครื่องมือที่มีอยู่ (93)

การจัดการพื้นที่เก็บข้อมูลและไฟล์

เครื่องมือคำอธิบาย
list_reposแสดงรายการพื้นที่เก็บข้อมูลที่จัดทำดัชนีทั้งหมดพร้อมข้อมูลเมตา
get_project_structureรับโครงสร้างไดเรกทอรีพร้อมไอคอนไฟล์และขนาด
get_fileรับเนื้อหาไฟล์พร้อมช่วงบรรทัดที่เลือกได้
get_excerptแยกโค้ดรอบบรรทัดเฉพาะพร้อมบริบท
reindexเรียกใช้การจัดทำดัชนีพื้นที่เก็บข้อมูลใหม่
discover_reposค้นพบพื้นที่เก็บข้อมูลอัตโนมัติในไดเรกทอรี
validate_repoตรวจสอบว่าเส้นทางเป็นพื้นที่เก็บข้อมูลที่ถูกต้องหรือไม่
get_index_statusแสดงสถิติดัชนีและฟีเจอร์ที่เปิดใช้งาน

การค้นหาและการนำทางสัญลักษณ์

เครื่องมือคำอธิบาย
find_symbolsค้นหา struct, class, ฟังก์ชันตามชนิด/รูปแบบ
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ค้นหาเส้นทางระหว่างสองฟังก์ชัน
get_complexityรับความซับซ้อน cyclomatic/cognitive
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การวิเคราะห์ taint ที่ปรับปรุงรวมการไหลของข้อมูลกับการอนุมานชนิด

กราฟการนำเข้า/การพึ่งพา

เครื่องมือคำอธิบาย
get_import_graphสร้างและวิเคราะห์กราฟการนำเข้า
find_circular_importsตรวจจับการพึ่งพาแบบวงจร
get_incremental_statusMerkle tree และสถิติการเปลี่ยนแปลง

การวิเคราะห์ความปลอดภัย - การติดตาม Taint

เครื่องมือคำอธิบาย
find_injection_vulnerabilitiesค้นหา SQL injection, XSS, command injection, path traversal
trace_taintติดตามการไหลของข้อมูลที่ปนเปื้อนจากแหล่งที่มา
get_taint_sourcesแสดงรายการแหล่ง taint (อินพุตผู้ใช้, ไฟล์, เครือข่าย)
get_security_summaryการประเมินความเสี่ยงด้านความปลอดภัยอย่างครอบคลุม

การวิเคราะห์ความปลอดภัย - เอ็นจินกฎ

เครื่องมือคำอธิบาย
scan_securityสแกนด้วยกฎความปลอดภัย (OWASP, CWE, crypto, secrets)
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_blameGit blame สำหรับไฟล์
get_file_historyประวัติคอมมิตสำหรับไฟล์
get_recent_changesคอมมิตล่าสุดในพื้นที่เก็บข้อมูล
get_hotspotsไฟล์ที่มีการเปลี่ยนแปลงสูงและความซับซ้อนสูง
get_contributorsผู้มีส่วนร่วมในพื้นที่เก็บข้อมูล/ไฟล์
get_commit_diffDiff สำหรับคอมมิตเฉพาะ
get_symbol_historyคอมมิตที่เปลี่ยนสัญลักษณ์
get_branch_infoสาขาปัจจุบันและสถานะ
get_modified_filesการเปลี่ยนแปลงใน working tree

การผสานรวม 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 / Knowledge Graph (ต้องใช้ --graph)

เครื่องมือคำอธิบาย
sparql_queryรันคิวรี SPARQL กับกราฟความรู้ RDF
list_sparql_templatesแสดงรายการเทมเพลตคิวรี SPARQL ที่มีอยู่
run_sparql_templateรันเทมเพลต SPARQL ที่กำหนดไว้ล่วงหน้าพร้อมพารามิเตอร์

กราฟบริบทโค้ด (CCG) (ต้องใช้ --graph)

CCG ให้การแสดงโค้ดเบสที่ได้มาตรฐานและใช้โดย AI ได้ในชั้นแบบลำดับชั้น

เครื่องมือคำอธิบาย
get_ccg_manifestแถลงการณ์ Layer 0 (~1-2KB JSON-LD) - ข้อมูลประจำตัวพื้นที่เก็บข้อมูล, จำนวน
export_ccg_manifestส่งออกแถลงการณ์ Layer 0 ไปยังไฟล์
export_ccg_architectureสถาปัตยกรรม Layer 1 (~10-50KB JSON-LD) - โมดูล, API
export_ccg_indexดัชนีสัญลักษณ์ Layer 2 (~100-500KB N-Quads บีบอัด)
export_ccg_fullรายละเอียดเต็ม Layer 3 (~1-20MB N-Quads บีบอัด)
export_ccgส่งออกชั้น CCG ทั้งหมดเป็นชุด
query_ccgคิวรี CCG โดยใช้ SPARQL
get_ccg_aclสร้างการควบคุมการเข้าถึง WebACL สำหรับชั้น CCG
get_ccg_access_infoรับข้อมูลระดับการเข้าถึง CCG
import_ccgนำเข้าชั้น CCG จาก URL หรือไฟล์
import_ccg_from_registryนำเข้า CCG จากรีจิสทรี codecontextgraph.com

กฎความปลอดภัย

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, command injection, TOCTOU)
  • elixir.yaml - รูปแบบ Elixir/BEAM (atom exhaustion, binary_to_term, Code.eval, Ecto SQL injection)
  • go.yaml - รูปแบบความปลอดภัยของ Go (SQL injection, TLS, command injection)
  • java.yaml - ช่องโหว่ของ Java (XXE, deserialization, LDAP injection)
  • csharp.yaml - ปัญหาความปลอดภัยของ C# (deserialization, XSS, path traversal)
  • kotlin.yaml - รูปแบบ Kotlin/Android (WebView, intents, secrets)
  • bash.yaml - ช่องโหว่ของ Shell script (command injection, 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-IDF1,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 สำหรับคำค้นหาส่วนใหญ่
  • การค้นหาแบบไฮบริดรัน BM25 + TF-IDF แบบขนานผ่าน rayon

การพัฒนา

# 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 การค้นหาแบบ Neural

# 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 เพิ่มฐานข้อมูล RDF ของ Oxigraph (ขนาดไบนารีเพิ่มเติม ~5MB) ซึ่งไม่จำเป็นสำหรับกรณีการใช้งานส่วนใหญ่ จึงถูกเก็บเป็นตัวเลือกเพื่อให้ไบนารีเริ่มต้นมีขนาดเล็กลง

วิธีตรวจสอบว่ากราฟเปิดใช้งานหรือไม่: ดูที่บันทึกการเริ่มต้น:

  • graph=true หมายความว่าฟีเจอร์ถูกคอมไพล์และเปิดใช้งาน
  • graph=false หมายความว่าฟีเจอร์ไม่ได้ถูกคอมไพล์ หรือไม่ได้ส่ง --graph

แผนงาน

เสร็จสมบูรณ์

  • การแยกสัญลักษณ์หลายภาษา (32 ภาษา)
  • การค้นหาข้อความเต็มด้วย Tantivy (การจัดอันดับ BM25)
  • การค้นหาแบบไฮบริด (BM25 + TF-IDF พร้อม RRF)
  • การแบ่งโค้ดที่รับรู้ AST
  • การรวม Git blame/history
  • การวิเคราะห์ call graph พร้อมตัวชี้วัดความซับซ้อน
  • การวิเคราะห์ control flow graph (CFG)
  • การวิเคราะห์ data flow (DFG) พร้อม reaching definitions
  • การตรวจจับ dead code และ dead store
  • การวิเคราะห์ taint สำหรับช่องโหว่การฉีด
  • เอ็นจินกฎความปลอดภัย (OWASP, CWE, crypto, secrets)
  • การสร้าง SBOM (CycloneDX, SPDX)
  • การตรวจสอบช่องโหว่ของ dependency (OSV)
  • การวิเคราะห์ความสอดคล้องของใบอนุญาต
  • import graph พร้อมการตรวจจับ circular dependency
  • การแก้ไขสัญลักษณ์ข้ามภาษา
  • การจัดทำดัชนีแบบเพิ่มหน่วยด้วย Merkle trees
  • การคงอยู่ของดัชนี
  • โหมดเฝ้าดูการเปลี่ยนแปลงไฟล์
  • การรวม LSP
  • การสนับสนุนที่เก็บระยะไกล
  • การตอบสนองแบบสตรีมมิ่ง

มีอะไรใหม่

v1.6.x (ปัจจุบัน)

  • การแบ่งโค้ดที่ป้องกันการขัดข้อง - แก้ไขการตัดสตริงระดับไบต์ที่ไม่ปลอดภัยใน chunk_file() และ extract_signature() ซึ่งทำให้ hybrid_search, search_chunks และ get_chunk_stats ขัดข้องเมื่อประมวลผลไฟล์ที่มีอักขระ UTF-8 หลายไบต์ (emoji, CJK, อักขระที่มีเครื่องหมาย) การตัดไบต์ทั้งหมดตอนนี้ใช้ content.get() ที่ปลอดภัยพร้อม fallback
  • การเรียงลำดับที่ปลอดภัย NaN - แก้ไข 5 ตำแหน่งในโมดูล search, embeddings, git, index และ extract ที่ partial_cmp().unwrap() จะ panic กับค่า NaN float การเรียงลำดับทั้งหมดตอนนี้ใช้ unwrap_or(Ordering::Equal)
  • การแบ่งโค้ดแบบ Defense-in-depth - เพิ่ม wrapper catch_unwind รอบลูป chunk_file() ทั่วทั้งที่เก็บ เพื่อให้ panic ในไฟล์หนึ่งข้ามไฟล์นั้นแทนที่จะทำให้เซิร์ฟเวอร์ MCP ทั้งหมดขัดข้อง
  • การยกเครื่อง frontend การแสดงภาพ - SPA เต็มรูปแบบพร้อมการกำหนดเส้นทาง HashRouter, แถบด้านข้างแผนผังไฟล์, โปรแกรมดูโค้ดที่เน้นไวยากรณ์, แดชบอร์ด และหน้าภาพรวมต่อที่เก็บ
  • ประสิทธิภาพมุมมองกราฟ - import graph ตอนนี้ใช้ข้อมูลดัชนีที่แคชแทนการเดินระบบไฟล์; symbol graph วนซ้ำแคชไฟล์โดยตรงแทนการไปกลับ markdown; ทุกมุมมองเคารพ max_nodes สำหรับการสิ้นสุดก่อนกำหนด
  • control flow graphs จริง - มุมมอง Flow ตอนนี้ใช้ตัวสร้าง CFG จริง (cfg::analyze_function) พร้อม basic blocks, เงื่อนไขสาขา และ loop back-edges ที่เหมาะสมแทน stub บล็อกเดียว
  • การแบ่งงบประมาณกราฟไฮบริด - มุมมองไฮบริดจัดสรรงบประมาณโหนด 60/40 ระหว่าง call และ import graphs เพื่อผลลัพธ์ที่สมดุล
  • แก้ไข #14: ขนาด embedding ที่กำหนดค่าได้ - เพิ่มอาร์กิวเมนต์ CLI --neural-dimension และการค้นหา default_dimension_for_model() เพื่อให้โมเดลเช่น text-embedding-3-large ใช้ขนาดที่ถูกต้อง (3072) แทน 1536 ที่ฮาร์ดโค้ด
  • แก้ไข #13: การสร้าง frontend Nix - เพิ่ม derivation frontendDist ใน flake.nix โดยใช้ buildNpmPackage เพื่อให้ nix profile install github:postrv/narsil-mcp#with-frontend ทำงาน
  • กฎความปลอดภัย Rust - 18 กฎใหม่ (RUST-004 ถึง RUST-021) ครอบคลุม command injection, transmute, ขอบเขต FFI, TOCTOU, ReDoS, static mut, SSRF และอื่นๆ
  • กฎความปลอดภัย Elixir - 18 กฎใหม่ (EX-001 ถึง EX-018) ครอบคลุม atom exhaustion, binary_to_term deserialization, Code.eval injection, Ecto SQL injection, Phoenix XSS, ความปลอดภัยการกระจาย Erlang
  • ย้ายจาก serde_yaml เป็น serde-saphyr - เลิกใช้ serde_yaml แทนที่ด้วยไลบรารี YAML ที่ดูแลรักษาอย่างแข็งขันและไม่มี panic
  • favicon ที่กำหนดเอง - frontend ตอนนี้ใช้ไอคอนแบรนด์ narsil-mcp แทนโลโก้ Vite เริ่มต้น
  • ความปลอดภัยของ dependency - อัปเดต time เป็น 0.3.47 (RUSTSEC-2026-0009), bytes เป็น 1.11.1 (RUSTSEC-2026-0007)
  • จำนวนการทดสอบ เพิ่มขึ้นจาก 1,611 เป็น 1,763 (+152 การทดสอบ)

v1.5.x

  • การแก้ไข call graph แบบกำหนด - การแพร่กระจายคำใบ้ขอบเขตแยกแยะการแก้ไข callee (เช่น App::run() แก้ไขเป็น src/app/mod.rs::run อย่างถูกต้อง)
  • การแก้ไขการวิเคราะห์กราฟ 8 รายการ - คีย์โหนดที่ผ่านการรับรอง, การกรอง hotspot, การจัดการนิพจน์ CFG, การแยกวิเคราะห์เส้นทาง import
  • การปรับปรุง Nix flake - helper mkPkg แบบ DRY, ลบ macOS frameworks ที่ไม่จำเป็น, กลยุทธ์การทดสอบ --lib สำหรับบิลด์ sandbox

v1.4.x

  • SPARQL / RDF Knowledge Graph - ค้นหาข้อมูลความฉลาดของโค้ดด้วย SPARQL ผ่าน Oxigraph
  • Code Context Graph (CCG) - 12 เครื่องมือสำหรับการแสดงที่เก็บโค้ดที่ได้มาตรฐานและ AI บริโภคได้พร้อมเลเยอร์แบบชั้น (L0-L3)
  • การวิเคราะห์ความปลอดภัยที่รับรู้ประเภท - การติดตาม taint ที่ปรับปรุงด้วยการอนุมานประเภทและการใช้งาน trait
  • CFG/DFG หลายภาษา - การวิเคราะห์ control flow และ data flow ขยายไปยัง Go, Java, C#, Kotlin
  • การสแกน Infrastructure as Code - กฎ iac.yaml ใหม่สำหรับ Terraform, CloudFormation, Kubernetes
  • กฎความปลอดภัยเฉพาะภาษา - กฎใหม่สำหรับ Go, Java, C#, Kotlin, Bash
  • 6 ภาษาใหม่ - Erlang, Elm, Fortran, PowerShell, Nix, Groovy
  • รวม 90 เครื่องมือ - เพิ่มขึ้นจาก 79 ด้วยความสามารถ SPARQL, CCG และการวิเคราะห์ใหม่

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

  • การค้นหาเชิงความหมายแบบ Neural - ค้นหาโค้ดที่คล้ายกันโดยใช้ embeddings ของ Voyage AI หรือ OpenAI
  • การอนุมานประเภท - อนุมานประเภทใน Python/JavaScript/TypeScript โดยไม่ต้องใช้เครื่องมือภายนอก
  • การวิเคราะห์ taint หลายภาษา - การสแกนความปลอดภัยสำหรับ PHP, Java, C#, Ruby, Kotlin
  • บิลด์ WASM - รันในเบราว์เซอร์สำหรับสนามเด็กเล่นโค้ดและเครื่องมือการศึกษา
  • กฎความปลอดภัยที่รวม 147 รายการ - การตรวจจับ OWASP, CWE, crypto, secrets, Rust, Elixir
  • รวมการกำหนดค่า IDE - เทมเพลต Claude Desktop, Cursor, VS Code, Zed

ใบอนุญาต

ได้รับอนุญาตภายใต้อย่างใดอย่างหนึ่ง:

ตามที่คุณเลือก

เครดิต

สร้างด้วย:

  • tree-sitter - การแยกวิเคราะห์แบบเพิ่มหน่วย
  • tantivy - การค้นหาข้อความเต็ม
  • tokio - รันไทม์แบบอะซิงโครนัส
  • rayon - ความขนานของข้อมูล
  • serde - การทำให้เป็นอนุกรม