MCP Samply

mcp样品

mcp-samply 是用于的MCP服务器 samply.

它专为需要以下功能的AI代理而设计：

• 记录CPU配置文件 samply
• 现有负载 profile.json / profile.json.gz 文件
• 将Firefox Profiler数据转化为简洁、对代理友好的热点摘要
• 深入到特定的线程和函数

预期运行时间为：

npx mcp-samply

为什么存在

samply 擅长记录配置文件并在Firefox Profiler中打开它们，但AI代理需要第二层：

• 稳定的MCP接口
• 结构化摘要，而不是原始表重的配置文件JSON
• 一种从保存的配置文件脱机工作的方法

mcp-samply 提供该层。

工具

服务器公开了八个MCP工具：

• samply_doctor：验证是否 samply 二进制文件可用，并报告版本/环境详细信息
• samply_record：run samply record --save-only 并将配置文件保存到磁盘
• samply_summarize_profile：生成线程、热点、标记和总体样本分布的简洁摘要
• samply_inspect_thread：详细检查一个螺纹，包括代表性堆栈
• samply_search_functions：在加载的配置文件中搜索函数或库名称
• samply_breakdown_subsystems：按命名空间前缀对本机函数进行分组，以便代理可以看到哪些Rust/C++子系统主导了配置文件
• samply_focus_functions：恢复目标函数或命名空间周围最常见的调用者/被调用者上下文
• samply_locate_symbols：将热本机符号映射回可能的本地源文件，以便代理可以检查实现细节

前符号化

默认情况下， samply_record 使能够 --unstable-presymbolicate.

这导致 samply 发出sidecar文件，例如：

profile.json.gz
profile.json.syms.json

mcp-samply 自动读取sidecar，并在离线分析期间使用它将本地地址解析为函数名。这对于人工智能驱动的绩效工作至关重要；没有它，保存的配置文件通常只包含原始地址。

与Codex一起使用

MCP服务器配置示例：

{
  "mcpServers": {
    "samply": {
      "command": "npx",
      "args": ["-y", "mcp-samply"],
      "env": {
        "MCP_SAMPLY_BIN": "samply"
      }
    }
  }
}

如果 samply 未打开 PATH，set MCP_SAMPLY_BIN 到绝对可执行路径。

即使在以下情况下，您仍然可以在现有配置文件上使用分析工具 samply 它本身没有安装。

典型代理工作流程

1. 呼叫 samply_doctor.
2. 呼叫 samply_record 使用命令、PID或 all=true.
3. 呼叫 samply_summarize_profile 在生产的轮廓上。
4. 使用 samply_inspect_thread 对于最热的线程。
5. 使用 samply_search_functions 针对重点跟进问题。
6. 使用 samply_breakdown_subsystems 通过crate/module前缀量化本地热点。
7. 使用 samply_focus_functions 转换系统调用，例如 stat / read 回到可操作的上游呼叫路径。
8. 使用 samply_locate_symbols 在读取或修补代码之前，将最热的本机帧映射回本地源文件。

本地开发

npm install
npm run build
npm test

在本地运行MCP服务器：

npm run dev

构建输出通过发布 mcp-samply 箱子入口，这样包裹就可以用 npx.

发布到npm

此存储库包括GitHub Actions工作流，位于 .github/workflows/publish-npm.yml.

在使用它之前，添加一个名为 NPM_TOKEN 具有发布访问权限 mcp-samply npm上的包。

工作流可以通过两种方式触发：

1. 发布一个标记与包版本匹配的GitHub Release，例如 v0.1.0.
2. 使用以下命令从“操作”选项卡手动运行工作流 workflow_dispatch 并提供确切的软件包版本，例如 0.1.0.

在每次发布运行时，工作流将：

1. 安装依赖项 npm ci.
2. 跑 npm run check.
3. 跑 npm pack --dry-run.
4. 发布方式 npm publish --provenance --access public.

调试MCP表面

此存储库还包括一个小型本地调试客户端，因此您可以检查MCP表面并调用工具，而无需先连接外部MCP主机。

列出暴露的MCP表面：

npm run debug:mcp -- list-tools

输出包括：

• tools：当前注册的MCP工具，包括输入和输出模式
• prompts：提示定义（如果有）
• resources：资源定义（如果有）

调用工具并打印完整的JSON结果：

npm run debug:mcp -- call samply_doctor

总结此仓库中提交的示例配置文件之一：

npm run debug:mcp -- call samply_summarize_profile --args '{"profilePath":".samply/presym-smoke.json.gz"}'

对本地源树运行符号查找：

npm run debug:mcp -- call samply_locate_symbols --args '{"roots":["/absolute/path/to/project"],"symbols":["rspack::Compiler::build"],"extensions":[".rs",".cc",".cpp"]}'

对于较大的有效载荷，将工具输入存储在JSON文件中并使用 --args-file:

npm run debug:mcp -- call samply_record --args-file ./tool-args.json

推荐的手动调试循环：

1. 跑 npm run debug:mcp -- list-tools 确认工具名称和模式。
2. 呼叫 samply_doctor 首先验证环境和二进制分辨率。
3. 使用 samply_record 或已保存 profile.json(.gz) 以生成真实的输入。
4. 跑 samply_summarize_profile，然后深入 samply_inspect_thread, samply_search_functions, samply_breakdown_subsystems，以及 samply_focus_functions.
5. 使用 samply_locate_symbols 使用项目根目录确认热点符号映射回您期望的文件。