SKILL.md
Narsil Code Intelligence
Narsil is an MCP server providing 90 code intelligence tools (plus 2 prompts: explaincodebase, findimplementation). 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 enabledFeature Requirements
Some tools require specific CLI flags when starting narsil-mcp:
| Feature | Required Flag | Tools |
|---|---|---|
| Git integration | --git |
getblame, getfilehistory, getrecentchanges, gethotspots, getcontributors, getcommitdiff, getsymbolhistory, getbranchinfo, getmodified_files |
| Call graph | --call-graph |
getcallgraph, getcallers, getcallees, findcallpath, getcomplexity, getfunction_hotspots |
| LSP | --lsp |
Enhanced: gethoverinfo, gettypeinfo, gotodefinition |
| Neural search | --neural |
neuralsearch, getneural_stats |
| Remote repos | --remote (+ GITHUB_TOKEN) |
addremoterepo, listremotefiles, getremotefile |
| Knowledge graph | --graph |
sparqlquery, listsparqltemplates, runsparqltemplate, getccgmanifest, exportccg*, queryccg, importccg, importccgfromregistry, getccgacl, getccgaccess_info |
If a tool returns empty results or errors, check getindexstatus to verify the feature is enabled.
Relevant environment variables
| Var | Purpose |
|---|---|
GITHUB_TOKEN |
Auth for --remote GitHub API calls |
EMBEDDINGAPIKEY / VOYAGEAPIKEY / OPENAIAPIKEY |
Neural embedding provider key |
EMBEDDINGSERVERENDPOINT |
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 | findsymbols with filepattern |
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 | findsimilarcode |
Have a code snippet |
| Find code like a symbol | findsimilarto_symbol |
Find patterns similar to existing function |
| Find code clones | findsemanticclones |
Detect duplicate/similar code (Type-3/4 clones) |
| Search AST chunks | search_chunks |
Want function/class boundaries |
| Fuzzy symbol search | workspacesymbolsearch |
Unsure of exact name |
| Compact codebase manifest | getccgmanifest |
AI-context-friendly summary of identity, symbol counts, languages, security posture (requires --graph) |
Note:
explaincodebaseandfindimplementationare 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 | getsymboldefinition |
| Find all references | find_references |
| Find all usages (cross-file) | findsymbolusages |
| See what exports a module has | getexportmap |
| Analyze imports/dependencies | get_dependencies |
| See what calls a function | get_callers |
| See what a function calls | get_callees |
| Full call graph | getcallgraph |
| Find path between functions | findcallpath |
| Function complexity | get_complexity |
| Find high-connection functions | getfunctionhotspots |
| Get type info at position | gethoverinfo |
| Get precise type info | gettypeinfo |
| Go to definition | gotodefinition |
Security Analysis
| Task | Best Tool |
|---|---|
| Full security scan | scan_security |
| Security overview | getsecuritysummary |
| OWASP Top 10 check | checkowasptop10 |
| CWE Top 25 check | checkcwetop25 |
| Find injection flaws | findinjectionvulnerabilities |
| Find taint sources | gettaintsources |
| Trace tainted data | trace_taint |
| Explain a vulnerability | explain_vulnerability |
| Get fix suggestion | suggest_fix |
| Check dependencies for CVEs | check_dependencies |
| Find upgrade paths | findupgradepath |
| License compliance | check_licenses |
| Generate SBOM | generate_sbom |
Static Analysis
| Task | Best Tool |
|---|---|
| Control flow graph | getcontrolflow |
| Data flow analysis | getdataflow |
| Reaching definitions | getreachingdefinitions |
| Find dead code | finddeadcode |
| Find dead stores | finddeadstores |
| Find uninitialized vars | find_uninitialized |
| Infer types (Python/JS/TS) | infer_types |
| Check type errors | checktypeerrors |
| Taint flow with types | gettypedtaint_flow |
| Import dependency graph | getimportgraph |
| Find circular imports | findcircularimports |
Remote GitHub Repos (requires --remote, GITHUB_TOKEN env)
| Task | Best Tool |
|---|---|
| Clone & index a GitHub repo | addremoterepo |
| List files via GitHub API (no clone) | listremotefiles |
| Fetch single file via GitHub API | getremotefile |
SPARQL Knowledge Graph (requires --graph)
| Task | Best Tool |
|---|---|
| Run a SPARQL query against the RDF graph | sparql_query |
| List built-in SPARQL templates | listsparqltemplates |
| Run a named SPARQL template with params | runsparqltemplate |
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) | getccgmanifest |
| Export Layer 0 manifest to file | exportccgmanifest |
| Export Layer 1 architecture (~10-50KB) | exportccgarchitecture |
| Export Layer 2 symbol index (gzipped N-Quads) | exportccgindex |
| Export Layer 3 full detail (gzipped N-Quads) | exportccgfull |
| 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 | getccgacl |
| Show available CCG access tier info | getccgaccess_info |
| Import a CCG from URL/file | import_ccg |
| Import from codecontextgraph.com registry | importccgfrom_registry |
Git History (requires --git)
| Task | Best Tool |
|---|---|
| Git blame for file | get_blame |
| File commit history | getfilehistory |
| Recent repo changes | getrecentchanges |
| High-churn files | get_hotspots |
| Contributors to file/repo | get_contributors |
| Diff for a commit | getcommitdiff |
| Symbol change history | getsymbolhistory |
| Current branch info | getbranchinfo |
| Uncommitted changes | getmodifiedfiles |
Utility & Diagnostics
| Task | Best Tool |
|---|---|
| List indexed repos | list_repos |
| Get project structure | getprojectstructure |
| Check enabled features | getindexstatus |
| Force re-index | reindex |
| Discover repos in directory | discover_repos |
| Validate repo path | validate_repo |
| Incremental index status | getincrementalstatus |
| Performance metrics | get_metrics |
| Embedding stats | getembeddingstats |
| Chunk stats | getchunkstats |
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 structureFind 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 codeSecurity 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 remediationUnderstand 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 flowHandling Large Results
For large codebases, use pagination and filtering:
max_resultsparameter limits output sizefile_patternfilters by glob (e.g.,"*.py","src/**/*.ts")severity_thresholdfilters security findings (critical, high, medium, low)
Troubleshooting
"No repository found" → Run list_repos and use exact repo name
Empty results from git tools → Check getindexstatus shows git enabled
Empty results from call graph → Check getindexstatus shows call-graph enabled
Slow searches → Use file_pattern to narrow scope
For detailed workflow examples, see [WORKFLOWS.md](WORKFLOWS.md).