### 功能描述 `mcp>=1.0.0,<2` 是核心硬依赖,`pt-snap-mcp` 自 v0.1.1 起随包发布,但仓库内 Agent 主路径(skills + CLI)不经过 MCP,MCP 指南也从未提供任何客户端配置示例。将 Agent 集成入口统一收敛到 skills + CLI、移除 MCP 入口,是一个明确的产品决策(0.x 阶段记 breaking)。 > 修正说明:传递依赖数量随解析结果变化,不宜固定表述为「20+」;`cryptography` 亦非 mcp 1.x 的直接依赖。仓库内无消费方只能证明内部工作流不依赖 MCP,不构成「外部无人使用」的证明,因此以产品决策而非事实断言作为移除依据。 ### 使用场景 只使用 CLI / Python API 的用户不应为不使用的 MCP 依赖栈付出安装成本;Agent 集成入口统一后,维护与测试面更小。 ### 期望的实现方式(已并入评审意见) 1. **删除范围**:`src/pt_snap_cli/mcp/`、`pt-snap-mcp` 入口、核心 `mcp` 依赖、`tests/test_mcp_server.py` 2. **`tests/test_contract_cli_mcp.py` 不整文件删除**:改写为 CLI ↔ `SnapshotAnalyzer` 契约测试并改名,保留 focus、模板列表/信息、`leak_detection` 结果、metadata JSON、缺 focus / 缺参 / 无效 device 等跨表面断言(这是目前唯一的跨表面契约覆盖) 3. **文档与治理清扫(完整清单)**: - `README.md` / `README_zh.md` / `docs/{en,zh}/mcp.md` / 各级 `AGENTS.md` - `docs/{en,zh}/querying.md`(`max_rows=100` 互链)、`database.md`、`skills.md`、`quickstart.md` - `.github/ISSUE_TEMPLATE/AGENTS.md`、`tests/skills/README.md` - `tests/test_governance.py` 的 `USER_INSTALL_DOCS` 硬编码了 `docs/*/mcp.md`,只删文件会红,需同步更新 - `api.py`、`tests/test_snapshot_analyzer_cache.py`、`tests/test_query_cache_perf.py` 中「MCP server singleton」注释改为「长驻 `SnapshotAnalyzer`」 - 历史 CHANGELOG 条目保留;仅在新版本记 breaking 4. 保留 `SnapshotAnalyzer`(`api.py` 不依赖 `mcp`);不把 skill 工作流或 import/split/report 迁回 MCP,该产品面就此关闭 ### 验收标准 - [ ] 安装 `pt-snap-cli`(无 extra)后依赖树不含 `starlette` / `uvicorn` / `mcp`(以依赖树验证,不限于 README 检查) - [ ] `tests/test_contract_cli_mcp.py` 改写为 CLI / `SnapshotAnalyzer` 契约并改名 - [ ] `pytest` 全绿(含改写后的契约测试与更新后的 `test_governance.py`) - [ ] 上述文档 / 治理清单全部清理 - [ ] CHANGELOG 记 breaking,下一发布版本 0.4.0
Activity
codeasier commentedon Sep 17, 2026
结论
问题成立:仓库内没有 MCP 客户端,Agent 主路径已是 skills + CLI,但
mcp>=1.0.0,<2仍是核心硬依赖。整段移除是可接受的产品决策,不是必须先改成 optional extra。实现时有三处边界需要收紧,否则会误删契约或漏改文档。问题是否存在
成立。
pyproject.toml把mcp放在dependencies,并发布pt-snap-mcp。mcp1.x 会带上starlette、uvicorn、httpx、pydantic、sse-starlette、jsonschema、pyjwt等。cryptography不是当前 1.x 的直接依赖,传递树大小取决于解析结果,不宜写成固定「20+」。skills/下没有任何 MCP /pt-snap-mcp引用。诊断 skill 走pt-snap query/pt-snap metadata,并禁止 persist focus。origin/main的AGENTS.md也写明 skill 管理是 CLI-only,不挂到 MCP。docs/en/mcp.md只有pt-snap-mcp启动命令,没有 Claude / Cursor 的客户端配置。pip install pt-snap-cli[mcp]。后来做成硬依赖,才造成现在的安装税。保留
SnapshotAnalyzer、不改 CLI 行为,这一点是对的。api.py不依赖mcp。方案是否合理
整段删除合理,前提是接受对已发布入口的 breaking。
pt-snap-mcp从 v0.1.1 起随包发布(现标签到 v0.3.0)。仓库证明不了外部没有mcp.json用户,但 MCP 指南从未给出客户端配置,skill 也不走这条路径。若维护者接受直接断入口,不必再经过[mcp]extra。0.x 下这次应记 breaking,并升到 0.4.0。需要收紧的不是「删不删」,而是「怎么删」。
tests/test_contract_cli_mcp.py不应整文件删除。它是目前唯一把 CLI 规范化输出和另一条编程面(现为 MCP 包装的
SnapshotAnalyzer)对齐的测试:focus、模板列表/信息、leak_detection结果、metadata JSON、缺 focus / 缺参 / 无效 device。test_cli.py和test_api.py只测各自表面。删 MCP 后应改成 CLI ↔SnapshotAnalyzer契约,而不是连跨表面断言一起丢掉。test_mcp_server.py可以删。文档和治理清扫范围大于 issue 所列。
除 README /
docs/*/mcp.md/ 各AGENTS.md外,origin/main上还有:docs/en/querying.md、docs/zh/querying.md(max_rows=100互链)docs/en/database.md、docs/zh/database.mddocs/en/skills.md、docs/zh/skills.mddocs/en/quickstart.md、docs/zh/quickstart.md.github/ISSUE_TEMPLATE/AGENTS.md(「CLI/MCP project」)tests/skills/README.md(评测适配器仍写 MCP)tests/test_governance.py的USER_INSTALL_DOCS硬编码了docs/*/mcp.md,只删文件会红历史 CHANGELOG 条目保留;新版本写 breaking 即可。
api.py、tests/test_snapshot_analyzer_cache.py、tests/test_query_cache_perf.py里「MCP server singleton」这类注释改成「长驻SnapshotAnalyzer」。验收应写成「安装
pt-snap-cli(无 extra)后依赖树不含starlette/uvicorn/mcp」。不要只搜 README。
pytest全绿要包括改写后的 CLI/API 契约和更新后的test_governance.py。建议边界
src/pt_snap_cli/mcp/、pt-snap-mcp、核心mcp依赖、tests/test_mcp_server.py。tests/test_contract_cli_mcp.py改成 CLI/SnapshotAnalyzer契约并改名。codeasier commentedon Sep 17, 2026
正文已按评审意见更新:修正「20+ 依赖」与 cryptography 表述、以产品决策(而非事实断言)作为移除依据;补入契约测试改写(非删除)、完整文档/治理清扫清单、依赖树验收与 0.4.0 版本约定。本 issue 现为 #136 Agent 友好化路线图的 P0 子任务。
codeasier commentedon Sep 18, 2026
复审结论:正文已吸收上一轮主要意见,可以按 breaking 产品变更实施。
mcp仍是核心硬依赖,SnapshotAnalyzer不依赖 MCP;保留 CLI/Python API、删除 MCP 入口的边界合理。基于当前 main(d73013d),建议再补三点:1. 契约迁移以最新测试全集为准,并保留 API 原有语义。
除正文列举的覆盖外,当前
tests/test_contract_cli_mcp.py已增加参数choices元数据、未知参数与非法 choices 拒绝、focus 的callstack_layout/callstack_layout_error、v1 inline callstack 查询,应一并迁移。缺模板场景也要保留,CLI 当前退出码为 1。迁移不能只替换调用对象:
SnapshotAnalyzer.get_template_info()缺模板返回None,MCP 才包装成{"error": ...};API 查询默认max_rows=None,MCP 才默认 100。应在测试侧规范化这些差异,不为迁移测试改变 API 契约。2. “完整清扫清单”仍有遗漏。
docs/README.md:14、docs/README.md:31仍链接到将删除的 MCP 指南。src/pt_snap_cli/context.py、src/pt_snap_cli/core/context_cache.py、src/pt_snap_cli/core/query_service.py、src/pt_snap_cli/query/executor.py仍用 MCP 举例说明缓存。tests/query/test_executor.py、tests/query/test_memory_peak_cte.py也有 MCP 相关说明。这些缓存实现和测试仍服务于长驻 Python API 调用者,应保留功能与覆盖,只更新说明。
3. 安装验收明确使用干净环境和构建产物。
建议从本次构建的 wheel 做无 extra 安装,核验依赖树无
mcp/starlette/uvicorn,发行包不再声明pt-snap-mcp入口,并验证pt-snap --help与SnapshotAnalyzer可正常使用。已有开发环境可能残留旧依赖,不能以其包列表判断移除是否成功。维持正文的 0.4.0 breaking 约定,历史 CHANGELOG 保留。