DFL可视化MCP服务器
该项目实现了一个模型上下文协议（MCP）服务器，用于可视化和分析来自科学工作流程的数据流生命周期（DFL）数据。它提供了生成交互式Sankey图、计算流统计数据和识别工作流执行跟踪中的关键路径的工具。
安装
先决条件：
- Python 3.10或更高版本（fastmcp要求）
uv包管理器（推荐）-安装时使用：curl -LsSf https://astral.sh/uv/install.sh | sh
选项1：使用 uv （推荐）
uv 自动管理虚拟环境和依赖关系：
# Install dependencies (uv will create venv automatically)
uv sync
# Or install in development mode
uv pip install -e .选项2：使用传统的Python工具
- 创建虚拟环境：
python -m venv .venv
# or with uv:
uv venv- 激活虚拟环境：
source .venv/bin/activate- 安装项目依赖项：
pip install -e .用法
MCP服务器可以以多种方式使用。推荐的方法是使用stdio传输将其与MCP兼容的客户端（如Gemini、Claude Desktop或Cursor IDE）集成。
选项1：通过Stdio集成MCP客户端（推荐）
这是使用MCP服务器的标准和推荐方式。服务器通过标准输入/输出（stdio）与客户端通信，客户端自动管理服务器进程。
重要：使用stdio传输，您 不要 手动运行服务器。您的MCP客户端将在需要时自动生成服务器进程。
Stdio MCP的工作原理
- 您配置 使用命令生成服务器的MCP客户端
- 客户端生成 使用工具时，服务器会自动处理
- 通信发生 通过stdin/stdout管道（由客户端管理）
- 你互动 与您的客户端正常通信，它在幕后调用MCP工具
可用工具
服务器公开了以下工具：
get_sankey_data-生成交互式Sankey图HTML（支持按阶段号、任务ID或任务范围过滤）get_flow_summary_stats-计算全面的工作流I/O统计数据analyze_critical_path-确定关键路径和优化机会adjust_sankey_canvas_size-调整上次生成的Sankey图的画布大小list_workflow_stages-列出工作流中的所有阶段及其任务
配置
配置您的MCP客户端以使用服务器。配置取决于您的客户端：
使用 uv run （推荐）：
{
"mcpServers": {
"flow-viz-mcp": {
"command": "uv",
"args": ["run", "run_server.py"],
"cwd": "
"
}
}
}直接使用Python的替代方案：
{
"mcpServers": {
"flow-viz-mcp": {
"command": "python",
"args": ["
/run_server.py"],
"cwd": "
",
"env": {
"PATH": "
/.venv/bin:${PATH}"
}
}
}
}重要提示： 替换 与你的绝对路径 flow-viz-mcp 目录。
客户特定集成
克劳德桌面
- 安装克劳德桌面 从 claude.ai
- 配置MCP服务器 通过添加到您的Claude Desktop配置文件：
- Linux： ~/.config/Claude/claude_desktop_config.json - macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json
- 重新启动克劳德桌面 -这些工具将出现在您的对话中
- 使用自然语言 请求分析：
- “为ddmd工作流生成Sankey图” - “为仅包含第1阶段和第2阶段任务的ddmd工作流生成Sankey图” - “使用体积作为指标分析关键路径” - “显示任务openmm_0到openmm_3的流统计信息” - “列出ddmd工作流中的所有阶段”
光标IDE
要将DFL可视化工具与Cursor IDE的AI代理一起使用，请参阅 集成指南 了解详细的分步说明。
快速摘要：
- 要编辑的文件：
~/.cursor/mcp.json（或游标的全局存储位置） - 配置： 添加具有绝对路径的MCP服务器配置
- 预期产量： Cursor的AI聊天中可用的工具（Cmd+L或Ctrl+L）
Gemini终端代理
要将DFL可视化工具与Gemini等终端代理一起使用，请参阅 Gemini集成指南 了解详细的分步说明。
快速摘要：
- 要编辑的文件：
~/.config/mcp.json或终端代理的配置文件 - 配置： 添加MCP服务器配置
- 预期产量： 查询终端代理时可用的工具
示例提示：
以下是您可以与终端代理一起使用的一些示例提示：
Q： 可用的工作流是什么，每个工作流的任务是什么。
A. 代理人将致电 list_workflow_stages 对于每个工作流和返回：
✦ Available workflows are ddmd and montage.
Workflow: ddmd
* Stage 1: openmm (12 instances)
* Stage 2: aggregate (1 instance), training (1 instance)
* Stage 3: inference (1 instance)
Workflow: montage
* Stage 1: mConcatFit (1 instance), mProject (26 instances)
* Stage 2: mBgModel (1 instance), mDiffFit (179 instances)
* Stage 3: mBackground (25 instances)
* Stage 4: mImgtbl (2 instances)
* Stage 5: mAdd (2 instances)
* Stage 6: mViewer (1 instance)Q： 显示ddmd中任务训练的I/O统计信息
A. 代理人将致电 get_flow_summary_stats 具体任务和返回：
✦ Here are the I/O statistics for the training_0 task in the ddmd workflow:
* Combined I/O:
* Volume: 4.8878 GiB (5,248,236,152 bytes)
* Operations: 3,706,214
* Average Bandwidth: 370.58 MB/s
* Read I/O:
* Volume: 0.5417 GiB (581,657,336 bytes)
* Operations: 3,698,942
* Average Bandwidth: 48.02 MB/s
* Write I/O:
* Volume: 4.3461 GiB (4,666,578,816 bytes)
* Operations: 7,272
* Average Bandwidth: 2,276.73 MB/sQ： 请绘制工作流ddmd中所有任务的数据流图，保存到名为ddmd_workflow的文件中
A. 代理人将致电 get_sankey_data 并生成：
✓ get_sankey_data (flow-viz-mcp MCP Server) {"workflow_name":"ddmd","output_file":"ddmd_workflow.html"}
Sankey diagram saved to output/ddmd_workflow.html
Full workflow visualized with 15 tasks
✦ The Sankey diagram has been saved to output/ddmd_workflow.html.查看生成的图表： 预览ddmd_workflow.html
*注：更换 yourusername 在上面的链接中输入您的实际GitHub用户名或组织名称。*
其他MCP兼容工具
服务器还可以使用：
- 克莱恩 -Claude的VS代码扩展
- 任何MCP客户端 -任何支持模型上下文协议（stdio传输）的工具
有关详细的集成说明，请参阅 集成指南.
选项2:MCP客户端通过HTTP/SSE集成
如果您的MCP客户端支持基于HTTP的连接，则可以使用服务器发送事件（SSE）通过HTTP运行服务器。
步骤1:启动HTTP服务器
使用 uv run （推荐）：
uv run run_server_http.py --host localhost --port 8000或者直接使用Python：
python run_server_http.py --host localhost --port 8000服务器将于启动 http://localhost:8000。您将看到：
============================================================
DFL Visualization MCP Server (HTTP/SSE)
============================================================
Server starting on http://localhost:8000
Available Endpoints:
- Health: http://localhost:8000/health
- Tools: http://localhost:8000/tools
- MCP Call: http://localhost:8000/mcp/call (POST)
- SSE: http://localhost:8000/sse步骤2：为HTTP配置客户端
更新MCP客户端配置以使用HTTP：
{
"mcpServers": {
"flow-viz-mcp": {
"url": "http://localhost:8000",
"transport": "http"
}
}
}备注：使用MCP客户端时，保持HTTP服务器在单独的终端中运行。
选项3：交互式CLI（直接使用）
交互式命令行界面提供了一种用户友好的方式，无需MCP客户端即可直接使用工具：
python interactive_cli.py特征：
- 生成桑基图 -工作流数据流的交互式可视化
- 按任务范围（开始/结束任务）筛选或可视化整个工作流程 - 选择度量（体积、操作计数或速率） - 可选关键路径突出显示
- 流量汇总统计 -分析I/O模式和瓶颈
- 关键路径分析 -确定性能关键操作
- 列出任务 -使用PID按拓扑顺序查看所有任务
- 多工作流支持 -在不同工作流之间切换
- 可调节画布尺寸 -交互式调整桑基图画布大小
工作流发现： CLI会自动发现 workflow_traces/ 启动时打开目录，并允许您选择要分析的目录。
选项4:MCP检查员（用于开发和测试）
MCP检查器提供了一个基于web的UI，用于测试您的MCP服务器：
# Install the MCP Inspector (one-time setup)
npm install -g @modelcontextprotocol/inspector
# Run the inspector with your server
npx @modelcontextprotocol/inspector python run_server.py这将打开一个浏览器界面，您可以在其中：
- 查看所有已注册的工具及其模式
- 具有自定义参数的测试工具调用
- 查看请求/响应日志
- 调试工具行为和输出
适用于：
- 验证工具合同和参数类型
- 无需编写代码即可测试边缘情况
- 调试服务器响应
可用工作流
将工作流跟踪数据放入 workflow_traces/ 目录具有以下结构：
workflow_traces/
/
_4n_pfs_large_schema.json
_4n_pfs_large/
*.BlockTrace.json
*.DatalifeTrace.json系统在启动时自动发现所有工作流。
配置
为了有效地使用此工具，您可能需要编辑以下文件和值：
- MCP客户端配置文件:
- 有关每个客户端的详细配置说明，请参阅 集成指南. - 克劳德桌面: claude_desktop_config.json （见上文克劳德桌面集成部分） - 光标IDE: mcp.json （参见 集成指南-Cursor IDE) - 终端代理：特定于代理的配置文件（请参见 集成指南-Gemini终端代理) - 要编辑的常用值: - "args": [" /run_server.py"]：更新 指向克隆此存储库的绝对路径。 - "cwd": " "：更新 指向此存储库的绝对路径。 - "PATH": " /.venv/bin:${PATH}"：更新 指向此存储库的绝对路径。
- 工作流跟踪(
workflow_traces/):
- 文件：这是一个放置工作流特定数据的目录。 - 位置: /workflow_traces/ - 要编辑的值：您将在此处添加子目录，每个子目录代表一个工作流。在每个工作流目录中，您将放置您的模式(*_schema.json)以及跟踪文件（例如。， *.BlockTrace.json, *.DatalifeTrace.json).有关预期结构，请参阅“可用工作流”部分。
项目结构
flow-viz-mcp/
README.md # Project overview and usage guide
interactive_cli.py # Interactive command-line interface
run_server.py # MCP server launcher (stdio)
run_server_http.py # MCP server launcher (HTTP/SSE)
pyproject.toml # Python project configuration
docs/ # Documentation
INTEGRATION_GUIDE.md # Integration instructions for various clients
GEMINI_INTEGRATION.md # Detailed Gemini terminal agent integration
FILTERING_GUIDE.md # Task filtering input format guide
workflow_structure.md # Required directory structure
prompt.json # MCP prompt templates
src/dfl_mcp/ # Main source code
server.py # MCP server implementation
config.py # Configuration settings
data_parser.py # Trace and schema parsers
graph_builder.py # DFL-DAG construction
models.py # Data models
analysis/ # Analysis modules
sankey_utils.py # Sankey diagram generation
metrics.py # Flow statistics
critical_path.py # Critical path analysis
pattern_rules.py # Pattern identification
task_ordering.py # Task ordering utilities
tests/ # Unit tests
test_parser.py
test_builder.py
test_sankey.py
test_stats.py
workflow_traces/ # Workflow trace data
ddmd/
ddmd_4n_pfs_large_schema.json
ddmd_4n_pfs_large/
*.BlockTrace.json
*.DatalifeTrace.json
montage/
...
output/ # Generated visualizations
sankey_*.html
*_summary.txt