knowledge-work-plugins 插件定制中的 MCP 发现与连接从目录检索到.mcp.json配置落地的完整指南【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins在 Claude Cowork 生态中为组织定制插件时最关键的一步是把插件内部以~~占位符标注的泛化工具引用如~~Jira、~~chat替换成组织实际使用的真实服务并把这些服务的 MCPModel Context Protocol连接配置写进插件。本文以 cowork-plugin-customizer 技能 的核心参考资料 mcp-servers.md 为主体系统讲解 MCP 目录检索、连接器安装与插件 MCP 配置文件更新的完整流程。读完本文你将掌握search_mcp_registry、suggest_connectors两个关键工具的正确用法、类别到关键词的映射规则以及如何定位并编写插件根目录下的.mcp.json让插件真正接入组织的工具链。MCP 发现与连接插件定制的最后一块拼图在完整的插件定制流程中MCP 连接发生在 cowork-plugin-customizer SKILL.md 定义的Phase 4Search for Useful MCPs当定制项占位符替换、内容更新、URL 模式更新、配置值填充都解决之后Agent 需要为识别出的每个工具执行三步操作——先在 MCP 目录中检索对应连接器再为未连接的工具展示连接按钮最后把获取到的端点写入插件的 MCP 配置文件。本文档正是这三步的标准操作手册回答了三个核心问题去哪里找MCP 连接器search_mcp_registry如何引导用户安装/连接它们suggest_connectors把连接配置写进哪个文件、用什么格式plugin.json/.mcp.json。两个核心工具search_mcp_registry与suggest_connectorssearch_mcp_registry检索 MCP 目录中的可用连接器该工具用于在 MCP 目录中按关键词搜索可用的连接器是发现阶段的主入口。输入一个关键词数组格式为{ keywords: [array, of, search, terms] }。输出最多返回10 条结果每条结果包含以下字段字段含义使用场景nameMCP 的显示名称向用户展示、识别服务description一行式描述帮助用户确认是否是其使用的工具tools该 MCP 提供的工具名列表验证其能力是否匹配插件需要urlMCP 端点 URL直接用于写入.mcp.jsondirectoryUuid目录条目 UUID传给suggest_connectors触发连接connected布尔值用户是否已连接该 MCP决定是否还需要调用suggest_connectors注意区分两个字段的用途url是配置文件的素材directoryUuid是连接 UI 的凭证。搜索命中后若connected为false就需要走第二步。suggest_connectors为用户展示 Connect 按钮该工具负责渲染一个带 Connect 按钮的 UI让用户一键安装/连接 MCP认证过程由用户在界面中完成。输入{ directoryUuids: [uuid1, uuid2] }即上一步搜索结果的directoryUuid数组。输出为每个 UUID 对应的 MCP 渲染带 Connect 按钮的界面用户点击后完成认证连接。它与search_mcp_registry是前后衔接的两个阶段先搜索拿到directoryUuid再据此展示连接按钮。类别到关键词的映射表把业务类别翻译成搜索词搜索时直接输入工具名如asana当然可行但当插件通过~~占位符表达的是类别如项目管理系统而非具体产品时就需要下面的映射表来生成候选关键词。这张表同时被 search-strategies.md 中知识 MCP 搜索策略所呼应——在 Phase 1 通过 Slack/文档/邮件等知识源收集组织实际使用的工具名后Phase 4 就用这张表把类别映射成具体检索词类别搜索关键词project-management[asana, jira, linear, monday, tasks]software-coding[github, gitlab, bitbucket, code]chat[slack, teams, discord]documents[google docs, notion, confluence]calendar[google calendar, calendar]email[gmail, outlook, email]design-graphics[figma, sketch, design]analytics-bi[datadog, grafana, analytics]crm[salesforce, hubspot, crm]wiki-knowledge-base[notion, confluence, outline, wiki]data-warehouse[bigquery, snowflake, redshift]conversation-intelligence[gong, chorus, call recording]使用要点如果 Phase 1 的调研已经明确用户使用某个具体工具例如已知组织用 Asana就直接搜索该工具名以拿到精确的url可以跳过通用的类别搜索只有没有前置线索时才用类别关键词批量检索并把全部结果展示给用户确认。这里还可以与 customized-mcp.json 示例 中的recommendedCategories字段互相印证——一个插件可以声明自己推荐接入的类别如source-control、project-management、chat、documents、wiki-knowledge-base、design-graphics、analytics-bi目录检索正好在这些类别内展开。六步工作流从占位符到已连接 MCPmcp-servers.md 给出的发现与连接流程共六步与父技能 SKILL.md 中 Phase 4 的指令完全对应找到定制点在插件文件中查找~~前缀的值例如~~Jira。父技能提供了定位命令grep -rn ~~\w /path/to/plugin --include*.md --include*.json。核对前置调研结论检查 Phase 1 是否已经获知组织使用的具体工具——是直接搜索该具体工具名拿到其url跳到第 5 步省去中间的选择环节否继续第 3 步。检索用上表的类别关键词或工具名调用search_mcp_registry。展示并询问用户把全部搜索结果展示出来问用户实际使用哪个。注意 search-strategies.md 的补充说明当知识 MCP 不可用时直接对所有类别改用 AskUserQuestion而 AskUserQuestion 自带 Skip 按钮和自由文本输入框因此不要额外提供None或Other选项。按需连接若该 MCP 尚未连接connected为false调用suggest_connectors传入directoryUuid由用户完成认证。更新 MCP 配置使用搜索结果中的url字段把配置写入插件的 MCP 配置文件。节奏提示SKILL.md 明确要求Phase 4 中所有 MCP 的检索与连接结果要收集齐后一次性呈现在最终摘要里不要逐个向用户展示。更新插件的 MCP 配置文件定位三规则找到正确的配置文件是写入成功的前提。按以下优先级判断检查plugin.json中的mcpServers字段如果存在它指向一个配置文件路径直接编辑该路径下的文件{ name: my-plugin, mcpServers: ./config/servers.json }该字段的值是相对于插件根目录的路径表示 MCP 配置被显式地放到了自定义位置。没有mcpServers字段时使用插件根目录下的.mcp.json默认位置。这也是 component-schemas.md 中 MCP Servers 组件规范声明的标准位置以及 example-plugins.md 中标准插件与全功能插件示例的存放位置。mcpServers仅指向.mcpb文件打包内嵌服务时此时插件内没有可编辑的常规 JSON 配置需要在插件根目录新建一个.mcp.json。在源码仓库中可见的直接对应关系是父技能 SKILL.md 的 Phase 4 第 3 步同样写明了检查plugin.json的自定义位置否则用根目录.mcp.json两份文档完全一致。配置文件格式wrapped 与 unwrapped以及三种服务器类型mcp-servers.md 说明配置文件同时支持 wrapped带mcpServers外层包裹与 unwrapped裸对象两种格式。标准写法是 wrapped 格式{ mcpServers: { github: { type: http, url: https://api.githubcopilot.com/mcp/ } } }其中的url字段必须取自search_mcp_registry的搜索结果以保证端点与目录条目一致。而 component-schemas.md 的 MCP Servers 章节进一步补全了服务器类型的完整规范写入配置时可参考stdio本地进程通过command/args启动本地进程可用env注入环境变量{ mcpServers: { my-server: { command: node, args: [${CLAUDE_PLUGIN_ROOT}/servers/server.js], env: { API_KEY: ${API_KEY} } } } }SSE远程Server-Sent Events 传输type: sseurl如https://mcp.asana.com/sse。HTTP远程流式 HTTP 传输type: httpurl可携带headers{ mcpServers: { api-service: { type: http, url: https://api.example.com/mcp, headers: { Authorization: Bearer ${API_TOKEN} } } } }环境变量展开所有 MCP 配置都支持${VAR_NAME}替换${CLAUDE_PLUGIN_ROOT}—— 插件目录为保证可移植性应始终使用${ANY_ENV_VAR}—— 用户环境变量如${GITHUB_TOKEN}。需要把配置中引用的全部环境变量记录在插件 README 中否则用户按装后无法认证。一个完整的实战示例仓库中的 customized-mcp.json 展示了同时混用多种传输类型、携带认证头、并附带recommendedCategories的真实成品{ mcpServers: { github: { type: http, url: https://api.githubcopilot.com/mcp/, headers: { Authorization: Bearer ${GITHUB_TOKEN} } }, asana: { type: sse, url: https://mcp.asana.com/sse }, slack: { type: http, url: https://slack.mcp.claude.com/mcp }, figma: { type: http, url: https://mcp.figma.com/mcp }, datadog: { type: http, url: https://api.datadoghq.com/mcp, headers: { DD-API-KEY: ${DATADOG_API_KEY}, DD-APPLICATION-KEY: ${DATADOG_APP_KEY} } } }, recommendedCategories: [ source-control, project-management, chat, documents, wiki-knowledge-base, design-graphics, analytics-bi ] }可以观察到几个要点GitHub 与 Datadog 这类需要鉴权的服务通过headers引用环境变量Asana 使用 SSE 传输recommendedCategories列出的类别与映射表中的分类体系project-management、chat、design-graphics、analytics-bi等一一对应。同样地example-plugins.md 中的标准插件与全功能插件示例也演示了.mcp.json中 linearSSE、githubHTTP、slackHTTP三种连接器共存的结构。没有 URL 的目录条目按名称匹配并非所有 MCP 目录条目都带url——部分服务的端点是动态的需要管理员在连接服务器时提供。这类服务器仍然可以通过名称在插件的 MCP 配置中被引用只要配置中的 MCP 服务器名称与目录条目名称一致就等同于 URL 匹配。这一点在 component-schemas.md 的Directory Servers Without a URL小节中被再次确认属于插件 MCP 配置的通用规则。实际影响是定制 Agent 在写入配置时遇到无url的搜索结果不必放弃只需保证mcpServers下的 key服务器名称与目录条目name完全一致即可连接由用户侧完成。收尾与定制全流程的衔接MCP 配置更新完成后cowork-plugin-management/skills/cowork-plugin-customizer/SKILL.md 的 Summary Output 环节要求把本阶段连接了哪些 MCP、用户还需要手动连接哪些 MCP 一起写入最终摘要并给出连接指引。如果 Phase 1 没有可用的知识 MCP、且用户至少手动回答过一个问题还要补充一句提示——连接 Slack 或 Microsoft Teams 之类的数据源下次定制插件时我就能自动找到答案了。至此从~~Jira占位符到{asana: {type: sse, url: https://mcp.asana.com/sse}}插件定制中 MCP 发现、连接与配置的完整链路就闭环了。进一步阅读cowork-plugin-customizer SKILL.md —— 定制全流程Phase 04、打包、摘要输出search-strategies.md —— 知识 MCP 的检索模式用于定制前收集组织上下文customized-mcp.json —— 一个已完成的.mcp.json成品示例component-schemas.md —— 插件组件规范含 MCP 服务器三种类型与环境变量展开的完整定义example-plugins.md —— 从单技能到全功能插件的.mcp.json示例【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
