grasp-mcp-server

Report Bug · Request Feature

Why Grasp?

Ever opened a new codebase and felt completely lost? Grasp turns any GitHub repository or local codebase into an interactive architecture map in seconds — no setup, no accounts, no data leaving your machine.

Paste URL / Select Files → See Architecture → Make Better Decisions

• No installation — runs 100% in your browser

• No data collection — your code never leaves your machine

• No accounts — paste a URL and go

• Works offline — analyze local files without internet

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

Features

🏛️ Architecture Diagram

Layer-by-layer diagram of your entire codebase. Components grouped by architectural layer (Config, Utils, Data, Services, Components, UI, Test) with dependency arrows between them. Pan, zoom, click any block to explore.

🕸️ Interactive Dependency Graph

Force-directed graph showing how every file connects. Click any node to highlight its dependencies. Drag, zoom, multi-select with Shift+click.

💥 Blast Radius Analysis

"If I change this file, what breaks?" — Select any file and see exactly how many files would be affected, highlighted directly on the graph.

👥 Code Ownership

Top contributors for any file based on git history, with line-percentage breakdowns. One-click jump to GitHub Blame.

🔐 Security Scanner

Automatic detection of:

• Hardcoded secrets & API keys

• SQL injection vulnerabilities

• Dangerous eval() usage

• Debug statements left in production

🧩 Pattern Detection

Automatically identifies Singleton, Factory, Observer/Event patterns, React custom hooks, and anti-patterns (God Objects, high coupling).

📊 Health Score

Instant A–F grade based on dead code percentage, circular dependencies, coupling metrics, and security issues.

🔥 Activity Heatmap

Color files by commit frequency to see the hot spots in your codebase. Works for both GitHub repos (via API) and local repos (via git log — no internet required).

🔍 Graph Node Filtering

Type in the filter bar at the top of the graph to instantly narrow 200+ nodes down to just the files you care about — matching nodes stay visible, their direct connections dim in, everything else fades out. Press Escape to clear.

🚫 Custom Ignore Patterns

Add your own directory exclusions (e.g. generated/, __mocks__/, fixtures/) via the ⋯ → 🚫 Ignore Patterns menu. Persists across sessions. Built-in defaults (node_modules, dist, .git, etc.) cannot be removed.

📋 PR Impact Analysis

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

📡 Live Watch Mode

Run grasp . --watch to start a local dev server with real-time SSE sync. Every time you save a file, the browser graph reloads automatically — no manual refresh. A LIVE badge appears in the top bar while connected.

⏮️ Time-Travel Architecture Scrubber

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

🏢 Team Dashboard (team-dashboard.html)

Track health across multiple repos in one view. Add any public (or private, with a token) GitHub repo and see score, grade, files, issues, circular deps, security findings, architectural layers, commit activity (7d / 30d), CI status (✅/❌/⏳), and a commit velocity sparkline — all in a live table with bar charts. Token is shared with the main Grasp app so you only set it once. Export the full table as CSV. Open local folders with 📁 Open Folder (File System Access API).

🤖 AI Chat Panel

Built-in AI assistant that knows your codebase. Ask questions like "why is auth.ts a hotspot?" or "which files are safest to refactor?" — it answers with direct references to your dependency graph. Supports Anthropic Claude and OpenAI GPT models. API key stays in your browser only.

🎨 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.

🔎 Duplicate & Similarity Detection

The Dup color mode highlights files with exact or near-duplicate code — bright red = many duplicates, orange = some, yellow = minor. The grasp_similarity MCP tool returns ranked duplicate clusters and code-clone groups for targeted refactoring.

🏢 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 the entire visualization to a single package — all graphs, treemaps, and metrics update instantly.

🧰 Refactor Wizard

The Refactor hints panel (click any file in the graph) shows a prioritized, step-by-step refactor plan for that file — based on fan-in, complexity, duplicate count, layer violations, and churn. The grasp_refactor MCP tool generates the same plan as structured output for agents.

🔗 Shareable Embeds

Click ⋯ → 🔗 Embed for a modal with a ready-to-paste <iframe>, README badge (![Health](…)), React component snippet, and a direct link — for sharing live health reports in docs, wikis, or dashboards.

💻 Local File Analysis

• Privacy First — your code never leaves your machine

• Offline Support — works without internet

• Drag & Drop — drag files or folders straight onto the page

• Recursive scanning — analyze entire project structures

Quick Start

Option 1: Self-Host (30 seconds)

git clone https://github.com/ashfordeOU/grasp.git
cd grasp
open index.html           # Main app
open team-dashboard.html  # Team Dashboard (track multiple repos)

No build process. No dependencies. No npm install. Two HTML files.

Option 2: Analyze Local Files

1. Open index.html in your browser

2. Click 📁 Open Folder

3. Select the folder to analyze

4. Everything processes entirely in your browser

Option 3: CLI (terminal)

npm install -g grasp-mcp-server   # Install once
grasp ./my-project                 # Analyse a local folder
grasp facebook/react               # Analyse a GitHub repo
grasp .                            # Analyse current directory

Outputs a colour-coded health report and writes grasp-report.json.
Exit code 0 = CI pass, 1 = issues found.

# One-off with npx
npx --package=grasp-mcp-server grasp .

# Watch mode — browser reloads live on every file save
grasp . --watch

# Time-travel — load last 30 commits as a scrubber
grasp . --timeline

# PR comment output — print markdown report to stdout
grasp . --pr-comment

For LLM Agents & AI Tools — 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.

cd mcp && npm install && npm run build

Then add to ~/.claude/claude_mcp_settings.json:

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

Or run without installing:

npx grasp-mcp-server

36 tools available to agents:

Works with GitHub repos and local directories. See mcp/README.md for full setup.

Usage

Public Repositories

Just paste:   facebook/react
Or full URL:  https://github.com/facebook/react

Private Repositories

1. Create a GitHub Personal Access Token with repo scope

2. Select Token from the auth dropdown and paste it in

3. Analyze your private repos — token stays in memory only

Shareable Links

After analysis, click 🔗 to copy a link anyone can use to re-run the same analysis.

Visualization Modes

Graph Types

Color Modes

Advanced Features

⚡ Command Palette

Press Cmd+K (Mac) / Ctrl+K (Windows) — search files, navigate to any function, or jump to issues instantly. 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.

📤 Export Reports

Export as JSON, Markdown, Plain Text, or SVG. Full schema in docs/api-schema.md.

🧩 VS Code Extension

Install the extension (vscode-extension/) for a live dependency graph in your sidebar. Features:

• 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 displayed in the panel header

• Double-click any node to open the file in the editor

• Right-click any file in Explorer or Editor → Grasp: Analyze File for instant details

• Directed links: blue = outgoing imports, green = incoming dependents

• Rich tooltips showing complexity, churn count, and top contributor per file

Version & Auto-Update

Both index.html and team-dashboard.html display the current version (v2.2.0) in the footer. On load, they silently check the npm registry for a newer grasp-mcp-server release. If one is found, a dismissible toast appears:

• Update Now — fetches the new HTML from GitHub, downloads it to your machine, and applies it in the current tab immediately

• Later — snoozes for 24 hours

No server, no background process. The update check is a single npm registry fetch.

CI/CD Integration

GitHub Actions — Automatic PR Comments

Add this workflow to get an automatic health report on every PR:

# .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 like this on every PR:

CLI-based CI Gate

- name: Check Grasp health
  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
      echo "Grasp CI check failed"
      cat grasp-report.json | jq '.ci.failures'
      exit 1
    fi

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

Keyboard Shortcuts

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

Privacy & Security

Your code stays on your machine.

Browser app:

• Runs 100% in the browser — no server, no proxy

• GitHub API calls go directly from your browser to GitHub

• Your token (if used) lives in localStorage only — never sent anywhere except the GitHub API

• 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 API

• No telemetry, no data collection

• Local directory analysis never leaves your machine — files are read and discarded in memory

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                              Grasp v2.2.0                            │
├─────────────────────┬──────────────────┬────────────┬───────────────┤
│    Browser App      │  Team Dashboard  │ MCP Server │  VS Code Ext  │
│    (index.html)     │(team-dashboard   │  (mcp/)    │(vscode-ext/)  │
│                     │      .html)      │            │               │
│  ┌─────────────┐    │  ┌───────────┐   │ ┌────────┐ │ ┌───────────┐ │
│  │Parser Engine│◄───┼──│parser.js  │   │ │parser  │ │ │Webview    │ │
│  │(embedded JS)│    │  └─────┬─────┘   │ └───┬────┘ │ │(D3 graph) │ │
│  └──────┬──────┘    │        │         │     │      │ └─────┬─────┘ │
│         │           │  ┌─────▼──────┐  │ ┌───▼────┐ │       │       │
│  ┌──────▼──────┐    │  │Multi-repo  │  │ │analyze │ │ ┌─────▼─────┐ │
│  │React+D3     │    │  │health table│  │ └───┬────┘ │ │FileWatcher│ │
│  │19 themes    │    │  │score charts│  │     │      │ │Status Bar │ │
│  │AI Chat      │    │  │CSV export  │  │ ┌───▼────┐ │ │Diagnostics│ │
│  │3D Graph     │    │  └────────────┘  │ │36 Tools│ │ └───────────┘ │
│  │Timeline     │    │                  │ │(stdio) │ │               │
│  │Workspaces   │    │  Shared token &  │ └────────┘ │               │
│  └─────────────┘    │  theme via       │            │               │
│                     │  localStorage    │ + CLI      │ + context menu│
│  Zero install —     │                  │            │               │
│  one HTML file      │  one HTML file   │            │               │
└─────────────────────┴──────────────────┴────────────┴───────────────┘

Browser app: zero dependencies to install. Everything runs from CDNs: React 18, D3.js 7, Babel.

MCP server: Node.js 18+, npm install inside mcp/.

VS Code extension: vsce package inside vscode-extension/.

GitHub API Limits

Contributing

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

Ideas welcome:

• More languages (Zig, V, Nim, Crystal)

• Full tree-sitter / AST support for JS/TS function extraction (MCP + CLI now use acorn in Node.js)

• More design pattern detection (Strategy, Command, State)

• Export to PNG

• 3D force graph visualization mode

• 19-theme system with hover picker — Matrix, Synthwave, Dracula, Nord, Tokyo Night, Catppuccin, Gruvbox, Obsidian Gold, Midnight Diamond, Carbon, Noir, Amber Terminal, Ocean Depth, Forest, Sunset, High Contrast, Solarized Light

• Team Dashboard (team-dashboard.html) — multi-repo health tracking, commit activity (7d/30d), CI status badges, commit velocity sparkline, CSV export, shared token/theme, Open Folder

• AI Chat panel — ask questions about the dependency graph, Claude + OpenAI support

• Auto-update system — version check via npm registry, in-tab update + file download

• MCP: 36 tools total — added grasp_dead_packages, grasp_sarif, grasp_runtime_calls, grasp_db_coupling, grasp_migration_plan, grasp_api_surface, grasp_commits, grasp_ci_status

• MCP: grasp_diff tool — compare two snapshots over time

• MCP: grasp_suggest tool — refactoring suggestions from hotspot data

• MCP: grasp_explain tool — plain-English file/function explanation

• MCP: grasp_watch tool — re-analyse directory and diff against prior run

• MCP: grasp_unused tool — dead code detection for agents

• MCP: grasp_rules_check tool — architecture rule violations

• MCP: grasp_issues tool — GitHub Issues → file mention mapping

• MCP: grasp_contributors tool — per-file ownership and bus-factor

• MCP: grasp_bundle tool — bundle size treemap

• MCP: grasp_dep_impact tool — dependency upgrade impact analysis

• MCP: grasp_coverage tool — test file coverage overlay

• MCP: grasp_timeline tool — git history with co-change matrix

• MCP: grasp_pr_comment tool — PR health comment with blast radius

• MCP: grasp_embed tool — shareable iframe, badge, React snippet

• MCP: grasp_refactor tool — step-by-step refactor plan

• MCP: grasp_cross_repo tool — compare two sessions / monorepo support

• MCP: grasp_similarity tool — duplicate clusters and code clones

• MCP: grasp_dead_packages — npm deps declared but never imported

• MCP: grasp_sarif — SARIF 2.1.0 export for GitHub Code Scanning

• MCP: grasp_runtime_calls — merge live trace with static graph

• MCP: grasp_db_coupling — ORM/SQL table coupling map

• MCP: grasp_migration_plan — phased package migration plan

• MCP: grasp_api_surface — unified API surface from OpenAPI, GraphQL, Express/FastAPI routes

• CLI: grasp ./my-project opens browser pre-loaded (local server + --report for terminal)

• CLI: grasp . --watch — live SSE browser sync, LIVE badge in UI

• CLI: grasp . --timeline — inject last 30 commits as time-travel scrubber

• CLI: grasp . --pr-comment — print PR comment markdown to stdout

• GitHub Action: post health score as PR comment, updates on re-push

• Graph: Color modes for Duplicate density, Code Ownership, GitHub Issues, Coverage, Bundle, API Surface, Runtime

• Graph: Workspace sidebar for monorepo sub-package filtering

• Graph: Refactor hints panel per selected file

• Graph: Shareable embed modal (iframe, badge, direct link)

• Graph: Timeline scrubber — yellow glow on changed nodes per commit

• Graph: persist pinned node positions across sessions

• Graph: Cmd+K search pans to the matching node

• Graph: minimap overlay for large codebases

• Function-level call graph drill-down per file

• VS Code: auto-reanalyse on file save (2s debounce)

• VS Code: 4 color mode buttons in panel header

• VS Code: health score badge in panel header

• VS Code: double-click node to open file in editor

• VS Code: right-click → Grasp: Analyze File context menu

• VS Code: directed link colors (blue = outgoing, green = incoming)

• VS Code: rich node tooltips (complexity, churn, contributor)

• VS Code: status bar item showing deps/dependents for active file

• VS Code: Problems panel integration — security + arch violations as diagnostics

• Custom ignore patterns UI — add/remove directory exclusions, persists in localStorage

• Local git history — churn heatmap works for local repos via git log

• Automated npm publish on git tags via GitHub Actions

License

MIT License — Copyright (c) 2026 Ashforde OÜ. Free to use, modify, and distribute. Keep the copyright notice intact in all copies.

Built for developers who want to truly understand their codebase

See the code. Know the code.