AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载摘要 本文围绕 claude-plugins-official 仓库中 mcp-server-dev 插件所附的 connector 目录提交检查清单directory-checklist展开逐项拆解远程 MCP App 进入 Claude Connector 目录前必须满足的硬性审查标准——从认证模型OAuth / authless、工具注解annotations、工具命名、Widget 布局与主题、外链与辅助工具的可见性控制到截图规格与上线后的滥用防护。读完本文你将掌握一套可直接对照自查的提交前检查流程并理解每一条标准背后的实现原理源码级佐证见文内相对路径。 /摘要为什么要有一份提交前检查清单在 claude-plugins-official 仓库中mcp-server-dev 插件 面向设计并构建能与 Claude 无缝协作的 MCP 服务器这一目标由三个技能组合成完整构建路径build-mcp-server入口负责定夺部署模型与工具设计模式、build-mcp-app在远程服务器与 MCPB 包之上叠加交互式 UI Widget、build-mcpb将本地 stdio 服务器连同运行时打包。其中 build-mcp-app 技能 定义了一个关键概念MCP App 是一个标准 MCP 服务器额外对外提供 UI 资源交互组件内联渲染在对话界面中。当你构建的是一个远程 MCP App并希望它出现在 Claude 的 connector 目录中供用户发现和连接时提交审核就开始了。directory-checklist 正是为这个时刻准备的提交远程 MCP App 到 Claude connector 目录前的预检pre-flight文档。它明确声明每一项都是硬性审查标准hard review criterion——不是建议而是不满足就会阻塞列出的门槛。这份清单按领域Area给出 8 类要求是 MCP App 开发者提交前最值得逐字对照的文档。下面按清单原骨架逐项展开并结合仓库中的源码与参考文档说明每条标准为什么存在、如何落地。一、认证AuthOAuth 或 authless二者必居其一目录清单对认证的要求原文如下OAuthDCR 或 CIMD或none无认证。静态 Bearer Token 仅限私有部署会阻塞目录列出。authless 对公共数据服务器有效——上游 API 密钥由服务器持有。这条标准背后是 Claude 的 MCP 客户端对认证类型的明确支持边界。auth.md 给出了完整参考认证类型说明oauth_dcr支持对高流量目录条目更推荐 CIMD 或 Anthropic 托管凭据——DCR 会在每次新连接时注册一个新客户端oauth_cimd支持目录条目推荐优先于 DCRspec 2025-11-25 已将其提升为 SHOULD/首选oauth_anthropic_creds合作伙伴向 Anthropic 提供client_id/client_secret用户同意后使用custom_connection用户在连接时自供 URL/凭据Snowflake 风格none无认证不被支持的类型是用户粘贴式 Bearer Tokenstatic_bearer以及无用户同意的纯机器对机器client_credentials授权。这正是清单中静态 Bearer Token 会阻塞目录列出的直接原因——静态令牌既无法支撑 OAuth 的回调/刷新流程也缺少用户授权语义目录侧不接受这种形态。清单同时指出authless 对公共数据服务器是合法的如果服务器只是代理公开数据上游 API 密钥如process.env.UPSTREAM_API_KEY应由服务器自身持有用户无需提供任何凭据。对于这类读取公开数据、无用户身份的场景无认证即可满足目录要求同时还能省去整条 OAuth 授权服务器的搭建成本。落地提示如果你走 OAuth 路线优先按 CIMD 实现——在/.well-known/oauth-authorization-server提供 RFC 8414 授权服务器元数据并声明client_id_metadata_document_supported: truehost 会把client_id当作一个 HTTPS URL你的授权服务器抓取并校验该文档后继续授权码流程。若需兼容尚未迁移到 CIMD 的 host再补充 DCR 的registration_endpoint作为回退。SDK 已提供mcpAuthRouter()、bearerAuth、proxyProvider等现成辅助不必手搓整个 OAuth AS 表面详见 auth.md。二、工具注解Tool annotationstitle 语义 Hint 一个都不能少清单要求每个工具都必须设置annotations.title并根据语义附加相关 Hintfetch/search 类工具置readOnlyHint: true写操作置destructiveHint/idempotentHint触及外部系统的工具置openWorldHint: true。注解annotations是 host 理解工具行为语义、决定 UI 呈现与风险提示的依据。title是工具的面向用户名称区别于name这个技术标识符必须逐工具设置其余 Hint 则按工具的副作用分类只读操作fetch、search、查询类readOnlyHint: true告诉 host 该调用不会产生副作用写操作根据是否破坏性、是否幂等设置destructiveHint与idempotentHint外联操作工具会触达外部系统第三方 API、远程服务时openWorldHint: true。在 build-mcp-app 的脚手架示例 中可以看到落地形态registerAppTool(server, pick_contact, { description: Open an interactive contact picker, annotations: { title: Pick Contact, readOnlyHint: true }, inputSchema: { filter: z.string().optional() }, _meta: { ui: { resourceUri: ui://widgets/contact-picker.html } }, }, async ({ filter }) { /* … */ });注意这里的readOnlyHint: true是合理选择——打开一个选择器并返回数据不改变任何状态。反过来如果你的工具会删除记录、发起扣费或触发远程写入就必须如实声明destructiveHint等注解让 host 能正确提示用户。三、工具命名Tool names≤ 64 字符snake/kebab 风格清单要求工具名 ≤ 64 个字符使用 snake_case 或 kebab-case。这是目录审查的可机械化校验项过长的名字会在 UI 中被截断风格不一致的名字则影响可读性与 host 的稳定性处理。在代码中工具名就是registerAppTool(server, pick_contact, …)或普通server.registerTool(search_repos, …)的第一个字符串参数——把命名规范当作提交前 grep 一遍即可完成的廉价检查统计所有工具名字符数上限、并统一为下划线或连字符风格。四、Widget 布局Widget layout高度、滚动、触控与对比度清单要求内联高度 ≤ 500px无嵌套滚动容器最小触控目标 44pt两种主题下均达到 WCAG-AA 对比度。这些约束服务于一个核心场景Widget 是渲染在聊天流中的内联 iframe而不是独立页面。超高的组件会把对话撑到无法阅读嵌套滚动外层页面滚动 内层 iframe 滚动会产生滚不动的交互死角44pt是移动端触控的最小安全目标对比度则保证亮/暗两套主题下文本都清晰可读。落地建议在设计阶段就给 Widget 容器设定max-height上限脚手架示例中列表即用了max-height: 300px; overflow-y: auto避免在 Widget 内部再套可滚动区域需要滚动时用最外层单一容器承载可点击项列表项、按钮的 padding 与字号合计不小于 44pt颜色不要写死在只适配亮色的数值上参照下文主题Theming一节用 host 变量 双主题覆盖。五、主题Theming透明背景 双主题 host 变量清单要求html, body { background: transparent }meta namecolor-scheme contentlight dark通过applyHostStyleVariables采纳 host 的 CSS 变量。为什么背景必须是透明的因为 host 会把 iframe 渲染进自己的卡片框架card chrome里——不透明的背景色块会破坏整体观感。iframe-sandbox.md 给出了完整的主题融合模板meta namecolor-scheme contentlight dark /:root { --ink: var(--color-text-primary, #0f1111); --sub: var(--color-text-secondary, #5a6270); --line: var(--color-border-default, #e3e6ea); } html, body { background: transparent; color: var(--ink); } :root.dark .thumb { mix-blend-mode: normal; } /* multiply → 暗色下图片会消失 */const { App, applyHostStyleVariables } globalThis.ExtApps; function applyHostContext(ctx) { document.documentElement.classList.toggle(dark, ctx?.theme dark); if (ctx?.styles?.variables) applyHostStyleVariables(ctx.styles.variables); } app.onhostcontextchanged applyHostContext; await app.connect(); applyHostContext(app.getHostContext());这里的关键机制meta namecolor-scheme contentlight dark声明页面同时适配两套配色applyHostStyleVariables会把 host 的--color-*/--font-*/--border-radius-*令牌写到 iframe 的:root上让 Widget 与宿主视觉完全同源上面的 hex 值只是 host 未提供令牌时的兜底app.onhostcontextchanged负责在运行中跟随主题切换亮 ↔ 暗实时更新连接后再用app.getHostContext()做初始应用暗色模式下要禁用mix-blend-mode: multiply否则图片会消失在暗色背景中。六、外部链接External links一律走app.openLink清单要求使用app.openLink打开外链在 connector 的Allowed link URIs中声明每个源如https://api.example.com使链接跳过确认弹窗。这一条是沙箱约束的直接结果MCP App 的 Widget 运行在带 sandbox 属性的 iframe 中window.open()与a target_blank均被拦截沙箱缺少allow-popups。iframe-sandbox.md 明确给出了三种写法对比// ✗ 被拦截 window.open(url, _blank); // ✗ 被拦截 a href… target_blank…/a // ✓ host 中介 await app.openLink({ url });锚点点击需要拦截默认行为再转交 hostel.addEventListener(click, (e) { e.preventDefault(); app.openLink({ url: el.href }); });为什么外链要由app.openLink中介因为只有 host 侧才有能力在新标签页打开链接并基于 connector 声明的 Allowed link URIs 判断是否弹出确认模态。提交前记得在 connector 配置里完整列出所有可能被打开的源否则用户每次点击都会先看到确认弹窗体验大打折扣。七、辅助工具Helper tools用_meta.ui.visibility藏起来清单要求仅 Widget 使用的工具几何/图片抓取器等要携带_meta.ui.visibility: [app]避免出现在 Claude 的工具列表中。MCP App 的 Widget 可以通过app.callServerTool({ name, arguments })回调服务器上的其他工具例如按需抓取大图、计算几何信息。这类为 Widget 服务的辅助工具如果暴露给 Claude会污染模型可选的工具集合、干扰工具选择。清单要求它们声明_meta: { ui: { visibility: [app] } }visibility: [app]的含义就是仅应用Widget可见。在 build-mcp-app 的宿主特性表 中它与resourceUri声明工具结果渲染哪个ui://资源、prefersBorder: false移动端去掉宿主外框、csp.{connectDomains, resourceDomains, baseUriDomains}声明外部源默认 block-all并列是_meta.ui.*命名空间下的标准键。八、截图Screenshots3–5 张 PNG≥ 1000px 宽只截 App 响应清单要求3–5 张 PNG宽度 ≥ 1000px裁剪范围仅限 App 响应本身——画面中不得包含提示词文本。截图是目录评审和用户浏览时了解该 MCP App 的第一印象因此要求明确数量3–5 张覆盖主要使用场景如表单、选择器、确认框、展示类 Widget 各一张尺寸宽 ≥ 1000px保证缩略与放大都清晰内容只截 App 的响应/Widget 呈现不要把对话框里的提示词prompt一起截进去——那是聊天内容而非产品能力。上线之后的配套防护authless 服务器的滥用防护清单最后一行给出衔接指引一旦 authless 端点公开请参见abuse-protection.md获取限流与 IP 分级tiering指南。abuse-protection.md 提醒了一个 authless 服务器必须正视的事实没有令牌、无会话 ID 的 stateless 传输意味着你拿不到按用户维度的身份。来自 claude.ai 的流量统一经过 Anthropic 出口 IP 段代理160.79.104.0/21 2607:6bc0::/48而 Claude Desktop / Claude Code 等宿主从用户机器直连天然带独立的用户 IP。因此防护设计通常采用分级令牌桶const ANTHROPIC_CIDRS [160.79.104.0/21, 2607:6bc0::/48]; const TIERS { anthropic: { capacity: 600, refillPerSec: 100 }, // 共享池 other: { capacity: 30, refillPerSec: 2 }, // 按 IP };将req.ip匹配 CIDR 后选择对应桶anthropic或ip:addr耗尽即返回 429 Retry-After。配套还有三条务实要点trust proxy必须匹配真实拓扑app.set(trust proxy, N)中 N 要设为可信跳数单 LB 后为 1Cloudflare → 源站 LB 后为 2生产环境绝不能用true否则直连客户端可伪造X-Forwarded-For: 160.79.108.42蹭进 Anthropic 高配额档不要硬性白名单放行 Anthropic IP把160.79.104.0/21之外的流量全拒会把 Desktop、Claude Code 及所有其他 MCP host 一起挡在门外CIDR 应作为限流分级依据而非访问门槛先缓存、后限流对包装第三方 API 的工具用进程内 LRU以规范化查询为键、TTL 以小时计、键中不含密钥吸收重复查询与惊群效应限流只是兜底安全网。提交前 10 分钟自查清单速查版把全文压缩成可勾选的清单供你提交 connector 目录前逐项过一遍认证OAuthCIMD 优先DCR 兼容或none没有 static_bearer每个工具都有annotations.title并按语义正确设置readOnlyHint/destructiveHint/idempotentHint/openWorldHint工具名 ≤ 64 字符统一 snake_case / kebab-caseWidget 内联高度 ≤ 500px无嵌套滚动容器触控目标 ≥ 44pt两套主题下对比度达 WCAG-AAhtml, body背景透明声明color-scheme: light dark接入applyHostStyleVariables所有外链走app.openLink且在 connector 的 Allowed link URIs 中声明全部源Widget 辅助工具声明_meta.ui.visibility: [app]提交 3–5 张 ≥ 1000px 宽的 PNG只含 App 响应、无提示词authless 端点公开后按 abuse-protection.md 配置分级限流、trust proxy与响应缓存延伸阅读directory-checklist.md本文所依据的原始文档build-mcp-app 技能主文件MCP App 架构、Widget 附着机制、App 类 API 与脚手架iframe-sandbox.mdCSP/沙箱约束、bundle 内联、外链与图片、宿主主题的完整问题→修复对照表auth.mdClaude 支持的认证类型全表与 CIMD/DCR 实现要点abuse-protection.mdauthless 服务器的限流、IP 分级与缓存策略mcp-server-dev 插件总览三个技能的职责划分与调用入口/mcp-server-dev:build-mcp-server赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐Grafana Tempo 提交前检查清单Pre-Commit Checklist实战指南从本地验证到 PR 全流程Grafana Tempo 提交前检查清单Pre Commit Checklist实战指南从本地验证到 PR 全流程 本文是 Grafana Tempo后端可观测性链路追踪pgvector在PostgreSQL中构建企业级向量数据库的3种核心模式pgvector在PostgreSQL中构建企业级向量数据库的3种核心模式 PostgreSQL作为最强大的开源关系数据库在AI时代面临着一个关键挑战如何数据库向量数据库Figma-Context-MCP社区贡献指南提交PR前的检查清单Figma Context MCP社区贡献指南提交PR前的检查清单 前言为什么需要贡献检查清单 作为Figma Context MCPMCP ServeAI 应用MCP 服务上一篇B站视频及弹幕下载器 bilibili —— 开源项目推荐下一篇Alertmanager Webhook接收器终极指南10个自定义告警处理方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考