Skip to content

[FEATURE] 移除 MCP 支持,剥离 mcp 依赖 #137

Closed

Description

@codeasier

功能描述

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

  1. codeasier commented on Sep 17, 2026

    @codeasier
    OwnerAuthor

    结论

    问题成立:仓库内没有 MCP 客户端,Agent 主路径已是 skills + CLI,但 mcp>=1.0.0,<2 仍是核心硬依赖。整段移除是可接受的产品决策,不是必须先改成 optional extra。实现时有三处边界需要收紧,否则会误删契约或漏改文档。

    问题是否存在

    成立。

    • pyproject.toml 把 mcp 放在 dependencies,并发布 pt-snap-mcp。mcp 1.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。
    • 仓库内没有 MCP 客户端;docs/en/mcp.md 只有 pt-snap-mcp 启动命令,没有 Claude / Cursor 的客户端配置。
    • #54 的验收本是 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。

    需要收紧的不是「删不删」,而是「怎么删」。

    1. 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 可以删。

    2. 文档和治理清扫范围大于 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.md
      • docs/en/skills.md、docs/zh/skills.md
      • docs/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」。
    3. 验收应写成「安装 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 契约并改名。
    • 按上面清单清扫 docs / AGENTS / governance / 测试注释。
    • CHANGELOG 记 breaking,下一发布 0.4.0。
    • 不把 skill 工作流或 import/split/report 迁回 MCP;那条产品面就此关闭。
  2. codeasier commented on Sep 17, 2026

    @codeasier
    OwnerAuthor

    正文已按评审意见更新:修正「20+ 依赖」与 cryptography 表述、以产品决策(而非事实断言)作为移除依据;补入契约测试改写(非删除)、完整文档/治理清扫清单、依赖树验收与 0.4.0 版本约定。本 issue 现为 #136 Agent 友好化路线图的 P0 子任务。

  3. codeasier commented on Sep 18, 2026

    @codeasier
    OwnerAuthor

    复审结论:正文已吸收上一轮主要意见,可以按 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 保留。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions