Telecom Browser MCP

电信浏览器mcp-Codex存储库指南

任务

此存储库是一个支持电信的浏览器MCP服务器和测试工具。针对以下方面进行优化：

1. 真实的MCP/工具合同
2. 失败关闭适配器行为
3. 确定性证据收集
4. 驾驭第一次繁殖
5. 在声明产品回归之前进行运行时现实验证

先读取

在编辑之前，请阅读最低限度的相关事实：

• README.md
• docs/setup/codex-mcp.md
• docs/usage/codex-agent-usage.md
• .github/workflows/ci.yml
• 触摸下的代码路径 src/telecom_browser_mcp/**
• 最接近匹配测试 tests/**

只有在需要真实完成任务时才能阅读更多内容。

合同授权令

当来源不一致时，请按以下顺序选择存储库真相：

1. .github/workflows/ci.yml
2. 执行公共MCP表面的合同和集成测试
3. 运行时代码 src/telecom_browser_mcp/**
4. 设置和使用文档 docs/**
5. README.md

除非合同变更是有意、实施、验证和记录的，否则不要放松测试或工作流程期望以适应意外行为。

当文档与可执行事实不一致时，更新同一任务中的文档。

每次适用的回购规则

• 保持公共MCP输入的明确性。不发布公共顶级 kwargs 现场。
• 保留结构化响应信封和显式故障元数据。
• 比起通用的点击/选择技巧，更喜欢回购脚本、MCP工具、线束流和适配器挂钩。
• 对于APNTalk适配器路径，在未实现行为时失败关闭。不要让通用的脚手架默认值、继承的存根或占位符成功信封伪装成工作行为。
• 将仅沙盒浏览器启动、设备、信号或媒体限制视为环境发现，除非在支持主机的运行时中再现。
• 当任务与运行时、浏览器、信号或媒体相关时，在补救之前收集证据。
• 在同一任务中更新相关测试和文档之前，不会进行更改。
• 不要默默地更改公共MCP工具名称、必填字段、响应信封或故障语义。
• 更喜欢最小的可防御的更改，以保持合同的清晰度和可重复性。
• 在没有复制证据的情况下，不要将环境限制转换为产品错误声明。

首选执行顺序

1. 绘制实际执行路径。
2. 确定最小的可防御切片。
3. 在运行时面临问题时复制和收集证据。
4. 实施。
5. 首先运行狭义验证。
6. 根据需要进行更广泛的验证。
7. 更新文件和证据。
8. 总结剩余风险和任何剩余的环境约束。

验证最低要求

• MCP工具输入/输出/包络更改：

从以下位置运行精确的合同工作流命令 .github/workflows/ci.yml 以及最接近的合同测试。

• 适配器行为更改：

运行最接近的单元测试和最窄的线束或集成路径来练习适配器。

• 运行时、浏览器、媒体或信号更改：

首先使用工具证据进行复制，将环境与产品进行分类，然后在声明产品回归之前进行主机验证。

• 诊断或证据管道变更：

验证确定性工件形状、故障元数据和最近的受影响测试。

• 仅文档更改：

验证引用的命令、路径、文件名和工具名称是否仍然存在。

仅在窄切片通过后或任务更改共享合约表面时才扩大验证范围。

证据和人工制品处理

• 尽可能为运行时面临的问题保存确定性证据。
• 比起纯散文的声明，更喜欢结构化的工件。
• 在提交工件或文档之前，修改机密、令牌、凭据、电话号码、会话标识符和私有端点。
• 不要从未保存、不可复制或仅限沙盒的观察中声明实时服务回归。
• 当证据不完整时，明确地说出来，并保持结论的界限。

首选工具和命令

• 搜索： rg, rg --files
• 独自创立 python -m pip install -e .[dev]
• 浏览器DEP： python -m playwright install chromium
• MCP烟雾（如有）： health, capabilities, list_sessions
• 互操作探测： python scripts/run_mcp_interop_probe.py
• 按照中的确切工作流命令进行操作 .github/workflows/ci.yml 当MCP收缩表面发生变化时。

安全和发布强化

Stdio是最安全的默认传输方式。HTTP/SSE传输绑定到 127.0.0.1 默认情况下，可以在本地运行，而无需开发人员使用令牌。非本地HTTP/SSE绑定失败关闭，除非两者都关闭 TELECOM_BROWSER_MCP_UNSAFE_BIND=1 和 TELECOM_BROWSER_MCP_AUTH_TOKEN 设置。不要暴露未经身份验证的HTTP/SSE传输。

open_app 仅接受 http 和 https URL。可以通过以下方式限制主机访问 TELECOM_BROWSER_MCP_ALLOWED_HOSTS 作为逗号分隔的主机名/glob列表。默认情况下，本地、环回、私有、链接本地、保留、多播和云元数据目标被阻止，包括DNS解析后到达的目标。仅利用局部目标需要两者 TELECOM_BROWSER_MCP_ALLOW_LOCAL_TARGETS=1 以及一个明确的本地主机允许列表条目。

同样的URL策略也被安装为Playwright浏览器请求保护，用于路由HTTP/HTTPS请求，包括文档导航、重定向、iframe导航、fetch/XHR和通过Playwright路由显示的子资源。这是一个有界闭包，而不是声称所有浏览器内部流量都受到控制；部署层出口控制仍然是深度生产防御所必需的。

证据包写在每个会话工件根下。文本JSON/HTML工件针对承载令牌、Cookie、密码、API密钥、SIP用户名、类电话号码值、会话ID、专用端点和敏感查询参数进行集中编辑。屏幕截图是敏感的像素伪影；默认情况下，它们对于非线束目标是禁用的，可以通过以下方式显式启用 TELECOM_BROWSER_MCP_CAPTURE_SCREENSHOTS=1.Bundle列出了记录屏幕截图敏感性元数据，并明确表示未实现像素级屏幕截图编辑。永远不要提交真正的调试包。

APNTalk现在支持可见UI登录和有界运行时桥观察。当APNTalk发出有效 window.__apnTalkTestBridge，适配器可以如实支持 get_registration_status, wait_for_registration, wait_for_ready, wait_for_incoming_call, get_peer_connection_summary，以及有边界的可见UI answer_call/hangup_call 仅使用主软电话控件。 get_store_snapshot 故意关闭。

有关当前有界APNTalk支持矩阵、快速入门、拒绝边界和网桥兼容性说明，请参阅 docs/modernization/apntalk-release-handoff.md, docs/用法/codex-agent-usage.md，以及 docs/apntalk运行时桥合同.md.

实时stdio/SSE/HTTP验证仍然是运行时现实的，而不是沙盒友好的。在受限环境中，环回套接字创建或子进程第一次接触可能会被阻止；将这些结果归类为环境限制，并在声明运行时兼容性之前运行具有主机功能的烟雾助手：

bash scripts/run_live_transport_smoke.sh all

目前的有界释放判决是 READY_FOR_BOUNDED_RELEASE关于当前的关闭状态、实时验证证据和剩余边界，请参见 docs/live-transport-verification-verdict.md, docs/residual-closure-audit.md，以及 docs/security-residual-register.md.

对于Codex CLI注册和复制粘贴传输示例，请从以下内容开始 docs/setup/codex-mcp.md.

目录映射

• src/telecom_browser_mcp/ --运行时代码、适配器、工具、服务器、诊断、证据
• tests/ --单元、合同、集成、线束、现场验证
• scripts/ --引导、探测器、护栏、释放助手
• docs/setup/ --设置和注册
• docs/usage/ --运行时指导和操作流程
• docs/ --诊断、发布强化、补救、治理类流程文档

何时使用子代理

• 使用 repo_mapper 用于大型或跨领域任务。
• 使用 contract_reviewer 在更换MCP表面之前或之后。
• 使用 runtime_triager 用于运行时/浏览器故障或实时验证。
• 使用 adapter_worker 一旦理解了问题，就可以进行有针对性的适配器或工具实现。
• 使用 ci_release_guard 用于工作流、打包、可安装性和发布强化任务。
• 使用 docs_evidence_curator 经过大量的取证工作。

如果命名的子代理在当前运行时不可用，请继续不使用它。不要发明缺失的子代理或假装它们已运行。

何时使用技能

• $telecom-mcp-bootstrap 用于设置、注册和首次运行验证
• $telecom-runtime-triage 用于浏览器/运行时/环境拆分
• $adapter-contract-work 用于适配器和APNTalk行为更改
• $tool-contract-guardrails 用于MCP工具、模式或信封更改
• $harness-scenario-work 用于确定性场景包
• $diagnostics-evidence 用于捆包审查和故障分类
• $release-hardening 用于打包、工作流和文档对齐
• $closed-loop-remediation 用于多步骤复制→ 分类→ 修理→ 验证回路

如果某个命名技能在当前运行时不可用，请继续不使用它。不要发明缺失的技能或阻止它们。

竣工标准

只有当以下所有条件都为真时，任务才完成：

• 变更已实施
• 最近的相关验证通过
• 当改变后的表面需要时，进行了更广泛的验证
• 文档和操作员指南与新的事实相一致
• 明确规定了剩余风险、环境限制和未经证实的假设