stacklok/toolhive-registry-server

[][release] [][ci] [][coveralls] [][license] [][stars] [][discord] # ToolHive 注册表服务器 **发现、治理和控制组织内对MCP服务器与技能的访问** ToolHive注册表服务器将来自Git仓库、Kubernetes集群、上游注册表和内部API的MCP服务器与技能聚合到命名目录中，供您的团队和AI客户端查询。每个目录都有其自身的访问控制和审计跟踪，因此您可以决定哪些条目对哪些用户可见——并且拥有谁访问了什么的记录。 它实现了官方的 [模型上下文协议 注册表API规范](https://modelcontextprotocol.io/development/roadmap#registry)。如果您不熟悉MCP：它是一个开放协议，允许AI助手连接到外部工具和数据源。此服务器是位于您的MCP基础设施和使用它的团队之间的治理层。 **为什么选择ToolHive注册表服务器？** 大多数MCP设置始于一个扁平的服务器列表，且没有访问控制。随着采用率的增长，您需要治理谁能看到什么，聚合来自多个源的服务器，并审计访问——而不锁定于专有的注册表。ToolHive注册表服务器是开源的，实现了官方MCP注册表API规范，并可集成到您现有的身份提供商中，将多租户基于声明的授权、多源聚合和符合SIEM的审计日志记录结合在一个服务中。 [了解更多关于ToolHive平台的信息 →](https://stacklok.com/platform) ## 目录 - [功能特性](#features) - [快速开始](#quickstart) - [核心概念](#core-concepts) - [API端点](#api-endpoints) - [配置](#configuration) - [ToolHive平台](#the-toolhive-platform) - [文档](#documentation) - [贡献指南](#contributing) ## 功能特性 ### 治理与访问控制 - **基于JWT声明的可见性**：按注册表控制每个用户或团队可以看到哪些MCP服务器和技能。一个"生产"注册表可以只暴露经过验证的条目，而一个"dev-team"注册表可以显示所有内容。 - **OAuth 2.0/OIDC认证**：接入您现有的身份提供商（Okta, Auth0, Azure AD）。OAuth是默认方式；匿名模式可用于开发环境。 - **基于角色的管理**：为管理来源、注册表和条目分离角色。将每个角色的范围限定到特定的JWT声明，以便团队管理自己的资源。 - **符合SIEM的审计日志记录**：结构化日志涵盖所有API操作，包含符合NIST SP 800-53 AU-3的字段，专用文件输出和可配置的事件过滤。 ### 从任何地方聚合 - **五种来源类型**：从Git仓库、上游MCP注册表、本地文件、Kubernetes集群拉取条目，或通过Admin API发布条目。 - **从多个来源组合目录**：每个注册表聚合一个或多个来源，按优先级顺序列出。一个来源可以供应多个注册表，因此同一个内部目录可以通过不同的可见性规则为不同的团队服务。 - **后台同步**：来源按可配置的时间间隔轮询，并带有重试逻辑。注册表无需人工干预即可保持最新。 ### Kubernetes 与可观测性 ## 快速开始 ### 前置条件 - Go 1.26 或更高版本（用于从源代码构建） - [Task](https://taskfile.dev) 用于构建自动化 - PostgreSQL 16+ ### 构建并运行 ``` # 构建二进制文件 task build # 使用 Git 源代码运行 thv-registry-api serve --config examples/config-git.yaml # 使用本地文件运行 thv-registry-api serve --config examples/config-file.yaml ``` 服务器默认在 `http://localhost:8080` 上启动。 ### Docker 快速开始 ``` # 使用 Task（推荐 - 确保全新状态） task docker-up # 或分离模式 task docker-up-detached # 访问 API curl http://localhost:8080/registry/default/v0.1/servers # 停止并清理 task docker-down ``` ## 核心概念 ### 来源与注册表 大多数组织的MCP服务器和技能存在于多个地方——公共目录、内部Git仓库、运行实时实例的Kubernetes集群。注册表服务器使用两个原语对此建模：**来源**（条目来自哪里）和**注册表**（消费者查询什么）。 **来源**是连接到MCP服务器和技能条目所在位置的连接。它告诉服务器"去这里查找条目"。来源有五种类型： | 类型 | 功能描述 | 示例 | 同步方式 | | ------------- | --------------------------------- | ------------------------------------------------------------ | ------------- | | **API** | 从上游注册表API拉取 | 位于 registry.modelcontextprotocol.io 的官方MCP注册表 | 自动 | | **Git** | 从Git仓库克隆条目 | 版本控制的内部目录 | 自动 | | **File** | 从本地文件系统读取 | 磁盘上策展的 `registry.json` | 自动 | | **Managed** | 通过Admin API发布的条目 | 动态注册的内部服务器 | 按需 | | **Kubernetes** | 发现已部署的MCP服务器 | 运行在您的K8s集群中的服务器 | 按需 | **注册表**是一个命名的目录，它将一个或多个来源聚合到一个面向消费者的端点中。每个注册表可以从不同的来源拉取数据，并通过JWT声明强制执行其自身的访问控制。来源按顺序列出——当同一个条目出现在多个来源中时，列表中的第一个来源获胜。 **它们为什么分开**：来源和注册表是多对多关系。一个来源可以供应多个注册表，一个注册表可以从多个来源拉取。这使您可以从相同的基础数据为不同的受众组合不同的目录： ``` Source: "official-catalog" ──┐ Source: "internal-tools" ──┼──> Registry: "production" (curated, vetted) │ Source: "internal-tools" ──┼──> Registry: "dev-team" (everything) Source: "k8s-deployed" ──┘ ``` 在此示例中，"生产"注册表仅暴露来自官方目录和内部工具的经过验证的条目，而"dev-team"注册表包括所有内容以及通过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 ``` 完整详情请参见 [配置指南](docs/configuration.md)。 ## 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、文件和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` - 列出注册表的条目 - `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（ToolHive特有） 只读端点，用于在注册表中发现技能： - `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**：管理来源和注册表，发布条目，查询注册表状态 完整API详情请参见 [MCP注册表API规范](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/openapi.yaml)。 ## 配置 所有配置都通过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 ``` ### 完整指南 - **[配置参考](docs/configuration.md)** - 完整的配置选项 - **[环境变量](docs/environment-variables.md)** - 使用环境变量进行配置 - **[数据库设置](docs/database.md)** - PostgreSQL配置、迁移和安全 - **[认证](docs/authentication.md)** - OAuth/OIDC设置和安全 ## ToolHive平台 注册表服务器可以作为独立项目部署，也可以作为完整的 [ToolHive](https://github.com/stacklok/toolhive) 平台的一部分部署。平台组件共同覆盖了完整的MCP生命周期： - **注册表**（本项目）——发现与治理。知道存在哪些MCP服务器和技能，谁可以访问它们，并跟踪所有操作。 - **[运行时](https://github.com/stacklok/toolhive)**——部署与管理。在Kubernetes上部署MCP服务器，使用注册表元数据来驱动生命周期决策。由运行时部署的服务器会自动出现在注册表中。 - **网关**——聚合与访问。将多个MCP服务器统一到一个端点，具有集中式认证、基于Cedar的授权、工具冲突解决和组合工作流。 - **门户**——管理UI。目录浏览、搜索和管理，由注册表API支持。 完整的平台架构请参见 [ToolHive文档](https://docs.stacklok.com/toolhive/)。 ## 文档 - **[配置参考](docs/configuration.md)** - 所有配置选项 - **[环境变量](docs/environment-variables.md)** - 环境变量覆盖 - **[数据库设置](docs/database.md)** - PostgreSQL设置和迁移 - **[认证](docs/authentication.md)** - OAuth/OIDC安全 - **[可观测性](docs/observability.md)** - OpenTelemetry追踪和指标 - **[注册表同步](docs/registry-sync.md)** - 后台同步如何工作 - **[Kubernetes部署](docs/deployment-kubernetes.md)** - K8s部署和高可用性 - **[Docker部署](docs/deployment-docker.md)** - Docker Compose设置 - **[API文档](docs/thv-registry-api/)** - 自动生成的OpenAPI文档 - **[CLI参考](docs/cli/)** - 命令行接口文档 - **[示例](examples/)** - 工作配置示例 ## 许可证 本项目根据 [Apache 2.0许可证](LICENSE) 授权。 **[ToolHive](https://github.com/stacklok/toolhive) 项目的一部分** - 简化并保障MCP服务器的安全

标签：AI 代理, AI 治理, API 管理, EVTX分析, Git 仓库, Kubernetes 集成, MCP 注册表, SIEM 兼容, Streamlit, 人工智能安全, 企业安全, 合规性, 多租户授权, 子域名突变, 审计跟踪, 开源, 技能管理, 日志审计, 服务发现, 测试用例, 网络安全研究, 网络资产管理, 访问控制, 请求拦截, 资源聚合, 身份提供商集成