Mastra MCP 注册表聚合器mastra/mcp-registry-registry 源码解析与实战指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/mcp-registry-registry是 Mastra 生态中面向 Model Context ProtocolMCP生态的聚合型目录包它将 API Tracker、Apify、Cursor、Smithery、Zapier 等数十个公开 MCP 注册表收录进一份可搜索的元数据目录。本文以该包的 CHANGELOG.md 为主线结合 README、registry 数据源 与 MCP Server 实现源码讲解其版本演进、核心数据模型、双工具工作流与二次开发方式帮助你直接用一份依赖即可跨注册表发现 MCP 服务器。一、这个包解决什么问题MCPModel Context Protocol生态中注册表呈碎片化状态Docker Hub 有 MCP 镜像目录、Apify Store 有抓取器、PulseMCP 有社区精选、Smithery 有托管的服务器列表。若每个都要单独对接一套 APIAgent 应用会陷入无穷无尽的集成工作。mastra/mcp-registry-registry将这一切收拢为一个统一的目录catalog并以两种形态交付作为数据包直接import { registryData }读取注册表元数据与可选的后处理器post-processors作为 MCP Server通过 stdio 对外暴露registryList与registryServers两个工具让任何 MCP 客户端如 Claude Desktop、Cursor、Mastra Agent直接调用。当前版本为1.1.2见 package.json运行要求 Node.js 22.13.0仅依赖modelcontextprotocol/sdk与zod两个运行时依赖并以mastra/core作为 peer dependency要求1.0.0-0 2.0.0-0。二、版本演进从 0.0.1 到 1.1.2CHANGELOG 完整记录了该包从初始版本到 1.x 稳定版的演进下面按阶段梳理其关键变更2.1 早期迭代0.0.1 ~ 0.10.x版本关键变更0.0.1引入 MCP Reg Reg mcp server、修复导出Fix exports、补充更多注册表条目0.0.3新增 Docker 注册表add docker registry0.10.0将mastra/core移入 peerDependenciesMove mastra/core to peerdeps新增 Apify 条目0.10.3新增 MCP Bar 注册表含描述与 URLmodelcontextprotocol/sdk升到^1.12.10.10.4SDK 升到^1.13.0为 MCPServer/MCPClient 增加 tool output schema 支持0.10.7修复 TypeScript 声明文件导入确保 ESM 兼容0.10.12package.json 补全repository、homepage、files等字段0.10.15清理 monorepo 中的 console 日志同步mastra/corepeer 版本0.10.20同步mastra/core0.22.0的 peer 依赖这段历史反映出该包作为目录型工具的三个持续主题不断扩充注册表条目Apify、Docker、MCP Bar 等、跟进 MCP SDK 与 core 的版本以及包发布元数据的规范化。2.2 迈向 1.0 稳定版1.0.0含1.0.0-beta.x是里程碑版本两项 Major 变更值得关注Node.js 最低版本提升到 22.13.0PR #9706标记为 stablecommit83d5942正式对外承诺 API 稳定性uuid依赖从^11.1.0升级到^13.0.0PR #10114并将 peerDependencies 与mastra/core1.0.0对齐PR #9237。2.3 1.x 时代的维护与安全版本关键变更1.0.1用lukeed/uuid与node:crypto替换uuid依赖PR #15691减少第三方依赖面1.0.2针对 2026-06-17 easy-day-js 供应链事件的安全修复发布干净版本并将latestdist-tag 前移以取代声明了恶意easy-day-js依赖的受影响版本PR #180561.1.0一次随机的版本抬升Random bumpPR #18178同步mastra/core1.45.01.1.1新增 Remote OpenClaw 到注册表列表PR #18900下方附官方示例代码1.1.2更新 README 使其准确反映当前能力PR #22858从 npm 发布文件中移除 CHANGELOG.md减小包体积PR #22737依赖mastra/core1.64.0其中1.1.1还给出了一个可运行示例展示如何从registryData中按 id 查询某个注册表import { registryData } from mastra/mcp-registry-registry; const remoteOpenClaw registryData.registries.find(r r.id remoteopenclaw); console.log(remoteOpenClaw?.url); // https://www.remoteopenclaw.com/三、核心数据模型registryData 目录结构3.1 类型定义registry/types.ts 用 zod 定义了服务器条目的 schema并用 TypeScript interface 描述注册表条目export const ServerEntrySchema z.object({ id: z.string(), name: z.string(), description: z.string(), createdAt: z.string(), updatedAt: z.string(), }); export interface RegistryEntry { id: string; name: string; description: string; url: string; servers_url?: string; tags?: string[]; count?: number | string; // Custom post-processing function for this registrys server data postProcessServers?: (data: unknown) ServerEntry[]; }各字段语义如下字段类型说明idstring注册表唯一标识用于registryServers工具定位namestring展示名称descriptionstring一句话描述urlstring注册表主站地址servers_urlstring可选拉取服务器列表的 API 端点tagsstring[]可选标记如verified、open-source、officialcountnumber | string可选服务器数量有些是估算字符串如17000postProcessServers函数可选将原始 API 响应规范化为ServerEntry[]的后处理函数3.2 内置注册表清单registry/registry.ts 中registryData共收录 30 个注册表条目按 tag 可大致分为三类verified官方/认证API Tracker、Docker MCP Catalog、Apify、Cline.bot、Cursor、Fleur、Make、MCP Composio、MCP Repository、MCP Resolver、MCP Run、MCP.so、OpenTools、Pipedream、Pulse MCP、Smithery、SuperMachine、Zapier 等open-source开源社区Awesome MCP servers、Glama、Gumloop、Klavis AI、MCP Bar、MCP-Get、mcpindex、MCP Store、mcpservers.org 等official官方参考实现modelcontextprotocol/servers官方参考实现仓库。其中带servers_url的注册表还配备了专用后处理器例如 DockerprocessDockerServers、ApifyprocessApifyServers、FleurprocessFleurServers、MCP RunprocessMcpRunServers、PulseprocessPulseMcpServers、API TrackerprocessApiTrackerServers。这些处理器的实现与单元测试分别位于 registry/processors/ 与 registry/tests/processors/是理解异构数据如何被归一化的最佳入口。四、两种使用方式4.1 作为数据包直接使用安装后直接导入目录并过滤npm install mastra/mcp-registry-registryimport { registryData } from mastra/mcp-registry-registry; const verifiedRegistries registryData.registries.filter(registry registry.tags?.includes(verified)); for (const registry of verifiedRegistries) { console.log(${registry.name}: ${registry.url}); }从源码结构看src/index.ts 目前仅导出./registry/registry即registryData。若需要进一步对某个注册表执行拉取服务器列表逻辑可参考 registry/fetch-servers.ts 与 registry/list-registries.ts 的实现与测试fetch-servers.test.ts、list-registries.test.ts。4.2 作为 MCP Server 使用该包内置一个基于官方modelcontextprotocol/sdk的 MCP Serverserver.ts声明toolscapability通过StdioServerTransport连接const server new Server( { name: Registry Registry Server, version: JSON.parse(await fs.readFile(fromPackageRoot(package.json), utf8)).version, }, { capabilities: { tools: {} }, }, );package.json中bin: dist/stdio.js说明它可直接作为可执行命令运行src/stdio.ts提供 CLI 入口。接入示例以 Claude Desktop 风格的配置为例{ mcpServers: { mcp-registry-registry: { command: npx, args: [-y, mastra/mcp-registry-registry] } } }五、两个核心 MCP 工具Server 暴露两个工具tools/输入 schema 均使用 zod 定义并经toJSONSchema转换为 MCP 的 JSON Schema 输入描述。5.1 registryList列出注册表定义于 tools/list.tsexport const listInputSchema z.object({ id: z.string().optional(), tag: z.string().optional(), name: z.string().optional(), detailed: z.boolean().optional().default(false), });参数类型默认值说明idstring—按注册表 id 精确过滤tagstring—按 tag 过滤如verified、open-sourcenamestring—按名称过滤detailedbooleanfalse是否输出详细视图默认为摘要视图执行时调用getRegistryListings(filter, { detailed })registry/list-registries.ts结果以 JSON 字符串形式放入 MCP text content 返回。5.2 registryServers拉取指定注册表的服务器定义于 tools/servers.tsexport const serversInputSchema z.object({ registryId: z.string(), tag: z.string().optional(), search: z.string().optional(), });参数类型必填说明registryIdstring是目标注册表的 id须存在于registryData.registriestagstring否对返回的服务器按 tag 过滤searchstring否对返回的服务器按关键词搜索执行时调用getServersFromRegistry(registryId, { tag, search })registry/fetch-servers.ts。从实现推断该函数会按id找到RegistryEntry若存在servers_url则拉取远端数据并交给postProcessServers归一化为ServerEntry[]再应用 tag/search 过滤。错误处理在 server.ts 中统一兜底zod 校验失败返回Invalid arguments: ...其余异常返回Error: ...且均标记isError: true。六、后处理器异构数据的归一化引擎各注册表的 API 返回结构千差万别postProcessServers正是为消除这种差异而设计的钩子。registry/processors/ 下每个处理器对应一个注册表apify.ts处理 Apify Store API 返回的 actor 列表apitracker.ts处理 API Tracker 的 MCP 服务器端点docker.ts处理 Docker Hub 的 MCP 目录仓库fleur.ts处理 Fleur 的 apps.jsonmcprun.ts处理 MCP Run 的 servlets APIpulse.ts处理 PulseMCP 的 v0beta/servers 端点default.ts与utils.ts公共兜底逻辑与工具函数。这些处理器把各家的原始 JSON 归一化为ServerEntrySchema定义的{ id, name, description, createdAt, updatedAt }结构从而让上层registryServers工具和调用方拿到统一的数据形状。每个处理器都有对应的单元测试如 apify.test.ts、docker.test.ts 等可据此验证归一化逻辑。七、在 Mastra 应用中的集成思路mastra/mcp-registry-registry与 Mastra 的 MCP 能力天然衔接。仓库中 packages/mcp/ 提供 Mastra 侧的 MCP 服务器/客户端封装而本包负责发现服务器。典型链路为通过registryList找出目标注册表例如按 tag 过滤出verified的供应商通过registryServers拉取该注册表下的服务器清单将筛选出的服务器接入 Mastra Agent 的工具集完成注册表发现 → 服务器接入 → Agent 调用的闭环。这种注册表聚合 工具化查询的模式避免了在每个 Agent 应用中硬编码注册表清单或重复实现多家 API 客户端。八、注意事项与局限运行环境Node.js 22.13.01.0.0起的要求低于该版本无法运行peer 依赖需与mastra/core1.0.0-0 2.0.0-0配合使用数据时效性registryData中的count、servers_url指向的是远端实时数据服务器数量是各注册表自行维护的数值实际以各站当前数据为准后处理覆盖并非所有注册表都提供servers_url与postProcessServers如 Awesome MCP servers、Gumloop 等仅有目录元数据对这些注册表registryServers可能无法直接拉取服务器列表安全维护历史上曾因第三方供应链事件发布过安全修复版本1.0.2使用时应保持依赖更新到最新补丁版本。九、总结mastra/mcp-registry-registry用一份依赖解决了跨注册表发现 MCP 服务器的集成痛点静态目录registryData提供元数据后处理器统一异构数据形状MCP Server 通过registryList/registryServers两个工具把能力开放给任意 MCP 客户端。从0.0.1到1.1.2的 CHANGELOG 也能看到一条清晰的演进曲线条目持续扩充、依赖持续收紧、发布物持续瘦身。对于正在构建 Agent 工具生态的开发者它是一个轻量且实用的基础设施组件。参考资料包 README安装与基础用法CHANGELOG完整版本历史registry 数据与类型、types.tsMCP Server 实现、stdio 入口工具定义、servers.ts处理器目录与对应测试package.json依赖、bin 与发布配置【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mastra MCP 注册表聚合器：@mastra/mcp-registry-registry 源码解析与实战指南
Mastra MCP 注册表聚合器mastra/mcp-registry-registry 源码解析与实战指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/mcp-registry-registry是 Mastra 生态中面向 Model Context ProtocolMCP生态的聚合型目录包它将 API Tracker、Apify、Cursor、Smithery、Zapier 等数十个公开 MCP 注册表收录进一份可搜索的元数据目录。本文以该包的 CHANGELOG.md 为主线结合 README、registry 数据源 与 MCP Server 实现源码讲解其版本演进、核心数据模型、双工具工作流与二次开发方式帮助你直接用一份依赖即可跨注册表发现 MCP 服务器。一、这个包解决什么问题MCPModel Context Protocol生态中注册表呈碎片化状态Docker Hub 有 MCP 镜像目录、Apify Store 有抓取器、PulseMCP 有社区精选、Smithery 有托管的服务器列表。若每个都要单独对接一套 APIAgent 应用会陷入无穷无尽的集成工作。mastra/mcp-registry-registry将这一切收拢为一个统一的目录catalog并以两种形态交付作为数据包直接import { registryData }读取注册表元数据与可选的后处理器post-processors作为 MCP Server通过 stdio 对外暴露registryList与registryServers两个工具让任何 MCP 客户端如 Claude Desktop、Cursor、Mastra Agent直接调用。当前版本为1.1.2见 package.json运行要求 Node.js 22.13.0仅依赖modelcontextprotocol/sdk与zod两个运行时依赖并以mastra/core作为 peer dependency要求1.0.0-0 2.0.0-0。二、版本演进从 0.0.1 到 1.1.2CHANGELOG 完整记录了该包从初始版本到 1.x 稳定版的演进下面按阶段梳理其关键变更2.1 早期迭代0.0.1 ~ 0.10.x版本关键变更0.0.1引入 MCP Reg Reg mcp server、修复导出Fix exports、补充更多注册表条目0.0.3新增 Docker 注册表add docker registry0.10.0将mastra/core移入 peerDependenciesMove mastra/core to peerdeps新增 Apify 条目0.10.3新增 MCP Bar 注册表含描述与 URLmodelcontextprotocol/sdk升到^1.12.10.10.4SDK 升到^1.13.0为 MCPServer/MCPClient 增加 tool output schema 支持0.10.7修复 TypeScript 声明文件导入确保 ESM 兼容0.10.12package.json 补全repository、homepage、files等字段0.10.15清理 monorepo 中的 console 日志同步mastra/corepeer 版本0.10.20同步mastra/core0.22.0的 peer 依赖这段历史反映出该包作为目录型工具的三个持续主题不断扩充注册表条目Apify、Docker、MCP Bar 等、跟进 MCP SDK 与 core 的版本以及包发布元数据的规范化。2.2 迈向 1.0 稳定版1.0.0含1.0.0-beta.x是里程碑版本两项 Major 变更值得关注Node.js 最低版本提升到 22.13.0PR #9706标记为 stablecommit83d5942正式对外承诺 API 稳定性uuid依赖从^11.1.0升级到^13.0.0PR #10114并将 peerDependencies 与mastra/core1.0.0对齐PR #9237。2.3 1.x 时代的维护与安全版本关键变更1.0.1用lukeed/uuid与node:crypto替换uuid依赖PR #15691减少第三方依赖面1.0.2针对 2026-06-17 easy-day-js 供应链事件的安全修复发布干净版本并将latestdist-tag 前移以取代声明了恶意easy-day-js依赖的受影响版本PR #180561.1.0一次随机的版本抬升Random bumpPR #18178同步mastra/core1.45.01.1.1新增 Remote OpenClaw 到注册表列表PR #18900下方附官方示例代码1.1.2更新 README 使其准确反映当前能力PR #22858从 npm 发布文件中移除 CHANGELOG.md减小包体积PR #22737依赖mastra/core1.64.0其中1.1.1还给出了一个可运行示例展示如何从registryData中按 id 查询某个注册表import { registryData } from mastra/mcp-registry-registry; const remoteOpenClaw registryData.registries.find(r r.id remoteopenclaw); console.log(remoteOpenClaw?.url); // https://www.remoteopenclaw.com/三、核心数据模型registryData 目录结构3.1 类型定义registry/types.ts 用 zod 定义了服务器条目的 schema并用 TypeScript interface 描述注册表条目export const ServerEntrySchema z.object({ id: z.string(), name: z.string(), description: z.string(), createdAt: z.string(), updatedAt: z.string(), }); export interface RegistryEntry { id: string; name: string; description: string; url: string; servers_url?: string; tags?: string[]; count?: number | string; // Custom post-processing function for this registrys server data postProcessServers?: (data: unknown) ServerEntry[]; }各字段语义如下字段类型说明idstring注册表唯一标识用于registryServers工具定位namestring展示名称descriptionstring一句话描述urlstring注册表主站地址servers_urlstring可选拉取服务器列表的 API 端点tagsstring[]可选标记如verified、open-source、officialcountnumber | string可选服务器数量有些是估算字符串如17000postProcessServers函数可选将原始 API 响应规范化为ServerEntry[]的后处理函数3.2 内置注册表清单registry/registry.ts 中registryData共收录 30 个注册表条目按 tag 可大致分为三类verified官方/认证API Tracker、Docker MCP Catalog、Apify、Cline.bot、Cursor、Fleur、Make、MCP Composio、MCP Repository、MCP Resolver、MCP Run、MCP.so、OpenTools、Pipedream、Pulse MCP、Smithery、SuperMachine、Zapier 等open-source开源社区Awesome MCP servers、Glama、Gumloop、Klavis AI、MCP Bar、MCP-Get、mcpindex、MCP Store、mcpservers.org 等official官方参考实现modelcontextprotocol/servers官方参考实现仓库。其中带servers_url的注册表还配备了专用后处理器例如 DockerprocessDockerServers、ApifyprocessApifyServers、FleurprocessFleurServers、MCP RunprocessMcpRunServers、PulseprocessPulseMcpServers、API TrackerprocessApiTrackerServers。这些处理器的实现与单元测试分别位于 registry/processors/ 与 registry/tests/processors/是理解异构数据如何被归一化的最佳入口。四、两种使用方式4.1 作为数据包直接使用安装后直接导入目录并过滤npm install mastra/mcp-registry-registryimport { registryData } from mastra/mcp-registry-registry; const verifiedRegistries registryData.registries.filter(registry registry.tags?.includes(verified)); for (const registry of verifiedRegistries) { console.log(${registry.name}: ${registry.url}); }从源码结构看src/index.ts 目前仅导出./registry/registry即registryData。若需要进一步对某个注册表执行拉取服务器列表逻辑可参考 registry/fetch-servers.ts 与 registry/list-registries.ts 的实现与测试fetch-servers.test.ts、list-registries.test.ts。4.2 作为 MCP Server 使用该包内置一个基于官方modelcontextprotocol/sdk的 MCP Serverserver.ts声明toolscapability通过StdioServerTransport连接const server new Server( { name: Registry Registry Server, version: JSON.parse(await fs.readFile(fromPackageRoot(package.json), utf8)).version, }, { capabilities: { tools: {} }, }, );package.json中bin: dist/stdio.js说明它可直接作为可执行命令运行src/stdio.ts提供 CLI 入口。接入示例以 Claude Desktop 风格的配置为例{ mcpServers: { mcp-registry-registry: { command: npx, args: [-y, mastra/mcp-registry-registry] } } }五、两个核心 MCP 工具Server 暴露两个工具tools/输入 schema 均使用 zod 定义并经toJSONSchema转换为 MCP 的 JSON Schema 输入描述。5.1 registryList列出注册表定义于 tools/list.tsexport const listInputSchema z.object({ id: z.string().optional(), tag: z.string().optional(), name: z.string().optional(), detailed: z.boolean().optional().default(false), });参数类型默认值说明idstring—按注册表 id 精确过滤tagstring—按 tag 过滤如verified、open-sourcenamestring—按名称过滤detailedbooleanfalse是否输出详细视图默认为摘要视图执行时调用getRegistryListings(filter, { detailed })registry/list-registries.ts结果以 JSON 字符串形式放入 MCP text content 返回。5.2 registryServers拉取指定注册表的服务器定义于 tools/servers.tsexport const serversInputSchema z.object({ registryId: z.string(), tag: z.string().optional(), search: z.string().optional(), });参数类型必填说明registryIdstring是目标注册表的 id须存在于registryData.registriestagstring否对返回的服务器按 tag 过滤searchstring否对返回的服务器按关键词搜索执行时调用getServersFromRegistry(registryId, { tag, search })registry/fetch-servers.ts。从实现推断该函数会按id找到RegistryEntry若存在servers_url则拉取远端数据并交给postProcessServers归一化为ServerEntry[]再应用 tag/search 过滤。错误处理在 server.ts 中统一兜底zod 校验失败返回Invalid arguments: ...其余异常返回Error: ...且均标记isError: true。六、后处理器异构数据的归一化引擎各注册表的 API 返回结构千差万别postProcessServers正是为消除这种差异而设计的钩子。registry/processors/ 下每个处理器对应一个注册表apify.ts处理 Apify Store API 返回的 actor 列表apitracker.ts处理 API Tracker 的 MCP 服务器端点docker.ts处理 Docker Hub 的 MCP 目录仓库fleur.ts处理 Fleur 的 apps.jsonmcprun.ts处理 MCP Run 的 servlets APIpulse.ts处理 PulseMCP 的 v0beta/servers 端点default.ts与utils.ts公共兜底逻辑与工具函数。这些处理器把各家的原始 JSON 归一化为ServerEntrySchema定义的{ id, name, description, createdAt, updatedAt }结构从而让上层registryServers工具和调用方拿到统一的数据形状。每个处理器都有对应的单元测试如 apify.test.ts、docker.test.ts 等可据此验证归一化逻辑。七、在 Mastra 应用中的集成思路mastra/mcp-registry-registry与 Mastra 的 MCP 能力天然衔接。仓库中 packages/mcp/ 提供 Mastra 侧的 MCP 服务器/客户端封装而本包负责发现服务器。典型链路为通过registryList找出目标注册表例如按 tag 过滤出verified的供应商通过registryServers拉取该注册表下的服务器清单将筛选出的服务器接入 Mastra Agent 的工具集完成注册表发现 → 服务器接入 → Agent 调用的闭环。这种注册表聚合 工具化查询的模式避免了在每个 Agent 应用中硬编码注册表清单或重复实现多家 API 客户端。八、注意事项与局限运行环境Node.js 22.13.01.0.0起的要求低于该版本无法运行peer 依赖需与mastra/core1.0.0-0 2.0.0-0配合使用数据时效性registryData中的count、servers_url指向的是远端实时数据服务器数量是各注册表自行维护的数值实际以各站当前数据为准后处理覆盖并非所有注册表都提供servers_url与postProcessServers如 Awesome MCP servers、Gumloop 等仅有目录元数据对这些注册表registryServers可能无法直接拉取服务器列表安全维护历史上曾因第三方供应链事件发布过安全修复版本1.0.2使用时应保持依赖更新到最新补丁版本。九、总结mastra/mcp-registry-registry用一份依赖解决了跨注册表发现 MCP 服务器的集成痛点静态目录registryData提供元数据后处理器统一异构数据形状MCP Server 通过registryList/registryServers两个工具把能力开放给任意 MCP 客户端。从0.0.1到1.1.2的 CHANGELOG 也能看到一条清晰的演进曲线条目持续扩充、依赖持续收紧、发布物持续瘦身。对于正在构建 Agent 工具生态的开发者它是一个轻量且实用的基础设施组件。参考资料包 README安装与基础用法CHANGELOG完整版本历史registry 数据与类型、types.tsMCP Server 实现、stdio 入口工具定义、servers.ts处理器目录与对应测试package.json依赖、bin 与发布配置【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考