<p float="left"> <picture> <img src="docs/images/toolhive-icon-1024.png" alt="ToolHive Studio logo" height="100" align="middle" /> </picture> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/images/toolhive-wordmark-white.png"> <img src="docs/images/toolhive-wordmark-black.png" alt="ToolHive wordmark" width="500" align="middle" hspace="20" /> </picture> <picture> <img src="docs/images/toolhive.png" alt="ToolHive mascot" width="125" align="middle"/> </picture> </p>

[![Release][release-img]][release] [![Build status][ci-img]][ci] [![Coverage Status][coveralls-img]][coveralls] [![License: Apache 2.0][license-img]][license] [![Star on GitHub][stars-img]][stars] [![Discord][discord-img]][discord]

ToolHive 注册表 API 服务器

符合标准的 MCP 注册表 API 服务器用于 ToolHive

ToolHive 注册表 API (thv-registry-api) 实现了官方的 模型上下文协议 (MCP) 注册表 API 规范。它提供了一个标准化的 REST API，用于从多个后端源发现和访问 MCP 服务器。

---

特性

• 符合标准：实现官方 MCP 注册表 API 规范
• 多种数据源：Git 仓库、API 端点和本地文件
• 自动同步：后台同步，可配置间隔和重试逻辑
• 容器就绪：设计用于在 Kubernetes 集群中部署
• 灵活部署：独立运行或作为 ToolHive 基础设施的一部分
• 生产就绪：内置健康检查、优雅关闭和同步状态持久化

快速开始

先决条件

• Go 1.23 或更高版本
• Task 用于构建自动化

构建二进制文件

# 构建二进制文件
task build

运行服务器

所有配置均通过 YAML 配置文件完成。参见 examples/ 目录中的示例配置。

快速开始使用 Git 源：

thv-registry-api serve --config examples/config-git.yaml

使用本地文件：

thv-registry-api serve --config examples/config-file.yaml

使用 API 端点：

thv-registry-api serve --config examples/config-api.yaml

默认情况下，服务器将在端口 8080 上启动。使用 --address :PORT 自定义。

服务器启动时会发生什么：

1. 从指定的 YAML 文件加载配置
2. 立即从配置的数据源获取注册表数据
3. 启动后台同步协调器以进行自动更新
4. 在配置的地址上提供 MCP 注册表 API 端点

有关详细的配置选项和示例，请参阅 examples/README.md。

可用命令

thv-registry-api CLI 提供以下命令：

# 启动 API 服务器
thv-registry-api serve --config config.yaml [--address :8080]

# 运行数据库迁移
thv-registry-api migrate up --config config.yaml [--yes]
thv-registry-api migrate down --config config.yaml --num-steps N [--yes]

# 显示版本信息
thv-registry-api version [--format json]

# 显示帮助
thv-registry-api --help
thv-registry-api <command> --help

有关更多关于使用迁移命令的信息，请参阅 数据库迁移 部分。

API 端点

服务器实现了标准的 MCP 注册表 API：

• GET /api/v0/servers - 列出所有可用的 MCP 服务器
• GET /api/v0/servers/{name} - 获取特定服务器的详细信息
• GET /api/v0/deployed - 列出已部署的服务器实例（仅限 Kubernetes）
• GET /api/v0/deployed/{name} - 获取特定服务器的已部署实例

有关完整的 API 细节，请参阅 MCP 注册表 API 规范。 注意：当前实现并不严格遵循标准。这些偏差将在未来的迭代中修复。

配置

所有配置均通过 YAML 文件完成。服务器需要一个指向 YAML 配置文件的 --config 标志。

配置文件结构

# 注册表名称/标识符（可选，默认为 "default"）
registryName: my-registry

# 数据源配置（必需）
source:
  # 源类型：git、api 或 file
  type: git

  # 数据格式：toolhive（原生）或 upstream（MCP 注册表格式）
  format: toolhive

  # 源特定配置
  git:
    repository: https://github.com/stacklok/toolhive.git
    branch: main
    path: pkg/registry/data/registry.json

# 自动同步策略（必需）
syncPolicy:
  # 同步间隔（例如："30m"，"1h"，"24h"）
  interval: "30m"

# 可选：服务器过滤
filter:
  names:
    include: ["official/*"]
    exclude: ["*/deprecated"]
  tags:
    include: ["production"]
    exclude: ["experimental"]

# 可选：数据库配置
database:
  host: localhost
  port: 5432
  user: registry
  passwordFile: /secrets/db-password  # 推荐用于生产环境
  database: registry
  sslMode: require
  maxOpenConns: 25
  maxIdleConns: 5
  connMaxLifetime: "5m"

命令行标志

标志	描述	必需	默认值
--config	YAML 配置文件路径	是	-
--address	服务器监听地址	否	:8080

数据源

服务器支持三种数据源类型：

1. Git 仓库 - 从 Git 仓库克隆和同步

   • 支持分支、标签或提交固定
   • 适用于受版本控制的注册表
   • 示例：config-git.yaml

2. API 端点 - 从上游 MCP 注册表 API 同步

   • 支持联邦和聚合场景
   • 从上游到 ToolHive 格式的转换
   • 示例：config-api.yaml

3. 本地文件 - 从文件系统读取

   • 适用于本地开发和测试
   • 支持容器中的挂载卷
   • 示例：config-file.yaml

有关完整的配置示例和高级选项，请参阅 examples/README.md。

数据库配置

服务器可选地支持 PostgreSQL 数据库连接，用于存储注册表状态和元数据。

配置字段

字段	类型	必需	默认值	描述
host	string	是	-	数据库服务器主机名或 IP 地址
port	int	是	-	数据库服务器端口
user	string	是	-	数据库用户名
passwordFile	string	否*	-	包含数据库密码的文件路径
database	string	是	-	数据库名称
sslMode	string	否	require	SSL 模式（disable，require，verify-ca，verify-full）
maxOpenConns	int	否	25	打开的数据库连接的最大数量，以防止数据库过载
maxIdleConns	int	否	5	连接池中空闲连接的最大数量
connMaxLifetime	string	否	5m	连接的最大生命周期（例如："1h"，"30m"）

* 密码配置是必需的，但有多个来源（请参阅下面的密码安全）

密码安全

服务器支持安全的密码管理，优先顺序如下：

1. 密码文件（推荐用于生产环境）：

   • 将 passwordFile 设置为包含仅密码的文件路径
   • 文件内容将去除首尾空白
   • 适用于作为文件挂载的 Kubernetes 密钥
   • 示例：

     database:
       passwordFile: /secrets/db-password
     

2. 环境变量：

   • 设置 THV_DATABASE_PASSWORD 环境变量
   • 如果未指定 passwordFile，则使用此变量
   • 示例：

     export THV_DATABASE_PASSWORD="your-secure-password"
     thv-registry-api serve --config config.yaml
     

最佳安全实践：

• 不要在配置文件中直接提交密码
• 使用具有受限权限的密码文件（例如，chmod 400）
• 在 Kubernetes 中，从密钥挂载密码
• 定期轮换密码

连接池

服务器使用连接池来高效管理数据库资源：

• MaxOpenConns：限制并发数据库连接，以防止数据库过载
• MaxIdleConns：维护空闲连接以加快查询执行速度
• ConnMaxLifetime：自动关闭并重新创建连接以防止连接泄漏

根据您的工作负载调整这些值：

• 高流量场景：增加 maxOpenConns 和 maxIdleConns
• 资源受限环境：减少池大小
• 长时间运行的服务：设置较短的 connMaxLifetime（例如："1h"）

数据库迁移

服务器包括内置的数据库迁移命令，用于管理数据库模式。

使用 CLI 运行迁移：

# 应用所有待处理的迁移
thv-registry-api migrate up --config examples/config-database-dev.yaml

# 非交互式应用迁移（适用于 CI/CD）
thv-registry-api migrate up --config config.yaml --yes

# 回滚最后的迁移（需要 --num-steps 以确保安全）
thv-registry-api migrate down --config config.yaml --num-steps 1

# 查看迁移帮助
thv-registry-api migrate --help

使用 Task 运行迁移：

# 应用迁移（开发）
export THV_DATABASE_PASSWORD="devpassword"
task migrate-up CONFIG=examples/config-database-dev.yaml

# 回滚迁移（指定步骤数以确保安全）
task migrate-down CONFIG=examples/config-database-dev.yaml NUM_STEPS=1

迁移流程：

1. 配置数据库：创建包含数据库设置的配置文件（参见 examples/config-database-dev.yaml）
2. 设置密码：设置 THV_DATABASE_PASSWORD 环境变量或在配置中使用 passwordFile
3. 运行迁移：使用 migrate up 应用模式更改
4. 启动服务器：使用相同的配置文件运行 serve 命令

示例：本地开发设置

# 1. 启动 PostgreSQL（示例使用 Docker）
docker run -d --name postgres \
  -e POSTGRES_USER=thv_user \
  -e POSTGRES_PASSWORD=devpassword \
  -e POSTGRES_DB=toolhive_registry \
  -p 5432:5432 \
  postgres:16

# 2. 设置密码环境变量
export THV_DATABASE_PASSWORD="devpassword"

# 3. 运行迁移
task migrate-up CONFIG=examples/config-database-dev.yaml

# 4. 启动服务器
thv-registry-api serve --config examples/config-database-dev.yaml

示例：生产部署

# 1. 创建密码文件
echo "your-secure-password" > /run/secrets/db_password
chmod 400 /run/secrets/db_password

# 2. 运行迁移（使用配置中的 passwordFile）
thv-registry-api migrate up \
  --config examples/config-database-prod.yaml \
  --yes

# 3. 启动服务器
thv-registry-api serve --config examples/config-database-prod.yaml

安全特性：

• migrate down 需要 --num-steps 标志以防止意外完全回滚
• 交互式确认提示（使用 --yes 标志绕过）
• 对破坏性操作显示强烈警告
• 在连接到数据库之前验证配置

有关完整的示例，请参阅：

• examples/config-database-dev.yaml - 开发配置
• examples/config-database-prod.yaml - 生产配置

示例 Kubernetes 部署与数据库

apiVersion: v1
kind: Secret
metadata:
  name: registry-db-password
type: Opaque
stringData:
  password: your-secure-password
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: registry-api-config
data:
  config.yaml: |
    registryName: my-registry
    source:
      type: git
      format: toolhive
      git:
        repository: https://github.com/stacklok/toolhive.git
        branch: main
        path: pkg/registry/data/registry.json
    syncPolicy:
      interval: "15m"
    database:
      host: postgres.default.svc.cluster.local
      port: 15432
      user: registry
      passwordFile: /secrets/db-password
      database: registry
      sslMode: require
      maxOpenConns: 25
      maxIdleConns: 5
      connMaxLifetime: "5m"
---
# 在部署服务器之前作为 Kubernetes Job 运行迁移
apiVersion: batch/v1
kind: Job
metadata:
  name: registry-migrate
spec:
  template:
    spec:
      restartPolicy: OnFailure
      containers:
      - name: migrate
        image: ghcr.io/stacklok/toolhive/thv-registry-api:latest
        args:
        - migrate
        - up
        - --config=/etc/registry/config.yaml
        - --yes
        volumeMounts:
        - name: config
          mountPath: /etc/registry
        - name: db-password
          mountPath: /secrets
          readOnly: true
      volumes:
      - name: config
        configMap:
          name: registry-api-config
      - name: db-password
        secret:
          secretName: registry-db-password
          items:
          - key: password
            path: db-password
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: registry-api
spec:
  template:
    spec:
      containers:
      - name: registry-api
        image: ghcr.io/stacklok/toolhive/thv-registry-api:latest
        args:
        - serve
        - --config=/etc/registry/config.yaml
        volumeMounts:
        - name: config
          mountPath: /etc/registry
        - name: db-password
          mountPath: /secrets
          readOnly: true
      volumes:
      - name: config
        configMap:
          name: registry-api-config
      - name: db-password
        secret:
          secretName: registry-db-password
          items:
          - key: password
            path: db-password

开发

构建命令

# 构建二进制文件
task build

# 运行代码检查
task lint

# 自动修复代码检查问题
task lint-fix

# 运行测试
task test

# 生成模拟对象
task gen

# 构建容器镜像
task build-image

# 数据库迁移
task migrate-up CONFIG=examples/config-database-dev.yaml
task migrate-down CONFIG=examples/config-database-dev.yaml NUM_STEPS=1

项目结构

cmd/thv-registry-api/
├── api/                 # REST API 实现
│   └── v1/              # API v1 处理程序和路由
├── app/                 # CLI 命令和应用程序设置
├── internal/service/    # 正在重构的遗留服务层
│   ├── file_provider.go     # 基于文件的注册表提供者
│   ├── k8s_provider.go      # Kubernetes 提供者
│   └── service.go           # 核心服务实现
└── main.go              # 应用程序入口点

pkg/
├── config/              # 配置加载和验证
├── sources/             # 数据源处理器
│   ├── git.go               # Git 仓库源
│   ├── api.go               # API 端点源
│   ├── file.go              # 文件系统源
│   ├── factory.go           # 注册表处理器工厂
│   └── storage_manager.go   # 存储抽象
├── sync/                # 同步管理器和协调
│   └── manager.go           # 后台同步逻辑
└── status/              # 同步状态跟踪
    └── persistence.go       # 状态文件持久化

examples/                # 示例配置

架构

服务器遵循干净架构模式，具有以下层次：

1. API 层 (cmd/thv-registry-api/api)：实现 MCP 注册表 API 的 HTTP 处理程序
2. 服务层 (cmd/thv-registry-api/internal/service)：正在重构的遗留业务逻辑
3. 配置层 (pkg/config)：YAML 配置加载和验证
4. **注册表