主题
MCP
SuccApp MCP 是服务端提供给 AI 客户端的工具协议入口。支持 MCP 的 AI 客户端连接 SuccApp 服务器后，可以通过标准的工具发现和工具调用方式读取系统信息、访问元数据和查询数据库。
MCP 适合让 AI 直接理解服务器现状；如果任务需要本地文件修改、Git 管理、diff 评审和发布流程，仍应使用 SuccApp 工作区，并配合 SuccApp CLI 和 SuccApp for VS Code。
接入方式
当前 SuccApp MCP 入口是服务器上的 HTTP JSON-RPC 接口 /api/mcp。客户端应使用 POST 请求提交 JSON-RPC 消息；当前不提供 GET、SSE 或事件流入口。
MCP 调用需要使用当前 SuccApp 服务器支持的认证方式，例如已登录会话或可访问该服务器的 Bearer token。客户端还应携带 MCP 协议要求的 Accept 和协议版本请求头；缺少必要请求头或认证失败时，服务端会返回结构化错误。
能力范围
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 的场景
- AI 需要快速了解服务器版本、项目列表和元数据文件。
- AI 需要搜索或读取服务器上的元数据，但暂时不需要克隆到本地工作区。
- AI 需要查看数据源方言信息、表摘要或执行限制行数的只读查询。
- 团队希望把 SuccApp 服务器能力接入已有 AI 客户端，而不是让 AI 只依赖终端命令。
文件读取和写入
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 等轻量字段，不再回传完整文件对象。
数据库摘要
succapp_db_list_datasources 只返回 AI 生成 SQL 所需的只读摘要，例如数据源名称、连接器类型、数据库产品版本、只读标记等。它不会返回连接串、主机、用户名、密码或 JDBC 参数，也不会把列表调用变成隐式连接测试。
需要了解表时，先使用 succapp_db_list_tables 获取 schema、tableName、tableType、comment 等摘要。需要字段细节时，可在权限允许的前提下使用 succapp_db_execute_query 执行受限查询。
与 CLI 和 VS Code 的区别
MCP 直接访问 SuccApp 服务器，强调 AI 客户端和服务器能力之间的连接。SuccApp CLI 强调终端、脚本化和本地工作区自动化；SuccApp for VS Code 强调人工浏览、编辑、diff、Changes 和文件历史。
需要可审计修改时，不建议只依赖 MCP 直接改服务器文件。更稳妥的流程是：在工作区中修改本地文件，通过 CLI 或 VS Code 检查差异，推送测试环境验证，再按团队流程提交 Git 和发布生产。
权限和安全边界
MCP 调用受当前账号权限限制。涉及写服务器文件、更新设置、执行 SQL、删除资源或覆盖已有内容时，应先说明服务器地址、目标对象、影响范围和回退方式，并等待人工确认。
生产环境上默认只使用只读能力。涉及生产写入、强制覆盖、删除或危险 SQL 时，按安全边界执行。
