Narsil Code Intelligence

Narsil is an MCP server providing 90 code intelligence tools (plus 2 prompts: explain_codebase, find_implementation). This skill helps you use them effectively.

Critical: Parameter Naming

Use short parameter names. These are the most common mistakes:

Wrong	Correct
repo_path	repo
symbol_name	symbol
file_path	path
function_name	function

The repo parameter expects the repository name from list_repos, not the full filesystem path.

Getting Started

Always start with:

list_repos  → See indexed repositories
get_index_status  → See which features are enabled

Feature Requirements

Some tools require specific CLI flags when starting narsil-mcp:

Feature	Required Flag	Tools
Git integration	--git	get_blame, get_file_history, get_recent_changes, get_hotspots, get_contributors, get_commit_diff, get_symbol_history, get_branch_info, get_modified_files
Call graph	--call-graph	get_call_graph, get_callers, get_callees, find_call_path, get_complexity, get_function_hotspots
LSP	--lsp	Enhanced: get_hover_info, get_type_info, go_to_definition
Neural search	--neural	neural_search, get_neural_stats
Remote repos	--remote (+ GITHUB_TOKEN)	add_remote_repo, list_remote_files, get_remote_file
Knowledge graph	--graph	sparql_query, list_sparql_templates, run_sparql_template, get_ccg_manifest, export_ccg_*, query_ccg, import_ccg, import_ccg_from_registry, get_ccg_acl, get_ccg_access_info

If a tool returns empty results or errors, check get_index_status to verify the feature is enabled.

Relevant environment variables

Var	Purpose
GITHUB_TOKEN	Auth for --remote GitHub API calls
EMBEDDING_API_KEY / VOYAGE_API_KEY / OPENAI_API_KEY	Neural embedding provider key
EMBEDDING_SERVER_ENDPOINT	Custom/self-hosted embeddings endpoint
RUST_LOG	Logging level (debug, info, warn, error)

Tool Selection Guide

Finding Code

Task	Best Tool	When to Use
Find files by name	find_symbols with file_pattern	Know filename pattern
Find function/class definitions	find_symbols	Know symbol type
Search by content	search_code	Keyword search
BM25-ranked search	semantic_search	Better ranking than search_code
Semantic code search	hybrid_search	Natural language queries (combines BM25 + TF-IDF)
Find similar code	find_similar_code	Have a code snippet
Find code like a symbol	find_similar_to_symbol	Find patterns similar to existing function
Find code clones	find_semantic_clones	Detect duplicate/similar code (Type-3/4 clones)
Search AST chunks	search_chunks	Want function/class boundaries
Fuzzy symbol search	workspace_symbol_search	Unsure of exact name
Compact codebase manifest	get_ccg_manifest	AI-context-friendly summary of identity, symbol counts, languages, security posture (requires --graph)

Note: explain_codebase and find_implementation are MCP prompts, not tools. They surface as templates the client can present to the user (or wrap as slash commands), and cannot be called from a tool-calling workflow. Use the tool sequences in the workflow tables below to achieve the same result.

Understanding Code

Task	Best Tool
Read a file	get_file
Read specific lines	get_excerpt
Get AST chunks for file	get_chunks
Get function source	get_symbol_definition
Find all references	find_references
Find all usages (cross-file)	find_symbol_usages
See what exports a module has	get_export_map
Analyze imports/dependencies	get_dependencies
See what calls a function	get_callers
See what a function calls	get_callees
Full call graph	get_call_graph
Find path between functions	find_call_path
Function complexity	get_complexity
Find high-connection functions	get_function_hotspots
Get type info at position	get_hover_info
Get precise type info	get_type_info
Go to definition	go_to_definition

Security Analysis

Task	Best Tool
Full security scan	scan_security
Security overview	get_security_summary
OWASP Top 10 check	check_owasp_top10
CWE Top 25 check	check_cwe_top25
Find injection flaws	find_injection_vulnerabilities
Find taint sources	get_taint_sources
Trace tainted data	trace_taint
Explain a vulnerability	explain_vulnerability
Get fix suggestion	suggest_fix
Check dependencies for CVEs	check_dependencies
Find upgrade paths	find_upgrade_path
License compliance	check_licenses
Generate SBOM	generate_sbom

Static Analysis

Task	Best Tool
Control flow graph	get_control_flow
Data flow analysis	get_data_flow
Reaching definitions	get_reaching_definitions
Find dead code	find_dead_code
Find dead stores	find_dead_stores
Find uninitialized vars	find_uninitialized
Infer types (Python/JS/TS)	infer_types
Check type errors	check_type_errors
Taint flow with types	get_typed_taint_flow
Import dependency graph	get_import_graph
Find circular imports	find_circular_imports

Remote GitHub Repos (requires --remote, GITHUB_TOKEN env)

Task	Best Tool
Clone & index a GitHub repo	add_remote_repo
List files via GitHub API (no clone)	list_remote_files
Fetch single file via GitHub API	get_remote_file

SPARQL Knowledge Graph (requires --graph)

Task	Best Tool
Run a SPARQL query against the RDF graph	sparql_query
List built-in SPARQL templates	list_sparql_templates
Run a named SPARQL template with params	run_sparql_template

Code Context Graph / CCG export (requires --graph)

CCG layers ship a portable, layered description of a codebase suitable for AI handoff or external indexing.

Task	Best Tool
Get Layer 0 manifest (~1-2KB JSON-LD)	get_ccg_manifest
Export Layer 0 manifest to file	export_ccg_manifest
Export Layer 1 architecture (~10-50KB)	export_ccg_architecture
Export Layer 2 symbol index (gzipped N-Quads)	export_ccg_index
Export Layer 3 full detail (gzipped N-Quads)	export_ccg_full
Export all CCG layers as a bundle	export_ccg
Run a SPARQL query against a repo's CCG	query_ccg
Generate WebACL access control file	get_ccg_acl
Show available CCG access tier info	get_ccg_access_info
Import a CCG from URL/file	import_ccg
Import from codecontextgraph.com registry	import_ccg_from_registry

Git History (requires --git)

Task	Best Tool
Git blame for file	get_blame
File commit history	get_file_history
Recent repo changes	get_recent_changes
High-churn files	get_hotspots
Contributors to file/repo	get_contributors
Diff for a commit	get_commit_diff
Symbol change history	get_symbol_history
Current branch info	get_branch_info
Uncommitted changes	get_modified_files

Utility & Diagnostics

Task	Best Tool
List indexed repos	list_repos
Get project structure	get_project_structure
Check enabled features	get_index_status
Force re-index	reindex
Discover repos in directory	discover_repos
Validate repo path	validate_repo
Incremental index status	get_incremental_status
Performance metrics	get_metrics
Embedding stats	get_embedding_stats
Chunk stats	get_chunk_stats

Common Patterns

Explore a new codebase

1. list_repos → get repo name
2. get_project_structure(repo) → see directory tree
3. find_symbols(repo, symbol_type="function") → see main functions
4. get_import_graph(repo) → understand module structure

Find where something is implemented

1. workspace_symbol_search(query="feature name") → find candidates
2. find_symbol_usages(repo, symbol) → see all usages
3. get_symbol_definition(repo, symbol) → read the code

Security audit

1. scan_security(repo) → get all findings
2. check_owasp_top10(repo) → check critical vulnerabilities
3. check_dependencies(repo) → find vulnerable dependencies
4. find_injection_vulnerabilities(repo) → focus on injection flaws
5. For each finding: suggest_fix(repo, path, line) → get remediation

Understand a function

1. get_symbol_definition(repo, symbol) → read source
2. get_callers(repo, function, transitive=true) → who calls it
3. get_callees(repo, function) → what it calls
4. get_complexity(repo, function) → cyclomatic complexity
5. get_data_flow(repo, path, function) → variable flow

Handling Large Results

For large codebases, use pagination and filtering:

• max_results parameter limits output size
• file_pattern filters by glob (e.g., "*.py", "src/**/*.ts")
• severity_threshold filters security findings (critical, high, medium, low)

Troubleshooting

"No repository found" → Run list_repos and use exact repo name

Empty results from git tools → Check get_index_status shows git enabled

Empty results from call graph → Check get_index_status shows call-graph enabled

Slow searches → Use file_pattern to narrow scope

For detailed workflow examples, see WORKFLOWS.md.