Skip to main content
Glama
Ripple-MCP
by 0xYubo

Ripple-MCP

字段级语义变更影响分析 · Field-Level Semantic Change Impact Analysis

PyPI Python License: MIT Tests

pip install ripple-impact-mcp

中文 · English


🇨🇳 中文

为什么需要 Ripple-MCP?

当你想分析「修改 machine.x/y 语义」或「把某字段类型从 INT 改为 VARCHAR」会影响哪些代码时,传统工具无法回答:

问题

示例

哪些地方直接读取了这个字段?

obj.x / obj['x'] / obj.get('x')

哪些地方用了这个字符串值?

"success" / "failed"

哪些地方调用了这个函数?

get_eq_partition()

哪些文件导入了这个模块?

from plogen_tools import ...

TypeScript / JavaScript 里哪些地方用了这个变量?

—

改了函数 X,哪些函数直接调用了它?

—

Ripple-MCP 把 Claude Code 的语义理解与 ripgrep / Python AST 的机械精确性结合,覆盖 codegraph 的所有盲区。


核心工具

工具

说明

scan_patterns

通用正则扫描,支持任意语言

analyze_python_ast

精准 Python AST 分析,区分属性访问 / 下标 / .get()

trace_callers

多层调用链追踪(BFS 上溯「调用者的调用者」,最多 5 层)

find_definition

符号定义查找(函数 / 类 / 常量,含签名与所在类)

generate_impact_report

语义变更影响的结构化 Markdown 报告

get_code_context

带上下文的代码片段提取


安装

环境要求: Python 3.10+

pip install ripple-impact-mcp

包名为 ripple-impact-mcp(PyPI 上 ripple-mcp 已被占用),安装后的命令行入口仍是 ripple-mcp。

或源码安装:

git clone https://github.com/0xYubo/Ripple-Mcp.git
cd Ripple-Mcp
pip install -e .

Claude Code 集成(MCP 配置):

# 方式一:命令行一键添加(推荐,-s user 表示全局可用)
claude mcp add ripple -s user -- ripple-mcp
// 方式二:手动编辑 MCP 配置文件
{
  "mcpServers": {
    "ripple": {
      "command": "ripple-mcp"
    }
  }
}

ripple-mcp 是 pip install -e . 注册的命令行入口,等价于 python -m field_impact_mcp。

配置完成后重启 Claude Code 即可生效。


使用方式

无需手动调用任何工具——在 Claude Code 对话中用自然语言描述变更意图,Claude 会自动编排下面的工具完成分析。

字段类型变更

分析「把 all_check 表的 survey_status_today 字段从 INT 改为 VARCHAR」
对 /path/to/backend 的影响范围

坐标语义变更

如果把机台坐标 x/y 从左上角改为中心点,
/path/to/project 里哪些地方需要修改?

函数重命名

把 get_eq_partition 重命名为 get_machine_partition,
/path/to/backend 里有多少个调用点?

API 路径变更

/api/external/apiKey/refresh 改为 /api/external/api-keys,
哪些前端文件引用了旧路径?

推荐工作流(Claude 自动执行,也可手动指定):

描述变更意图
  → scan_patterns + analyze_python_ast(并行扫描)
  → get_code_context(对可疑命中确认上下文)
  → generate_impact_report(生成结构化影响报告)

MCP 工具参数说明

scan_patterns — 通用 pattern 扫描

接受任意正则表达式,支持所有语言和文件类型。

{
  "project_path": "/path/to/project",
  "patterns": ["machine\\.x", "survey_status_today", "/api/external/"],
  "extensions": [".py", ".ts", ".tsx", ".sql"],
  "max_results": 500
}

返回(按文件聚合,file 为相对 project_path 的路径):

{
  "engine": "rg",
  "total_found": 12,
  "returned": 12,
  "truncated": false,
  "files": [{"file": "pkg/a.py", "hits": [{"line": 2, "code": "...", "patterns": ["..."], "confidence": "low"}]}]
}

truncated: true 时表示命中数超过 max_results,可增大后重试。 analyze_python_ast / find_definition 返回相同的聚合结构(hits 内分别为 {line, kind, value, extra, function, confidence} / {line, kind, name, signature, parent})。

analyze_python_ast — Python AST 精确分析

比 grep 更精确,区分访问方式,标注所在函数。

{
  "project_path": "/path/to/backend",
  "field_names":   ["x", "y", "survey_status_today"],
  "string_values": ["success", "failed"],
  "call_names":    ["get_eq_partition"],
  "import_names":  ["plogen_tools"]
}

kind 与置信度对应:

kind

说明

confidence

attr_access

obj.field

high

subscript_access

obj['field']

high

get_call

obj.get('field')

high

call

函数 / 方法调用

medium

import / import_from

导入

medium

type_annotation

类型注解

low

trace_callers — 多层调用链追踪

{
  "project_path": "/path/to/backend",
  "function_name": "get_eq_partition",
  "depth": 3
}

depth=1 找直接调用者,depth=2 再找「调用者的调用者」,依此类推(上限 5 层)。返回:

{
  "target": "get_eq_partition", "max_depth": 3, "total_found": 5, "truncated": false,
  "levels": [{"depth": 1, "callers": [{"file": "svc/a.py", "line": 12, "caller_function": "do_calc", "callee": "get_eq_partition", "confidence": "high"}]}]
}

confidence=high 表示 foo(x) 直呼;medium 表示 obj.foo() 按方法名匹配,可能是其他类的同名方法。

find_definition — 符号定义查找

{
  "project_path": "/path/to/backend",
  "name": "get_eq_partition"
}

返回函数 / 类 / 模块级与类级赋值的定义处,含签名(def fn(a, b) -> int)和所在类(parent)。与 trace_callers 配对使用:先看定义签名,再追调用链。

get_code_context — 代码上下文

{
  "file_path": "pkg/a.py",
  "line_number": 254,
  "context_lines": 8,
  "project_path": "/path/to/project"
}

file_path 可直接使用扫描结果中的相对路径(需同时传 project_path),也可传绝对路径。 验证多个命中时推荐批量模式:传 locations: [{file_path, line_number}] 数组,一次返回多段上下文。

generate_impact_report — 生成影响报告

先调用 scan_patterns / analyze_python_ast(结果自动缓存),再调用此工具只传 change_description 即可。

{
  "change_description": "将 survey_status_today 字段从 INT 改为 VARCHAR(16)",
  "project_path": "/path/to/project"
}

与 codegraph 的关系

Ripple-MCP 不是 codegraph 的替代品,而是补充:

分析场景

codegraph

Ripple-MCP

函数 / 类调用图

✅

✅

字段级读写追踪

❌

✅

字符串字面量匹配

❌

✅

枚举值引用追踪

❌

✅

类型注解分析

❌

✅

跨语言扫描(Python + TS/JS)

❌

✅


Related MCP server: Axon.MCP.Server

🇺🇸 English

Why Ripple-MCP?

When you want to analyze the impact of "changing machine.x/y semantics" or "converting a field type from INT to VARCHAR", traditional tools can't answer:

Question

Example

Where is this field read directly?

obj.x / obj['x'] / obj.get('x')

Where is this string value used?

"success" / "failed"

What functions call this function?

get_eq_partition()

Which files import this module?

from plogen_tools import ...

Where is this variable used in TypeScript / JavaScript?

—

If function X changes, which callers are affected?

—

Ripple-MCP combines Claude Code's semantic understanding with the mechanical precision of ripgrep / Python AST, covering all blind spots left by codegraph.


Core Tools

Tool

Description

scan_patterns

Universal regex-based pattern matching across any language

analyze_python_ast

Precise Python AST analysis — distinguishes attribute access, subscript, and .get()

trace_callers

Multi-level call chain tracking (BFS up to 5 levels of "callers of callers")

find_definition

Symbol definition lookup (function / class / constant, with signature and enclosing class)

generate_impact_report

Structured Markdown report of semantic change impact

get_code_context

Contextual code snippet retrieval with surrounding lines


Installation

Requirements: Python 3.10+

pip install ripple-impact-mcp

The package name is ripple-impact-mcp (ripple-mcp was taken on PyPI); the installed CLI entry point is still ripple-mcp.

Or install from source:

git clone https://github.com/0xYubo/Ripple-Mcp.git
cd Ripple-Mcp
pip install -e .

Claude Code Integration:

# Option 1: one-liner via CLI (recommended, -s user = available in all projects)
claude mcp add ripple -s user -- ripple-mcp
// Option 2: edit the MCP config manually
{
  "mcpServers": {
    "ripple": {
      "command": "ripple-mcp"
    }
  }
}

ripple-mcp is the console entry point registered by pip install -e ., equivalent to python -m field_impact_mcp.

Restart Claude Code after configuring.


Usage

No manual tool calls needed — just describe your change intent in natural language inside Claude Code, and Claude orchestrates the tools below automatically.

Field type change

Analyze the impact of changing the survey_status_today column
of the all_check table from INT to VARCHAR on /path/to/backend

Coordinate semantics change

If machine coordinates x/y change from top-left to center,
which places in /path/to/project need updating?

Function rename

Rename get_eq_partition to get_machine_partition —
how many call sites exist in /path/to/backend?

API path change

/api/external/apiKey/refresh becomes /api/external/api-keys —
which frontend files reference the old path?

Recommended workflow (orchestrated by Claude automatically):

Describe the change intent
  → scan_patterns + analyze_python_ast  (parallel scan)
  → get_code_context                    (confirm suspicious hits)
  → generate_impact_report              (structured impact report)

MCP Tool Reference

scan_patterns — universal pattern scan

Accepts any regex; works across all languages and file types.

{
  "project_path": "/path/to/project",
  "patterns": ["machine\\.x", "survey_status_today", "/api/external/"],
  "extensions": [".py", ".ts", ".tsx", ".sql"],
  "max_results": 500
}

Returns (grouped by file; file is relative to project_path):

{
  "engine": "rg",
  "total_found": 12,
  "returned": 12,
  "truncated": false,
  "files": [{"file": "pkg/a.py", "hits": [{"line": 2, "code": "...", "patterns": ["..."], "confidence": "low"}]}]
}

When truncated: true, hits exceeded max_results — retry with a larger value. analyze_python_ast / find_definition return the same grouped structure (hits contain {line, kind, value, extra, function, confidence} / {line, kind, name, signature, parent} respectively).

analyze_python_ast — precise Python AST analysis

More accurate than grep — distinguishes access kinds and annotates the enclosing function.

{
  "project_path": "/path/to/backend",
  "field_names":   ["x", "y", "survey_status_today"],
  "string_values": ["success", "failed"],
  "call_names":    ["get_eq_partition"],
  "import_names":  ["plogen_tools"]
}

kind → confidence mapping:

kind

Meaning

confidence

attr_access

obj.field

high

subscript_access

obj['field']

high

get_call

obj.get('field')

high

call

function / method call

medium

import / import_from

import

medium

type_annotation

type annotation

low

trace_callers — multi-level call chain tracking

{
  "project_path": "/path/to/backend",
  "function_name": "get_eq_partition",
  "depth": 3
}

depth=1 finds direct callers; depth=2 walks up to "callers of callers", etc. (max 5). Returns:

{
  "target": "get_eq_partition", "max_depth": 3, "total_found": 5, "truncated": false,
  "levels": [{"depth": 1, "callers": [{"file": "svc/a.py", "line": 12, "caller_function": "do_calc", "callee": "get_eq_partition", "confidence": "high"}]}]
}

confidence=high means a direct foo(x) call; medium means obj.foo() matched by method name — possibly a same-named method on another class.

find_definition — symbol definition lookup

{
  "project_path": "/path/to/backend",
  "name": "get_eq_partition"
}

Returns definitions of functions / classes / module-level and class-level assignments, with signature (def fn(a, b) -> int) and enclosing class (parent). Pairs with trace_callers: inspect the signature first, then trace the call chain.

get_code_context — code context

{
  "file_path": "pkg/a.py",
  "line_number": 254,
  "context_lines": 8,
  "project_path": "/path/to/project"
}

file_path accepts the relative paths from scan results (pass project_path along), or an absolute path. To verify multiple hits, prefer batch mode: pass locations: [{file_path, line_number}] to get all snippets in one call.

generate_impact_report — impact report

Call scan_patterns / analyze_python_ast first (results are cached server-side), then pass only change_description.

{
  "change_description": "Change survey_status_today from INT to VARCHAR(16)",
  "project_path": "/path/to/project"
}

Relationship with codegraph

Ripple-MCP is not a replacement for codegraph — it fills the gaps:

Scenario

codegraph

Ripple-MCP

Function / class call graph

✅

✅

Field-level read/write tracking

❌

✅

String literal matching

❌

✅

Enum value reference tracking

❌

✅

Type annotation analysis

❌

✅

Cross-language scan (Python + TS/JS)

❌

✅


License: MIT

Available Tools

6 tools
analyze_python_astA
Read-only

对 Python 代码做 AST 级别精确分析,比 grep 更准确。支持多种搜索目标,可同时指定多类:

  • symbols: 任何标识符(变量名、类名、常量名)

  • field_names: 字段/属性名(捕获 obj.field / obj['field'] / obj.get('field'))

  • string_values: 字符串字面量值(捕获代码中的字符串常量)

  • call_names: 函数/方法调用名

  • import_names: 导入的模块或符号名 每个命中都标注所在函数名、访问方式和置信度,适合需要精确上下文的场景。返回按文件聚合的 JSON:{total_found, returned, truncated, files:[{file:相对路径, hits:[{line, kind, value, extra, function, confidence}]}]}。

Inputs: project_path (required), symbols, call_names, field_names, +4 more.

find_definitionA
Read-only

找出符号在项目中的定义处:函数定义、类定义、模块级/类级赋值(常量、类属性)。与 trace_callers 配对使用——先找定义看签名,再追调用链。返回按文件聚合的 JSON:{total_found, returned, truncated, files:[{file:相对路径, hits:[{line, kind, name, signature, parent}]}]},kind 为 function/class/assignment,parent 为所在类或函数(顶层为 )。

Inputs: name (required), project_path (required), exclude_dirs.

generate_impact_reportA
Read-only

将扫描结果聚合成结构化 Markdown 影响分析报告。若不传 scan_results/ast_results,自动使用该 project_path 的最近一次扫描缓存。推荐工作流:先调用 scan_patterns 和/或 analyze_python_ast,再调用此工具生成报告。

Inputs: project_path (required), change_description (required), ast_results, scan_results.

get_code_contextA
Read-only

获取代码上下文,帮助判断命中处是否真正受变更影响。支持两种模式:单点(file_path + line_number)或批量(locations 数组,推荐——验证多个命中时一次调用替代多次往返)。

Inputs: file_path, locations, line_number, project_path, +1 more.

scan_patternsA
Read-only

在代码库中搜索任意正则表达式 pattern,支持 Python/TypeScript/JavaScript/任意文本文件。这是最通用的搜索工具,适用于所有变更场景:字段访问、函数调用、字符串值、常量、配置项、API 路径、SQL 字段名、注释、枚举值等任何内容。当用户描述任何类型的代码变更并想知道影响范围时,调用此工具。由 Claude 根据变更描述决定要搜什么 pattern,此工具只负责机械执行搜索。返回按文件聚合的 JSON:{engine, total_found, returned, truncated, files:[{file:相对路径, hits:[{line, code, patterns, confidence}]}]}。

Inputs: patterns (required), project_path (required), extensions, max_results, +1 more.

trace_callersA
Read-only

BFS 逐层找出调用指定函数的函数:depth=1 为直接调用者,depth=2 再找「调用者的调用者」,依此类推(上限 5 层)。适合回答「改了函数 X,影响会波及到哪里?」返回 {target, max_depth, total_found, truncated, levels:[{depth, callers:[{file, line, caller_function, callee, confidence}]}]}。confidence=high 表示 foo(x) 直呼;medium 表示 obj.foo() 按方法名匹配,可能是其他类的同名方法。

Inputs: project_path (required), function_name (required), depth, max_results, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose: scan_patterns does regex search across any file, analyze_python_ast does AST-based Python analysis, get_code_context retrieves code snippets, generate_impact_report aggregates results, trace_callers finds callers, and find_definition locates definitions. No two tools overlap ambiguously.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with lowercase and underscores: scan_patterns, analyze_python_ast, get_code_context, generate_impact_report, trace_callers, find_definition. The naming is uniform and predictable.

    Tool Count5/5

    Six tools is well-scoped for a code impact analysis server. Each tool serves a distinct function in the workflow: searching, analyzing, getting context, tracing callers, finding definitions, and generating reports. No redundancy or unnecessary tools.

    Completeness5/5

    The tool set covers the full lifecycle of impact analysis: search (scan_patterns), precise analysis (analyze_python_ast), context (get_code_context), caller tracing (trace_callers), definition lookup (find_definition), and report generation (generate_impact_report). No obvious gaps for static code change impact assessment.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server enabling symbol-aware semantic search in Claude Code, allowing precise location of functions, types, and implementations via a symbol graph and embeddings.
      9
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that transforms codebases into intelligent, queryable knowledge bases, enabling AI assistants to perform semantic search, explore architecture, and analyze code relationships.
      166
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that transforms Claude Code into an intelligent refactoring assistant, enabling code scanning, hotspot detection, optimization reports, and safe refactoring for large repositories.
      159 npm
      9
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for local-first code intelligence, providing structural code graph, semantic search, and impact analysis to AI agents.
      2
      MIT