Toolhive Registry Server

  ](https://github.com/stacklok/toolhive-registry-server) 

ToolHive注册表服务器

发现、管理和控制整个组织对MCP服务器的访问和技能

ToolHive注册表服务器将来自Git仓库、Kubernetes集群、上游注册表和内部API的MCP服务器和技能聚合到您的团队和AI客户端可以查询的命名目录中。每个目录都有自己的访问控制和审计跟踪，因此您可以决定哪些条目对哪些用户可见，并记录谁访问了什么。

它实现了官方 模型上下文协议（MCP）注册表API规范如果你不熟悉MCP：它是一种开放协议，允许AI助手连接到外部工具和数据源。此服务器是位于MCP基础架构和使用它的团队之间的治理层。

为什么选择ToolHive注册表服务器？ 大多数MCP设置都是从一个简单的服务器列表开始的，没有访问控制。随着采用率的增长，您需要管理谁看到什么，聚合来自多个来源的服务器，并审核访问权限，而无需锁定到专有注册表。ToolHive注册表服务器是开源的，实现官方的MCP注册表API规范，并插入您现有的身份提供商，将基于多对映声明的授权、多源聚合和符合SIEM的审计日志记录结合在一个服务中。

了解有关ToolHive平台的更多信息→

______________________________________________________________________

目录

• 特性
• 快速入门
• 核心概念
• API终点
• 配置
• ToolHive平台
• 文档
• 贡献

特性

治理和访问控制

• JWT基于索赔的可见性：控制每个注册表中每个用户或团队可以看到的MCP服务器和技能。“生产”注册表只能公开经过审查的条目，而“开发团队”注册表则显示所有内容。
• OAuth 2.0/OIDC身份验证：插入您现有的身份提供程序（Okta、Auth0、Azure AD）。OAuth是默认设置；匿名模式可用于开发。
• 基于角色的管理：管理源、注册表和条目的独立角色。根据特定的JWT声明确定每个角色的范围，以便团队管理自己的资源。
• 符合SIEM标准的审计日志记录：包含所有API操作的结构化日志，具有NIST SP 800-53 AU-3兼容字段、专用文件输出和可配置事件过滤。

从任何地方聚合

• 五种来源类型：从Git repos、上游MCP注册表、本地文件、Kubernetes集群中提取条目，或通过Admin API发布它们。
• 从多个来源编写目录：每个登记册按优先顺序汇总一个或多个来源。一个源可以为多个注册表提供数据，因此同一个内部目录可以为具有不同可见性规则的不同团队提供服务。
• 背景同步：使用重试逻辑按可配置的间隔轮询源。注册表保持最新状态，无需人工干预。

Kubernetes和可观察性

• Kubernetes本地发现：内置的协调器监视命名空间中的MCP服务器CRD，并将其自动同步到注册表中。通过CRD注释、多命名空间支持和HA领导者选举进行按条目访问控制。
• 开放遥测：开箱即用的分布式跟踪和指标。
• 符合标准：实现官方MCP注册表API规范。说规范的客户会打破常规。
• PostgreSQL后端：具有自动迁移功能的数据库存储。

快速入门

先决条件

• 转到1.26或更高版本（用于从源代码构建）
• 任务 用于构建自动化
• PostgreSQL 16+

构建并运行

# Build the binary
task build

# Run with Git source
thv-registry-api serve --config examples/config-git.yaml

# Run with local file
thv-registry-api serve --config examples/config-file.yaml

服务器启动于 http://localhost:8080 默认情况下。

Docker快速入门

# Using Task (recommended - ensures fresh state)
task docker-up

# Or detached mode
task docker-up-detached

# Access the API
curl http://localhost:8080/registry/default/v0.1/servers

# Stop and clean up
task docker-down

注： 这 task docker-up 命令通过重建映像和清除所有卷（数据库+注册表数据）来确保重新开始。这可以防止过时的状态问题。

核心概念

来源和登记处

大多数组织在多个地方都有MCP服务器和技能——公共目录、内部Git仓库、运行实时实例的Kubernetes集群。注册表服务器使用两个原语对此进行建模： 来源 （条目来源）以及 注册表 （消费者的疑问）。

A. 来源 是指向MCP服务器和技能条目所在位置的连接。它告诉服务器“去这里找条目”。来源有五种类型：

A. 注册表 是一个命名目录，它将一个或多个源聚合到一个面向消费者的端点中。每个注册表都可以从不同的来源获取信息，并通过JWT声明实施自己的访问控制。源按顺序列出——当同一条目出现在多个源中时，列表中的第一个源获胜。

为什么他们分开：来源和登记处之间存在多对多关系。一个源可以为多个注册表提供数据，一个注册表可以从多个源中提取数据。这使您可以从相同的基础数据为不同的受众组合不同的目录：

Source: "official-catalog"  ──┐
Source: "internal-tools"    ──┼──> Registry: "production"  (curated, vetted)
                              │
Source: "internal-tools"    ──┼──> Registry: "dev-team"    (everything)
Source: "k8s-deployed"      ──┘

在这个例子中，“生产”注册表只公开官方目录和内部工具中经过审查的条目，而“开发团队”注册表则包括所有内容以及Kubernetes发现的实时服务器。

配置示例：

sources:
  - name: official-catalog
    api:
      endpoint: https://registry.modelcontextprotocol.io
    syncPolicy:
      interval: "1h"

  - name: internal-tools
    git:
      repository: https://github.com/myorg/mcp-catalog.git
      branch: main
      path: registry.json
    syncPolicy:
      interval: "30m"

registries:
  - name: production
    sources:
      - official-catalog
      - internal-tools

  - name: dev-team
    sources:
      - internal-tools

看 配置指南 了解完整细节。

API端点

注册表API v0.1（只读，符合标准）

与上游MCP注册表API规范完全兼容：

• GET /registry/{registryName}/v0.1/servers -列出特定注册表中的服务器
• GET /registry/{registryName}/v0.1/servers/{name}/versions -列出服务器的所有版本
• GET /registry/{registryName}/v0.1/servers/{name}/versions/{version} -获取特定的服务器版本

注： Git、API、File和Kubernetes源代码通过注册表API是只读的。

管理员API v1

用于管理源、注册表和条目的ToolHive特定端点：

源管理 （要求 manageSources 角色）：

• GET /v1/sources -列出所有已配置的源
• GET /v1/sources/{name} -按名称获取源
• PUT /v1/sources/{name} -创建或更新源
• DELETE /v1/sources/{name} -删除源
• GET /v1/sources/{name}/entries -列出源的条目

注册表管理 （读：认证；写要求 manageRegistries 角色）：

• GET /v1/registries -列出所有已配置的注册表及其状态
• GET /v1/registries/{name} -获取注册表详细信息和同步状态
• GET /v1/registries/{name}/entries -列出注册表项（需要 manageRegistries 角色）
• PUT /v1/registries/{name} -创建或更新注册表
• DELETE /v1/registries/{name} -删除注册表

出入管理 （要求 manageEntries 角色）：

• POST /v1/entries -发布服务器或技能条目
• DELETE /v1/entries/{type}/{name}/versions/{version} -删除已发布的条目
• PUT /v1/entries/{type}/{name}/claims -更新入境申报

技能扩展API（特定于工具组）

用于在注册表中发现技能的只读端点：

• GET /registry/{registryName}/v0.1/x/dev.toolhive/skills -列出技能（分页）
• GET /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name} -获取技能的最新版本
• GET /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions -列出技能的所有版本
• GET /registry/{registryName}/v0.1/x/dev.toolhive/skills/{namespace}/{name}/versions/{version} -获取特定技能版本

操作端点

• GET /health -健康检查
• GET /readiness -准备就绪检查
• GET /version -版本信息
• GET /v1/me -返回调用者的身份和角色
• GET /.well-known/oauth-protected-resource -OAuth发现（RFC 9728）

用例

• 注册API：为客户和上游集成提供符合标准的MCP发现
• 管理员API：管理源和注册表、发布条目、查询注册表状态

请参阅 MCP注册表API规范 获取API的完整详细信息。

配置

所有配置都是通过YAML文件完成的。服务器需要 --config 旗帜。

基本示例

sources:
  - name: local
    file:
      path: /data/registry.json

registries:
  - name: my-registry
    sources:
      - local

auth:
  mode: anonymous # Use "oauth" for production

database:
  host: localhost
  port: 5432
  user: registry
  database: registry

完整指南

• 配置参考 -完整的配置选项
• 环境变量 -使用环境变量进行配置
• 数据库设置 -PostgreSQL配置、迁移和安全
• 认证 -OAuth/OIDC设置和安全

ToolHive平台

注册表服务器可以独立部署，也可以作为完整注册表的一部分部署 ToolHive 平台。平台组件共同覆盖了整个MCP生命周期：

• 注册表 （本项目）——发现和治理。了解MCP服务器和技能，谁可以访问它们，并跟踪所有操作。
• 运行时 --部署和管理。使用注册表元数据在Kubernetes上部署MCP服务器以驱动生命周期决策。运行时部署的服务器会自动出现在注册表中。
• 网关 --聚合和访问。通过集中身份验证、基于Cedar的授权、工具冲突解决和复合工作流将多个MCP服务器统一到一个端点中。
• 门户 --管理UI。由注册表API支持的目录浏览、搜索和管理。

请参阅 ToolHive文档 对于完整的平台架构。

文档

• 配置参考 -所有配置选项
• 环境变量 -环境变量覆盖
• 数据库设置 -PostgreSQL设置和迁移
• 认证 -OAuth/OIDC安全
• 可观测性 -OpenTetry跟踪和指标
• 注册表同步 -后台同步的工作原理
• Kubernetes部署 -K8s部署和HA
• **** -Docker编写设置
• API文档 -自动生成的OpenAPI文档
• CLI参考 -命令行界面文档
• 示例 -工作配置示例

贡献

我们欢迎捐款！请参阅 贡献指南 首先，包括开发设置、构建命令、架构概述和项目结构。

• 行为准则 -社区指南
• 安全政策 -报告安全漏洞

许可证

该项目根据 Apache 2.0许可证.

______________________________________________________________________

部分 ToolHive 项目 -简化和保护MCP服务器