grasp-mcp-server

Grasp MCP Server

Expose Grasp's codebase analysis engine as MCP tools for Claude Code and other LLM agents.

Supports GitHub repositories and local directories. Analyzes dependency graphs, architecture layers, circular deps, security issues, design patterns, dead code, code metrics, git history, duplicate detection, cross-repo comparison, monorepo workspaces, runtime call graphs, database schema coupling, API surface maps, and migration planning.

Force-directed dependency graph — the same data the MCP server exposes via grasp_analyze, grasp_dependents, graph_query, etc.

Table of Contents

• Setup
• Configure in Claude Code
• Tools
• Example Usage
• GitHub Token
• GitLab Support
• CLI
• JetBrains Plugin
• Claude Code Slash Commands
• Privacy

Current version: 3.21.0 — 150 tools + 8 MCP Resources + 2 guided Prompts.

New in v3.21.0 — Multimodal Knowledge Graph: ingest any artifact (code, Markdown, PDF, Word .docx, Excel .xlsx, HTML, images via OCR, audio/video via local Whisper, YouTube) into a queryable semantic knowledge graph, then ask it in natural language. New tools: grasp_ingest, grasp_kg_ask, grasp_kg_trace, grasp_kg_explain, grasp_kg_stats, grasp_kg_export (Cypher/Neo4j/GraphML/JSON/Mermaid), grasp_llm_status. Pluggable LLM backends (Anthropic, OpenAI, Gemini, DeepSeek, Kimi, Azure, Bedrock, Ollama — local-first, cloud opt-in; extraction falls back to a deterministic local extractor with zero credentials). Optional MCP-over-HTTP transport for shared team access (GRASP_HTTP_MCP=1, optional API key). Three new AST languages (Bash, Elixir, Julia → 19 tree-sitter-backed). See ## Multimodal Knowledge Graph below.

v3.20.0 added: Full security scanning suite — grasp_vulnerabilities covers five threat vectors (OSV.dev dependency CVEs, NIST NVD container/runtime CVEs, local supply-chain integrity checks, Socket.dev behavioral analysis, and scheduled grasp_vuln_watch monitoring), plus skip_container / skip_socket / skip_integrity fast-scan flags.

v3.19.0 added: Team Dashboard visual parity with the Grasp app — teal brand sweep, Lucide SVG icon system, multi-provider auth (GitLab, GitHub Enterprise, Bitbucket, Azure DevOps, Gitea), mobile More menu, keyboard shortcut popover.

v3.18.0 added: 10 new MCP tools (grasp_hub_nodes, grasp_bridge_nodes, grasp_surprising_connections, grasp_knowledge_gaps, grasp_suggested_questions, grasp_minimal_context, grasp_traverse, grasp_semantic_search, grasp_apply_refactor, grasp_architecture_overview); 3 graph export formats (grasp_export_graphml, grasp_export_cypher, grasp_export_obsidian); TS-config path-alias and Jedi-style Python import resolvers; Claude Code slash commands; token-reduction eval harness (scripts/eval-token-reduction.mjs); localized READMEs (Hindi/Japanese/Korean/Simplified Chinese).

Recent additions (see CHANGELOG.md for full history):

• v3.17.1 — per-directory lockfile scoping in the OSV scanner; test-fixture manifests skipped; CWS-token rotation script.
• v3.17.0 — OSV.dev SCA scanner (grasp_vulnerabilities + grasp vulns CLI); architecture drift detection (grasp_snapshot + grasp_diff_snapshots + grasp drift CLI); org-level dashboard (grasp_org_summary + grasp org CLI); test-coverage gap map; graph schema v3 (TestFile nodes, TESTS/COVERS edges).
• v3.16.0 — PR Impact GitHub Action; Brain context tools (grasp_diff_symbols, grasp_exec_flow, grasp_skillmd, grasp_hooks, grasp_mro, grasp_communities, grasp_contracts); confidence scoring; wiki generator; registry tools.
• v3.15.0 — Kuzu graph schema v2; cross-file type propagation; ORM tracker; grasp_detect_changes; 8 MCP Resources; 2 MCP Prompts; grasp setup one-command editor auto-config.

Verticals shipped before v3.15: aerospace/safety-critical (requirement traceability, MISRA, DO-178C, ECSS-E-ST-40C, Ada/SPARK), AI research (safety-constraint tracing, eval coverage, ML pipeline DAG, Jupyter notebooks), enterprise (SBOM CycloneDX/SPDX, DORA, AI-powered ADR, PII trace, separation of duties, finance latency / model risk), OS/kernel (subsystem boundaries, ABI stability, Kconfig, IRQ graph, patch series impact), open source (good-first-issues, fork divergence, OpenSSF scorecard, deps.dev), and a hosted SaaS API (saas/).

Verify Provenance

Every release is signed. Verify before installing:

npm package (SLSA provenance):

npm install -g @sigstore/verify  # one-time
sigstore verify npm grasp-mcp-server@3.21.0

Docker image (Cosign keyless signature):

cosign verify \
  --certificate-identity-regexp="https://github.com/ashfordeOU/grasp/.github/workflows/publish.yml" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  ghcr.io/ashfordeou/grasp:v3.21.0

Signatures are stored transparently in the Sigstore Rekor public ledger.

Multimodal Knowledge Graph

Beyond code analysis, Grasp can ingest any artifact into a queryable semantic knowledge graph and answer natural-language questions grounded with citations.

// Ingest a folder of docs, a PDF, or a URL (incl. YouTube)
grasp_ingest { "source": "./docs" }
grasp_ingest { "source": "/papers/spec.pdf" }
grasp_ingest { "source": "https://youtu.be/…" }   // local Whisper transcription

// Ask it
grasp_kg_ask   { "question": "How does auth flow through the billing service?" }
grasp_kg_trace { "from": "Auth", "to": "Postgres" }     // shortest relationship path
grasp_kg_explain { "name": "Billing Service" }          // neighbourhood + sources
grasp_kg_stats {}                                       // counts + god-nodes
grasp_kg_export { "format": "cypher", "out_path": "kg.cypher" }  // Neo4j/FalkorDB

Local-first, cloud opt-in. Code parsing stays deterministic (tree-sitter AST). Semantic entity/relationship extraction uses whichever LLM you configure and auto-detects a local Ollama before any cloud key; with no LLM at all it falls back to a deterministic extractor so everything still works offline. Every edge is tagged EXTRACTED (stated in the source) vs INFERRED (derived), with a source locator.

Backend	Env
Ollama (local, default)	runs at localhost:11434 — nothing else needed
Anthropic / OpenAI / Gemini / DeepSeek / Kimi	ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / DEEPSEEK_API_KEY / MOONSHOT_API_KEY
Azure OpenAI / AWS Bedrock	AZURE_OPENAI_* / AWS_*

Select explicitly with GRASP_LLM_PROVIDER + GRASP_LLM_MODEL, or per-call via the provider/model/api_key tool args. Run grasp_llm_status to see what's available.

Optional parsers (installed on demand, keeping the core install lean): npm i pdf-parse mammoth xlsx tesseract.js youtube-transcript. Audio/video transcription additionally needs ffmpeg on PATH.

Shared team access (MCP over HTTP)

GRASP_HTTP_MCP=1 GRASP_HTTP_API_KEY=… grasp-mcp   # serves Streamable HTTP on :7333/mcp

Point any MCP client at http://host:7333/mcp (send the key as Authorization: Bearer … or x-api-key). /health returns liveness. Grasp's tools are stateless, so one endpoint serves a team's agents.

Where it lives

The multimodal pipeline is MCP-server-side (Node) and does not run in the browser app — see the source layout under mcp/src/:

• ingest/* — artifact parsers (PDF, Word .docx, Excel .xlsx, HTML, image OCR, audio/video, URL, YouTube; heavy parsers lazy-loaded on demand)
• llm/provider.ts — pluggable multi-provider LLM layer (local-first Ollama auto-detect → cloud key → deterministic fallback)
• semantic/* — SQLite knowledge-graph store, hybrid BM25 + vector retrieval, BFS path-tracing, hub/god-node detection
• tree-sitter/* — deterministic AST parsing across 19 languages

Setup

cd mcp
npm install
npm run build

Configure in Claude Code

Add to ~/.claude/claude_mcp_settings.json:

{
  "mcpServers": {
    "grasp": {
      "command": "node",
      "args": ["/absolute/path/to/grasp/mcp/dist/index.js"]
    }
  }
}

Or install globally via npm:

{
  "mcpServers": {
    "grasp": {
      "command": "npx",
      "args": ["grasp-mcp-server"]
    }
  }
}

Tools

Core Analysis

Tool	Description
grasp_analyze	Full analysis — run first, returns session_id
grasp_file_deps	Outgoing deps for a file (what it imports)
grasp_dependents	Incoming deps — blast radius if you change this file
grasp_cycles	All circular dependency chains
grasp_architecture	Files grouped by layer (services/data/utils/test…)
grasp_hotspots	Most coupled + complex files, ranked
grasp_metrics	Lines, functions, complexity, fan-in/fan-out per file
grasp_find_path	Shortest dependency path between two files
grasp_security	Hardcoded secrets, SQL injection risks, insecure patterns
grasp_patterns	Detected design patterns and anti-patterns
grasp_unused	Dead code — functions defined but never called
grasp_sessions	List persisted analysis sessions — survive restarts, expire after 7 days
grasp_config_check	Run grasp.yml architecture rules against a session — returns violations with severity

History & Comparison

Tool	Description
grasp_diff	Compare two session snapshots — files added/removed, health delta
grasp_watch	Re-analyse a local directory and diff against a prior session
grasp_timeline	Last N git commits with per-commit changed files and co-change matrix
grasp_cross_repo	Compare two sessions — shared filenames, diverged functions, workspace info
grasp_similarity	Ranked duplicate clusters, code clones, naming clashes, hottest files

Code Quality

Tool	Description
grasp_suggest	Ranked refactoring suggestions from hotspot + issue data
grasp_explain	Plain-English explanation of any file or function
grasp_rules_check	Run architecture rules and report all violations
grasp_refactor	Step-by-step refactor plan with metrics table for a file or session
grasp_coverage	Test coverage overlay — files with no test counterpart
grasp_vulnerabilities	OSV.dev SCA scanner — known CVEs in declared dependencies (npm/PyPI/Go/Cargo/Maven). Severity-classified (CVSS), fix-version suggestions, severity filter (all/critical/high/medium/low). Pairs with grasp vulns <path> CLI (exit 1 on critical/high) — new in v3.17.0

Ecosystem Integration

Tool	Description
grasp_issues	Map GitHub Issues to the files they mention
grasp_contributors	Per-file ownership, bus-factor score, top contributors
grasp_bundle	Bundle size treemap — files ranked by size with category breakdown
grasp_dep_impact	Impact of upgrading a dependency — which files import it
grasp_pr_comment	Generate a PR health comment with blast radius for changed files
grasp_embed	Generate iframe, README badge, and React snippet for sharing
grasp_dead_packages	npm deps declared in package.json but never imported by any source file
grasp_sarif	Export analysis as SARIF 2.1.0 for GitHub Code Scanning upload

Runtime & Infrastructure Intelligence

Tool	Description
grasp_runtime_calls	Merge a GraspTracer JSON trace with static edges — shows actual call paths and hot files
grasp_db_coupling	ORM/SQL-to-table coupling map — god tables, high-coupling files, shared-table clusters
grasp_migration_plan	Phased, topologically-ordered plan for replacing or removing a package/module
grasp_api_surface	Unified API surface map from OpenAPI specs, GraphQL SDL, Express/FastAPI/Next.js routes

GitHub Activity

Tool	Description
grasp_commits	Commit counts for last 7d and 30d, plus commits since a given timestamp (staleness since last analysis)
grasp_ci_status	Latest GitHub Actions run — passing/failing/in-progress, with recent run history

Codebase Intelligence (v2.4–v2.9)

Tool	Description
grasp_env_vars	Scan all env var reads — cross-references .env.example, flags undocumented and test-only vars
grasp_events	Map event emitters and subscribers — detects orphaned emits (no listener) and ghost subscriptions (no emitter)
grasp_stale	Find active but abandoned files — low churn, high fan-in, no test counterpart. Returns staleness score 0–100
grasp_change_risk	Risk score 0–100 for a set of changed files — blast radius, complexity, churn, and layer violations combined
grasp_feature_flags	Find all feature flag reads — LaunchDarkly, GrowthBook, OpenFeature, env-var flags, and custom patterns
grasp_perf	Detect N+1 queries, synchronous I/O calls, and JSON serialization inside loops
grasp_license	Scan node_modules for dependency licenses — reports permissive, copyleft, and unknown; flags violations
grasp_onboard	Ordered reading path for new engineers entering an area of the codebase — sorted by layer and fan-in
grasp_types	Type annotation coverage per file — prioritises high fan-in files lacking types
grasp_diagram	Generate Mermaid flowchart or C4 diagrams (context, container, or component level) from the dependency graph
grasp_pr_review	Post inline review comments on a GitHub PR at high-severity lines — blast radius, complexity, security
grasp_suggest	Ranked refactoring suggestions with effort-to-impact ratio — sorted best ROI first

Aerospace / Safety-Critical

Tool	Description
grasp_req_trace	Requirement traceability — scan @REQ-NNN tags in code against a requirements CSV; returns coverage %, covered, uncovered, and unspecified files
grasp_anomaly	Anomaly investigation — callers, callees, transitive blast radius (BFS 50 files), security in call chain, plain-English summary; for incident response
grasp_reuse	Software reuse assessor — Red/Amber/Green matrix across Interface Compatibility, Dependencies, Security, and Architecture Fitness

AI Research / AI Safety

Tool	Description
grasp_safety_trace	Safety constraint tracer — mark safety gates, entry points, output points; returns all entry→output paths that bypass every gate (ungated paths = critical)
grasp_run_diff	Training run diff — compare two YAML/JSON configs, find changed hyperparameters and which code files read each changed key
grasp_eval_coverage	Eval coverage map — BFS trace from eval scripts through imports; shows covered %, lists uncovered files, flags safety gates with no eval coverage

Enterprise / Compliance

Tool	Description
grasp_sbom	SBOM generation — CycloneDX 1.4 or SPDX 2.3 JSON. Parses package.json, requirements.txt, Cargo.toml, go.mod, pyproject.toml. Optional CVE enrichment.
grasp_dora	DORA metrics — Deployment Frequency, Lead Time for Changes, Change Failure Rate via GitHub Actions and PR history. Elite/High/Medium/Low tier.
grasp_adr	AI-powered ADR generation — MADR-format Architecture Decision Record using codebase context + optional PR diff. Supports any AI Chat provider.

Multi-Repo / Platform (v3.4.x)

Tool	Description
grasp_org_graph	Org-level multi-repo dependency graph — merge N sessions into one org view with inter-repo edges and shared libs
grasp_api_diff	Breaking API change detector — compare exported symbols between two sessions, flag removed/changed signatures
grasp_plugins	Extension-point map — detect plugin interfaces, hook points, and strategy patterns across a codebase
grasp_semver	Semantic versioning enforcer — compare two sessions and validate semver bump is correct for the change set

Finance / Compliance (v3.5.x)

Tool	Description
grasp_pii_trace	PII data flow tracer — BFS downstream traversal from user-marked PII source files; shows all consumers
grasp_duties	Separation of duties validator — detects files that both initiate and approve transactions (SOX/FDA compliance)
grasp_reg_impact	Regulatory change impact mapper — keywords-to-blast-radius for GDPR/HIPAA/SOX/PCI-DSS article changes
grasp_latency	Finance/trading latency hotspot detection — blocking I/O, GC pressure, lock contention, allocation in loops
grasp_model_risk	Financial model risk auditor — hardcoded parameters, missing NaN checks, division without zero-guard

OS / Kernel (v3.6.x)

Tool	Description
grasp_subsystems	Kernel/OS subsystem boundary map — directory-level groupings, cross-subsystem dependency violations
grasp_abi_diff	ABI/API stability checker — compare exported symbols between sessions, stability score 0–100
grasp_kconfig	Kconfig/build-time conditional analysis — CONFIG_* usage map, high-risk toggles affecting >50 files
grasp_irq	IRQ/interrupt dependency graph — dynamic allocation, blocking calls, and fan-out in interrupt handlers
grasp_patch_impact	Patch series impact analyzer — rank patches by blast radius + complexity for kernel code review

Open Source (v3.7.x)

Tool	Description
grasp_good_first_issues	Good first issue generator — isolated, low-complexity, untested files with GitHub issue draft text
grasp_api_stability	API stability score (0–100) between two sessions — tracks breaking change rate for library authors
grasp_dependents	Dependents in the wild — query deps.dev for public package dependent count
grasp_fork_diff	Fork divergence analysis — diverged/identical/fork-only files and merge blast radius

Ada / Heritage (v3.8.x)

Tool	Description
grasp_multilang	Cross-language call graph — Ada→C pragma Import, Python ctypes/cffi, JS→WASM boundaries
grasp_heritage	Heritage software genealogy — overlay origin-mission manifest, identify zero-delta certification shortcuts
grasp_icd	ICD mapper — match Interface Control Document entries to exported functions, flag unimplemented interfaces
grasp_ecss	ECSS-E-ST-40C compliance checker — DI-01 headers, DI-04 docs, DI-07 tests, DI-10 no cycles, DI-15 no dead code

Graph Tools (New in v3.11.0)

Tool	Description
graph_query	Run read-only Cypher queries against the Grasp function-level call graph
call_chain	Traverse callers/callees N hops from a named function
type_propagation	Find all functions returning a given type and their call neighbors
function_graph	Render a function subgraph as Mermaid, DOT, or JSON

Requires grasp_brain_index to be run first.

Example: find all functions that eventually call anything returning AuthToken:

MATCH (f:Function)-[:CALLS*1..3]->(g:Function)
WHERE g.returnType CONTAINS 'AuthToken'
RETURN f.name, g.name, g.returnType

Brain & Persistent Intelligence (v3.10+)

Tool	Description
grasp_brain_index	Index a repo into the persistent SQLite brain store (~/.grasp/brain.db) — files, functions, edges, health, security, layer. Also builds FTS index, 384D vector embeddings, and execution-flow process tags
grasp_brain_status	List all repos indexed in the brain: sources, file counts, indexed-at timestamps, health scores
grasp_context	Rich context for any file from the brain: layer, complexity, coupling, churn, grade, up to 20 deps/dependents, security issues — instant, no re-analysis
grasp_arch_diff	Compare current codebase against brain baseline: grade regressions, health delta, new security issues since last index
grasp_ask	Natural language questions against the brain store — no AI key needed. Recognises intents: complexity · coupling · security · blast-radius · layer · grade · churn · cycles. Falls back to hybrid semantic search (BM25 + vector)
grasp_diff_symbols	Map git diff hunks → functions; returns blast radius and complexity for every function touched by a PR
grasp_exec_flow	BFS execution flow from any entry point — traces call paths with STEP_IN_PROCESS edges, outputs Mermaid flowchart
grasp_skillmd	Auto-generate a SKILL.md / CLAUDE.md snippet for AI agents — layers, key files, health grade, patterns, and security findings
grasp_hooks	Generate .claude/settings.json PostToolUse hook and .cursor/rules/grasp.mdc for automatic context injection on every file edit
grasp_mro	Method Resolution Order — C3 linearisation for Python multiple inheritance, MRO for Ruby and Java hierarchies
grasp_communities	Leiden/Louvain community detection on the Kuzu graph — cohesive clusters, bounded contexts, microservice split candidates
grasp_contracts	Multi-repo contract analysis — provider exports vs consumer imports across repos, violations and coverage %
grasp_confidence	Score every cross-file connection 0–1: explicit import = 1.0 · same folder = 0.8 · cross-folder = 0.6 · low-frequency = 0.4
grasp_wiki	Auto-generate a markdown wiki: index.md overview, one page per folder, api.md sorted by caller count
grasp_registry_list	List all repos in the Grasp Brain registry with health grade, file count, function count, active session IDs
grasp_registry_status	Registry health summary: total indexed repos, active session count, grade distribution (A/B/C/D/F)
grasp_resolve_receiver	Resolve the concrete class for every method call — Python, JavaScript, Java, Ruby self/this inference
grasp_service_graph	Build a service dependency graph from OpenTelemetry traces — nodes are services, edges are call paths with latency and error rate
grasp_jira_issues	Fetch Jira issues for the repo and map them to files — identify which files have the most open bugs
grasp_deps_dev	Query deps.dev for public dependent count, OpenSSF scorecard, and dependency health for any npm/PyPI/Go package

Semantic Search & Rename (v3.14+)

Tool	Description
grasp_search	Hybrid semantic search (BM25 FTS5 + 384D vector embeddings merged with Reciprocal Rank Fusion) against the brain index. Results include processes[] field grouping matches by execution flow. Supports @groupName fan-out
grasp_rename	Graph-aware whole-word symbol rename across all files in the brain index. apply: false (default) returns a dry-run diff; apply: true writes changes to disk
grasp_route_map	Scan for HTTP route definitions (Express/Fastify/Hono, FastAPI/Flask, Gin) — maps each route to its handler function with file location
grasp_api_impact	Given a route or handler name, returns all callers, downstream services, and blast radius using brain graph edges
grasp_tool_map	Scan for MCP tool definitions (server.tool / server.registerTool) and gRPC service definitions — returns a service contract map
grasp_shape_check	For any function, traces parameter types and return types across all call sites from the brain index; flags call-site mismatches
grasp_group_add	Add a repo source to a named group in ~/.grasp/groups.json for multi-repo fan-out
grasp_group_list	List all named groups and their member repos from ~/.grasp/groups.json

Graph Intelligence (v3.15.0)

Tool	Description
grasp_graph_schema	Kuzu schema v3 introspection — all node/edge table definitions (File, Function, Class, Interface, Method, Constructor, TestFile + 12 edge types including TESTS and COVERS) with live row counts per table
grasp_type_propagation	Cross-file type inference via topological propagation — follows import graph (Kahn's algorithm) to infer return types at every call site; returns top 20 inferred types with confidence 0–1
grasp_orm_map	ORM query tracker — detects Prisma, TypeORM, Sequelize, SQLAlchemy patterns; results grouped by model with call sites, operations, and frequency; filter by orm_filter param
grasp_detect_changes	Git diff → symbol impact map. scope: unstaged · staged · all · compare (with base_ref). Returns changed files, affected functions with line ranges, impacted process flows, and risk level: LOW · MEDIUM · HIGH · CRITICAL
grasp_generate_agents_md	Generate a rich AGENTS.md in the repo root from brain session data — top 5 functional communities with key files, top 3 execution processes with entry points, health grade, top issues
grasp_generate_skills	Per-community skill files — writes .claude/skills/generated/<community>.md for each detected functional cluster; each skill includes key files, entry points, cross-area dependencies, and common operations

v3.20.0 — Team Dashboard Parity

Team Dashboard brought to full visual and UX parity with the Grasp app — teal brand tokens, Lucide SVG icons throughout, multi-provider auth (GitLab, GitHub Enterprise, Bitbucket, Azure DevOps, Gitea) with shared localStorage keys, mobile More-menu at ≤860px, auth-bar flex-wrap, and a keyboard shortcut popover (kbd-fab).

v3.18.0 — Graph Analytics & LLM Context

Tool	Description
grasp_hub_nodes	Top-N most connected files by fan-in + fan-out (degree centrality). Identifies architectural hubs
grasp_bridge_nodes	Brandes betweenness centrality. Files that sit on the critical path between others. Auto-samples 100 sources for repos > 500 nodes
grasp_surprising_connections	Rare cross-layer edges, flagged by frequency-weighted rarity. Likely architecture violations
grasp_knowledge_gaps	Isolated files (no edges, not test/fixture), untested high-call-count hotspots, weak communities (small layers with high outgoing coupling)
grasp_suggested_questions	Auto-generates 5–10 review questions composing hubs + bridges + circular deps + duplicates + layer violations
grasp_minimal_context	Sub-100-token repo orientation. The LLM's first call before deeper queries. Returns top hubs, layer breakdown, language list, health summary
grasp_traverse	Token-budget-aware BFS from a start node. Walks file/function graph until budget or depth exhausts. Returns truncated view with remaining-budget
grasp_semantic_search	Cosine-similarity over function signatures via @xenova/transformers (Xenova/all-MiniLM-L6-v2). 15s embedder-load timeout race with substring keyword fallback. Capped at 2,000 sigs
grasp_apply_refactor	Executes rename ops with dry_run preview default. dry_run=false writes files back to disk for local sources
grasp_architecture_overview	Combined community + hub + question report. Single executive summary for new contributors / reviewers
grasp_export_graphml	yEd / Gephi-compatible GraphML XML export of the dependency graph
grasp_export_cypher	Neo4j CREATE statements that reproduce the full graph for offline analysis
grasp_export_obsidian	.canvas JSON for Obsidian Canvas with per-layer column layout
grasp_export_dot	Graphviz DOT (digraph) with rankdir=LR, layer subgraph clusters, layer-coloured nodes, and labelled edges. Default cap 200 nodes (most-connected first) — set max_nodes to override
grasp_export_mermaid	Mermaid graph LR with one subgraph per layer. Renders inline on GitHub / GitLab / Notion / Obsidian
grasp_export_d2	Terrastruct D2 (direction: right) with layer containers and labelled imports edges. Render via the d2 CLI
grasp_export_plantuml	PlantUML class diagram (@startuml ... @enduml, !theme cerulean) with package per layer. Works in Confluence, Jira, IntelliJ, VS Code, the PlantUML server
grasp_export_dgml	Visual Studio Directed Graph (DGML) XML. Opens natively in the VS Architecture window with one Category per layer
grasp_export_gexf	Gephi-native GEXF 1.3 with layer / lines / complexity / churn node attributes plus weighted edges
grasp_export_drawio	draw.io / diagrams.net XML with simple grid layout (column per layer). Open and edit in https://app.diagrams.net or the VS Code draw.io extension
grasp_export_csv	Three CSVs (files / connections / issues) concatenated with --- <name>.csv --- separators. Pass format=files|connections|issues for a single sheet, default bundle for all three

MCP Resources (v3.15.0)

8 live data URIs consumable directly by MCP clients without tool calls:

Resource URI	Description
grasp://repos	List all repos indexed in the brain store
grasp://setup	AGENTS.md-style context block for all indexed repos
grasp://repo/{repoId}/context	Codebase stats, health grade, staleness check
grasp://repo/{repoId}/clusters	All functional communities from Louvain detection
grasp://repo/{repoId}/processes	All execution processes traced from entry points
grasp://repo/{repoId}/schema	Kuzu node/edge counts + schema definition
grasp://repo/{repoId}/cluster/{clusterName}	Deep dive into one functional community
grasp://repo/{repoId}/process/{processName}	Step-by-step execution process trace

MCP Prompts (v3.15.0)

Prompt	Args	Description
detect_impact	source, scope?, base_ref?	Guided multi-step workflow: detect changes → identify affected symbols → trace processes → assess risk → suggest test scope
generate_map	source?, format?	Guided multi-step workflow: list repos → run grasp_analyze → architecture diagram → list communities → generate wiki

Example Usage

"Analyze the express repo"
  → grasp_analyze("expressjs/express")

"What would break if I change src/router/index.js?"
  → grasp_dependents(session_id, "src/router/index.js")

"Are there any circular dependencies?"
  → grasp_cycles(session_id)

"Which files are riskiest to touch?"
  → grasp_hotspots(session_id)

"Show me the architecture layers"
  → grasp_architecture(session_id)

"What files changed most often together in the last 20 commits?"
  → grasp_timeline(session_id, n=20)

"Are there duplicate code blocks I should clean up?"
  → grasp_similarity(session_id)

"Give me a refactor plan for src/services/auth.ts"
  → grasp_refactor(session_id, file="src/services/auth.ts")

"Compare main and feature branch analyses"
  → grasp_cross_repo(session_id_a, session_id_b)

"Generate a PR comment for these changed files"
  → grasp_pr_comment(session_id, changed_files=["src/auth.ts","src/router.ts"])

"Which npm packages are declared but never actually imported?"
  → grasp_dead_packages(session_id)

"Export this session as SARIF for GitHub Code Scanning"
  → grasp_sarif(session_id)

"Show me which files actually call each other at runtime"
  → grasp_runtime_calls(trace_json="...", session_id=session_id)

"Which database tables are touched by the most files?"
  → grasp_db_coupling(session_id)

"Plan a migration from moment.js to date-fns"
  → grasp_migration_plan(session_id, from_package="moment", to_package="date-fns")

"Map all our API endpoints across Express routes and our OpenAPI spec"
  → grasp_api_surface(session_id)

"How many commits landed in express/express in the last 7 days?"
  → grasp_commits("expressjs/express")

"Is CI passing on vuejs/vue right now?"
  → grasp_ci_status("vuejs/vue")

"How many commits landed since my last analysis at 2026-04-10T12:00:00Z?"
  → grasp_commits("owner/repo", since_timestamp="2026-04-10T12:00:00Z")

"Which requirements are not covered by any code? Upload our REQ-NNN CSV."
  → grasp_req_trace(session_id, requirements=[{id:"REQ-001",desc:"Input validation",level:"A"},...])

"Which file in our codebase is most suspicious for this anomaly? Trace callers and callees."
  → grasp_anomaly(session_id, suspect_file="src/sensor/parser.c")

"Can we safely reuse the auth module from project A in project B?"
  → grasp_reuse(session_id_candidate, session_id_target, module_path="src/auth")

"Which code paths reach an output without passing through a safety gate?"
  → grasp_safety_trace(session_id, gates=["src/filters/constitutional_ai.py","src/output/sanitizer.py"])

"What changed semantically between training run A and run B?"
  → grasp_run_diff(session_id, config_a="...", config_b="...", format="yaml")

"Which parts of the model code are NOT exercised by any eval script?"
  → grasp_eval_coverage(session_id, eval_patterns=["evals/","*_eval.py"])

"Generate a CycloneDX SBOM with CVE data for this repo."
  → grasp_sbom(session_id, format="cyclonedx", include_vulns=true)

"What are our DORA metrics — deployment frequency, lead time, failure rate?"
  → grasp_dora(session_id, token="ghp_...")

"How much technical debt do we have in developer-days?"
  → grasp_adr(session_id, focus_files=["src/auth.ts","src/router.ts"], llm_provider="anthropic", api_key="sk-ant-...")

GitHub Token

For large repos (>100 files), pass a GitHub PAT to avoid rate limiting:

grasp_analyze("owner/repo", token="ghp_...")

Without a token: 60 req/hour. With a token: 5,000 req/hour.

GitLab Support

Grasp works with gitlab.com and self-hosted GitLab instances.

Token auth (quickest)

# Set env vars — works for all MCP tools
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
export GITLAB_HOST=gitlab.internal.company.com   # omit for gitlab.com

Self-hosted Docker bot (automated MR comments)

cd deploy
cp .env.gitlab.example .env.gitlab
# Edit .env.gitlab with your GITLAB_HOST, GITLAB_TOKEN, WEBHOOK_SECRET
docker compose -f docker-compose.gitlab.yml --env-file .env.gitlab up -d

Then register a GitLab webhook pointing to http://your-host:7332/webhook with your WEBHOOK_SECRET.

Tunnel agent (internal GitLab, no inbound ports needed)

docker run ghcr.io/ashfordeou/grasp-agent:latest \
  --token=<your-agent-token> \
  --gitlab-host=gitlab.internal.company.com

CLI

Grasp ships a grasp CLI alongside the MCP server:

# Analyze a local directory
npx grasp analyze ./my-project

# Export analysis as SARIF (for GitHub Code Scanning)
npx grasp analyze ./my-project --format=sarif --output=grasp.sarif

# Scan declared dependencies for known CVEs (OSV.dev)
# Exits 1 if any critical or high vulnerability — drop into CI as a quality gate
grasp vulns ./my-project

# Detect architecture drift vs the last snapshot — exits 1 on CRITICAL drift
grasp drift ./my-project

# Generate a multi-repo org dashboard (HTML / JSON / Markdown)
grasp org my-github-org --format=html --max=20

# One-command MCP auto-config for Claude Code, Cursor, Windsurf, Codex, OpenCode
grasp setup

JetBrains Plugin

A JetBrains IDE plugin (IntelliJ IDEA, WebStorm, PyCharm, GoLand) is available under jetbrains-plugin/. It adds:

• Tool window — interactive dependency graph rendered in JCEF, falls back to text summary
• Status bar widget — live health score (e.g. ⬡ 87 B) with click-to-open
• Editor annotations — inline warnings for layer violations and circular deps
• File-save re-analysis — automatic re-analysis on save for watched extensions
• Settings — configurable CLI path, annotation toggles

Build with ./gradlew buildPlugin from jetbrains-plugin/.

SaaS API Server

A lightweight hosted analysis API lives under saas/. It wraps Grasp analysis behind:

• Redis/LRU cache — identical requests served instantly, configurable TTL
• Sliding-window rate limiter — per-key, configurable limits
• Async job queue — POST returns 202 immediately; analysis runs in background
• POST /analyze — accepts { repo: "owner/repo" } or { repo: "https://github.com/..." }

cd saas && npm install && npm run build && npm start

Slack / Teams Bot

Automated health alerts and weekly digests live under slack-bot/. Features:

• Hourly regression alerts — fires when score drops ≥10 points, new security issues, or new circular deps appear
• Weekly digest — configurable cron (default Monday 09:00) with multi-repo summary
• Slack Block Kit and MS Teams Adaptive Cards (v1.4) formatting
• Configurable via environment variables (SLACK_WEBHOOK_URL, TEAMS_WEBHOOK_URL, GRASP_REPOS, etc.)

cd slack-bot && npm install && npm run build && npm start

GitHub Actions Workflows

Workflow	Trigger	Purpose
ci.yml	Push / PR to main	Build, test, lint
publish.yml	Push tag v*	Publish to npm
grasp-sarif.yml	Push to main	Self-analysis → SARIF → GitHub Code Scanning
grasp-health.yml	Schedule (daily)	Post health summary as commit status

Claude Code Slash Commands

Three pre-built slash commands ship under .claude/commands/ so any Claude Code workspace can invoke Grasp's most common flows in one step:

Command	What it does
/grasp:build-graph	Runs grasp_analyze on the current dir + grasp_minimal_context for a sub-100-token orientation
/grasp:review-delta	Detects changes since the base branch and produces a risk-scored impact report
/grasp:review-pr	Full PR review composing grasp_detect_changes + grasp_suggested_questions + grasp_surprising_connections + grasp_knowledge_gaps

Each command is a markdown file (.claude/commands/grasp-*.md) with allowed-tools and a template body — edit them in-repo to customize.

Workflow Tip

Always call grasp_analyze first — it returns a session_id that all other tools require. Sessions are held in memory and expire when the MCP server restarts.

In-app help: when running the browser app, press ? to open a floating popover listing every shortcut, tab, and overlay. The Team Dashboard (team-dashboard.html) ships its own help modal.

Privacy

Grasp does not collect any data. The MCP server runs as a local subprocess; the only outbound calls are to the GitHub/GitLab API, OSV.dev for CVE lookups, and (optionally) the AI provider you configure. Your code never passes through an Ashforde server. Full privacy policy: PRIVACY.md.