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를 사용하여 라이선스 준수를 검증하세요.

  • 코드 품질 문제 감지 — find_dead_code 및 check_type_errors로 Python, JavaScript 및 TypeScript에서 죽은 코드, 초기화되지 않은 변수 또는 유형 불일치를 식별하세요.

문서

narsil-mcp

코드 인텔리전스를 위한 초고속, 프라이버시 우선 MCP 서버

License Rust Tests MCP

Rust로 구동되는 MCP(Model Context Protocol) 서버로, 90개의 특화된 도구를 통해 AI 어시스턴트에게 깊이 있는 코드 이해를 제공합니다.

narsil-mcp를 선택해야 하는 이유는?

기능narsil-mcpXRAYSerenaGitHub MCP
언어32430+ (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클래스, 객체, 트레이트, 함수, 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+ 내장 시각화 웹 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

다섯 가지 그래프 보기:

보기설명
호출 그래프깊이 제어 및 방향 필터링이 있는 함수 호출 관계
임포트 그래프코드베이스 전반의 파일 수준 임포트 의존성
심볼 그래프파일 클러스터링이 있는 심볼에 대한 모든 참조
하이브리드분할 예산이 있는 결합 호출 + 임포트 그래프
제어 흐름기본 블록, 분기 및 루프 백엣지가 있는 실제 CFG

기능:

  • 드래그, 확대/축소 및 더블클릭 드릴다운이 가능한 대화형 Cytoscape.js 그래프
  • 색상 코딩(녹색/노란색/주황색/빨간색)이 있는 복잡성 메트릭 오버레이
  • 오염 소스와 싱크를 강조하는 보안 취약점 오버레이
  • 여섯 가지 레이아웃 알고리즘 (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을 통해 사용할 수 있습니다 — 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_path두 함수 사이의 경로 찾기
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_statusMerkle 트리 및 변경 통계

보안 분석 - 오염 추적

도구설명
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특정 커밋에 대한 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 gzipped)
export_ccg_full레이어 3 전체 세부 정보 (~1-20MB N-Quads gzipped)
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 - 코드형 인프라 (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 커널78,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, 인덱스 및 추출 모듈 전반에 걸쳐 NaN 부동 소수점 값에서 partial_cmp().unwrap()이 패닉을 일으키는 5개 위치를 수정했습니다. 모든 정렬은 이제 unwrap_or(Ordering::Equal)을 사용합니다.
  • 심층 방어 청킹 - 저장소 전체 chunk_file() 루프 주위에 catch_unwind 래퍼를 추가하여 한 파일의 패닉이 MCP 서버 전체를 충돌시키는 대신 해당 파일을 건너뜁니다.
  • 시각화 프론트엔드 개편 - HashRouter 라우팅, 파일 트리 사이드바, 구문 강조 코드 뷰어, 대시보드 및 저장소별 개요 페이지를 갖춘 완전한 SPA
  • 그래프 뷰 성능 - 가져오기 그래프는 이제 파일 시스템 탐색 대신 캐시된 인덱스 데이터를 사용합니다. 심볼 그래프는 마크다운 왕복 대신 파일 캐시를 직접 반복합니다. 모든 뷰는 조기 종료를 위해 max_nodes을 존중합니다.
  • 실제 제어 흐름 그래프 - 흐름 뷰는 이제 단일 블록 스텁 대신 적절한 기본 블록, 분기 조건 및 루프 백엣지가 있는 실제 CFG 빌더(cfg::analyze_function)를 사용합니다.
  • 하이브리드 그래프 예산 분할 - 하이브리드 뷰는 균형 잡힌 결과를 위해 호출 그래프와 가져오기 그래프 간에 60/40 노드 예산을 할당합니다.
  • Fix #14: 구성 가능한 임베딩 차원 - --neural-dimension CLI 인수 및 default_dimension_for_model() 조회를 추가하여 text-embedding-3-large과 같은 모델이 하드코딩된 1536 대신 올바른 차원(3072)을 사용하도록 했습니다.
  • Fix #13: Nix 프론트엔드 빌드 - nix profile install github:postrv/narsil-mcp#with-frontend이 작동하도록 buildNpmPackage을 사용하여 flake.nix에 frontendDist 파생을 추가했습니다.
  • 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 flake 개선 - DRY mkPkg 헬퍼, 불필요한 macOS 프레임워크 제거, 샌드박스 빌드를 위한 --lib 테스트 전략.

v1.4.x

  • SPARQL / RDF 지식 그래프 - Oxigraph를 통해 SPARQL로 코드 인텔리전스 데이터를 쿼리합니다.
  • 코드 컨텍스트 그래프 (CCG) - 계층화된 레이어(L0-L3)를 갖춘 표준화된 AI 소비 가능 코드베이스 표현을 위한 12개 도구.
  • 유형 인식 보안 분석 - 유형 추론 및 특성 구현을 통한 향상된 오염 추적.
  • 다중 언어 CFG/DFG - 제어 흐름 및 데이터 흐름 분석을 Go, Java, C#, Kotlin으로 확장했습니다.
  • 코드형 인프라 스캐닝 - 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 템플릿.

라이선스

다음 중 하나에 따라 라이선스가 부여됩니다:

선택에 따라.

크레딧

다음을 사용하여 구축: