> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcphub.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 群组

> 管理服务器群组以组织和路由请求。

<Card title="GET /api/groups" href="#get-all-groups">获取所有群组的列表。</Card>
<Card title="POST /api/groups" href="#create-a-new-group">创建一个新群组。</Card>
<Card title="GET /api/groups/:id" href="#get-a-group">获取特定群组的详细信息。</Card>
<Card title="PUT /api/groups/:id" href="#update-a-group">更新现有群组。</Card>
<Card title="DELETE /api/groups/:id" href="#delete-a-group">删除一个群组。</Card>
<Card title="POST /api/groups/:id/servers" href="#add-server-to-group">将服务器添加到群组。</Card>
<Card title="DELETE /api/groups/:id/servers/:serverName" href="#remove-server-from-group">从群组中删除服务器。</Card>
<Card title="PUT /api/groups/:id/servers/batch" href="#batch-update-group-servers">批量更新群组中的服务器。</Card>
<Card title="GET /api/groups/:id/server-configs" href="#get-group-server-configs">获取群组中详细的服务器配置。</Card>
<Card title="PUT /api/groups/:id/server-configs/:serverName/tools" href="#update-group-server-tools">更新群组中服务器的工具选择。</Card>

***

### 获取所有群组

检索所有服务器群组的列表。

* **端点**: `/api/groups`
* **方法**: `GET`
* **成功响应**:
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "group-1",
        "name": "我的群组",
        "description": "服务器的集合。",
        "servers": ["server1", "server2"],
        "owner": "admin"
      }
    ]
  }
  ```

***

### 创建一个新群组

创建一个新的服务器群组。

* **端点**: `/api/groups`
* **方法**: `POST`
* **正文**:
  * `name` (string, 必填): 群组的名称。
  * `description` (string, 可选): 群组的描述。
  * `servers` (array of strings, 可选): 要包含在群组中的服务器名称列表。
* **请求示例**:
  ```json theme={null}
  {
    "name": "我的新群组",
    "description": "新群组的描述",
    "servers": ["server1", "server2"]
  }
  ```

***

### 获取一个群组

通过 ID 或名称检索特定群组的详细信息。

* **端点**: `/api/groups/:id`
* **方法**: `GET`
* **参数**:
  * `:id` (string, 必填): 群组的 ID 或名称。

***

### 更新一个群组

更新现有群组的名称、描述或服务器列表。

* **端点**: `/api/groups/:id`
* **方法**: `PUT`
* **参数**:
  * `:id` (string, 必填): 要更新的群组的 ID 或名称。
* **正文**:
  * `name` (string, 可选): 群组的新名称。
  * `description` (string, 可选): 群组的新描述。
  * `servers` (array, 可选): 群组的新服务器列表。格式请参阅 [批量更新群组服务器](#batch-update-group-servers)。
* **请求示例**:
  ```json theme={null}
  {
    "name": "更新后的群组名称",
    "description": "更新后的描述"
  }
  ```

***

### 删除一个群组

通过 ID 或名称删除一个群组。

* **端点**: `/api/groups/:id`
* **方法**: `DELETE`
* **参数**:
  * `:id` (string, 必填): 要删除的群组的 ID 或名称。

***

### 将服务器添加到群组

将单个服务器添加到群组。

* **端点**: `/api/groups/:id/servers`
* **方法**: `POST`
* **参数**:
  * `:id` (string, 必填): 群组的 ID 或名称。
* **正文**:
  * `serverName` (string, 必填): 要添加的服务器的名称。
* **请求示例**:
  ```json theme={null}
  {
    "serverName": "my-server"
  }
  ```

***

### 从群组中删除服务器

从群组中删除单个服务器。

* **端点**: `/api/groups/:id/servers/:serverName`
* **方法**: `DELETE`
* **参数**:
  * `:id` (string, 必填): 群组的 ID 或名称。
  * `:serverName` (string, 必填): 要删除的服务器的名称。

***

### 批量更新群组服务器

用新的列表替换群组中的所有服务器。该列表可以是简单的字符串或详细的配置对象。

* **端点**: `/api/groups/:id/servers/batch`
* **方法**: `PUT`
* **参数**:
  * `:id` (string, 必填): 群组的 ID 或名称。
* **正文**:
  * `servers` (array, 必填): 服务器名称（字符串）或服务器配置对象的数组。
* **请求示例 (简单)**:
  ```json theme={null}
  {
    "servers": ["server1", "server2"]
  }
  ```
* **请求示例 (详细)**:
  ```json theme={null}
  {
    "servers": [
      { "name": "server1", "tools": "all" },
      { "name": "server2", "tools": ["toolA", "toolB"] }
    ]
  }
  ```

服务器配置对象还可以包含 `pinnedTools`：不带前缀的工具名数组，这些工具会在分组的 `$smart/{group}` 端点中与元工具一同列出（参见 [固定工具](/zh/features/smart-routing#固定工具)）。只有同时在 `tools` 中选中的固定工具才会生效。

***

### 获取群组服务器配置

检索群组内所有服务器的详细配置，包括启用了哪些工具。

* **端点**: `/api/groups/:id/server-configs`
* **方法**: `GET`
* **参数**:
  * `:id` (string, 必填): 群组的 ID 或名称。
* **成功响应**:
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "name": "server1",
        "tools": "all"
      },
      {
        "name": "server2",
        "tools": ["toolA", "toolB"]
      }
    ]
  }
  ```

***

### 更新群组服务器工具

更新群组内特定服务器的工具选择。

* **端点**: `/api/groups/:id/server-configs/:serverName/tools`
* **方法**: `PUT`
* **参数**:
  * `:id` (string, 必填): 群组的 ID 或名称。
  * `:serverName` (string, 必填): 要更新的服务器的名称。
* **正文**:
  * `tools` (string or array of strings, 必填): 字符串 `"all"` 表示启用所有工具，或一个工具名称数组以指定启用哪些工具。未包含在数组中的工具会被移除固定（`pinnedTools`）。
* **请求示例**:
  ```json theme={null}
  {
    "tools": ["toolA", "toolC"]
  }
  ```

## 可见性字段

`POST /api/groups`、`POST /api/groups/batch` 中的各组以及 `PUT /api/groups/:id`
支持 `visibility`（`private | group | public`）和 `sharedWithUsers`（非空用户名数组）。
新组默认私有，更新时省略字段则保持原值。`shared` 和 `null` 不是合法的可见性值。
共享用户为空时仅所有者和管理员有权限。

`GET /api/groups/:id/share-candidates` 返回按名称排序的用户名数组（不包含所有者），
仅所有者和管理员可调用。共享允许发现和使用，不赋予管理权限。
组读取响应会隐藏无权访问的服务器；替换服务器列表时保留已有的隐藏条目。
历史组兼容和数据库升级规则见[组管理](/zh/features/group-management)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.