金大哥 - semantic-d1-mcp MCP 详情

article

README

🚀 语义D1 MCP

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

📚 目录

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

🎯 项目独特之处

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

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

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

🚀 快速开始

前提条件

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

安装

克隆仓库

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

安装依赖

npm install

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

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

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

构建服务器

npm run build

启动MCP服务器

npm start

或者使用提供的shell脚本：

./start-d1-mcp.sh

获取Cloudflare API令牌

访问 Cloudflare 仪表盘
导航到 我的资料 → API令牌
点击 创建令牌
使用 编辑Cloudflare Workers 模板
添加 D1 权限：D1:Read
将令牌复制到你的 .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辅助的数据库开发。

配置

编辑Claude桌面版配置 - 转到设置 → 开发者 → 编辑配置
添加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"
      }
    }
  }
}

重启Claude桌面版
验证工具是否可用 - 你应该在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服务器初始化
工具注册和路由
请求/响应格式化

语义意图原则

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

语义优先于结构

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

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

意图保留

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

可观察锚定

// ✅ 基于直接可观察的属性
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 - 架构细节

🤝 贡献代码

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

如何贡献

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

贡献标准

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

快速链接：

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

社区

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

🔒 安全

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

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

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

🔬 研究基础

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

应用的核心原则

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

📊 项目路线图

✅ 阶段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）
是语义意图研究计划的一部分

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

semantic-d1-mcp

README

🚀 语义D1 MCP

📚 目录

🎯 项目独特之处

🚀 快速开始

前提条件

安装

获取Cloudflare API令牌

获取D1数据库ID

🛠️ MCP工具

1. analyze_database_schema

2. get_table_relationships

3. validate_database_schema

4. suggest_database_optimizations

🔌 连接到Claude桌面版

配置

使用示例

🏗️ 架构

实现状态

各层职责

语义意图原则

🧪 测试

测试覆盖率

运行测试

测试框架

📖 从本实现中学习

值得研究的关键文件

相关项目

🤝 贡献代码

如何贡献

贡献标准

社区

🔒 安全

🔬 研究基础

应用的核心原则

相关资源

📊 项目路线图

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

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

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

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

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

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

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

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

📄 许可证

🙏 致谢

运行方式说明

托管运行

本地运行 / 其它方式