Treg Claude Connector 目录提交指南：从工程验证到发布回滚的完整 Runbook

后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载本文是一份面向 Treg 项目维护者的发布准入手册解读围绕docs/CLAUDE-CONNECTOR-SUBMISSION.md展开它完整记录了将 Treg 的 catalog-only Claude 连接器提交到 Anthropic Connectors Directory 所需的目录字段、Owner 前置条件、工程证据、强制生产测试、评审与监控回滚流程。读完本文你将掌握连接器目录提交的每一道关卡并理解仓库中/mcp/v2/表面背后的源码实现src/treg/mcp.py、src/treg/config.py、src/treg/bootstrap.py如何支撑这些验收标准。一、提交全貌目录字段与连接器定位Treg 的 Claude 连接器是一个**仅面向目录catalog-only**的 MCP 服务Claude 通过它搜索并调用 Treg 精选的外部数据 API 目录而无需把任何 API Key 交给 Claude。提交到目录时的字段值如下表来自 docs/CLAUDE-CONNECTOR-SUBMISSION.md字段提交值NameTregTaglineLive data and APIs for Claude, without API keysCategoriesData; Sales and marketing; ProductivityPublisherSuperdesignTransportStreamable HTTPServer URLhttps://treg.to/mcp/v2/AuthenticationOAuth DCR/CIMD with S256 PKCEDocumentationhttps://treg.to/connectors/claudePrivacyhttps://treg.to/privacySupporthttps://treg.to/supportLogoplugin/assets/logo.png1024×1024 市场 LogoAllowed link URIsNoneAvailabilityImmediately after directory approval其中Allowed link URIs 为 None是一个有意的安全决策连接器不向 Claude 暴露任何可跳转的外部链接详见下文 402 错误处理中的去支付指针逻辑。定位红线Treg 连接器必须始终被描述为Superdesign 发布的第三方/社区连接器。除非 Anthropic 明确授予相应标签不得在列表中使用 official官方、Anthropic-builtAnthropic 构建、Anthropic-approvedAnthropic 批准、verified已验证或 certified已认证等措辞。这一点同时在 src/treg/web/claude-connector.html 中体现——页面醒目位置标注 Community connector 与 Published by Superdesign目录工具描述中也被测试强制排除 official / anthropic verified / best provider 等词见 tests/test_mcp_directory.py 中test_v2_declares_exact_directory_contract。注意版本语义的区分/mcp/v2/是 Treg 的第二个 MCP 传输表面URL 中的 v2而Connector release V1指提交到目录的第一个产品发布版本二者是不同概念docs/context/architecture/mcp-oauth.md。二、Owner 前置条件组织权限与评审访问提交之前Owner 必须逐项完成runbook 中的复选框获得 Claude.ai Team 或 Enterprise 组织的 Owner 权限。注意platform.claude.com 的 API 组织不满足此要求。批准名称、标语、分类、catalog-only 范围、数据处理答案和 Logo。选择一种评审者访问方式选项说明默认评审者用任意已验证邮箱注册。新 Treg 团队获得$1.00 免费额度无需绑定支付方式可立即使用平台提供的 catalog 端点扩展测试评审者将用于登录的 Treg 邮箱发给 SuperdesignSuperdesign 向claude-connector-review-org发送邮箱绑定邀请该组织含$20.00 评审额度。邀请绑定特定邮箱不是通用或可分享的代码评审结束后撤销评审 OAuth 授权以及验收调用中使用的任何临时 provider 访问。runbook 还强调不得在仓库或测试证据中存储任何评审者密码、OAuth code、访问令牌、刷新令牌或 provider 密钥评审者密码、OTP 或令牌不得写入普通提交笔记。三、工程证据六工具契约与归因提交前必须完成以下工程检查并保存带日期、无密钥的证据测试输出、Inspector 结果、端点 id、预期/实际余额差值、审计 id、已打码截图全量自动化测试通过覆盖六工具契约、注解annotations、schema、方法分离读/写、catalog-only 解析、OAuth 版本隔离、传输保护、定价、计量、审计、幂等与错误归因。MCP Inspector连接https://treg.to/mcp/v2/完成认证列出恰好六个预期工具并成功调用每个工具。部署后的连接器在 catalog 搜索、请求、详情、余额读取和 provider 调用中发出claude-connector归因。既有团队 MCP 契约https://treg.to/mcp/保持不变。六工具契约的源码对照runbook 中列出的六个核心工具是catalog_search、catalog_get、catalog_call_read、catalog_call_write、balance、catalog_request。从 src/treg/mcp.py 源码看目录表面directory_mcp实际注册了完整的十工具集合六工具契约是其核心子集工具职责注解annotationscatalog_search按任务词搜索目录返回价格与实测可靠性read-only idempotentcatalog_get单个端点全量信息参数、价格、示例响应、同能力可比 providerread-only idempotentcatalog_call_read仅调用目录中声明为 GET/HEAD/OPTIONS 的端点read-only open-worldcatalog_call_write仅调用目录中声明为 POST/PUT/PATCH/DELETE 的端点destructive open-worldcatalog_call_media音频端点返回原生 MCP AudioContentdestructive open-worldresources_list列出当前团队持有的 provider 资源如 Fish 音色read-only idempotentbalance团队预付费余额与在途 holdsread-only idempotentcatalog_request记录目录缺失的能力需求不调用 provider、不扣费非幂等、非破坏性feedback提交问题报告或建议非幂等、非破坏性review对某次调用评价有用性非幂等、非破坏性关键设计源码证据方法分离由 catalog 数据驱动catalog_call_read传入allowed_methodsfrozenset({GET,HEAD,OPTIONS})catalog_call_write传入allowed_methodsfrozenset({POST,PUT,PATCH,DELETE})src/treg/mcp.py 第 1479–1518 行。调用前先校验 HTTP 方法类别方法不符直接返回明确错误测试test_v2_call_tools_enforce_catalog_method_class_before_calling_api验证了这一点。catalog-only 边界V2 表面无法解析团队自有工具路径team-tool/private会返回 unknown endpointmy_tools与通用call工具不在目录表面中tests/test_marketplace_call.py 专门证明同名团队工具无法遮蔽 catalog-only 调用路由。工具标题双写每个工具在annotations.title中重复其显示标题Anthropic 提交门户会独立于顶层工具标题校验注解标题测试逐项断言test_v2_declares_exact_directory_contract。归因V2 表面通过_DIRECTORY_SURFACEclient_nameclaude-connector注入X-Treg-Client: claude-connector与团队表面mcp区分审计行中client字段因此可区分两个表面tests/test_mcp_directory.py 的test_team_and_directory_catalog_call_results_match_except_attribution断言{row[client]} {mcp, claude-connector}。四、强制生产自定义连接器测试九步验收Anthropic 文档说明自定义连接器与目录连接器使用同一运行时因此 runbook 将该测试设为阻断提交的关卡。在 Claude.ai 中按以下九步执行每一步记录 pass/fail、UTC 时间、surface、端点 id、预期费用、实际费用与对应审计 id添加自定义连接器在 Claude.ai 中将https://treg.to/mcp/v2/添加为自定义连接器。登录与身份核对用评审者邮箱按所选访问方式登录选择生成的团队核对显示的 identity、团队、余额与每日上限。只搜索、不调用让 Claude 搜索example.com的反链端点对比多个定价选项在发起 provider 调用前停下。读类调用选一个启用平台 Key 的、价格低于 $0.01 的 GET/HEAD/OPTIONS 端点让 Claude 执行验证无需写入确认即可成功记录精确余额与审计差值。写类调用选一个价格低于 $0.01 的基于 POST 的搜索端点非变更型让 Claude 执行验证Claude 呈现写入审批批准后记录成功与精确差值。余额与请求让 Claude 查询balance然后提交一个明确标注的测试catalog_request。工具清单核对验证工具列表仅包含catalog_search、catalog_get、catalog_call_read、catalog_call_write、balance、catalog_request创建或使用同名团队工具验证它无法遮蔽 catalog 端点。重连断开连接器重新连接再次完成 OAuth。跨客户端冒烟在 Claude Code 与 Claude Desktop 中用同一账号冒烟测试仅当实际测试过移动端才记录 mobile 已测。提交包中绝不粘贴包含个人数据的原始 provider 响应。为什么自定义测试能通过生产路径的源码保障该九步测试之所以可行是因为/mcp/v2/表面在源码层已经实现了对应的保障机制OAuth 流程RequireAuthForProtectedTools中间件对任何未携带凭据的 MCP 请求返回 401 并携带WWW-Authenticate: Bearer scope… resource_metadata…头src/treg/mcp.py 第 1694 行起。已过期的 access token 返回errorinvalid_tokenRFC 6750 §3.1这正是 OAuth 客户端触发刷新 grant 的信号。V1/V2 的 audience 严格隔离V2 token 无法通过/mcp/校验反之亦然test_transports_reject_the_other_mcp_versions_token。无写确认的读调用catalog_call_read的注解为read_only_hintTrue, destructive_hintFalseClaude 据此对 GET/HEAD/OPTIONS 类调用不呈现写入确认。写审批catalog_call_write注解为destructive_hintTrue, open_world_hintTrue促使 Claude 对 POST/PUT/PATCH/DELETE 呈现审批。无法遮蔽catalog-only 调用路由走/catalog/call/{id}而团队自有工具路由是/call/{rest}V2 表面只接受 catalog idcatalog_onlyTrue。无支付指针余额不足时/catalog/call/返回 402_without_purchase_pointers递归剥除topup_url键并从任何字符串中移除 URL——这是 ChatGPT 提交表单是否引导用户离开进行购买问题的诚实验证答案仅限 MCP 路径CLI 与 dashboard 的 402 仍携带充值链接。测试test_v2_write_call_and_insufficient_balance_errors_use_shared_behavior断言 402 响应中无topup_url、无任何http:///https://子串。五、提交与评审流程细节Owner 终审完整审查字段集、证据、数据处理答案与声明。提交入口从 Claude.ai 组织的 settings 提交而非API Console 组织。稳定性承诺评审期间保持/mcp/v2/及其工具名稳定。反馈闭环将评审者反馈转交工程任何实质性范围、文案、安全或品牌变更须经 Owner 批准后再提交。上线前验证在批准公告前验证在线列表、其链接、OAuth 流程、Logo、社区/验证标签与工具集。源码侧对应的评审期间稳定性由测试保障test_v2_declares_exact_directory_contract将工具名、标题、注解与 schema 形状锁定为精确契约且断言输出 schema 所有字段非必填not tool.output_schema.get(required)。六、发布后监控与回滚七天窗口发布后前七天每日审查claude-connector流量与 Anthropic 健康视图之后每周。跟踪指标包括OAuth 失败率401/403/421 状态码比率工具错误与 provider 错误率延迟与花费余额不足拒绝用量回滚是加性的additive卸载或禁用/mcp/v2/不修改/mcp/。已存在的 v2 grant 仍被存储但无法触达任何活动的 v2 资源。这一设计在 src/treg/bootstrap.py 中体现TREG_CLAUDE_CONNECTOR_ENABLED默认falsesrc/treg/config.py 第 437 行关闭时 V2 不挂载、其 lifespan 不启动、V2 资源元数据与新 grant 被拒绝、catalog-only 调用路由返回 404而团队/mcp/表面完全不受该开关影响docs/context/architecture/mcp-oauth.md 的 Claude connector feature flag 一节。测试test_v2_feature_flag_disables_mount_metadata_grants_and_catalog_route逐一验证了这四类关闭行为。七、双表面维护契约为什么提交一个表面不会破坏另一个runbook 反复强调现有团队 MCP 契约不变其源码支撑是一张严格的共享/差异表docs/context/architecture/mcp-oauth.md领域必须共享有意差异catalog 搜索加载、排序、价格视图、near-miss、同一进程观测缓存下一步指引next与事件源端点详情/catalog/endpoints/{id}路由与错误形状客户端归因调用请求组装、凭据、策略、限额、幂等、relay、错误、计量、审计团队 MCP 接受团队工具V2 仅接受 catalog id 且按读/写拆分方法余额/反馈/catalog 请求路由、错误形状、类别、限速、调用者 IP客户端归因与事件源传输host 检查、压缩、缓存头、eager auth、静态能力V2 有独立 audience、元数据路径、scope 标记与 Claude 浏览器 Origin实现层面_SurfacePolicy承载可差异的小集合公共工具注册完全独立名称、描述、输入 schema、安全注解都是公开契约build_mcp_app拒绝 server 与 OAuth 资源版本不匹配的组合ValueError: the MCP server and resource version do not name the same public surface。V2 的_allowed_origins(v2)显式加入https://claude.ai而 V1 不加test_claude_origin_is_explicitly_allowed_and_unknown_origins_are_not且NormalizeDirectoryMCPPath将无尾斜杠的/mcp/v2重写为/mcp/v2/防止 Claude 去掉斜杠后请求落入 V1 挂载点、领到错误 audience 的 tokentest_v2_no_slash_path_rejects_a_v1_token_with_the_v2_challenge。结语这份 runbook 的价值在于它把上架一个目录连接器从一次性配置变成了可复核的工程流程字段与定位先定死Owner 权限与评审额度先备好六工具契约与claude-connector归因由自动化测试锁定生产自定义连接器九步测试作为阻断关卡发布后七天每日监控加加性回滚兜底。对于任何计划把自建 MCP 服务发布到 Claude 目录的团队docs/CLAUDE-CONNECTOR-SUBMISSION.md 与 tests/test_mcp_directory.py 的组合是一套可以直接借鉴的验收模板。赞分享后端API网关MCP 服务dsh-plugin【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址https://gitcode.com/GitHub_Trending/treg/treg点击查看免费下载相关推荐OpenCreator Desktop 跨平台发布实战从离线打包、签名公证到自动更新与回滚的完整 RunbookOpenCreator Desktop 跨平台发布实战从离线打包、签名公证到自动更新与回滚的完整 Runbook 本文是一份可直接照做的 OpenCreato人工智能AI 应用AI AgentAI 技能媒体生成音视频桌面应用OmniRoute 发布检查清单实战指南从版本号提升、npm 可信发布到回滚的完整发布流程OmniRoute 发布检查清单实战指南从版本号提升、npm 可信发布到回滚的完整发布流程 导读 OmniRoute 是一个单端点接入 350 提供方、1后端API网关LLM 网关人工智能大模型MCP 服务桌面应用LiteParse 文档解析缺字、乱码还是空白4 个症状带你 5 分钟定位LiteParse 文档解析缺字、乱码还是空白4 个症状带你 5 分钟定位 LiteParse 是一款开源、本地运行的文档解析工具支持 PDF/Office后端API网关MCP 服务dsh-plugin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考