# MCP 服务概述
URL: https://docs.ones.cn/on-premises/7.33/product-manual/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
``` | `X-ONES-MCP-Token: ` ，也支持 `Authorization: Bearer ` |
| 续期方式 | 支持使用 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` 获取。
- **权限与可见性** ：工具出现在列表中不等于能操作任意业务对象；具体执行仍可能因业务权限、许可、参数或环境能力不足而失败。