Grasp — Code Architecture & Dependency Analysis

Grasp MCP 服务

将 Grasp 代码库分析引擎作为 MCP 工具开放，供 Claude Code 和其他大模型 Agent 使用。

支持 GitHub 仓库和本地目录。可分析依赖关系图、架构分层、循环依赖、安全问题、设计模式、死代码、代码指标、Git 历史、重复项检测、跨仓库对比、单体仓库工作区、运行时调用图、数据库架构耦合、API 面图和迁移规划。

力导向依赖关系图——MCP 服务通过 grasp_analyze、grasp_dependents、graph_query 等工具开放的正是这些数据。

目录

• 设置
• 在 Claude Code 中配置
• 工具
• 使用示例
• GitHub 令牌
• GitLab 支持
• 命令行
• JetBrains 插件
• Claude Code 斜杠命令
• 隐私

---

当前版本：3.21.0 — 150 个工具 + 8 个 MCP 资源 + 2 个引导式提示词。

v3.21.0 新增 — 多模态知识图谱： 将任意制品（代码、Markdown、PDF、Word .docx、Excel .xlsx、HTML、通过 OCR 处理的图像、通过本地 Whisper 处理的音频/视频、YouTube）导入可查询的语义知识图谱，然后用自然语言向它提问。新增工具：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。可插拔的大模型后端（Anthropic、OpenAI、Gemini、DeepSeek、Kimi、Azure、Bedrock、Ollama — 本地优先，可选择使用云端；提取功能可回退到确定性的本地提取器，无需任何凭据）。可选的 MCP-over-HTTP 传输方式，支持团队共享访问（GRASP_HTTP_MCP=1，可选 API 密钥）。新增三种 AST 语言（Bash、Elixir、Julia → 19 种由 tree-sitter 支持的语言）。请参阅下文的 ## Multimodal Knowledge Graph。

v3.20.0 新增： 完整的安全扫描套件 — grasp_vulnerabilities 覆盖五种威胁向量（OSV.dev 依赖项 CVE、NIST NVD 容器/运行时 CVE、本地供应链完整性检查、Socket.dev 行为分析，以及定时的 grasp_vuln_watch 监控），并提供 skip_container / skip_socket / skip_integrity 快速扫描标志。

v3.19.0 新增： 团队仪表板在视觉上与 Grasp 应用保持一致 — 青绿色品牌风格、Lucide SVG 图标系统、多提供商身份验证（GitLab、GitHub Enterprise、Bitbucket、Azure DevOps、Gitea）、移动端 More 菜单、键盘快捷键弹出框。

v3.18.0 新增： 10 个新的 MCP 工具（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 种图导出格式（grasp_export_graphml、grasp_export_cypher、grasp_export_obsidian）；TS-config 路径别名和 Jedi 风格的 Python 导入解析器；Claude Code 斜杠命令；令牌缩减评估工具（scripts/eval-token-reduction.mjs）；本地化 README（印地语/日语/韩语/简体中文）。

近期新增 （完整历史请参阅 CHANGELOG.md）：

• v3.17.1 — OSV 扫描器按目录限定锁文件范围；跳过测试夹具清单；CWS 令牌轮换脚本。
• v3.17.0 — OSV.dev SCA 扫描器（grasp_vulnerabilities + grasp vulns CLI）；架构漂移检测（grasp_snapshot + grasp_diff_snapshots + grasp drift CLI）；组织级仪表板（grasp_org_summary + grasp org CLI）；测试覆盖率缺口图；图架构 v3（TestFile 节点、TESTS/COVERS 边）。
• v3.16.0 — PR Impact GitHub Action；Brain 上下文工具（grasp_diff_symbols、grasp_exec_flow、grasp_skillmd、grasp_hooks、grasp_mro、grasp_communities、grasp_contracts）；置信度评分；Wiki 生成器；注册表工具。
• v3.15.0 — Kuzu 图架构 v2；跨文件类型传播；ORM 跟踪器；grasp_detect_changes；8 个 MCP 资源；2 个 MCP 提示词；通过 grasp setup 一条命令自动配置编辑器。

v3.15 之前已推出的垂直领域： 航空航天/安全关键领域（需求可追溯性、MISRA、DO-178C、ECSS-E-ST-40C、Ada/SPARK）、AI 研究（安全约束追踪、评估覆盖率、ML 流水线 DAG、Jupyter 笔记本）、企业（SBOM CycloneDX/SPDX、DORA、AI 驱动的 ADR、PII 跟踪、职责分离、金融延迟/模型风险）、操作系统/内核（子系统边界、ABI 稳定性、Kconfig、IRQ 图、补丁系列影响）、开源（适合新手的问题、分支分歧、OpenSSF 评分卡、deps.dev），以及托管的 SaaS API（saas/）。

验证来源

每个版本都会签名。安装前请先验证：

npm 包（SLSA 来源证明）：

npm install -g @sigstore/verify  # one-time
sigstore verify npm [email protected]

Docker 镜像（Cosign 无密钥签名）：

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

签名会透明地存储在 Sigstore Rekor 公共账本中。

---

多模态知识图谱

除了代码分析，Grasp 还可以将任何工件导入可查询的语义知识图谱，并回答有引用依据的自然语言问题。

// 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

本地优先，云端按需启用。 代码解析保持确定性（tree-sitter AST）。语义实体／关系提取使用你配置的 LLM，并会在使用任何云端密钥前自动检测本地 Ollama；如果完全没有 LLM，则会回退到确定性提取器，因此离线时仍可正常工作。每条边都会标记为已提取（源文件中明确说明）或已推断（推导所得），并附带来源定位信息。

后端	环境变量
Ollama（本地，默认）	在 localhost:11434 运行——无需其他配置
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_*

使用 GRASP_LLM_PROVIDER + GRASP_LLM_MODEL 显式选择，或通过每次调用的 provider/model/api_key 工具参数选择。运行 grasp_llm_status 查看可用选项。

可选解析器（按需安装，保持核心安装精简）：npm i pdf-parse mammoth xlsx tesseract.js youtube-transcript。音频／视频转录还需要将 ffmpeg 加入 PATH。

团队共享访问（通过 HTTP 使用 MCP）

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

将任意 MCP 客户端指向 http://host:7333/mcp（通过 Authorization: Bearer … 或 x-api-key 发送密钥）。/health 会返回存活状态。Grasp 的工具是无状态的，因此一个端点即可供团队的多个 Agent 使用。

代码所在位置

多模态流水线位于 MCP 服务端（Node），不会在浏览器应用中运行——请参阅 mcp/src/ 下的源代码布局：

• ingest/* — 工件解析器（PDF、Word .docx、Excel .xlsx、HTML、图像 OCR、音频／视频、URL、YouTube；大型解析器按需延迟加载）
• llm/provider.ts — 可插拔的多提供商 LLM 层（本地优先，自动检测 Ollama → 云端密钥 → 确定性回退）
• semantic/* — SQLite 知识图谱存储、BM25 + 向量混合检索、BFS 路径追踪、枢纽／超级节点检测
• tree-sitter/* — 支持 19 种语言的确定性 AST 解析

---

设置

cd mcp
npm install
npm run build

在 Claude Code 中配置

添加到 ~/.claude/claude_mcp_settings.json：

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

或者通过 npm 全局安装：

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

工具

核心分析

工具	描述
grasp_analyze	完整分析——首先运行，返回 session_id
grasp_file_deps	文件的出向依赖（它导入了什么）
grasp_dependents	文件的入向依赖——修改此文件可能造成的影响范围
grasp_cycles	所有循环依赖链
grasp_architecture	按层对文件分组（服务／数据／工具／测试……）
grasp_hotspots	按耦合度和复杂度排名最高的文件
grasp_metrics	每个文件的行数、函数数、复杂度、扇入／扇出
grasp_find_path	两个文件之间最短的依赖路径
grasp_security	硬编码密钥、SQL 注入风险、不安全模式
grasp_patterns	检测到的设计模式和反模式
grasp_unused	死代码——已定义但从未调用的函数
grasp_sessions	列出已持久化的分析会话——重启后仍保留，7 天后过期
grasp_config_check	对会话运行 grasp.yml 架构规则——返回带严重性级别的违规项

历史记录与比较

工具	描述
grasp_diff	比较两个会话快照——新增/删除的文件、健康度变化
grasp_watch	重新分析本地目录，并与之前的会话进行差异比较
grasp_timeline	最近 N 次 git 提交，包含每次提交变更的文件和共同变更矩阵
grasp_cross_repo	比较两个会话——共享文件名、存在差异的函数、工作区信息
grasp_similarity	排序后的重复代码簇、代码克隆、命名冲突和最热门文件

代码质量

工具	描述
grasp_suggest	根据热点和问题数据生成排序后的重构建议
grasp_explain	用通俗易懂的语言解释任意文件或函数
grasp_rules_check	运行架构规则并报告所有违规项
grasp_refactor	为文件或会话提供分步重构计划和指标表
grasp_coverage	测试覆盖率叠加视图——列出没有对应测试的文件
grasp_vulnerabilities	OSV.dev SCA 扫描器——检查已声明依赖项（npm/PyPI/Go/Cargo/Maven）中的已知 CVE。按严重程度（CVSS）分类，提供修复版本建议，并支持严重程度筛选（all/critical/high/medium/low）。可与 grasp vulns <path> CLI 配合使用（存在严重/高危问题时退出码为 1）——v3.17.0 新增

生态系统集成

工具	描述
grasp_issues	将 GitHub Issues 映射到其中提及的文件
grasp_contributors	按文件统计所有权、团队依赖度评分和主要贡献者
grasp_bundle	包体积树状图——按大小排列文件并按类别细分
grasp_dep_impact	分析升级依赖项的影响——哪些文件会导入该依赖项
grasp_pr_comment	为变更文件生成 PR 健康度评论，并附带影响范围
grasp_embed	生成用于分享的 iframe、README 徽章和 React 代码片段
grasp_dead_packages	在 package.json 中声明、但未被任何源文件导入的 npm 依赖项
grasp_sarif	将分析结果导出为 SARIF 2.1.0，以便上传到 GitHub Code Scanning

运行时与基础设施智能分析

工具	描述
grasp_runtime_calls	将 GraspTracer JSON 跟踪记录与静态边合并——显示实际调用路径和热点文件
grasp_db_coupling	ORM/SQL 到表的耦合关系图——万能表、高耦合文件、共享表簇
grasp_migration_plan	以阶段划分并按拓扑顺序排列的计划，用于替换或移除软件包/模块
grasp_api_surface	根据 OpenAPI 规范、GraphQL SDL、Express/FastAPI/Next.js 路由生成统一的 API 接口图

GitHub 活动

工具	描述
grasp_commits	过去 7 天和 30 天的提交数，以及自指定时间戳以来的提交数（上次分析后的陈旧度）
grasp_ci_status	最新的 GitHub Actions 运行状态——通过/失败/进行中，并附带近期运行历史

代码库智能（v2.4–v2.9）

工具	描述
grasp_env_vars	扫描所有环境变量读取操作——交叉核对 .env.example，标记未记录的变量和仅用于测试的变量
grasp_events	映射事件发送器和订阅者——检测孤立的事件发送（无监听器）和无来源的订阅（无发送器）
grasp_stale	查找活跃但已被弃用的文件——改动少、扇入高且没有对应测试。返回 0–100 的陈旧度评分
grasp_change_risk	为一组已更改文件计算 0–100 的风险评分——综合评估影响范围、复杂度、改动频率和层级违规
grasp_feature_flags	查找所有功能标志读取操作——包括 LaunchDarkly、GrowthBook、OpenFeature、环境变量标志和自定义模式
grasp_perf	检测 N+1 查询、同步 I/O 调用和循环内的 JSON 序列化
grasp_license	扫描 node_modules 中依赖项的许可证——报告宽松型、著佐权型和未知许可证；标记违规项
grasp_onboard	为新加入某个代码库领域的工程师提供有序阅读路径——按层级和扇入排序
grasp_types	统计每个文件的类型注解覆盖率——优先处理缺少类型注解且扇入高的文件
grasp_diagram	根据依赖图生成 Mermaid 流程图或 C4 图（上下文、容器或组件级别）
grasp_pr_review	在 GitHub PR 的高严重性代码行上发布行内审查评论——涵盖影响范围、复杂度和安全性
grasp_suggest	提供按投入产出比排序的重构建议——优先列出 ROI 最高的建议

航空航天 / 安全关键领域

工具	描述
grasp_req_trace	需求可追溯性——扫描代码中的 @REQ-NNN 标签并与需求 CSV 核对；返回覆盖率、已覆盖、未覆盖和未指定的文件
grasp_anomaly	异常调查——调用方、被调用方、传递影响范围（BFS 50 个文件）、调用链中的安全问题和通俗易懂的摘要；用于事件响应
grasp_reuse	软件复用评估器——围绕接口兼容性、依赖项、安全性和架构适用性生成红／黄／绿矩阵

AI 研究 / AI 安全

工具	描述
grasp_safety_trace	安全约束追踪器——标记安全关卡、入口点和输出点；返回所有绕过每个关卡的入口→输出路径（未设关卡的路径为严重问题）
grasp_run_diff	训练运行差异分析——比较两个 YAML/JSON 配置，查找已更改的超参数，以及读取每个已更改键的代码文件
grasp_eval_coverage	评估覆盖图——从评估脚本沿导入关系进行 BFS 追踪；显示覆盖率、列出未覆盖文件，并标记没有评估覆盖的安全关卡

企业 / 合规

工具	描述
grasp_sbom	生成 SBOM——采用 CycloneDX 1.4 或 SPDX 2.3 JSON 格式。解析 package.json、requirements.txt、Cargo.toml、go.mod、pyproject.toml。可选补充 CVE 信息。
grasp_dora	DORA 指标——通过 GitHub Actions 和 PR 历史记录计算部署频率、变更前置时间和变更失败率。分为 Elite/High/Medium/Low 级别。
grasp_adr	AI 驱动的 ADR 生成——结合代码库上下文和可选的 PR 差异，生成 MADR 格式的架构决策记录。支持任意 AI Chat 提供商。

多仓库 / 平台（v3.4.x）

工具	描述
grasp_org_graph	组织级多仓库依赖图——将 N 个会话合并为一个组织视图，包含仓库间依赖边和共享库
grasp_api_diff	破坏性 API 变更检测器——比较两个会话的导出符号，标记已移除或签名已更改的符号
grasp_plugins	扩展点映射——在整个代码库中检测插件接口、钩子点和策略模式
grasp_semver	语义化版本管理强制器——比较两个会话，并验证版本递增是否与变更集相符

金融 / 合规（v3.5.x）

工具	描述
grasp_pii_trace	PII 数据流追踪器 — 从用户标记的 PII 源文件开始进行下游广度优先遍历；显示所有使用方
grasp_duties	职责分离验证器 — 检测同时发起和批准交易的文件（SOX/FDA 合规）
grasp_reg_impact	监管变更影响映射器 — 将关键词关联到 GDPR/HIPAA/SOX/PCI-DSS 条款变更的影响范围
grasp_latency	金融 / 交易延迟热点检测 — 阻塞式 I/O、GC 压力、锁竞争、循环中的内存分配
grasp_model_risk	金融模型风险审计器 — 硬编码参数、缺少 NaN 检查、未进行零值保护的除法

OS / 内核（v3.6.x）

工具	描述
grasp_subsystems	内核 / OS 子系统边界图 — 目录级分组、跨子系统依赖违规
grasp_abi_diff	ABI/API 稳定性检查器 — 比较不同会话之间的导出符号，稳定性评分为 0–100
grasp_kconfig	Kconfig/构建时条件分析 — CONFIG_* 使用情况图、影响超过 50 个文件的高风险开关
grasp_irq	IRQ/中断依赖关系图 — 中断处理程序中的动态分配、阻塞调用和扇出
grasp_patch_impact	补丁系列影响分析器 — 在内核代码审查中按影响范围和复杂度对补丁排序

开源（v3.7.x）

工具	描述
grasp_good_first_issues	新手友好问题生成器 — 找出独立、低复杂度、未经测试的文件，并生成 GitHub 问题草稿文本
grasp_api_stability	两个会话之间的 API 稳定性评分（0–100）— 为库作者追踪破坏性变更率
grasp_dependents	公开使用方 — 查询 deps.dev，获取公开软件包的依赖方数量
grasp_fork_diff	Fork 差异分析 — 找出存在差异、相同和仅在 Fork 中存在的文件，以及合并影响范围

Ada / 遗留系统（v3.8.x）

工具	描述
grasp_multilang	跨语言调用图 — Ada→C pragma Import、Python ctypes/cffi、JS→WASM 边界
grasp_heritage	遗留软件谱系分析 — 叠加源任务清单，识别零差异认证捷径
grasp_icd	ICD 映射器 — 将接口控制文档条目与导出函数匹配，并标记未实现的接口
grasp_ecss	ECSS-E-ST-40C 合规检查器 — DI-01 标头、DI-04 文档、DI-07 测试、DI-10 无循环依赖、DI-15 无死代码

图工具（v3.11.0 新增）

工具	描述
graph_query	对 Grasp 函数级调用图运行只读 Cypher 查询
call_chain	从指定函数开始，遍历 N 跳范围内的调用方 / 被调用方
type_propagation	查找所有返回指定类型的函数及其调用邻居
function_graph	将函数子图渲染为 Mermaid、DOT 或 JSON

需要先运行 grasp_brain_index。

示例：查找最终会调用任何返回 AuthToken 的函数的所有函数：

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

大脑与持久化智能（v3.10+）

工具	描述
grasp_brain_index	将代码库索引到持久化 SQLite 大脑存储（~/.grasp/brain.db）中——包括文件、函数、边、健康状况、安全性和层级。还会构建 FTS 索引、384D 向量嵌入和执行流流程标签
grasp_brain_status	列出大脑中已索引的所有代码库：来源、文件数量、索引时间戳、健康评分
grasp_context	从大脑中获取任意文件的丰富上下文：层级、复杂度、耦合度、变更频率、评级、最多 20 个依赖项/被依赖项、安全问题——即时返回，无需重新分析
grasp_arch_diff	将当前代码库与大脑基线进行比较：评级退化、健康度变化、自上次索引以来新增的安全问题
grasp_ask	使用自然语言查询大脑存储——无需 AI 密钥。可识别以下意图：复杂度 · 耦合度 · 影响范围 · 层级 · 评级 · 变更频率 · 循环依赖。无法识别时，会回退到混合语义搜索（BM25 + 向量）
grasp_diff_symbols	将 git diff 区块映射到函数；为 PR 涉及的每个函数返回影响范围和复杂度
grasp_exec_flow	从任意入口点进行 BFS 执行流分析——通过 STEP_IN_PROCESS 边追踪调用路径，并输出 Mermaid 流程图
grasp_skillmd	为 AI Agent 自动生成 SKILL.md / CLAUDE.md 片段——包括层级、关键文件、健康评级、模式和安全发现
grasp_hooks	生成 .claude/settings.json PostToolUse hook 和 .cursor/rules/grasp.mdc，以便在每次文件编辑时自动注入上下文
grasp_mro	方法解析顺序——适用于 Python 多重继承的 C3 线性化，以及 Ruby 和 Java 层级结构的 MRO
grasp_communities	在 Kuzu 图上进行 Leiden/Louvain 社区检测——识别凝聚集群、有界上下文和微服务拆分候选项
grasp_contracts	多代码库契约分析——检查跨代码库的提供方导出与使用方导入，找出违规项并计算覆盖率百分比
grasp_confidence	为每个跨文件连接评分（0–1）：显式导入 = 1.0 · 同一文件夹 = 0.8 · 跨文件夹 = 0.6 · 低频连接 = 0.4
grasp_wiki	自动生成 Markdown 维基：index.md 概览、每个文件夹一个页面、按调用方数量排序的 api.md
grasp_registry_list	列出 Grasp Brain 注册表中的所有代码库及其健康评级、文件数量、函数数量和活动会话 ID
grasp_registry_status	注册表健康摘要：已索引代码库总数、活动会话数、评级分布（A/B/C/D/F）
grasp_resolve_receiver	解析每次方法调用对应的具体类——支持 Python、JavaScript、Java，以及 Ruby 中 self/this 的推断
grasp_service_graph	根据 OpenTelemetry 追踪数据构建服务依赖图——节点为服务，边为带延迟和错误率的调用路径
grasp_jira_issues	获取代码库的 Jira 问题并将其映射到文件——识别未关闭缺陷最多的文件
grasp_deps_dev	查询 deps.dev，获取任意 npm/PyPI/Go 软件包的公开依赖方数量、OpenSSF 记分卡和依赖健康状况

语义搜索与重命名（v3.14+）

工具	描述
grasp_search	针对 brain 索引进行混合语义搜索（BM25 FTS5 + 384D 向量嵌入，并通过 Reciprocal Rank Fusion 合并结果）。结果包含 processes[] 字段，按执行流程对匹配项分组。支持 @groupName 扇出
grasp_rename	在 brain 索引的所有文件中，以图感知方式重命名完整单词符号。apply: false（默认值）返回试运行差异；apply: true 将更改写入磁盘
grasp_route_map	扫描 HTTP 路由定义（Express/Fastify/Hono、FastAPI/Flask、Gin），将每条路由映射到其处理函数及文件位置
grasp_api_impact	给定路由或处理函数名称，使用 brain 图谱边返回所有调用方、下游服务和影响范围
grasp_tool_map	扫描 MCP 工具定义（server.tool / server.registerTool）和 gRPC 服务定义，返回服务契约映射
grasp_shape_check	对任意函数，通过 brain 索引追踪所有调用点的参数类型和返回类型；标记调用点不匹配
grasp_group_add	将仓库源添加到 ~/.grasp/groups.json 中的命名组，以支持多仓库扇出
grasp_group_list	列出 ~/.grasp/groups.json 中所有命名组及其成员仓库

图谱智能（v3.15.0）

工具	描述
grasp_graph_schema	Kuzu schema v3 内省——所有节点/边表定义（File、Function、Class、Interface、Method、Constructor、TestFile，以及包括 TESTS 和 COVERS 在内的 12 种边类型），并显示每张表的实时行数
grasp_type_propagation	通过拓扑传播进行跨文件类型推断——沿导入图（Kahn 算法）推断每个调用点的返回类型；返回置信度为 0–1 的前 20 种推断类型
grasp_orm_map	ORM 查询追踪器——检测 Prisma、TypeORM、Sequelize、SQLAlchemy 模式；按模型对结果分组，包含调用点、操作和频率；可通过 orm_filter 参数筛选
grasp_detect_changes	Git 差异 → 符号影响映射。scope：unstaged · staged · all · compare（搭配 base_ref）。返回已更改文件、受影响函数及行范围、受影响的流程，以及风险级别：LOW · MEDIUM · HIGH · CRITICAL
grasp_generate_agents_md	根据 brain 会话数据在仓库根目录生成内容丰富的 AGENTS.md——排名前 5 的功能社区及其关键文件、排名前 3 的执行流程及其入口点、健康等级和主要问题
grasp_generate_skills	按社区生成技能文件——为每个检测到的功能集群写入 .claude/skills/generated/<community>.md；每项技能都包含关键文件、入口点、跨区域依赖项和常见操作

v3.20.0 — 团队仪表板功能对齐

团队仪表板在视觉和用户体验上与 Grasp 应用全面对齐——采用青绿色品牌设计令牌、全面使用 Lucide SVG 图标、多提供商身份验证（GitLab、GitHub Enterprise、Bitbucket、Azure DevOps、Gitea）并共享 localStorage 键、≤860px 时显示移动端“更多”菜单、身份验证栏支持 flex-wrap，以及键盘快捷键弹出框（kbd-fab）。

v3.18.0 — 图分析与大模型上下文

工具	描述
grasp_hub_nodes	按入度 + 出度（度中心性）列出连接最多的前 N 个文件。用于识别架构枢纽
grasp_bridge_nodes	Brandes 中介中心性。列出位于其他文件关键路径上的文件。对于节点数 > 500 的代码库，会自动抽样 100 个源节点
grasp_surprising_connections	按频率加权稀有度标记罕见的跨层边。可能是架构违规
grasp_knowledge_gaps	孤立文件（没有边，且不是测试/fixture）、未经测试但调用次数很高的热点，以及薄弱社区（出度耦合高的小型层）
grasp_suggested_questions	自动生成 5–10 个审查问题，结合枢纽、桥接节点、循环依赖、重复项和层违规
grasp_minimal_context	不足 100 个 token 的代码库概览。大模型深入查询前的首次调用。返回主要枢纽、层分布、语言列表和健康状况摘要
grasp_traverse	感知 token 预算，从起始节点开始进行 BFS。在预算或深度耗尽前遍历文件/函数图。返回带有剩余预算的截断视图
grasp_semantic_search	通过 @xenova/transformers（Xenova/all-MiniLM-L6-v2）对函数签名进行余弦相似度搜索。嵌入模型加载设置 15 秒超时竞速，并在超时后回退到子串关键词搜索。最多处理 2,000 个签名
grasp_apply_refactor	执行重命名操作，默认通过 dry_run 预览。对于本地源，dry_run=false 会将文件写回磁盘
grasp_architecture_overview	综合社区、枢纽和问题报告。为新贡献者/审查者提供单一执行摘要
grasp_export_graphml	导出与 yEd / Gephi 兼容的依赖图 GraphML XML
grasp_export_cypher	生成可重现完整图结构的 Neo4j CREATE 语句，用于离线分析
grasp_export_obsidian	生成 Obsidian Canvas 使用的 .canvas JSON，并按层设置列布局
grasp_export_dot	Graphviz DOT（digraph），包含 rankdir=LR、分层子图集群、按层着色的节点和带标签的边。默认上限为 200 个节点（优先选择连接最多的节点）——设置 max_nodes 可覆盖此上限
grasp_export_mermaid	生成每层一个子图的 Mermaid graph LR。可在 GitHub / GitLab / Notion / Obsidian 中内嵌渲染
grasp_export_d2	生成带有分层容器和带标签 imports 边的 Terrastruct D2（direction: right）。通过 d2 CLI 渲染
grasp_export_plantuml	生成 PlantUML 类图（@startuml ... @enduml、!theme cerulean），每层使用一个 package。可用于 Confluence、Jira、IntelliJ、VS Code 和 PlantUML 服务
grasp_export_dgml	导出 Visual Studio 有向图（DGML）XML。可在 VS Architecture 窗口中原生打开，每层对应一个 Category
grasp_export_gexf	导出 Gephi 原生 GEXF 1.3，包含层 / 行数 / 复杂度 / 变更量节点属性及加权边
grasp_export_drawio	导出 draw.io / diagrams.net XML，采用简单网格布局（每层一列）。可在 https://app.diagrams.net 或 VS Code draw.io 扩展中打开和编辑
grasp_export_csv	生成三个 CSV（文件 / 连接 / 问题），并以 --- <name>.csv --- 分隔符串联。传入 format=files|connections|issues 可导出单个工作表；默认 bundle 导出全部三个

MCP 资源（v3.15.0）

8 个实时数据 URI，MCP 客户端无需调用工具即可直接使用：

资源 URI	描述
grasp://repos	列出 brain store 中索引的所有仓库
grasp://setup	适用于所有已索引仓库的 AGENTS.md 风格上下文块
grasp://repo/{repoId}/context	代码库统计数据、健康等级、陈旧度检查
grasp://repo/{repoId}/clusters	Louvain 检测得出的所有功能社区
grasp://repo/{repoId}/processes	从入口点追踪的所有执行流程
grasp://repo/{repoId}/schema	Kuzu 节点/边数量及架构定义
grasp://repo/{repoId}/cluster/{clusterName}	深入了解一个功能社区
grasp://repo/{repoId}/process/{processName}	逐步追踪执行流程

MCP 提示词（v3.15.0）

提示词	参数	描述
detect_impact	source、scope?、base_ref?	引导式多步骤工作流：检测变更 → 确定受影响的符号 → 追踪流程 → 评估风险 → 建议测试范围
generate_map	source?、format?	引导式多步骤工作流：列出仓库 → 运行 grasp_analyze → 生成架构图 → 列出社区 → 生成 wiki

使用示例

"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 令牌

对于大型仓库（>100 个文件），请传入 GitHub PAT 以避免速率限制：

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

不使用令牌：60 次请求/小时。使用令牌：5,000 次请求/小时。

GitLab 支持

Grasp 支持 gitlab.com 和可自托管的 GitLab 实例。

令牌身份验证（最快）

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

自托管 Docker 机器人（自动发布 MR 评论）

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

然后注册一个 GitLab webhook，指向 http://your-host:7332/webhook，并使用你的 WEBHOOK_SECRET。

隧道 Agent（内部 GitLab，无需开放入站端口）

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

CLI

Grasp 除了 MCP 服务外，还提供 grasp CLI：

# 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 插件

JetBrains IDE 插件（IntelliJ IDEA、WebStorm、PyCharm、GoLand）位于 jetbrains-plugin/。它提供：

• 工具窗口 — 在 JCEF 中渲染交互式依赖关系图，无法渲染时回退到文本摘要
• 状态栏组件 — 实时健康评分（例如 ⬡ 87 B），点击即可打开
• 编辑器注释 — 针对分层违规和循环依赖的行内警告
• 文件保存时重新分析 — 保存文件时自动重新分析受监视的扩展名
• 设置 — 可配置 CLI 路径和注释开关

在 jetbrains-plugin/ 中运行 ./gradlew buildPlugin 进行构建。

SaaS API 服务

轻量级托管分析 API 位于 saas/ 下。它通过以下功能封装 Grasp 分析：

• Redis/LRU 缓存 — 相同请求可立即返回结果，TTL 可配置
• 滑动窗口速率限制器 — 可按密钥配置限制
• 异步任务队列 — POST 立即返回 202；分析在后台运行
• POST /analyze — 接受 { repo: "owner/repo" } 或 { repo: "https://github.com/..." }

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

Slack / Teams 机器人

自动健康警报和每周摘要位于 slack-bot/ 下。功能包括：

• 每小时回归警报 — 评分下降 ≥10 分、出现新的安全问题或新的循环依赖时触发
• 每周摘要 — 可配置 cron（默认周一 09:00），包含多仓库摘要
• Slack Block Kit 和 MS Teams Adaptive Cards（v1.4）格式
• 通过环境变量配置（SLACK_WEBHOOK_URL、TEAMS_WEBHOOK_URL、GRASP_REPOS 等）

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

GitHub Actions 工作流

工作流	触发条件	用途
ci.yml	推送至 main / 向 main 提交 PR	构建、测试、代码检查
publish.yml	推送标签 v*	发布到 npm
grasp-sarif.yml	推送至 main	自分析 → SARIF → GitHub Code Scanning
grasp-health.yml	定时（每天）	将健康摘要作为提交状态发布

Claude Code 斜杠命令

.claude/commands/ 下提供了三个预构建的斜杠命令，任何 Claude Code 工作区都可以通过一步操作调用 Grasp 最常用的流程：

命令	功能
/grasp:build-graph	对当前目录运行 grasp_analyze，并运行 grasp_minimal_context，生成少于 100 个 token 的概览
/grasp:review-delta	检测自基准分支以来的更改，并生成带风险评分的影响报告
/grasp:review-pr	完整的 PR 审查，组合调用 grasp_detect_changes、grasp_suggested_questions、grasp_surprising_connections 和 grasp_knowledge_gaps

每个命令都是一个 Markdown 文件（.claude/commands/grasp-*.md），包含 allowed-tools 和模板正文；可在仓库中编辑这些文件以进行自定义。

工作流提示

始终先调用 grasp_analyze——它会返回一个其他所有工具都需要的 session_id。会话保存在内存中，并会在 MCP 服务重启时过期。

应用内帮助：运行浏览器应用时，按 ? 可打开浮动弹出窗口，其中列出了所有快捷键、选项卡和覆盖层。Team Dashboard（team-dashboard.html）自带帮助模态框。

隐私

Grasp 不会收集任何数据。MCP 服务以本地子进程的形式运行；唯一的外发请求是调用 GitHub/GitLab API、OSV.dev 进行 CVE 查询，以及（可选）调用你配置的 AI 服务提供商。你的代码绝不会经过 Ashforde 服务器。完整隐私政策：PRIVACY.md。