# MCP 服务概述

URL: https://docs.ones.cn/ones-mcp/mcp-service-overview

## 什么是 MCP

MCP（Model Context Protocol）用于连接 AI 应用与外部数据和工具。ONES MCP 服务让支持相应连接与认证方式的客户端，以当前用户的身份查询和操作 ONES 数据。

ONES 公有云版本注册了 66 个 MCP 工具。覆盖项目管理、知识库、测试管理、账号与通知、附件读取。实际返回给客户端的工具还取决于授权方式、授权范围和团队能力；业务数据访问继续受 ONES 用户权限限制。

## 获取 MCP 服务器地址

在 ONES 的个人中心 > 已授权 MCP 客户端页面查看并复制团队的 MCP 服务器地址，将完整地址填入客户端。服务端 MCP 端点为 `/mcp` ，不要将 OAuth 授权地址或内部管理接口作为 MCP 服务器地址。

## 授权与连接方式

当前支持 OAuth 授权和手工 Token 授权两种方式，均绑定用户、团队和组织身份。

| 对比项 | OAuth 授权 | 手工 Token 授权 |
| --- | --- | --- |
| 适用客户端 | 支持 ONES MCP OAuth 流程的客户端 | 支持设置请求头或 Bearer Token 的客户端 |
| 获取凭据 | 在浏览器完成授权，由客户端交换访问令牌 | 在 ONES 支持的管理入口创建 Token，并配置到客户端 |
| 请求携带方式 | `Authorization: Bearer <OAuth access token>` | `X-ONES-MCP-Token: <manual token>` ，也支持 `Authorization: Bearer <manual token>` |
| 续期方式 | 支持使用 Refresh Token 刷新访问令牌 | 不提供 Refresh Token，按设置的有效期失效 |
| 授权范围 | 创建、更新按 scope 校验；读取存在下文说明的例外 | 读取、创建、更新均按 scope 校验 |
| 删除操作 | 暂不支持 | 暂不支持 |

### 方式一：OAuth 授权

1. 在 MCP 客户端中配置 ONES MCP 服务器地址，发起连接。
2. 客户端引导你进入 ONES 授权页面。核对实际客户端名称、个人身份和生效团队；客户端名称不固定为原文中的 "MCP CLI Proxy"。
3. 按使用需要选择授权范围并确认授权。
4. 客户端完成授权码交换后，使用访问令牌连接 MCP 服务。

### 方式二：手工 Token 授权

对于不支持浏览器 OAuth 跳转、但支持自定义请求头或 Bearer Token 的客户端，可以手动配置 Token。

1. 在 ONES 提供的 MCP Token 管理入口创建 Token，设置名称、有效期和所需授权范围，并确认绑定的团队。
2. 获取生成的 Token，将团队 MCP 服务器地址填入客户端。
3. 根据客户端支持的方式，选择以下一种请求头配置。
4. 连接后获取工具列表，检查所需工具是否出现。
Bearer 方式：

```text
Authorization: Bearer <你创建的 MCP Token>
```

## 授权范围与可用能力

> 操作:资源类别:资源名称

| 资源 scope | 含义 | 工具涉及的操作 |
| --- | --- | --- |
| `project:project` | 项目、迭代及项目相关查询 | read、create、update |
| `project:issue` | 工作项及附件内容读取 | read、create、update |
| `project:issueType` | 工作项类型、状态与层级配置 | read |
| `project:issueField` | 工作项字段与选项 | read |
| `project:issueComment` | 工作项评论 | read、create、update |
| `project:workhour` | 工时模式、工时记录与预估 | read、create、update |
| `wiki:space` | 知识空间及页面目录 | read、create |
| `wiki:page` | 知识库页面、内容检索和附件文本 | read、create |
| `testcase:library` | 测试用例库及模块 | read、create、update |
| `testcase:testcase` | 测试用例 | read、create、update |
| `account:user` | 成员、当前用户及通知 | read |
| `docs:search` | ONES 官方文档搜索 | read |

例如，创建项目、创建工作项、发表评论和新增工时分别对应 `create:project:project` 、 `create:project:issue` 、 `create:project:issueComment` 和 `create:project:workhour` 。创建知识空间还需要 `create:wiki:space` 。

## 管理已授权客户端与 Token

OAuth 授权后，可通过个人中心的授权管理入口查看客户端名称、生效团队、授权范围、创建时间与上次访问时间，并修改授权或取消授权。

手工 Token 单独管理，支持查看、修改名称、有效期和授权范围，以及撤销。撤销后，后续认证无法再使用该凭据。

"上次访问时间"表示认证访问记录，不等同于最后一次成功执行某个工具的时间。

## 可用工具一览

表中 scope 为完整授权标识；标记 † 的工具依赖团队开启 Assistant 且具备可用的嵌入模型／检索能力，条件不满足时不会向客户端展示，也不能调用。

### 项目管理：工作项（19 个）

| 工具名称 | 说明 | 授权 scope |
| --- | --- | --- |
| `create_new_issue` | 创建工作项，如任务、缺陷、需求等。 | `create:project:issue` |
| `execute_issue_workflow` | 执行工作项的可用工作流，变更工作项状态。 | `update:project:issue` |
| `find_similar_issues` | 根据指定工作项的内容查找相似工作项。† | `read:project:issue` |
| `get_issue_activities` | 获取工作项动态，包括字段变更、评论和状态变更等。 | `read:project:issue` |
| `get_issue_code_info` | 获取工作项关联的代码提交、分支和 Pull Request 信息。 | `read:project:issue` |
| `get_issue_human_readable_keys` | 批量获取工作项的可读编号。 | `read:project:issue` |
| `get_issue_details` | 获取工作项详情。 | `read:project:issue` |
| `get_issue_executable_workflows` | 获取指定工作项当前可执行的工作流。 | `read:project:issue` |
| `get_issue_fields` | 获取工作项字段、字段类型、必填规则等信息。 | `read:project:issueField` |
| `get_issue_status` | 获取工作项状态信息。 | `read:project:issueType` |
| `get_issue_type_hierarchy_configs` | 获取工作项类型的层级及父子关系配置。 | `read:project:issueType` |
| `get_list_of_issue_comments` | 获取工作项评论列表。 | `read:project:issueComment` |
| `get_onesql_grammar_help` | 获取 ONESQL 语法及查询规则；执行 ONESQL 查询前应先调用。 | `read:project:issue` |
| `post_issue_comment` | 发表工作项评论，支持提及成员。 | `create:project:issueComment` |
| `query_issues_by_onesql` | 使用 ONESQL 查询工作项。 | `read:project:issue` |
| `search_for_issue_field_options` | 按关键字查找指定工作项字段的可选项。 | `read:project:issueField` |
| `search_for_issue_types` | 按关键字查找工作项类型。 | `read:project:issueType` |
| `update_issue` | 更新工作项指定字段；状态变更使用工作流工具。 | `update:project:issue` |
| `update_issue_comment` | 修改工作项评论。 | `update:project:issueComment` |

### 项目管理：项目、迭代与相关对象（12 个）

| 工具名称 | 说明 | 授权 scope |
| --- | --- | --- |
| `add_project_members` | 向项目添加成员。 | `update:project:project` |
| `create_new_project` | 创建项目。 | `create:project:project` |
| `create_sprint` | 创建迭代。 | `create:project:project` |
| `get_project_details_by_project_id` | 根据项目 ID 获取项目详情。 | `read:project:project` |
| `get_sprint_details` | 获取迭代详情。 | `read:project:project` |
| `search_for_epics` | 按名称关键字查找史诗，可限定项目。 | `read:project:project` |
| `search_for_modules` | 按名称关键字查找项目模块，可限定项目。 | `read:project:project` |
| `search_for_projects` | 按项目名称及其他条件查找项目。 | `read:project:project` |
| `search_for_releases` | 查找发布版本，可限定项目。 | `read:project:project` |
| `search_for_sprints` | 按名称关键字查找迭代，可限定项目。 | `read:project:project` |
| `update_project_by_project_id` | 更新项目基本信息。 | `update:project:project` |
| `update_sprint` | 更新迭代信息。 | `update:project:project` |

### 项目管理：工时（11 个）

| 工具名称 | 说明 | 授权 scope |
| --- | --- | --- |
| `get_manhour_mode` | 获取当前团队的工时模式：简单模式或汇总模式。 | `read:project:workhour` |
| `get_manhour_list_in_simple_mode` | 获取工作项的工时记录列表（简单模式）。 | `read:project:workhour` |
| `set_manhour_estimated_in_simple_mode` | 设置工作项预估工时（简单模式）。 | `update:project:workhour` |
| `set_manhour_remaining_in_simple_mode` | 设置工作项剩余工时（简单模式）。 | `update:project:workhour` |
| `add_workhour_in_simple_mode` | 新增实际工时登记（简单模式）。 | `create:project:workhour` |
| `update_workhour_in_simple_mode` | 更新已登记实际工时（简单模式）。 | `update:project:workhour` |
| `get_manhour_list_in_summary_mode` | 获取工作项的工时记录列表（汇总模式）。 | `read:project:workhour` |
| `add_manhour_estimated_in_summary_mode` | 新增预估工时记录（汇总模式）。 | `create:project:workhour` |
| `update_manhour_estimated_in_summary_mode` | 更新预估工时记录（汇总模式）。 | `update:project:workhour` |
| `add_workhour_in_summary_mode` | 新增实际工时登记（汇总模式）。 | `create:project:workhour` |
| `update_workhour_in_summary_mode` | 更新已登记实际工时（汇总模式）。 | `update:project:workhour` |

### 知识库（11 个）

| 工具名称 | 说明 | 授权 scope |
| --- | --- | --- |
| `create_space` | 创建知识空间（页面组）；需要创建权限及可用的 Wiki 许可。 | `create:wiki:space` |
| `get_space_details` | 获取知识空间详情，包括首页 ID。 | `read:wiki:space` |
| `get_list_of_space_pages` | 获取知识空间中的页面列表及父子关系信息。 | `read:wiki:space` |
| `search_pages_by_title` | 按标题关键字搜索页面，可限定知识空间。 | `read:wiki:space` |
| `search_for_spaces` | 按关键字查找知识空间。 | `read:wiki:space` |
| `create_page` | 创建知识库页面。 | `create:wiki:page` |
| `get_page_details` | 获取知识库页面详情。 | `read:wiki:page` |
| `get_page_changes` | 获取指定时间之后的页面变更及按用户分组的编辑操作；是否支持取决于页面类型。 | `read:wiki:page` |
| `get_page_attachment_text` | 读取知识库附件已转换的文本或已有转写内容。† | `read:wiki:page` |
| `get_favorite_or_watch_pages` | 获取当前用户收藏或关注的页面。 | `read:wiki:page` |
| `search_for_references_in_wiki` | 按问题检索知识库相关页面与附件内容，可限定知识空间或页面。† | `read:wiki:page` |

### 测试管理（9 个）

| 工具名称 | 说明 | 授权 scope |
| --- | --- | --- |
| `create_module_in_testcase_library` | 在测试用例库中创建模块。 | `create:testcase:library` |
| `create_new_testcase_in_library` | 在测试用例库中创建测试用例。 | `create:testcase:testcase` |
| `get_testcase_details` | 获取测试用例详情。 | `read:testcase:testcase` |
| `get_testcase_library_fields` | 获取测试用例库的字段配置。 | `read:testcase:library` |
| `search_for_modules_in_testcase_library` | 按名称关键字查找测试用例库模块。 | `read:testcase:library` |
| `search_for_testcases_in_library` | 在测试用例库中查找测试用例。 | `read:testcase:testcase` |
| `search_for_testcase_libraries` | 按名称及其他条件查找测试用例库。 | `read:testcase:library` |
| `update_module_in_testcase_library` | 更新测试用例库模块名称。 | `update:testcase:library` |
| `update_testcase` | 更新测试用例。 | `update:testcase:testcase` |

### 账号与通知（3 个）

| 工具名称 | 说明 | 授权 scope |
| --- | --- | --- |
| `search_for_users` | 按姓名、邮箱或工号等关键字搜索成员。 | `read:account:user` |
| `who_am_i` | 获取当前调用身份的信息，可用于确定用户时区。 | `read:account:user` |
| `get_user_notices` | 获取指定时间之后的用户通知。 | `read:account:user` |

### 附件（1 个）

| 工具名称 | 说明 | 授权 scope |
| --- | --- | --- |
| `read_attachment_content` | 根据资源 ID 读取附件文本或图片供模型理解，不保存文件到本地。 | `read:project:issue` |

### 使用限制与说明

- 工时模式：先调用 `get_manhour_mode` 确认团队使用简单模式还是汇总模式，再选择对应工具。
- 知识库创建： `create_space` 创建知识空间后返回首页 ID，可作为 `create_page` 的父页面 ID 使用；
- 附件内容： `read_attachment_content` 返回模型可读的文本或图片，不将原始文件下载到本地，不返回视频、音频或压缩包等二进制内容；文本上限为 128 KiB，图片上限为 10 MiB。知识库附件已转换的文本通过 `get_page_attachment_text` 获取。
- 权限与可见性：工具出现在列表中不等于能操作任意业务对象；具体执行仍可能因业务权限、许可、参数或环境能力不足而失败。