群组

---

​

获取所有群组

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

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

---

​

创建一个新群组

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

• 端点: /api/groups
• 方法: POST
• 正文:
  • name (string, 必填): 群组的名称。
  • description (string, 可选): 群组的描述。
  • instructions (string, 可选): 在该群组路由上作为 MCP initialize 的 instructions 发送。参见分组说明。
  • servers (array of strings, 可选): 要包含在群组中的服务器名称列表。
• 请求示例:
  {
    "name": "我的新群组",
    "description": "新群组的描述",
    "servers": ["server1", "server2"]
  }
  

---

​

获取一个群组

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

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

---

​

更新一个群组

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

• 端点: /api/groups/:id
• 方法: PUT
• 参数:
  • :id (string, 必填): 要更新的群组的 ID 或名称。
• 正文:
  • name (string, 可选): 群组的新名称。
  • description (string, 可选): 群组的新描述。
  • instructions (string, 可选): 群组的新说明；空字符串表示移除。
  • servers (array, 可选): 群组的新服务器列表。格式请参阅 批量更新群组服务器。
• 请求示例:
  {
    "name": "更新后的群组名称",
    "description": "更新后的描述"
  }
  

---

​

删除一个群组

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

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

---

​

将服务器添加到群组

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

• 端点: /api/groups/:id/servers
• 方法: POST
• 参数:
  • :id (string, 必填): 群组的 ID 或名称。
• 正文:
  • serverName (string, 必填): 要添加的服务器的名称。
• 请求示例:
  {
    "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, 必填): 服务器名称（字符串）或服务器配置对象的数组。
• 请求示例 (简单):
  {
    "servers": ["server1", "server2"]
  }
  
• 请求示例 (详细):
  {
    "servers": [
      { "name": "server1", "tools": "all" },
      { "name": "server2", "tools": ["toolA", "toolB"] }
    ]
  }
  

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

---

​

获取群组服务器配置

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

• 端点: /api/groups/:id/server-configs
• 方法: GET
• 参数:
  • :id (string, 必填): 群组的 ID 或名称。
• 成功响应:
  {
    "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）。
• 请求示例:
  {
    "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 返回按名称排序的用户名数组（不包含所有者）， 仅所有者和管理员可调用。共享允许发现和使用，不赋予管理权限。 组读取响应会隐藏无权访问的服务器；替换服务器列表时保留已有的隐藏条目。 历史组兼容和数据库升级规则见组管理。