|
1 |
| -**开务数据库 MCP 服务设计文档 V1.0** |
2 |
| - |
3 |
| - |
4 |
| - |
5 |
| - |
6 |
| -1\. **文档说明** |
7 |
| - |
8 |
| -1.1 **术语与缩写解释** |
9 |
| - |
10 |
| -| 术语 | 说明 | |
11 |
| -|-------------|----------------------------------------------------------------------| |
12 |
| -| KWDB | 开务数据库(KaiwuDB)的开源版名称 | |
13 |
| -| SSE | Server-Sent Events,服务器推送事件协议 | |
14 |
| -| MCP | Model Context Protocol,模型上下文协议,用于LLM Agent与外部资源通信 | |
15 |
| -| Prompt | 提示词,用于指导AI模型生成特定类型的回应 | |
16 |
| -| LLM | Large Language Model,大型语言模型 | |
17 |
| -| Agent | 智能代理,能够根据用户输入执行任务的自动化系统 | |
18 |
| -| Tool | MCP协议提供的工具,Agent可调用的函数或服务 | |
19 |
| -| Resource | MCP协议提供的资源,Agent可查询或订阅的数据 | |
20 |
| - |
21 |
| - |
22 |
| -2\. **设计概述** |
23 |
| - |
24 |
| -2.1 **架构设计** |
25 |
| - |
26 |
| -```mermaid |
27 |
| -flowchart TD |
28 |
| - A[MCP协议层] --> B[工具调度器] |
29 |
| - A --> C[资源管理器] |
30 |
| - B --> D{查询类型判断} |
31 |
| - D -->|读操作| E[查询执行引擎] |
32 |
| - D -->|写操作| F[事务处理引擎] |
33 |
| - E --> G[结果格式化] |
34 |
| - F --> G |
35 |
| - G --> H[响应生成] |
36 |
| - C --> I[数据库元数据] |
37 |
| - C --> J[表结构信息] |
38 |
| - H --> A |
39 |
| - I --> E |
40 |
| - J --> E |
41 |
| -``` |
42 |
| - |
43 |
| -2.2 **核心流程** |
44 |
| -- 协议解析:处理MCP标准输入或HTTP SSE请求 |
45 |
| -- 工具路由:根据工具类型(read/write)分发处理 |
46 |
| -- 查询预处理:自动添加LIMIT、语法检查 |
47 |
| -- 连接池管理:维护数据库连接的生命周期 |
48 |
| -- 结果封装:统一JSON响应格式 |
49 |
| - |
50 |
| -3\. **功能设计** |
51 |
| - |
52 |
| -3.1 **外部接口** |
53 |
| - |
54 |
| -3.1.1 **MCP Tools 接口** |
55 |
| -```mermaid |
56 |
| -flowchart LR |
57 |
| - Tool[LLM Agent] -- JSON-RPC --> MCP_Server |
58 |
| - subgraph MCP_Server |
59 |
| - direction TB |
60 |
| - Tool_Dispatcher --> Read_Query |
61 |
| - Tool_Dispatcher --> Write_Query |
62 |
| - Read_Query --> DB_Conn[连接池] |
63 |
| - Write_Query --> DB_Conn |
64 |
| - end |
65 |
| -``` |
66 |
| - |
67 |
| -3.1.2 **接口定义** |
68 |
| -1. 读查询工具: |
69 |
| -```json |
70 |
| -{ |
71 |
| - "name": "read-query", |
72 |
| - "input": { |
73 |
| - "sql": "SELECT * FROM table LIMIT 10" |
74 |
| - } |
75 |
| -} |
76 |
| -``` |
77 |
| - |
78 |
| -2. 写查询工具: |
79 |
| -```json |
80 |
| -{ |
81 |
| - "name": "write-query", |
82 |
| - "input": { |
83 |
| - "sql": "INSERT INTO table VALUES(...)" |
84 |
| - } |
85 |
| -} |
86 |
| -``` |
87 |
| - |
88 |
| -3.2 **MCP Resources** |
89 |
| -| 资源类型 | URI格式 | 示例 | |
90 |
| -|-------------------------|----------------------------------|-------------------------------| |
91 |
| -| 数据库产品信息 | kwdb://product_info | kwdb://product_info/ | |
92 |
| -| 数据库元信息 | kwdb://db_info/{database_name} | kwdb://db_info/db_shig | |
93 |
| -| 表结构信息 | kwdb://table/{table_name} | kwdb://table/user_profile | |
94 |
| - |
95 |
| -3.3 **Prompt管理架构** |
96 |
| -```mermaid |
97 |
| -flowchart TD |
98 |
| - A[Prompt Markdown文件] --> B[编译时嵌入] |
99 |
| - B --> C[运行时缓存] |
100 |
| - C --> D[LLM交互接口] |
101 |
| - D --> E[动态内容更新] |
102 |
| - B -->|版本控制| F[Git仓库] |
103 |
| - |
104 |
| - subgraph 核心组件 |
105 |
| - C --> G[Prompt缓存管理器] |
106 |
| - G --> H[查询处理器] |
107 |
| - end |
108 |
| -``` |
109 |
| - |
110 |
| -3.4 **Prompt分类规范** |
111 |
| -| 类别 | 用途说明 | 示例提示词 | |
112 |
| -|-------------------|----------------------------------|------------------------------| |
113 |
| -| 数据库描述 | 数据库功能特性说明 | db_description | |
114 |
| -| 语法指南 | SQL语法参考手册 | syntax_guide | |
115 |
| -| 集群管理 | 节点配置与监控指南 | cluster_management | |
116 |
| -| 数据迁移 | 数据导入导出规范 | data_migration | |
117 |
| -| 性能调优 | 查询优化策略 | performance_tuning | |
118 |
| -| 故障排查 | 常见错误解决方案 | troubleshooting | |
119 |
| -| 安装部署 | 环境配置指南 | installation | |
120 |
| -| DBA模板 | 管理提示词模板 | dba_template | |
121 |
| - |
122 |
| - |
123 |
| - |
124 |
| -4\. **非功能性设计** |
125 |
| - |
126 |
| -4.1 **性能设计** |
127 |
| -- 连接池复用机制 |
128 |
| -- 查询超时控制(默认30s) |
129 |
| -- 自动LIMIT 20保护 |
130 |
| -- 批量查询结果分页 |
131 |
| - |
132 |
| -4.2 **安全设计** |
133 |
| -```mermaid |
134 |
| -flowchart TD |
135 |
| - A[输入SQL] --> B{语法解析} |
136 |
| - B -->|SELECT| C[允许执行] |
137 |
| - B -->|SHOW| C |
138 |
| - B -->|EXPLAIN| C |
139 |
| - B -->|INSERT/UPDATE/DELETE| D[写操作验证] |
140 |
| - D --> E[事务日志记录] |
141 |
| - B -->|其他| F[拒绝执行] |
142 |
| -``` |
143 |
| - |
144 |
| -4.3 **错误处理规范** |
145 |
| -| 错误代码 | 触发场景 | 处理策略 | |
146 |
| -|----------------|---------------------------|------------------------------| |
147 |
| -| KWDB-4001 | 语法错误 | 返回具体错误位置 | |
148 |
| -| KWDB-4002 | 权限不足 | 中断执行并告警 | |
149 |
| -| KWDB-4003 | 连接超时 | 重试机制(最多3次) | |
150 |
| -| KWDB-4004 | 资源不存在 | 返回404状态码 | |
151 |
| - |
152 |
| -5\. **部署架构** |
153 |
| - |
154 |
| -```mermaid |
155 |
| -flowchart LR |
156 |
| - Client[LLM Agent] -->|HTTP SSE| Server1[MCP Server] |
157 |
| - Client -->|StdIO| Server2[MCP Server] |
158 |
| - Server1 --> KWDB[KaiwuDB Cluster] |
159 |
| - Server2 --> KWDB |
160 |
| -``` |
| 1 | +**开务数据库 MCP 服务设计文档 V1.0** |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | + |
| 6 | +1\. **文档说明** |
| 7 | + |
| 8 | +1.1 **术语与缩写解释** |
| 9 | + |
| 10 | +| 术语 | 说明 | |
| 11 | +|-------------|----------------------------------------------------------------------| |
| 12 | +| KWDB | 开务数据库(KaiwuDB)的开源版名称 | |
| 13 | +| SSE | Server-Sent Events,服务器推送事件协议 | |
| 14 | +| MCP | Model Context Protocol,模型上下文协议,用于LLM Agent与外部资源通信 | |
| 15 | +| Prompt | 提示词,用于指导AI模型生成特定类型的回应 | |
| 16 | +| LLM | Large Language Model,大型语言模型 | |
| 17 | +| Agent | 智能代理,能够根据用户输入执行任务的自动化系统 | |
| 18 | +| Tool | MCP协议提供的工具,Agent可调用的函数或服务 | |
| 19 | +| Resource | MCP协议提供的资源,Agent可查询或订阅的数据 | |
| 20 | + |
| 21 | + |
| 22 | +2\. **设计概述** |
| 23 | + |
| 24 | +2.1 **架构设计** |
| 25 | + |
| 26 | +```mermaid |
| 27 | +flowchart TD |
| 28 | + A[MCP协议层] --> B[工具调度器] |
| 29 | + A --> C[资源管理器] |
| 30 | + B --> D{查询类型判断} |
| 31 | + D -->|读操作| E[查询执行引擎] |
| 32 | + D -->|写操作| F[事务处理引擎] |
| 33 | + E --> G[结果格式化] |
| 34 | + F --> G |
| 35 | + G --> H[响应生成] |
| 36 | + C --> I[数据库元数据] |
| 37 | + C --> J[表结构信息] |
| 38 | + H --> A |
| 39 | + I --> E |
| 40 | + J --> E |
| 41 | +``` |
| 42 | + |
| 43 | +2.2 **核心流程** |
| 44 | +- 协议解析:处理MCP标准输入或HTTP SSE请求 |
| 45 | +- 工具路由:根据工具类型(read/write)分发处理 |
| 46 | +- 查询预处理:自动添加LIMIT、语法检查 |
| 47 | +- 连接池管理:维护数据库连接的生命周期 |
| 48 | +- 结果封装:统一JSON响应格式 |
| 49 | + |
| 50 | +3\. **功能设计** |
| 51 | + |
| 52 | +3.1 **外部接口** |
| 53 | + |
| 54 | +3.1.1 **MCP Tools 接口** |
| 55 | +```mermaid |
| 56 | +flowchart LR |
| 57 | + Tool[LLM Agent] -- JSON-RPC --> MCP_Server |
| 58 | + subgraph MCP_Server |
| 59 | + direction TB |
| 60 | + Tool_Dispatcher --> Read_Query |
| 61 | + Tool_Dispatcher --> Write_Query |
| 62 | + Read_Query --> DB_Conn[连接池] |
| 63 | + Write_Query --> DB_Conn |
| 64 | + end |
| 65 | +``` |
| 66 | + |
| 67 | +3.1.2 **接口定义** |
| 68 | +1. 读查询工具: |
| 69 | +```json |
| 70 | +{ |
| 71 | + "name": "read-query", |
| 72 | + "input": { |
| 73 | + "sql": "SELECT * FROM table LIMIT 10" |
| 74 | + } |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +2. 写查询工具: |
| 79 | +```json |
| 80 | +{ |
| 81 | + "name": "write-query", |
| 82 | + "input": { |
| 83 | + "sql": "INSERT INTO table VALUES(...)" |
| 84 | + } |
| 85 | +} |
| 86 | +``` |
| 87 | + |
| 88 | +3.2 **MCP Resources** |
| 89 | +| 资源类型 | URI格式 | 示例 | |
| 90 | +|-------------------------|----------------------------------|-------------------------------| |
| 91 | +| 数据库产品信息 | kwdb://product_info | kwdb://product_info/ | |
| 92 | +| 数据库元信息 | kwdb://db_info/{database_name} | kwdb://db_info/db_shig | |
| 93 | +| 表结构信息 | kwdb://table/{table_name} | kwdb://table/user_profile | |
| 94 | + |
| 95 | +3.3 **Prompt管理架构** |
| 96 | +```mermaid |
| 97 | +flowchart TD |
| 98 | + A[Prompt Markdown文件] --> B[编译时嵌入] |
| 99 | + B --> C[运行时缓存] |
| 100 | + C --> D[LLM交互接口] |
| 101 | + D --> E[动态内容更新] |
| 102 | + B -->|版本控制| F[Git仓库] |
| 103 | + |
| 104 | + subgraph 核心组件 |
| 105 | + C --> G[Prompt缓存管理器] |
| 106 | + G --> H[查询处理器] |
| 107 | + end |
| 108 | +``` |
| 109 | + |
| 110 | +3.4 **Prompt分类规范** |
| 111 | +| 类别 | 用途说明 | 示例提示词 | |
| 112 | +|-------------------|----------------------------------|------------------------------| |
| 113 | +| 数据库描述 | 数据库功能特性说明 | db_description | |
| 114 | +| 语法指南 | SQL语法参考手册 | syntax_guide | |
| 115 | +| 集群管理 | 节点配置与监控指南 | cluster_management | |
| 116 | +| 数据迁移 | 数据导入导出规范 | data_migration | |
| 117 | +| 性能调优 | 查询优化策略 | performance_tuning | |
| 118 | +| 故障排查 | 常见错误解决方案 | troubleshooting | |
| 119 | +| 安装部署 | 环境配置指南 | installation | |
| 120 | +| DBA模板 | 管理提示词模板 | dba_template | |
| 121 | + |
| 122 | + |
| 123 | + |
| 124 | +4\. **非功能性设计** |
| 125 | + |
| 126 | +4.1 **性能设计** |
| 127 | +- 连接池复用机制 |
| 128 | +- 查询超时控制(默认30s) |
| 129 | +- 自动LIMIT 20保护 |
| 130 | +- 批量查询结果分页 |
| 131 | + |
| 132 | +4.2 **安全设计** |
| 133 | +```mermaid |
| 134 | +flowchart TD |
| 135 | + A[输入SQL] --> B{语法解析} |
| 136 | + B -->|SELECT| C[允许执行] |
| 137 | + B -->|SHOW| C |
| 138 | + B -->|EXPLAIN| C |
| 139 | + B -->|INSERT/UPDATE/DELETE| D[写操作验证] |
| 140 | + D --> E[事务日志记录] |
| 141 | + B -->|其他| F[拒绝执行] |
| 142 | +``` |
| 143 | + |
| 144 | +4.3 **错误处理规范** |
| 145 | +| 错误代码 | 触发场景 | 处理策略 | |
| 146 | +|----------------|---------------------------|------------------------------| |
| 147 | +| KWDB-4001 | 语法错误 | 返回具体错误位置 | |
| 148 | +| KWDB-4002 | 权限不足 | 中断执行并告警 | |
| 149 | +| KWDB-4003 | 连接超时 | 重试机制(最多3次) | |
| 150 | +| KWDB-4004 | 资源不存在 | 返回404状态码 | |
| 151 | + |
| 152 | +5\. **部署架构** |
| 153 | + |
| 154 | +```mermaid |
| 155 | +flowchart LR |
| 156 | + Client[LLM Agent] -->|HTTP SSE| Server1[MCP Server] |
| 157 | + Client -->|StdIO| Server2[MCP Server] |
| 158 | + Server1 --> KWDB[KaiwuDB Cluster] |
| 159 | + Server2 --> KWDB |
| 160 | +``` |
0 commit comments