DOCSEARCHbyAlgolia
Submit Docs

narsil-mcp

repository·main·Indexed 41 days ago

https://github.com/postrv/narsil-mcp

A high-performance, privacy-first Model Context Protocol (MCP) server written in Rust. It provides AI assistants with deep code intelligence across 32 languages, including semantic search, security analysis, and structural code understanding. Version 1.7.0 features a Code Context Graph (CCG) for hierarchical repository analysis and integrates with Claude Desktop, Cursor, VS Code (GitHub Copilot), and Continue.dev.

Tokens
67.4K
Snippets
217
Records
307
Agent score
52%

What's inside narsil-mcp

  1. Overview of narsil-mcp features

    main

    narsil-mcp is a high-performance MCP server providing 90+ tools for code intelligence across 32 supported languages (via tree-sitter). Key capabilities include:

    • Search: Multi-mode search supporting BM25, TF-IDF, hybrid, and neural embeddings.
    • Call Graph Analysis: Analysis of callers, callees, paths, and hotspots.
    • Security Scanning: Detection of OWASP Top 10, CWE Top 25, and secrets.
    • Git Integration: Access to blame, history, contributors, and hotspots.
    • Static Analysis: Control Flow Graphs (CFG), Data Flow Graphs (DFG), type inference, and taint analysis.

  2. Understand the narsil-mcp repository structure

    main

    The narsil-mcp repository follows an open-core model. The public repository contains the core MCP server implementation, language parsers, indexing infrastructure, and open-source components of the persistence and CCG (Code Context Graph) layers.

    Core Components

    • src/mcp.rs: The MCP server implementation.
    • src/parser.rs: Includes 16+ language parsers.
    • src/persistence/: Contains the open part of the local Oxigraph implementation, including the KnowledgeGraph struct and SPARQL query support.
    • src/ccg/: Contains the open part of CCG generation, specifically supporting L0, L1, and L2 layers, along with JSON-LD and N-Quads export/import.
    • ontology/: Contains core RDF ontologies (narsil.ttl and ccg.ttl).
    • rules/: YAML-based security rules for various languages (OWASP, CWE, Rust, Python, etc.).
    • schema/: Contains the ccg-v1.json JSON-LD schema.

  3. Understand the Narsil Open Core Licensing Model

    main

    Narsil follows an Open Core model, separating the open-source core from proprietary commercial features. This means the core functionality is free to use, modify, and distribute, while advanced enterprise features are managed through a separate commercial repository and license.

    Repository Breakdown

    • narsil-mcp (Open Source): Licensed under the MIT License. Includes everything needed for local use, such as Oxigraph integration and L0-L2 CCG generation.
    • narsil-cloud (Commercial): Licensed under a Proprietary license. Contains advanced features like L3 CCG generation, hosted registries, and enterprise management tools.

  4. Compare Open vs. Commercial CCG (Code Context Graph) capabilities

    main

    The level of detail and the tools available for Code Context Graphs (CCG) depend on whether you are using the open-source core or the commercial cloud service:

    Open Source (narsil-mcp)

    • CCG Specification: JSON-LD schema and ontology.
    • L0-L2 Generation: Tools for generating Manifest (L0), Architecture (L1), and Symbol Index (L2).
    • Tools: export_ccg_manifest, export_ccg_architecture, export_ccg_index, get_ccg_manifest, export_ccg (L0-L2 bundled).
    • Import: Ability to import CCGs from registry URLs.

    Commercial (narsil-cloud)

    • L3 Generation: export_ccg_full tool for high-detail graphs (~1-20MB).
    • Querying: query_ccg tool against hosted L3 graphs.
    • Management: CCG storage in the registry and versioning/history support.
    • Verification: compare_ccg, verify_ccg, and generate_target_ccg for refactoring assurance.

  5. Understand WASM vs Native feature availability

    main

    When using the WebAssembly (WASM) version of narsil-mcp, be aware of the feature limitations compared to the native build.

    Available in WASM:

    • Multi-language parsing (Rust, Python, JS, TS, Go, C, C++, Java, C#)
    • Symbol extraction (functions, classes, structs, etc.)
    • Full-text search with BM25 ranking
    • TF-IDF code similarity search
    • In-memory file storage

    NOT available in WASM (requires native build):

    • Git integration
    • File system watching
    • LSP integration
    • Neural embeddings (API calls)
    • Index persistence

  6. Compare Open vs. Commercial Oxigraph (RDF) capabilities

    main

    Narsil provides RDF-based knowledge graph capabilities through Oxigraph, with a distinction between local and hosted usage:

    Open Source (narsil-mcp)

    • Local Storage: Uses a KnowledgeGraph struct with a local Oxigraph store.
    • Ontology: Uses the narsil: RDF ontology.
    • Transformations: Converts symbols, call-graphs, and security findings to RDF.
    • Local Queries: Includes the sparql_query tool for local queries.
    • Persistence: Supports the --persist-graph CLI flag.

    Commercial (narsil-cloud)

    • Hosted Storage: Multi-tenant isolated graph storage.
    • Federation: Cross-repository SPARQL queries and graph federation across organizations.
    • Metering: Usage metering and quotas.

  7. Understand narsil-mcp tool categories and requirements

    main

    narsil-mcp organizes its 90 tools into 12 functional categories. Some categories are enabled by default, while others require specific CLI flags or environment variables to function:

    Always Enabled

    • Repository: File and repo operations (e.g., list_repos, get_file).
    • Symbols: Navigation and search (e.g., find_symbols, get_export_map).
    • Security: Vulnerability scanning (e.g., scan_security).
    • Analysis: Code analysis (e.g., get_control_flow, infer_types).

    Enabled by Default (with exceptions)

    • Search: Multi-mode search. Note: neural_search requires the --neural flag.

    Requires CLI Flags

    • Git: Requires --git flag (e.g., get_blame, get_commit_diff).
    • CallGraph: Requires --call-graph flag (e.g., get_call_graph, get_complexity).
    • LSP: Enhanced with --lsp flag (e.g., get_hover_info).
    • Remote: Requires --remote flag and GITHUB_TOKEN environment variable.
    • Graph: Requires --http flag (e.g., get_code_graph).

    Optional / Specialized

    • SupplyChain: Analysis like generate_sbom. Often disabled in lightweight presets due to performance.
    • Experimental: AI-assisted tools like explain_codebase.

  8. Use Named Repository Profiles for multi-repo projects

    main

    Profiles allow you to store reusable workspace definitions in your configuration file. This is useful when switching between different multi-repo projects.

    Example Profile Definition (YAML):

    version: "1.0"
profiles:
  platform:
    repos:
      - ~/src/api
      - ~/src/web
    git: true
    call_graph: true
    persist: true
    preset: balanced

    Usage:

    • Start with a profile: narsil-mcp --profile platform
    • List profiles: narsil-mcp config profiles

    Note: CLI flags take precedence over profile settings. For example, narsil-mcp --profile platform --repos ~/src/one-off will use the explicit --repos value while keeping other profile defaults.

  9. Understand the narsil-mcp and narsil-cloud separation

    main

    The project follows an 'Open Core' architecture where the core functionality is public and the commercial features are private:

    1. narsil-mcp (PUBLIC): The open-source core repository. It contains the primary logic and is licensed under the MIT License.
    2. narsil-cloud (PRIVATE): A commercial-only repository that depends on narsil-mcp as a git dependency. It contains proprietary features, billing, and cloud-specific deployments.

    Developers using the open-source version interact solely with the narsil-mcp repository.

  10. Understand the Code Context Graph (CCG) Layer Architecture

    main

    A Code Context Graph (CCG) is a multi-layer RDF dataset that provides hierarchical code intelligence. It uses a four-layer architecture to balance LLM context efficiency with deep analysis capabilities. This allows developers and AI agents to progressively fetch more detail as needed, starting from a lightweight manifest and moving toward full source-level analysis.

    • Layer 0 (Manifest): Minimal repository metadata (~1-2 KB). Always included in context to provide identity and layer URIs.
    • Layer 1 (Architecture): Module hierarchy and public API surface (~10-50 KB). Loaded by default to provide structural understanding.
    • Layer 2 (Symbol Index): All symbols, signatures, and call graph edges (~100-500 KB). Used for selective retrieval and navigation.
    • Layer 3 (Full Detail): Complete RDF dataset, including source snippets and security findings (~1-20 MB). Accessed via SPARQL queries for complex analysis.
    +------------------------------------------------------------------+
|  LAYER 0: MANIFEST (~1-2 KB)           Always in context         |
|  - Repository identity                                            |
|  - Symbol and security summaries                                  |
|  - Layer URIs for progressive fetching                           |
+------------------------------------------------------------------+
|  LAYER 1: ARCHITECTURE (~10-50 KB)     Loaded by default         |
|  - Module/package hierarchy                                       |
|  - Public API surface                                             |
|  - Module dependency graph                                       |
+------------------------------------------------------------------+
|  LAYER 2: SYMBOL INDEX (~100-500 KB)   Selective retrieval         |
|  - All symbols with signatures                                    |
|  - Full call graph edges                                          |
|  - Complexity metrics                                             |
+------------------------------------------------------------------+
|  LAYER 3: FULL DETAIL (~1-20 MB)       SPARQL queries only        |
|  - Complete RDF dataset                                           |
|  - Source snippets                                                |
|  - Security findings with remediation                             |
|  - Data flow and taint analysis                                   |
+------------------------------------------------------------------+

  11. How narsil-mcp works with AI assistants

    main

    narsil-mcp is an MCP (Model Context Protocol) server that provides AI assistants (like Claude) with direct access to code intelligence tools.

    Instead of being a plugin or a manual skill, it acts as a server that the AI client connects to. When you ask questions about your codebase, the AI automatically decides which tools to call to navigate code, search for symbols, analyze dependencies, scan for security vulnerabilities, or track git history. You do not need to manually trigger tool calls; the AI uses them to ground its answers in your actual source code.

  12. Supply Chain Analysis Workflow

    main

    The supply-chain command executes the following automated workflow:

    1. Identify repository: Uses the provided argument or prompts via list_repos.
    2. Generate SBOM: Creates a Software Bill of Materials using generate_sbom with format="cyclonedx".
    3. Check for vulnerabilities: Runs check_dependencies with include_dev=true and severity_threshold="low" to detect CVEs.
    4. Find upgrade paths: Uses find_upgrade_path to identify safe versions for vulnerable dependencies.
    5. Check license compliance: Runs check_licenses to identify issues, optionally using a user-specified project_license.
    6. Summarize findings: Produces a report including total dependencies, vulnerability severity breakdown, safe upgrades, license compatibility, and prioritized recommended actions.