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）
• 是 語義意圖 研究計劃的一部分

本項目是一個參考實現，展示了用於數據庫內省的語義意圖模式。你可以研究代碼、學習模式並將其應用到自己的項目中。🏗️