](https://mseep.ai/app/semanticintent-semantic-d1-mcp)
语义D1 MCP（注：D1和MCP在此处可能代表特定的技术或概念，但根据上下文无法确定具体含义，因此直接保留原英文缩写。在实际应用中，应根据具体领域或上下文给出准确解释。）
   ](https://nodejs.org/) 
  
语义意图作为单一真实来源模式的参考实现 一个用于Cloudflare D1数据库内省的模型上下文协议（MCP）服务器，展示了语义锚定、可观察属性以及面向领域驱动设计的AI辅助数据库开发。
📚 目录
🎯 何以与众不同
这不仅仅是一个数据库内省工具——它是一个 参考实现 已证实的语义意图模式：
- ✅ 语义锚定基于意义的模式分析（表格目的、关系），而非技术指标（行数、大小）
- ✅ 可观察属性基于可直接观察的模式标记（外键、索引、约束）的决策
- ✅ 意图保持（或意图保留）数据库语义在所有转换过程中（开发→预生产→生产）均得到维护
- ✅ 领域边界明确的语义归属（模式域 ≠ 查询优化域 ≠ MCP协议域）
基于（某机构/某人的）研究成果构建 语义意图作为唯一真相来源这一实现展示了如何构建可维护、对AI友好的数据库工具，同时保持设计意图。
______________________________________________________________________
🚀 快速入门
先决条件
- Node.js 20.x 或更高版本
- 拥有D1数据库的Cloudflare账户
- Cloudflare API令牌，具有D1访问权限
安装
- 克隆仓库
git clone https://github.com/semanticintent/semantic-d1-mcp.git
cd semantic-d1-mcp- 安装依赖项
npm install- 配置环境
复制示例配置：
cp .env.example .env更新 .env 使用您的Cloudflare凭据：
# Cloudflare Configuration
CLOUDFLARE_ACCOUNT_ID=your_cloudflare_account_id
CLOUDFLARE_API_TOKEN=your_cloudflare_api_token
# D1 Database Configuration - Development
D1_DEV_DATABASE_ID=your_dev_database_id
D1_DEV_DATABASE_NAME=your_dev_database_name
# D1 Database Configuration - Staging (Optional)
D1_STAGING_DATABASE_ID=your_staging_database_id
D1_STAGING_DATABASE_NAME=your_staging_database_name
# D1 Database Configuration - Production (Optional)
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
# List all your D1 databases
wrangler d1 list
# Get specific database info
wrangler d1 info 将数据库ID复制到您的（相应位置） .env 文件。
______________________________________________________________________
🛠️ MCP 工具
这台服务器提供 4款全面的MCP工具 用于D1数据库的内省（或自省）：
1. 分析数据库架构
分析完整的数据库模式结构，包括元数据和可选的样本数据。
参数：
environment（必填）："development"|"staging"|"production"includeSamples（可选，默认：true): 包括表格中的示例数据maxSampleRows（可选，默认：5): 每个表样本的最大行数
返回值：
- 完整的模式分析
- 带有列、类型和约束的表结构
- 索引和外键
- 每个表中的示例数据（如果已启用）
- 模式元数据和统计信息
示例：
{
"name": "analyze_database_schema",
"arguments": {
"environment": "development",
"includeSamples": true,
"maxSampleRows": 5
}
}2. 获取表关系
提取并分析表之间的外键关系。
参数：
environment（必需）：数据库环境tableName（可选）：为特定表过滤关系
返回值：
- 具有基数（一对多、多对一）的外键关系
- 引用完整性规则（级联、设为NULL等）
- 关系元数据和统计信息
示例：
{
"name": "get_table_relationships",
"arguments": {
"environment": "production",
"tableName": "users"
}
}3. 验证数据库模式
验证数据库模式是否存在常见问题和反模式。
参数：
environment（必需）：数据库环境
返回值：
- 模式验证结果
- 缺少主键
- 没有索引的外键
- 命名规范违规
- 没有关系的表
示例：
{
"name": "validate_database_schema",
"arguments": {
"environment": "production"
}
}4. 建议数据库优化
基于结构分析生成模式优化建议。
参数：
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桌面版
- 验证工具是否可用 - 你应该在克劳德的工具列表中看到4个D1工具
使用示例
在Claude桌面版中：
“分析我的生产数据库架构，并为包含外键的表提出优化建议”
克劳德将使用 analyze_database_schema 并且 suggest_database_optimizations 自动工具。
______________________________________________________________________
🏗️ 建筑学
这个项目展示了 领域驱动六边形架构 具有清晰的职责分离：
┌─────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ (MCP Server - Protocol Handling) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ Application Layer │
│ (Use Cases - Schema Analysis Orchestration) │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ Domain Layer │
│ (Schema Entities, Relationship Logic, Services) │
│ Pure Business Logic │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ Infrastructure Layer │
│ (Cloudflare D1 REST API, HTTP Client) │
│ Technical Adapters │
└─────────────────────────────────────────────────────────┘实施状态
状态✅ 六边形架构重构完成
当前结构:
src/
├── domain/ # Business logic (entities, services)
│ ├── entities/ # DatabaseSchema, TableInfo, Column, etc.
│ ├── services/ # SchemaAnalyzer, RelationshipAnalyzer, etc.
│ ├── repositories/ # Port interfaces
│ └── value-objects/ # Environment enum
├── application/ # Use cases and orchestration
│ ├── use-cases/ # AnalyzeSchema, GetRelationships, etc.
│ └── ports/ # Cache provider interface
├── infrastructure/ # External adapters
│ ├── adapters/ # CloudflareD1Repository, Cache
│ ├── config/ # CloudflareConfig, DatabaseConfig
│ └── http/ # CloudflareAPIClient
├── presentation/ # MCP protocol layer
│ └── mcp/ # D1DatabaseMCPServer
└── index.ts # Composition root (DI)看 ARCHITECTURE.md（文件名可译为“架构.md”，其中“.md”表示Markdown格式文件） 用于详细设计文档。
层职责
领域层：
- 数据库模式实体（模式、表、关系、索引）
- 模式分析业务逻辑
- 关系抽取逻辑
- 优化推荐规则
应用层：
- 协调领域服务
- 执行用例（分析模式、获取关系等）
- 协调基础设施适配器
基础设施层：
- Cloudflare D1 REST API 集成
- API调用的HTTP客户端
- 缓存提供程序（内存中）
表示层：
- MCP服务器初始化
- 工具注册和路由
- 请求/响应格式化
语义意图原则
这个代码库遵循严格的语义锚定规则：
- “Semantic Over Structural”可以翻译为“语义优于结构”或“结构之上重语义”。这里，“Semantic”指的是语义或含义，“Over”表示优于或超越，“Structural”则指的是结构。因此，整个短语强调的是在某种情境下，语义的重要性超过了结构的重要性，或者语义在结构之上的优先地位
// ✅ SEMANTIC: Based on observable schema properties
const needsIndex = table.hasForeignKey() && !table.hasIndexOnForeignKey()
// ❌ STRUCTURAL: Based on technical metrics
const needsIndex = table.rowCount > 10000 && table.queryCount > 100- 意图保持（或意图保留）
// ✅ Environment semantics preserved through transformations
const schema = await fetchSchema(Environment.PRODUCTION)
// Schema analysis preserves "production" intent - no overrides- 可观察锚定
// ✅ Based on directly observable properties
const relationships = extractForeignKeys(sqliteMaster)
// ❌ Based on inferred behavior
const relationships = inferFromQueryPatterns(logs)见 《语义锚定治理.md》 以形成完整的治理规则。
______________________________________________________________________
🧪 测试
状态✅ 全面的测试套件，398项测试通过
测试覆盖率
- ✅ 领域层212项测试（实体、服务、验证）
- ✅ 基础设施层64项测试（D1适配器、API客户端、配置）
- ✅ 应用层35项测试（用例、编排）
- ✅ 表示层（或称展示层）13项测试（MCP服务器，工具路由）
- ✅ 整合15项测试（端到端流程）
- ✅ 值对象59项测试（环境、不可变性）
总计398项测试（全部通过 ✅）
运行测试
# Run all tests
npm test
# Watch mode
npm run test:watch
# With UI
npm run test:ui
# Coverage report
npm run test:coverage测试框架
- Vitest快速单元测试框架
- @vitest/coverage-v8（可译为：“用于Vitest的V8覆盖率工具”或保持原样，因为这是特定于项目或库的名称，直接翻译可能失去其原始含义）代码覆盖率报告
- 模拟策略通过接口实现模拟Cloudflare D1 API的响应
______________________________________________________________________
📖 从这次实施中学习
这个代码库作为 参考实现 用于数据库工具中的语义意图模式。
需研究的关键文件
六边形架构的实现:
- src/index.ts 翻译为中文是：“源代码目录下的入口文件（或索引文件）.ts” 或者简化为 “源文件目录中的索引文件 .ts”。不过，通常在中文语境下，我们可能会直接说成“src目录下的index.ts文件”或“源码中的index.ts文件”，以保持表述的简洁性 - 带有依赖注入的组合根（或：带有依赖注入的组合结构根）
- src/（源代码目录）/domain/（领域目录）/entities/（实体目录） - 具有语义验证的领域实体
- src/域/服务/ - 纯业务逻辑服务
- src/应用程序/用例/ - 编排层
- src/infrastructure/adapters/ 可以翻译为：“源代码/基础设施/适配器/” - 外置适配器
- src/presentation/mcp/ 翻译为中文可以是：“源代码/展示层/MCP（多控制协议或具体项目/模块名称，根据上下文确定）/” - MCP协议层
参考文档：
- D1_MCP重构计划.md - 完整的重构计划
- 《语义锚定治理.md》 - 治理规则
- ARCHITECTURE.md（文件名，可译为“架构.md”或保持原样，因为文件名通常不翻译，但根据语境，“架构说明文件”或“架构文档”也是可接受的译法，具体取决于上下文和使用场景） - 建筑细节
相关项目
- 语义上下文-MCP（或：多上下文感知处理/机制，具体含义需根据上下文确定，MCP为缩写，可能代表多种概念） - 用于上下文管理的兄弟参考实现
______________________________________________________________________
🤝 贡献（或“参与贡献”）
我们欢迎投稿！这是一个 参考实现因此，贡献应遵循语义意图原则。
如何贡献（或：如何参与贡献）
- 阅读指南： CONTRIBUTING.md 翻译为中文是：“贡献指南文件（或：贡献说明文件）”。这个文件通常用于说明如何为某个项目或组织做出贡献，包括提交代码、报告问题、参与讨论等指南
- 检查重构计划： D1_MCP重构计划.md
- 遵循架构保持层边界和语义锚定
- 添加测试所有更改都需要全面的测试覆盖
- 文档意图解释“为什么”，而不仅仅是“是什么”
贡献标准
- ✅ 遵循语义意图模式
- ✅ 保持六边形架构（重构后）
- ✅ 添加全面测试（目标覆盖率90%以上）
- ✅ 包含语义文档
- ✅ 通过所有持续集成（CI）检查
快速链接：
社区
- 💬 讨论 - 提问
- 🐛（这个符号在中文里通常被用作表示“虫子”或“小错误”的表情符号，直接翻译可能无实际意义，但可理解为“小虫子”或“小错误”的意象） 问题 - 报告错误
- 🔒（锁形符号，常用于表示安全、保密或锁定状态） 安全 - 私下报告漏洞
______________________________________________________________________
🔒 安全
安全是首要任务。请查阅我们的 安全政策 for:（在中文中，这个短语通常不单独翻译，因为它是一个介词短语的一部分，需要结合上下文来理解。但如果是直接翻译“for”这个单词，可以翻译为“为了”或“对于”，具体取决于上下文。）
- API令牌管理最佳实践
- 要提交什么/要排除什么
- 报告安全漏洞
- 部署安全检查清单
发现漏洞了吗？ 电子邮箱：security@semanticintent.dev
______________________________________________________________________
🔬 研究基金会
这个实现是基于一篇研究论文的 “语义意图作为唯一真相来源：为AI辅助开发提供不可变治理”。
应用核心原则
- “Semantic Over Structural”可以翻译为“语义优先于结构”或“结构之上是语义”。这里，“Semantic”指的是语义，即信息的内容和意义；“Structural”指的是结构，即信息的组织和排列方式。整个短语强调了在考虑信息或系统时，语义的重要性高于结构 - 基于意义而非指标的模式分析
- 意图保持（或：意图保留） - 通过转换维护的环境语义
- 可观察锚定 - 基于直接可观察模式属性的决策
- 不可变治理 - 在运行时保护语义完整性
相关资源
- 研究论文 （即将推出）
- 语义锚定治理
- semanticintent.dev 翻译为中文是“语义意图开发平台”或“语义意图网站”，具体翻译可能根据上下文有所调整。在这里，“semanticintent”指的是与语义意图相关的概念，而“.dev”通常表示这是一个开发或测试性质的网站域名。因此，整个域名可以理解为一个专注于语义意图技术或应用的开发平台或网站 （即将推出）
______________________________________________________________________
📊 项目路线图
✅ 阶段0：初步实施（已完成）
- 集成了6种工具的单片式MCP服务器
- D1 REST API 集成
- 基本模式分析
✅ 第一阶段：领域层（已完成）
- 10个具有语义验证的领域实体
- 3个领域服务（SchemaAnalyzer，RelationshipAnalyzer，OptimizationService）
- 212项测试通过
✅ 第二阶段：基础设施层（已完成）
- Cloudflare D1 数据库适配器
- Cloudflare API 客户端 HTTP 客户端
- 内存缓存提供程序
- 64项测试通过
✅ 第三阶段：应用层（已完成）
- 4个用例（分析模式、获取关系、验证模式、建议优化）
- 端口接口（ICloudflareD1Repository，ICacheProvider）
- 35项测试通过
✅ 第四阶段：表示层（已完成）
- 带有4个MCP工具的D1DatabaseMCPServer
- 请求/响应数据传输对象（DTOs）
- 13项测试通过
✅ 第五阶段：集成与组合根（完成）
- 在index.ts中的依赖注入
- 环境配置
- 15项集成测试
✅ 第六阶段：持续集成/持续交付（CI/CD）与文档编写（已完成）
- TypeScript 构建验证
- README已更新
- 398项总测试通过
🎯 第七阶段：生产准备（计划中）
- GitHub Actions 持续集成/持续部署 (CI/CD) 工作流
- Dependabot 自动化
- 安全扫描
- GitHub仓库设置
见 D1_MCP重构计划.md 以获取详细路线图。
______________________________________________________________________
📄 许可证
这个项目采用MIT许可证授权——详见 许可证 详情请查阅文件。
______________________________________________________________________
🙏 致谢
______________________________________________________________________
这是一个参考实现，展示了数据库内省的语义意图模式。研究这段代码，学习这些模式，并将它们应用到你自己的项目中。 🏗️ 翻译成中文是“建筑工地”或“正在建造”。这个表情符号通常用来表示与建筑、施工或建造相关的场景或活动。