---
title: MCP
navTitle: MCP
---
# MCP

SuccApp MCP 是服务端提供给 AI 客户端的工具协议入口。支持 MCP 的 AI 客户端连接 SuccApp 服务器后，可以通过标准的工具发现和工具调用方式读取系统信息、访问元数据和查询数据库。

MCP 适合让 AI 直接理解服务器现状；如果任务需要本地文件修改、Git 管理、diff 评审和发布流程，仍应使用 SuccApp 工作区，并配合 [SuccApp CLI](./cli.md) 和 [SuccApp for VS Code](./vscode.md)。

## 接入方式{#connection}

当前 SuccApp MCP 入口是服务器上的 HTTP JSON-RPC 接口 `/api/mcp`。客户端应使用 `POST` 请求提交 JSON-RPC 消息；当前不提供 `GET`、SSE 或事件流入口。

MCP 调用需要使用当前 SuccApp 服务器支持的认证方式，例如已登录会话或可访问该服务器的 Bearer token。客户端还应携带 MCP 协议要求的 `Accept` 和协议版本请求头；缺少必要请求头或认证失败时，服务端会返回结构化错误。

## 能力范围{#capabilities}

MCP 能力按领域组织：

| 领域 | 能力 |
| --- | --- |
| 系统和项目 | 读取 SuccApp 系统信息，列出服务器项目。 |
| 元数据文件 | 列出、搜索、读取元数据文件；在权限允许时保存、移动、删除文件。 |
| 设置 | 读取和更新系统、项目或应用相关设置。 |
| 数据库 | 列出数据源只读摘要、schema、表摘要，执行只读查询；在权限允许并确认风险后执行受控 SQL。 |

MCP 返回结构化结果，适合 AI 客户端继续分析和生成后续调用。`tools/list` 固定返回当前版本支持的全部工具，不按当前账号权限裁剪；具体权限、资源是否可访问、危险操作是否已确认，都在 `tools/call` 时返回结构化错误。

当前工具清单包括：

| 工具 | 用途 |
| :--- | :--- |
| `succapp_system_info` | 读取服务器版本、时间和元数据内容版本。 |
| `succapp_project_list` | 列出当前账号可读取的元数据项目。 |
| `succapp_settings_get` | 读取系统、项目或应用设置。 |
| `succapp_settings_set` | 更新系统、项目或应用设置。 |
| `succapp_file_list` | 列出目录下的元数据文件。 |
| `succapp_file_search` | 按路径、名称和文件类型搜索元数据文件。 |
| `succapp_file_read` | 读取文件摘要，并可按需返回文本内容。 |
| `succapp_file_save` | 保存文件或目录；传 `createIfMissing` 可创建不存在的目标。 |
| `succapp_file_delete` | 删除文件或目录。 |
| `succapp_file_move` | 移动或重命名文件。 |
| `succapp_db_list_datasources` | 列出可见数据源的只读摘要和数据库版本信息。 |
| `succapp_db_list_schemas` | 列出数据源下可见的 schema 或 catalog。 |
| `succapp_db_list_tables` | 列出表和视图摘要。 |
| `succapp_db_execute_query` | 执行只读 SQL 查询。 |
| `succapp_db_execute_any` | 执行 SQL 语句；危险 SQL 需要显式确认。 |

## 适合使用 MCP 的场景{#scenarios}

1. AI 需要快速了解服务器版本、项目列表和元数据文件。
2. AI 需要搜索或读取服务器上的元数据，但暂时不需要克隆到本地工作区。
3. AI 需要查看数据源方言信息、表摘要或执行限制行数的只读查询。
4. 团队希望把 SuccApp 服务器能力接入已有 AI 客户端，而不是让 AI 只依赖终端命令。

## 文件读取和写入{#files}

`succapp_file_read` 合并了文件信息和文件内容读取。默认只返回 `path`、`revision`、`modifyTime`、`mimeType`、`byteLength` 和轻量 `fileInfo`，不会把正文放入上下文。需要正文时，调用方传入：

```json
{
  "path": "/demo/data/USERS.tbl",
  "includeContent": true,
  "maxContentBytes": 65536
}
```

返回结果中的 `contentReturned` 表示本次响应是否包含正文。未请求正文、二进制文件或无法返回正文时，工具会通过 `contentOmittedReason` 说明原因；文本内容超过 `maxContentBytes` 时，会返回截断后的正文并设置 `contentTruncated`。这些情况不代表读取失败。文件不存在、无权限等情况仍会作为 tool error 返回。

`succapp_file_save` 是唯一的文件写入口。写入结果只返回 `ok`、`path`、`revision`、`modifyTime`、`created`、`contentChanged`、`metaInfoChanged` 等轻量字段，不再回传完整文件对象。

## 数据库摘要{#database}

`succapp_db_list_datasources` 只返回 AI 生成 SQL 所需的只读摘要，例如数据源名称、连接器类型、数据库产品版本、只读标记等。它不会返回连接串、主机、用户名、密码或 JDBC 参数，也不会把列表调用变成隐式连接测试。

需要了解表时，先使用 `succapp_db_list_tables` 获取 `schema`、`tableName`、`tableType`、`comment` 等摘要。需要字段细节时，可在权限允许的前提下使用 `succapp_db_execute_query` 执行受限查询。

## 与 CLI 和 VS Code 的区别{#difference}

MCP 直接访问 SuccApp 服务器，强调 AI 客户端和服务器能力之间的连接。SuccApp CLI 强调终端、脚本化和本地工作区自动化；SuccApp for VS Code 强调人工浏览、编辑、diff、Changes 和文件历史。

需要可审计修改时，不建议只依赖 MCP 直接改服务器文件。更稳妥的流程是：在工作区中修改本地文件，通过 CLI 或 VS Code 检查差异，推送测试环境验证，再按团队流程提交 Git 和发布生产。

## 权限和安全边界{#safety}

MCP 调用受当前账号权限限制。涉及写服务器文件、更新设置、执行 SQL、删除资源或覆盖已有内容时，应先说明服务器地址、目标对象、影响范围和回退方式，并等待人工确认。

生产环境上默认只使用只读能力。涉及生产写入、强制覆盖、删除或危险 SQL 时，按[安全边界](./safety.md)执行。