MCP工具桥接器

用于回放工作流程步骤的MCP工具桥

docs/MISSION.md --范围、非目标、成功标准，以及此回购与上游回放的关系。

贡献.md --本地 pytest / 拉夫 命令和公关期望（与CI保持一致）。

更改日志.md --发布说明（保留更改日志）。

与重播的兼容性

声明的支持是 replayt>=0.4.25,<0.5 在 pyproject.toml.CI重新安装 replayt==0.4.25 在 replayt-floor 保护下限的工作；默认作业解析最新的 回放 与该范围兼容。

重播时 次要的 或 主要的 如果行更改了此桥使用的行为或API，维护人员应增加依赖范围 pyproject.toml，刷新此表，然后 更改日志.md，如果需要新的地板销，则扩展CI。对于即将到来的 0.5.x 线，请参见 docs/REPLAYT_0_5_COMPATILITY_SPIKE.md （状态、重新运行命令和迁移草稿）。 订购维护人员检查表 （依赖线、表、变更日志、CI层、MCP工具映射、合同测试）： docs/MISSION.md§重播次要线路升级手册.

python pyproject.toml 套 requires-python = ">=3.11".CI练习 CPython 3.11、3.12和3.13 上 乌班图 (ubuntu-latest)以及 CPython 3.12 上 windows-latest，每个都是一样的 拉夫 + pytest 步骤如 本地检查 （参见 .github/works/ci.yml).Windows作业涵盖了打包、控制台脚本和stdio烟雾测试，其中README WinError / Scripts\ 指南适用——请参见 docs/MISSION.md§Windows CI运行程序.Trove分类器列出了口译员未成年人 Linux 矩阵覆盖；内较新的CPython版本 requires-python 在矩阵扩展之前，最好在本地进行验证。

概述

该项目建立在 回放.使用 docs/REPLAYT_ECOSYSTEM_IDEA.md 用于定位上下文和所选的主要模式。

设计原则

docs/DESIGN_PRINCIPLES.md 覆盖 回放 兼容性、版本控制和（用于展示） LLM 边界。

docs/MCP_TOOLS.md 列出MCP工具名称、JSON模式样式输入和 工具→回放 映射表。 docs/MISSION.md§第一次回放支持的工具调用 各州完善了最小回放支持路径和测试的验收标准。

docs/MISSION.md§一次性操作员健康检查 指定 health 子命令（非交互式导入/日志记录/重放版本探测）。基本原理、非目标和架构说明见 docs/ARCHITECTURE.md.

docs/ARCHITECTURE.md 描述了流程边界、分层、工具组，以及此仓库如何保持重播的瘦消费者。

安全、机密和MCP托管

docs/SECURITY.md 列出影响桥接和回放的环境变量， 绝不能记录的内容 （令牌、PII、原始工具参数），推荐 本地stdio与远程stdio 部署模式，以及如何 重放凭据 与这个过程互动。在将服务器暴露给受信任的本地MCP父级之前，请先阅读它。对于 剥离继承的环境 在高保证主机（挂钩、提供者密钥、生成配方）上，请参阅 最小环境继承.

工具暴露： 使用 MCP工具能力等级 桌子在 docs/SECURITY.md 对于每个注册工具的单一、面向操作员的视图（诊断、工作流自检、持久性读取），文件系统和网桥拥有的网络含义，以及建议的默认值 本地dev 对比 共享工作站.为 部分曝光--在给定网桥的固定注册表面的情况下，MCP主机如何限制可调用工具，以及仍然存在哪些风险（包括 带有错误消息的路径或提示)--看 主机侧部分工具暴露.为 什么结构性错误 message 字符串可能包含 共享成绩单时，请参阅 结构化错误消息：路径和操作细节。层表交叉链接 安全和信任边界 在任务文档中保持一致。

参考文件（可选）

docs/reference-documentation/ 可能包括 归因于 上游回放快照 用于离线阅读的文档（来自PyPI sdists）。他们确实如此 不 替换此仓库自己的合同文档(docs/MCP_TOOLS.md等等）。 要在更改支持的重播范围后刷新快照，请运行 python scripts/refresh_replayt_reference_docs.py 从repo根目录（有关详细信息，请参阅参考README）。

快速开始

MCP主机： 为配置客户端 标准 并运行 replayt-mcp-bridge 控制台脚本（来自 [project.scripts] 在 pyproject.toml)或 python -m replayt_mcp_bridge 安装后；两者都通过stdin/stdout使用MCP。看 集成器配方 用于复制粘贴主机JSON和 docs/MISSION.md#mcp服务器stdio 查看完整的规格和验收说明。

诊断回声门（可选）： 省略 replayt_echo 从 tools/list，set REPLAYT_MCP_BRIDGE_DISABLE_DIAGNOSTIC_ECHO_TOOLS 对真理的象征或补充 --no-diagnostic-echo-tools 在服务器启动之前（不适用于 health).看 docs/SECURITY.md.

安全： 任何连接到流程的MCP客户端都可以调用已注册的工具；stdio由父进程控制，因此仅在边界与您的策略匹配的环境中运行网桥。看 安全、机密和MCP托管 和 安全和信任边界.

登录中： 启动时，网桥配置 replayt_mcp_bridge 记录仪 INFO 默认情况下，写入 JSON行 到stderr(event, tool，可选 mcp_request_id, status, …).集 REPLAYT_MCP_BRIDGE_LOG_LEVEL 转换为另一个stdlib级别名称（例如。 DEBUG 或 WARNING)调整冗长。看 docs/SECURITY.md 用于编辑规则和MCP主机日志记录风险。

操作员安装探头： 使用 health 单次检查的子命令（无MCP会话，进程立即退出）：

python -m replayt_mcp_bridge health
replayt-mcp-bridge health

探测器导入桥梁和 回放，以与相同的方式解析重播版本 replayt_version_info 工具，调用 configure_bridge_logging()，并写入人类可读的行以及至少一行 JSON 测井线( replayt_mcp_bridge.health.ok )to 标准错误 关于成功。

完全接受标准和非目标 docs/MISSION.md§一次性操作员健康检查.

python -m venv .venv
# Windows: .venv\Scripts\activate
# Editable install pulls replayt (see pyproject.toml) and pytest; add [dev] for ruff.
pip install -U pip
pip install -e .
# Optional: pip install -e ".[dev]"  # includes ruff

开 视窗，如果 pip install -e . 失败与 WinError 2 更新时 replayt.exe 在...之下 Scripts\，你通常有 混合用户站点和系统 安装或半删除脚本。使用上面的venv（因此所有内容都安装在 .venv\)或修复/移除损坏的部件 replayt 安装无效 ~… pip警告的文件夹 Lib\site-packages.

集成器配方

复制粘贴 标准 MCP主机配置 克劳德桌面 (mcpServers), 光标 (.cursor/mcp.json 和 type: "stdio")，以及 泽德 (context_servers)--包括 command / args, cwd 或工作区笔记，以及 通用的 路径占位符（没有真正的秘密）--位于 docs/MCP_HOST_CONFIG.md。示例使用与此README相同的规范入口点： replayt-mcp-bridge 和 python -m replayt_mcp_bridge.

本地检查（pytest和Ruff）

之后 pip install -e ".[dev]" 在你的venv（拉夫在 dev 额外；pytest包含在基本可编辑安装中）：

ruff check src tests
ruff format --check src tests
pytest -q -m "not network"

一个命令包装器： 从回购根开始， python scripts/run_ci_checks.py 之后 pip install -e ".[dev]" （参见 CONTRIBUTING.md§打开PR前进行检查).奇偶校验规则和范围在 docs/MISSION.md§单一本地检查入口点.

依赖性审计： Linux CI运行 pip-audit 在一个单独的 supply-chain 同样的工作之后 pip install -e ".[dev]".审核失败 那项工作失败了 （封锁）；它是 不 与默认值捆绑在一起 pytest 步骤。从复制确切的命令 docs/DEPENDENCY_AUDIT.md 或 贡献.md.

工作流操作引脚： .github/dependabot.yml 配置 Dependabot 为了 uses: 参考文献（每周，分组PR）。这条路与 pip-audit；参见 贡献.md§GitHub操作引脚更新 和 docs/MISSION.md§依赖机器人.

CI运行相同 拉夫 和 pytest -m 'not network' 踩在 Linux （矩阵 3.11–3.13)等等 视窗 (windows-latest, 3.12 仅）；看见 .github/works/ci.yml, 贡献.md，以及 docs/MISSION.md§Windows CI运行程序.

可选代理工作流

此回购可能包括 .cursor/skills/ 游标样式代理技能目录。调整或删除它以 匹配您团队的工具。

项目布局