grasp-mcp-server a

The code architecture suite — dependency graphs, health scores & security, everywhere you work.

         

🌐 Browser App  ·  📦 MCP Server  ·  🐛 Report Bug  ·  ✨ Request Feature  ·  🔒 Privacy

What is Grasp?

Ever opened a new codebase and felt completely lost? Grasp turns any GitHub or GitLab repository — cloud or self-hosted — or local codebase into an interactive architecture map in seconds.

Paste URL / Open Folder  →  AST Analysis Engine  →  See Architecture + Make Better Decisions

Screenshots

🕸️ Dependency Graph — see exactly how files connect

🏛️ Architecture Diagram — your codebase by layer

📦 Treemap — files sized by line count

🏢 Team Dashboard — health across all your repos at a glance

Quick Start

Option 1 — Browser (zero setup)

git clone https://github.com/ashfordeOU/grasp.git
open index.html           # Main app
open team-dashboard.html  # Team Dashboard

No build step. No npm install. Two HTML files.

Option 2 — CLI

npm install -g grasp-mcp-server

grasp ./my-project        # Analyse a local folder
grasp facebook/react      # Analyse a GitHub repo
grasp .                   # Analyse current directory
grasp . --watch           # Live mode — browser reloads on every file save
grasp . --timeline        # Time-travel — last 30 commits as a scrubber
grasp . --report          # Terminal-only report + JSON output
grasp . --format=sarif    # Export SARIF for GitHub Code Scanning
grasp . --pr-comment      # Print GitHub PR comment markdown to stdout
grasp . --check           # Enforce grasp.yml architecture rules (CI gate)

Option 3 — IDE Extensions

Option 4 — Browser Extension

A floating Grasp button appears on every GitHub and GitLab page. Supports self-hosted GitLab, GitHub Enterprise, and any custom host via on-demand permission grants.

curl -sL https://github.com/ashfordeOU/grasp/releases/latest/download/grasp-safari-extension.zip \
  -o /tmp/grasp-safari.zip \
  && unzip -q /tmp/grasp-safari.zip -d /tmp/grasp-safari \
  && mv /tmp/grasp-safari/Grasp.app /Applications/ \
  && open /Applications/Grasp.app

How It Works

┌─────────────────────────────────────────────────────────────┐
│  Input                                                       │
│  github.com/owner/repo  ·  gitlab.com/ns/proj  ·  ./folder  │
└───────────────────────────────┬─────────────────────────────┘
                                ▼
┌─────────────────────────────────────────────────────────────┐
│  Tree-sitter AST Parser (16 languages, native bindings)      │
│                                                              │
│  • Dependency extraction      • Layer classification         │
│  • Cyclomatic complexity      • Security pattern detection   │
│  • Function call graph        • Dead code analysis           │
└───────────┬─────────────────────────┬───────────────────────┘
            │                         │
    ┌───────▼────────┐     ┌──────────▼─────────┐
    │  Browser App   │     │   MCP Server (CLI)  │
    │  index.html    │     │   grasp-mcp-server  │
    │                │     │                     │
    │  9 graph views │     │  70+ agent tools    │
    │  16 color modes│     │  Brain store        │
    │  AI Chat       │     │  CI/CD reports      │
    │  Ask Grasp     │     │  SARIF / SBOM       │
    │  Team Dashboard│     │  Arch diff          │
    └────────────────┘     └─────────────────────┘

Visualizations

Graph Types

Color Modes

Code Intelligence

📊 Health Score

Instant A–F grade based on dead code, circular dependencies, coupling metrics, and security issues. Displayed as a score (0–100) with a visual bar.

🔐 Security Scanner

Automatic detection of hardcoded secrets & API keys, SQL injection risks, dangerous eval() usage, and debug statements left in production.

🧩 Pattern Detection

Identifies Singleton, Factory, Observer/Event patterns, React hooks, and anti-patterns (God Objects, high coupling) — automatically.

💥 Blast Radius Analysis

"If I change this file, what breaks?" — select any file and see every downstream file that would be affected, highlighted on the graph.

🔥 Activity Heatmap

Colors files by commit frequency. Works for GitHub repos (via API) and local repos (via git log — no internet required).

🔎 Duplicate & Similarity Detection

The Dup color mode highlights files with exact or near-duplicate code. The grasp_similarity MCP tool returns ranked duplicate clusters for targeted refactoring.

👥 Code Ownership

Top contributors per file from git history, with line-percentage breakdowns. One-click jump to GitHub Blame.

📋 PR Impact Analysis

Paste a PR URL to see which files it touches and calculate the blast radius of proposed changes before merging.

💰 Technical Debt Quantification

Converts every architectural issue into developer-hours using configurable estimates — circular dep = 4h, god file = 16h, critical security = 8h — with a coupling multiplier. Shown in the health panel and Team Dashboard.

🔗 Shareable Embeds

Click ⋯ → 🔗 Embed for a ready-to-paste <iframe>, README badge, React snippet, and direct link — share live health reports in docs, wikis, or dashboards.

AI Chat — 15 Providers

Built-in AI assistant that knows your entire codebase. Ask "why is auth.ts a hotspot?", "which files are safest to refactor?", or "explain the security issues in this call chain" — answers reference your live dependency graph, security findings, and architectural layers.

Features:

• Multi-turn conversation memory — persisted in localStorage across page refreshes
• Selected-file context — layer, functions, complexity, and issues injected automatically when a file is selected
• Rich codebase context — top 80 files with metadata, all issues, security findings, circular deps, layer breakdown
• Markdown rendering with syntax-highlighted code blocks
• API key stays in your browser only, never sent anywhere except the chosen provider

Grasp Brain — Persistent Architecture Intelligence (v3.10.0)

Grasp Brain is a persistent SQLite store (~/.grasp/brain.db) that remembers your codebase across sessions. Index once, then query instantly — no re-analysis needed.

How it works

grasp index ./my-project    →  analysis stored in ~/.grasp/brain.db
grasp context src/api.ts    →  instant file context from the stored index
grasp diff ./my-project     →  compare current state vs stored baseline
grasp daemon ./my-project   →  watch for changes, re-index automatically

CLI Subcommands

grasp index <path>           # Analyse and persist a repo to the brain
grasp context <src> <file>   # Get rich context for any file
grasp setup [path]           # Install hooks in Claude Code / Cursor / Windsurf
grasp diff <path>            # Compare current analysis vs brain baseline
grasp daemon <path>          # Watch directory and auto-reindex on changes

Ask Grasp — Natural Language Architecture Queries

Both the browser app (Ask Grasp panel) and grasp_ask MCP tool support plain-English questions about your codebase:

Arch Diff

grasp diff (and grasp_arch_diff MCP tool) compares your current codebase against the stored brain baseline and surfaces:

• Grade degradations (files that got worse: A→B, B→C, etc.)
• Health score delta
• New security issues introduced since baseline

Editor Hooks (grasp setup)

Detects .claude/, .cursor/, .windsurf/ in your repo and installs a pre-tool-use hook that automatically gives your AI coding assistant codebase context before every action. Also writes CLAUDE.md and AGENTS.md with architecture summaries.

Team & Collaboration

🏢 Team Dashboard

Track health across multiple repos in one view. Add any public (or private, with a token) GitHub repo and see:

• Health score, grade, files, issues
• Circular deps, security findings, architectural layers
• Commit activity (7d / 30d) and CI status (✅/❌/⏳)
• Commit velocity sparkline
• Technical debt in developer-days

Export the full table as CSV or JSON. Open local folders with 📁 Open Folder (File System Access API).

🔄 Live Team Collaboration

Grasp's CLI hosts a real-time collaboration server for your whole team:

npx grasp --host=0.0.0.0 --room-secrets=backend:pass1,frontend:pass2
#   → main app:       http://server-ip:7331/
#   → team dashboard: http://server-ip:7331/dashboard
#   → health check:   http://server-ip:7331/api/health

• WebSocket sync — workspace changes propagate to all connected team members instantly
• Named rooms — ?sync_room=backend-team isolates each team's workspace
• Presence indicators — see who's online in the Sync panel
• Share links — ⎘ Copy team link or 👁 Copy read-only link
• Read-only mode — ?readonly=1 for observers
• Password protection — --room-secrets=room:password
• REST API — GET /api/health · GET /api/rooms · GET/PUT /api/workspace/:room

LAN hosting: anyone on the same network accesses http://server-ip:7331/dashboard — no cloud needed.

🏢 Monorepo & Workspace Support

Grasp automatically detects sub-packages in monorepos (package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml). A Workspace sidebar lets you filter to a single package — all graphs, treemaps, and metrics update instantly.

⏮️ Time-Travel Architecture Scrubber

Run grasp . --timeline to load your last 30 git commits as a scrubber panel. Drag the slider to any commit — changed nodes glow yellow on the graph so you can watch your architecture evolve over time.

📡 Live Watch Mode

Run grasp . --watch for a local dev server with real-time SSE sync. Every file save reloads the browser graph automatically — a LIVE badge appears while connected.

Industry Verticals

✈️ Aerospace / Safety-Critical

🧠 AI Research

🏢 Enterprise

For AI Agents — MCP Server

Grasp ships a Model Context Protocol (MCP) server that exposes the full analysis engine as callable tools for Claude Code, Cursor, and any MCP-compatible agent.

Setup

# Install
npm install -g grasp-mcp-server

# Or run without installing
npx grasp-mcp-server

Add to ~/.claude/claude_mcp_settings.json:

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

Works with GitHub repos and local directories. See mcp/README.md for GitLab, Docker, and self-hosted options.

Tools Reference

Core Analysis

File & Code Intelligence

Security & Compliance

Team & DevOps

Brain / Intelligence (v3.10.0)

Advanced Analysis

Aerospace / Safety-Critical Vertical

AI Research Vertical

Multi-Repo / Platform

CI/CD Integration

GitHub Actions — Automatic PR Comments

# .github/workflows/grasp.yml
name: Grasp Health Check
on:
  pull_request:
    types: [opened, synchronize, reopened]
jobs:
  health:
    uses: ashfordeOU/grasp/.github/workflows/grasp-health.yml@main

The workflow posts and updates a comment on every PR:

Architecture Rules (grasp.yml)

rules:
  - min_health_score: 70       # fail CI if score drops below 70
  - max_blast_radius: 20       # flag any file affecting 20+ others

Run locally with grasp . --check, or use the GitHub Actions template.

CLI-based CI Gate

grasp . --report   # Writes grasp-report.json, exit 0 = pass, exit 1 = fail

- name: Grasp health gate
  run: |
    PASSED=$(cat grasp-report.json | jq '.ci.passed')
    SCORE=$(cat grasp-report.json | jq '.ci.score')
    echo "Health score: $SCORE"
    if [ "$PASSED" != "true" ]; then
      cat grasp-report.json | jq '.ci.failures'
      exit 1
    fi

See docs/api-schema.md for the full export schema.

SARIF Upload (GitHub Code Scanning)

grasp . --format=sarif   # Writes grasp-results.sarif

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: grasp-results.sarif

Advanced Features

⚡ Command Palette

Cmd+K (Mac) / Ctrl+K (Windows) — search files, jump to functions, navigate to issues. Selecting a result pans the graph to that node.

🔍 Path Finder

Select two files in the details panel to find the shortest dependency chain between them.

🏛️ Architecture Rule Engine

Define custom FORBIDDEN dependency rules (e.g., utils → services is FORBIDDEN). Violations are flagged as issues and persist across sessions.

📅 History & Snapshots

Every analysis is saved automatically. Click HISTORY in the right panel to compare health scores over time with a D3 sparkline and range slider.

🚫 Custom Ignore Patterns

⋯ → 🚫 Ignore Patterns — add directory exclusions (e.g., generated/, __mocks__/). Persists across sessions. Built-in defaults (node_modules, dist, .git) cannot be removed.

📤 Export Reports

JSON, Markdown, Plain Text, SVG, SARIF 2.1.0. Full schema in docs/api-schema.md.

🤖 AI Coding Tool Support

Grasp works via MCP with all major AI coding tools: Claude Code, Cursor, Cline, Roo Code, Kilo Code, OpenCode, Trae, Grok CLI, Codex CLI, Droid

See ai-tools/ for per-tool setup guides.

🔖 Health Badge

![Grasp Health](https://grasp.ashforde.org/badge/owner/repo.svg)

@grasp-bot in PRs

Comment @grasp-bot analyze on any PR — Grasp posts a full health report inline.

VS Code Extension

• Auto-analyses workspace on startup, re-analyses on file save (2s debounce)
• Status bar shows ↑ N deps ↓ M dependents for the active file
• Pans to the active file on every editor switch
• Surfaces security issues and arch violations in the Problems panel (squiggly lines)
• 4 color mode buttons in the panel header: Layer / Folder / Churn / Complexity
• Health score badge in the panel header
• Double-click any node to open the file in the editor
• Right-click any file → Grasp: Analyze File for instant details
• Directed links: blue = outgoing imports, green = incoming dependents
• Rich tooltips: complexity, churn count, top contributor per file

Keyboard Shortcuts

19 Themes

Full theme system with hover picker and click-to-cycle:

Dark · Light · Matrix · Amber Terminal · Dracula · Nord · Tokyo Night · Catppuccin · Gruvbox · Obsidian Gold · Midnight Diamond · Carbon · Noir · Synthwave · Ocean Depth · Forest · Sunset · High Contrast · Solarized Light

Theme choice persists across sessions and is shared between Grasp and Team Dashboard.

Supported Languages

JavaScript · TypeScript · Python · Go · Java · Rust · C · C++ · C# · Ruby · PHP · Swift · Kotlin · Scala · Vue · Svelte · Dart · Elixir · Erlang · Haskell · Lua · R · Julia · Perl · Shell · PowerShell · F# · OCaml · Clojure · Elm · VBA · Groovy · Ada · Zig

GitHub API Rate Limits

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                          Analysis Engine  (mcp/src/)                    │
│                                                                         │
│  ┌──────────────────────┐   ┌──────────────────────────────────────┐   │
│  │  AST Parser          │   │  Analyzer                            │   │
│  │  tree-sitter WASM    │   │  · Dependency extraction             │   │
│  │  16 languages        │   │  · Cyclomatic complexity             │   │
│  │  native bindings     │   │  · Layer classification              │   │
│  └──────────────────────┘   │  · Security pattern detection        │   │
│                              │  · Dead code & duplicate analysis    │   │
│  ┌──────────────────────┐   └──────────────────────────────────────┘   │
│  │  Source Adapters     │                                               │
│  │  GitHub  · GitLab    │   ┌──────────────────────────────────────┐   │
│  │  Azure   · Bitbucket │   │  Brain Store  (~/.grasp/brain.db)    │   │
│  │  Gitea   · Local FS  │   │  SQLite · repos / files / edges      │   │
│  └──────────────────────┘   └──────────────────────────────────────┘   │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┼─────────────────────────┐
           ▼                         ▼                         ▼
┌─────────────────────┐  ┌───────────────────────┐  ┌──────────────────────┐
│    Browser Apps     │  │   MCP Server + CLI    │  │   IDE Extensions     │
│                     │  │   (grasp-mcp-server)  │  │                      │
│  index.html         │  │                       │  │  VS Code             │
│  · React + D3       │  │  70+ MCP tools        │  │  JetBrains           │
│  · 9 graph views    │  │  Brain (SQLite)        │  │  Zed                 │
│  · AI Chat (15 prov)│  │  Ask architecture     │  │  Neovim · Vim        │
│  · Ask Grasp panel  │  │  Arch diff            │  │  Emacs               │
│  · 19 themes        │  │  WatchDaemon          │  │  Eclipse             │
│                     │  │                       │  │  Continue            │
│  team-dashboard.html│  │  CLI flags:           │  │                      │
│  · Multi-repo health│  │  --watch  --timeline  │  │  Browser Extensions  │
│  · DORA + sparklines│  │  --report --check     │  │  Chrome · Firefox    │
│  · WebSocket rooms  │  │  --format=sarif       │  │  Safari              │
│  · LAN hosting      │  │  --pr-comment         │  │                      │
└─────────────────────┘  └───────────────────────┘  └──────────────────────┘
           │                         │                         │
           └─────────────────────────┴─────────────────────────┘
                                     │
┌────────────────────────────────────▼────────────────────────────────────┐
│                           Integrations                                  │
│                                                                         │
│  CI/CD             Bots & Alerts       AI Coding Tools   Project Mgmt  │
│  GitHub Action     Slack Bot           Claude Code       Jira          │
│  GitLab CI         Discord Bot         Cursor            Linear        │
│  Bitbucket Pipe    Teams Bot           Copilot Extension Raycast       │
│  CircleCI Orb      @grasp-bot          Amazon Q                        │
│  Jenkins Plugin                        GPT Actions                     │
│                                        Cline · Roo · Droid             │
│                                                                         │
│  SaaS / Cloud: grasp.dev API · badge service · GitHub OAuth           │
└─────────────────────────────────────────────────────────────────────────┘

Browser app: zero dependencies to install. React 18, D3.js 7, Babel from CDNs. Tree-sitter WASM grammars load lazily and cache in IndexedDB.

MCP server: Node.js 18+. Native tree-sitter bindings for AST-backed function extraction and cyclomatic complexity across 16 languages: Python, Go, Java, Kotlin, Rust, C, C++, C#, Ruby, JavaScript, TypeScript, TSX, Swift, PHP, Scala, Zig.

Brain store: persistent SQLite at ~/.grasp/brain.db — repos, files, functions, edges, with full transactional writes and indexed queries.

IDE extensions: VS Code (vscode-extension/), JetBrains (jetbrains-plugin/), Zed, Neovim, Vim, Emacs, Eclipse, Continue — all backed by the same MCP server.

Browser extensions: Chrome, Firefox, and Safari (browser-extension/, safari-extension/) — MV3, inject a floating Grasp button on GitHub and GitLab pages.

Version & Auto-Update

Both index.html and team-dashboard.html display the current version (v3.10.0) in the footer. On load, they silently check the npm registry for a newer release. If found, a dismissible toast appears:

• Update Now — fetches the new HTML from GitHub, downloads it, and applies it immediately
• Later — snoozes for 24 hours

No server, no background process.

Privacy & Security

Your code stays on your machine.

Browser app:

• Runs 100% in the browser — no server, no proxy
• GitHub/GitLab API calls go directly from your browser to the provider
• Your token lives in localStorage only — never sent anywhere except the chosen Git provider
• No analytics, no tracking, no accounts
• The entire app is one open-source HTML file — audit it yourself

MCP server:

• Runs locally as a subprocess — no outbound connections except the GitHub/GitLab API
• No telemetry, no data collection
• Local directory analysis is read and discarded in memory; Brain store stays on your machine at ~/.grasp/brain.db

Contributing

See CONTRIBUTING.md for setup, code structure, and PR checklist.

Found a bug? Open an issue

Adding a language? Tree-sitter grammar sources are in mcp/src/extractors/ — follow the existing pattern for a new language file.

Adding an MCP tool? Register in mcp/src/index.ts following the existing server.registerTool pattern. Add tests in mcp/tests/.

License

Elastic License 2.0 — Copyright (c) 2026 Ashforde OÜ.

Free to use, modify, and self-host. You may not offer Grasp as a hosted or managed service, strip copyright notices, or redistribute it under a different brand. See LICENSE for full terms.