MCP/database

Fork 0

zpc bd1e1201f1 12

2025-12-27 16:21:09 +08:00

9.4 KiB

Raw Permalink Blame History

v1.0.2 版本开发计划总览

版本目标

主要功能: 添加 SQL Server 数据库支持，使服务器能够同时管理 PostgreSQL 和 SQL Server 数据库。

版本号: 1.0.2 预计开发周期: 8-10 周 优先级: P0 (高优先级)

一、核心需求

1.1 功能需求

多数据库类型支持
- 支持同时配置 PostgreSQL 和 SQL Server 环境
- 每个环境可独立配置数据库类型
- 保持现有 PostgreSQL 功能完全兼容
SQL Server 核心功能
- 连接池管理
- 基本查询操作 (SELECT, INSERT, UPDATE, DELETE)
- 事务支持 (BEGIN, COMMIT, ROLLBACK)
- 元数据浏览 (表、视图、存储过程、索引等)
- 批量操作
- 分页查询
统一的 MCP 工具接口
- 现有的 30+ MCP 工具对两种数据库都适用
- 工具自动根据环境类型选择对应的数据库驱动
- 错误提示能明确区分数据库类型

1.2 非功能需求

向后兼容性
- 现有 PostgreSQL 配置和功能不受影响
- API 接口保持兼容
- 配置文件可平滑迁移
性能要求
- SQL Server 操作性能不低于 PostgreSQL
- 连接池效率与现有水平相当
- 查询执行延迟增加不超过 5%
代码质量
- 代码覆盖率 > 80%
- 关键路径必须有集成测试
- 遵循现有代码规范

二、架构变更概览

2.1 核心变更

引入数据库驱动抽象层

新增: src/drivers/
├── database-driver.ts      # 驱动接口定义
├── driver-factory.ts       # 驱动工厂
├── postgres/
│   └── postgres-driver.ts  # PostgreSQL 驱动实现
└── sqlserver/
    └── sqlserver-driver.ts # SQL Server 驱动实现

重构核心层使用驱动
- ConnectionManager: 接收并使用驱动实例
- QueryRunner: 通过驱动执行 SQL
- MetadataBrowser: 使用驱动提供的元数据查询
- BulkHelpers: 使用驱动的批量操作语法
- TransactionManager: 基本不变 (SQL 标准通用)

配置类型扩展

interface EnvironmentConfig {
  type: 'postgres' | 'sqlserver';  // 扩展类型
  connection: {
    // PostgreSQL 和 SQL Server 通用字段
    host: string;
    port: number;
    database: string;
    user: string;
    password: string;
    // SQL Server 特有字段
    domain?: string;          // Windows 域认证
    instanceName?: string;    // 命名实例
    encrypt?: boolean;        // 加密连接
    trustServerCertificate?: boolean;
  };
  // 其他字段保持兼容
}

2.2 依赖库新增

{
  "dependencies": {
    "mssql": "^10.0.0"  // SQL Server 官方驱动
  },
  "devDependencies": {
    "@types/mssql": "^9.1.0"
  }
}

三、开发阶段规划

阶段一：基础架构重构 (2-3 周)

目标: 建立驱动抽象层，重构现有代码

任务列表:

设计并实现 DatabaseDriver 接口
提取 PostgreSQL 驱动实现
重构 ConnectionManager 使用驱动
重构 QueryRunner 使用驱动
重构 MetadataBrowser 使用驱动
重构 BulkHelpers 使用驱动
更新单元测试确保 PostgreSQL 功能不受影响
验证向后兼容性

交付物:

驱动接口定义完成
PostgreSQL 驱动实现完成
核心层重构完成
所有现有测试通过
重构后的架构文档

阶段二：SQL Server 基础支持 (2-3 周)

目标: 实现 SQL Server 驱动核心功能

任务列表:

实现 SqlServerDriver 连接管理
实现基本查询执行
实现事务管理
实现基础元数据查询 (listSchemas, listTables, describeTable)
实现分页查询
添加配置加载和验证
编写 SQL Server 集成测试

交付物:

SQL Server 驱动基础实现
连接池正常工作
基本 CRUD 操作可用
事务支持完成
集成测试通过

阶段三：完整功能实现 (2-3 周)

目标: 完成所有 SQL Server 功能

任务列表:

实现完整元数据浏览 (视图、索引、存储过程、触发器等)
实现批量插入操作
实现 UPSERT 操作 (使用 MERGE 语句)
实现诊断功能 (活跃连接、锁信息等)
实现查询分析功能
适配所有 MCP 工具支持 SQL Server
完善错误处理和日志记录

交付物:

30+ MCP 工具全部支持 SQL Server
元数据浏览功能完整
批量操作性能良好
诊断功能可用
端到端测试通过

阶段四：测试、优化和文档 (1-2 周)

目标: 全面测试、性能优化、文档更新

任务列表:

编写完整的单元测试
编写集成测试 (PostgreSQL + SQL Server 混合环境)
性能基准测试和优化
边界条件和异常处理测试
更新 CLAUDE.md 文档
更新 README.md
编写 SQL Server 配置指南
编写迁移指南
更新 changelog.json

交付物:

测试覆盖率 > 80%
性能测试报告
完整的用户文档
迁移指南
版本发布说明

四、技术难点和风险

4.1 技术难点

难点	描述	解决方案
SQL 语法差异	PostgreSQL 和 SQL Server SQL 语法有显著差异	通过驱动层抽象，每个驱动生成特定 SQL
参数占位符	PostgreSQL `$1` vs SQL Server `@p1`	驱动层处理参数化，返回完整 SQL
Schema 概念	PostgreSQL search_path vs SQL Server 默认 dbo	SQL Server 使用完整限定名 `schema.table`
UPSERT 语法	ON CONFLICT vs MERGE	驱动提供不同实现
元数据查询	系统表完全不同	每个驱动实现独立的元数据查询
类型映射	数据类型名称差异	驱动层提供类型映射表

4.2 风险管理

风险	概率	影响	缓解措施
向后兼容破坏	中	高	充分的回归测试；渐进式迁移；保留旧接口
性能下降	低	中	性能基准测试；优化关键路径
SQL Server 功能不完整	中	中	明确功能范围；文档化限制；分阶段实现
测试环境缺失	高	中	Docker 容器化测试；CI/CD 集成
开发周期超期	中	中	任务拆分；优先级管理；定期进度review

五、成功标准

5.1 功能完整性

所有现有 PostgreSQL 功能正常工作
SQL Server 支持以下操作：
- 连接和认证
- 基本查询 (SELECT, INSERT, UPDATE, DELETE)
- 事务管理
- 元数据浏览 (表、视图、索引、存储过程)
- 批量操作
- 分页查询
- 查询分析

5.2 性能指标

PostgreSQL 操作性能不受影响 (±5% 范围内)
SQL Server 连接池利用率 > 80%
SQL Server 查询响应时间 < 100ms (简单查询)
批量插入性能 > 1000 rows/s

5.3 质量指标

代码覆盖率 > 80%
零个 P0/P1 级别 Bug
所有集成测试通过
文档完整且准确

5.4 兼容性

现有配置文件无需修改即可运行
现有客户端无需更改即可连接
API 接口保持兼容

六、后续版本规划

v1.0.3 - 性能优化和高级功能

查询结果缓存
连接池预热
慢查询自动优化建议
查询执行计划可视化

v1.0.4 - MySQL/MariaDB 支持

复用现有驱动架构
添加 MySQL 驱动实现
支持三种主流数据库

v1.1.0 - 企业级功能

RBAC 权限控制
多租户支持
审计日志增强
Prometheus 监控集成

七、资源需求

7.1 人力资源

后端开发工程师: 1-2 人
测试工程师: 0.5 人
技术文档: 0.5 人

7.2 环境资源

PostgreSQL 测试数据库 (已有)
SQL Server 测试数据库 (需新建)
CI/CD 环境 (需配置)

7.3 第三方依赖

mssql npm 包 (MIT License)
SQL Server Docker 镜像 (免费 Express 版本)

八、项目时间线

Week 1-3   : 阶段一 - 基础架构重构
  ├─ Week 1  : 设计驱动接口，提取 PostgreSQL 驱动
  ├─ Week 2  : 重构核心层使用驱动
  └─ Week 3  : 测试和验证向后兼容性

Week 4-6   : 阶段二 - SQL Server 基础支持
  ├─ Week 4  : 实现连接和查询
  ├─ Week 5  : 实现事务和元数据
  └─ Week 6  : 集成测试

Week 7-9   : 阶段三 - 完整功能实现
  ├─ Week 7  : 元数据浏览和批量操作
  ├─ Week 8  : 诊断功能
  └─ Week 9  : MCP 工具适配

Week 10    : 阶段四 - 测试和文档
  ├─ 性能测试和优化
  ├─ 文档编写
  └─ 发布准备

九、关键里程碑

里程碑	日期	交付物
M1: 架构设计完成	Week 1	驱动接口定义、架构文档
M2: PostgreSQL 重构完成	Week 3	重构代码、通过所有测试
M3: SQL Server 基础可用	Week 6	基本 CRUD 和事务支持
M4: 功能完整	Week 9	所有 MCP 工具支持 SQL Server
M5: 版本发布	Week 10	发布 v1.0.2

十、沟通计划

每日站会: 同步进度和阻塞
每周评审: 代码评审和技术讨论
双周演示: 向相关方展示进展
发布前评审: 全面的代码和文档审查

文档维护:

负责人: [待指定]
更新频率: 每周
最后更新: 2024-12-27

9.4 KiB Raw Permalink Blame History Unescape Escape

v1.0.2 版本开发计划总览

版本目标

一、核心需求

1.1 功能需求

1.2 非功能需求

二、架构变更概览

2.1 核心变更

2.2 依赖库新增

三、开发阶段规划

阶段一：基础架构重构 (2-3 周)

阶段二：SQL Server 基础支持 (2-3 周)

阶段三：完整功能实现 (2-3 周)

阶段四：测试、优化和文档 (1-2 周)

四、技术难点和风险

4.1 技术难点

4.2 风险管理

五、成功标准

5.1 功能完整性

5.2 性能指标

5.3 质量指标

5.4 兼容性

六、后续版本规划

v1.0.3 - 性能优化和高级功能

v1.0.4 - MySQL/MariaDB 支持

v1.1.0 - 企业级功能

七、资源需求

7.1 人力资源

7.2 环境资源

7.3 第三方依赖

八、项目时间线

九、关键里程碑

十、沟通计划

9.4 KiB

Raw Permalink Blame History