Grasp — Code Architecture & Dependency Analysis

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.

[Grasp dependency graph] 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.3 — 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-timesigstore verify npm [email protected]

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:latest

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 itgrasp_kg_ask   { "question": "How does auth flow through the billing service?" }grasp_kg_trace { "from": "Auth", "to": "Postgres" }     // shortest relationship pathgrasp_kg_explain { "name": "Billing Service" }          // neighbourhood + sourcesgrasp_kg_stats {}                                       // counts + god-nodesgrasp_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.

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 mcpnpm installnpm 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

History & Comparison

Code Quality

Ecosystem Integration

Runtime & Infrastructure Intelligence

GitHub Activity

Codebase Intelligence (v2.4–v2.9)

Aerospace / Safety-Critical

AI Research / AI Safety

Enterprise / Compliance

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

Finance / Compliance (v3.5.x)

OS / Kernel (v3.6.x)

Open Source (v3.7.x)

Ada / Heritage (v3.8.x)

Graph Tools (New in v3.11.0)

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+)

Semantic Search & Rename (v3.14+)

Graph Intelligence (v3.15.0)

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

MCP Resources (v3.15.0)

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

MCP Prompts (v3.15.0)

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 toolsexport GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxxexport GITLAB_HOST=gitlab.internal.company.com   # omit for gitlab.com

Self-hosted Docker bot (automated MR comments)

cd deploycp .env.gitlab.example .env.gitlab# Edit .env.gitlab with your GITLAB_HOST, GITLAB_TOKEN, WEBHOOK_SECRETdocker 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 directorynpx 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 gategrasp vulns ./my-project
# Detect architecture drift vs the last snapshot — exits 1 on CRITICAL driftgrasp 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, OpenCodegrasp 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

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:

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.