Semantic D1 MCP

🚀 语义D1 MCP

语义D1 MCP是一个用于Cloudflare D1数据库内省的模型上下文协议（MCP）服务器，它展示了语义锚定、可观察属性以及用于AI辅助数据库开发的领域驱动设计，是语义意图作为单一事实来源模式的参考实现。

📚 目录

• 项目独特之处
• 快速开始
• MCP工具
• 架构
• 测试
• 贡献代码
• 安全
• 许可证

🎯 项目独特之处

这不仅仅是另一个数据库内省工具，它是经过验证的语义意图模式的参考实现：

• ✅ 语义锚定：基于含义（表用途、关系）而非技术指标（行数、大小）进行模式分析。
• ✅ 可观察属性：决策基于直接可观察的模式标记（外键、索引、约束）。
• ✅ 意图保留：在所有转换过程（开发 → 暂存 → 生产）中保持数据库语义。
• ✅ 领域边界：明确的语义所有权（模式领域 ≠ 查询优化领域 ≠ MCP协议领域）。

该实现基于语义意图作为单一事实来源的研究，展示了如何构建可维护、对AI友好且能保留意图的数据库工具。

🚀 快速开始

前提条件

• Node.js 20.x 或更高版本
• 拥有D1数据库的Cloudflare账户
• 具有D1访问权限的Cloudflare API令牌

安装

1. 克隆仓库

git clone https://github.com/semanticintent/semantic-d1-mcp.git
cd semantic-d1-mcp

2. 安装依赖

npm install

3. 配置环境 复制示例配置文件：

cp .env.example .env

使用你的Cloudflare凭证更新 .env 文件：

# Cloudflare配置
CLOUDFLARE_ACCOUNT_ID=your_cloudflare_account_id
CLOUDFLARE_API_TOKEN=your_cloudflare_api_token

# D1数据库配置 - 开发环境
D1_DEV_DATABASE_ID=your_dev_database_id
D1_DEV_DATABASE_NAME=your_dev_database_name

# D1数据库配置 - 暂存环境（可选）
D1_STAGING_DATABASE_ID=your_staging_database_id
D1_STAGING_DATABASE_NAME=your_staging_database_name

# D1数据库配置 - 生产环境（可选）
D1_PROD_DATABASE_ID=your_prod_database_id
D1_PROD_DATABASE_NAME=your_prod_database_name

注意：至少需要配置一个数据库环境。

4. 构建服务器

npm run build

5. 启动MCP服务器

npm start

或者使用提供的shell脚本：

./start-d1-mcp.sh

获取Cloudflare API令牌

1. 访问 Cloudflare 仪表盘
2. 导航到 我的资料 → API令牌
3. 点击 创建令牌
4. 使用 编辑Cloudflare Workers 模板
5. 添加 D1 权限：D1:Read
6. 将令牌复制到你的 .env 文件中

获取D1数据库ID

# 列出所有D1数据库
wrangler d1 list

# 获取特定数据库信息
wrangler d1 info <database-name>

将数据库ID复制到你的 .env 文件中。

🛠️ MCP工具

该服务器为D1数据库内省提供了4个全面的MCP工具：

1. analyze_database_schema

分析完整的数据库模式结构，包含元数据和可选的示例数据。 参数：

• environment（必需）："development" | "staging" | "production"
• includeSamples（可选，默认值：true）：包含表中的示例数据
• maxSampleRows（可选，默认值：5）：每个表示例的最大行数

返回值：

• 完整的模式分析
• 包含列、类型、约束的表结构
• 索引和外键
• 每个表的示例数据（如果启用）
• 模式元数据和统计信息

示例：

{
  "name": "analyze_database_schema",
  "arguments": {
    "environment": "development",
    "includeSamples": true,
    "maxSampleRows": 5
  }
}

2. get_table_relationships

提取并分析表之间的外键关系。 参数：

• environment（必需）：数据库环境
• tableName（可选）：过滤特定表的关系

返回值：

• 具有基数（一对多、多对一）的外键关系
• 引用完整性规则（CASCADE、SET NULL等）
• 关系元数据和统计信息

示例：

{
  "name": "get_table_relationships",
  "arguments": {
    "environment": "production",
    "tableName": "users"
  }
}

3. validate_database_schema

验证数据库模式是否存在常见问题和反模式。 参数：

• environment（必需）：数据库环境

返回值：

• 模式验证结果
• 缺失的主键
• 没有索引的外键
• 命名约定违规
• 没有关系的表

示例：

{
  "name": "validate_database_schema",
  "arguments": {
    "environment": "production"
  }
}

4. suggest_database_optimizations

根据结构分析生成模式优化建议。 参数：

• environment（必需）：数据库环境

返回值：

• 优先优化建议（高/中/低）
• 缺失索引建议
• 主键建议
• 模式改进机会
• 性能优化提示

示例：

{
  "name": "suggest_database_optimizations",
  "arguments": {
    "environment": "production"
  }
}

🔌 连接到Claude桌面版

将此MCP服务器连接到Claude桌面版，以实现AI辅助的数据库开发。

配置

1. 编辑Claude桌面版配置 - 转到设置 → 开发者 → 编辑配置
2. 添加MCP服务器配置：

{
  "mcpServers": {
    "semantic-d1": {
      "command": "node",
      "args": [
        "/absolute/path/to/semantic-d1-mcp/dist/index.js"
      ],
      "env": {
        "CLOUDFLARE_ACCOUNT_ID": "your_account_id",
        "CLOUDFLARE_API_TOKEN": "your_api_token",
        "D1_DEV_DATABASE_ID": "your_dev_db_id",
        "D1_DEV_DATABASE_NAME": "your_dev_db_name",
        "D1_STAGING_DATABASE_ID": "your_staging_db_id",
        "D1_STAGING_DATABASE_NAME": "your_staging_db_name",
        "D1_PROD_DATABASE_ID": "your_prod_db_id",
        "D1_PROD_DATABASE_NAME": "your_prod_db_name"
      }
    }
  }
}

3. 重启Claude桌面版
4. 验证工具是否可用 - 你应该在Claude的工具列表中看到4个D1工具

使用示例

在Claude桌面版中：

"分析我的生产数据库模式，并为具有外键的表建议优化方案"

Claude将自动使用 analyze_database_schema 和 suggest_database_optimizations 工具。

🏗️ 架构

该项目展示了领域驱动的六边形架构，实现了关注点的清晰分离：

┌─────────────────────────────────────────────────────────┐
│                   表示层                                 │
│              (MCP服务器 - 协议处理)                      │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                  应用层                                 │
│        (用例 - 模式分析编排)                            │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                    领域层                               │
│     (模式实体、关系逻辑、服务)                         │
│              纯粹的业务逻辑                             │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                基础设施层                               │
│       (Cloudflare D1 REST API、HTTP客户端)             │
│           技术适配器                                   │
└─────────────────────────────────────────────────────────┘

实现状态

状态：✅ 六边形架构重构完成

当前结构：

src/
├── domain/              # 业务逻辑 (实体、服务)
│   ├── entities/        # 数据库模式、表信息、列等
│   ├── services/        # 模式分析器、关系分析器等
│   ├── repositories/    # 端口接口
│   └── value-objects/   # 环境枚举
├── application/         # 用例和编排
│   ├── use-cases/       # 分析模式、获取关系等
│   └── ports/           # 缓存提供程序接口
├── infrastructure/      # 外部适配器
│   ├── adapters/        # CloudflareD1存储库、缓存
│   ├── config/          # Cloudflare配置、数据库配置
│   └── http/            # Cloudflare API客户端
├── presentation/        # MCP协议层
│   └── mcp/             # D1数据库MCP服务器
└── index.ts             # 组合根 (依赖注入)

详细的设计文档请参阅 ARCHITECTURE.md。

各层职责

领域层：

• 数据库模式实体（模式、表、关系、索引）
• 模式分析业务逻辑
• 关系提取逻辑
• 优化建议规则

应用层：

• 编排领域服务
• 执行用例（分析模式、获取关系等）
• 协调基础设施适配器

基础设施层：

• Cloudflare D1 REST API集成
• 用于API调用的HTTP客户端
• 缓存提供程序（内存中）

表示层：

• MCP服务器初始化
• 工具注册和路由
• 请求/响应格式化

语义意图原则

此代码库遵循严格的语义锚定规则：

1. 语义优先于结构

// ✅ 语义：基于可观察的模式属性
const needsIndex = table.hasForeignKey() && !table.hasIndexOnForeignKey()

// ❌ 结构：基于技术指标
const needsIndex = table.rowCount > 10000 && table.queryCount > 100

2. 意图保留

// ✅ 在转换过程中保留环境语义
const schema = await fetchSchema(Environment.PRODUCTION)
// 模式分析保留 "生产" 意图 - 无覆盖

3. 可观察锚定

// ✅ 基于直接可观察的属性
const relationships = extractForeignKeys(sqliteMaster)

// ❌ 基于推断的行为
const relationships = inferFromQueryPatterns(logs)

完整的治理规则请参阅 SEMANTIC_ANCHORING_GOVERNANCE.md。

🧪 测试

状态：✅ 全面的测试套件，398个测试全部通过

测试覆盖率

• ✅ 领域层：212个测试（实体、服务、验证）
• ✅ 基础设施层：64个测试（D1适配器、API客户端、配置）
• ✅ 应用层：35个测试（用例、编排）
• ✅ 表示层：13个测试（MCP服务器、工具路由）
• ✅ 集成测试：15个测试（端到端流程）
• ✅ 值对象：59个测试（环境、不可变性）

总计：398个测试（全部通过 ✅）

运行测试

# 运行所有测试
npm test

# 监视模式
npm run test:watch

# 带UI
npm run test:ui

# 覆盖率报告
npm run test:coverage

测试框架

• Vitest：快速单元测试框架
• @vitest/coverage-v8：代码覆盖率报告
• 模拟策略：通过接口实现模拟Cloudflare D1 API响应

📖 从本实现中学习

此代码库是数据库工具中语义意图模式的参考实现。

值得研究的关键文件

六边形架构实现：

• src/index.ts - 带有依赖注入的组合根
• src/domain/entities/ - 具有语义验证的领域实体
• src/domain/services/ - 纯粹的业务逻辑服务
• src/application/use-cases/ - 编排层
• src/infrastructure/adapters/ - 外部适配器
• src/presentation/mcp/ - MCP协议层

参考文档：

• D1_MCP_REFACTORING_PLAN.md - 完整的重构计划
• SEMANTIC_ANCHORING_GOVERNANCE.md - 治理规则
• ARCHITECTURE.md - 架构细节

相关项目

• semantic-context-mcp - 用于上下文管理的兄弟参考实现

🤝 贡献代码

我们欢迎贡献！这是一个参考实现，因此贡献应遵循语义意图原则。

如何贡献

1. 阅读指南：CONTRIBUTING.md
2. 查看重构计划：D1_MCP_REFACTORING_PLAN.md
3. 遵循架构：保持层边界和语义锚定
4. 添加测试：所有更改都需要全面的测试覆盖
5. 记录意图：解释原因，而不仅仅是做了什么

贡献标准

• ✅ 遵循语义意图模式
• ✅ 保持六边形架构（重构后）
• ✅ 添加全面的测试（目标覆盖率90%以上）
• ✅ 包含语义文档
• ✅ 通过所有CI检查

快速链接：

• 贡献指南 - 详细指南
• 行为准则 - 社区标准
• 架构指南 - 设计原则
• 安全策略 - 报告漏洞

社区

• 💬 讨论 - 提问
• 🐛 问题 - 报告错误
• 🔒 安全 - 私下报告漏洞

🔒 安全

安全是重中之重。请查看我们的 安全策略，了解：

• API令牌管理最佳实践
• 应提交/应排除的内容
• 报告安全漏洞
• 部署的安全检查清单

发现漏洞？ 发送电子邮件至：security@semanticintent.dev

🔬 研究基础

此实现基于研究论文 "Semantic Intent as Single Source of Truth: Immutable Governance for AI-Assisted Development"。

应用的核心原则

1. 语义优先于结构 - 基于含义而非指标进行模式分析
2. 意图保留 - 在转换过程中保持环境语义
3. 可观察锚定 - 基于直接可观察的模式属性进行决策
4. 不可变治理 - 在运行时保护语义完整性

相关资源

• 研究论文（即将推出）
• 语义锚定治理
• semanticintent.dev（即将推出）

📊 项目路线图

✅ 阶段0：初始实现（已完成）

• 具有6个工具的单体MCP服务器
• D1 REST API集成
• 基本的模式分析

✅ 阶段1：领域层（已完成）

• 10个具有语义验证的领域实体
• 3个领域服务（模式分析器、关系分析器、优化服务）
• 212个通过的测试

✅ 阶段2：基础设施层（已完成）

• CloudflareD1Repository适配器
• CloudflareAPIClient HTTP客户端
• 内存缓存提供程序
• 64个通过的测试

✅ 阶段3：应用层（已完成）

• 4个用例（分析模式、获取关系、验证模式、建议优化）
• 端口接口（ICloudflareD1Repository、ICacheProvider）
• 35个通过的测试

✅ 阶段4：表示层（已完成）

• 具有4个MCP工具的D1DatabaseMCPServer
• 请求/响应DTO
• 13个通过的测试

✅ 阶段5：集成与组合根（已完成）

• index.ts中的依赖注入
• 环境配置
• 15个集成测试

✅ 阶段6：CI/CD与文档（已完成）

• TypeScript构建验证
• 更新README
• 总计398个测试通过

🎯 阶段7：生产就绪（计划中）

• GitHub Actions CI/CD工作流
• Dependabot自动化
• 安全扫描
• GitHub仓库设置

详细的路线图请参阅 D1_MCP_REFACTORING_PLAN.md。

📄 许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• 基于Anthropic的 模型上下文协议 构建
• 受 六边形架构（Alistair Cockburn）启发
• 基于 领域驱动设计 原则（Eric Evans）
• 是 语义意图 研究计划的一部分

本项目是一个参考实现，展示了用于数据库内省的语义意图模式。你可以研究代码、学习模式并将其应用到自己的项目中。🏗️