Semantic D1 MCP

🚀 Semantic D1 MCP

このプロジェクトは、シングルソースオブトゥルースパターンとしてのセマンティックインテントの参照実装です。Cloudflare D1データベースのイントロスペクションを行うModel Context Protocol (MCP)サーバーで、セマンティックアンカリング、観測可能なプロパティ、およびAI支援によるデータベース開発のためのドメイン駆動設計を実証しています。

📚 目次

• このプロジェクトの特徴
• クイックスタート
• MCPツール
• アーキテクチャ
• テスト
• コントリビューション
• セキュリティ
• ライセンス

🎯 このプロジェクトの特徴

これは単なるデータベースイントロスペクションツールではなく、実績のあるセマンティックインテントパターンの参照実装です。

• ✅ セマンティックアンカリング：技術的な指標（行数、サイズ）ではなく、意味（テーブルの目的、関係）に基づくスキーマ分析
• ✅ 観測可能なプロパティ：直接観測可能なスキーママーカー（外部キー、インデックス、制約）に基づく決定
• ✅ インテントの保持：すべての変換（開発 → ステージング → 本番）を通じてデータベースのセマンティクスを維持
• ✅ ドメイン境界：明確なセマンティックな所有権（スキーマドメイン ≠ クエリ最適化ドメイン ≠ MCPプロトコルドメイン）

Semantic Intent as Single Source of Truthの研究に基づいて構築されており、インテントを保持した、保守可能で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
   

   .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
   

   注意：少なくとも1つのデータベース環境を設定する必要があります。

4. サーバーをビルドする

   npm run build
   

5. MCPサーバーを起動する

   npm start
   

   または、提供されているシェルスクリプトを使用することもできます。

   ./start-d1-mcp.sh
   

Cloudflare APIトークンを取得する

1. Cloudflareダッシュボードにアクセスします。
2. My Profile → API Tokensに移動します。
3. Create Tokenをクリックします。
4. Edit 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 (オプション): 特定のテーブルの関係をフィルタリングする

戻り値:

• カーディナリティ（1対多、多対1）を含む外部キー関係
• 参照整合性ルール（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 Desktopへの接続

このMCPサーバーをClaude Desktopに接続して、AI支援によるデータベース開発を行うことができます。

設定

1. Claude Desktopの設定を編集する - 設定 → 開発者 → 設定を編集に移動します。

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 Desktopを再起動する

4. ツールが利用可能であることを確認する - Claudeのツールリストに4つのD1ツールが表示されるはずです。

使用例

Claude Desktopで次のように入力します。

"本番データベースのスキーマを分析し、外部キーを持つテーブルの最適化提案をしてください"

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を参照してください。

各層の責任

ドメイン層:

• データベーススキーマエンティティ（スキーマ、テーブル、関係、インデックス）
• スキーマ分析のビジネスロジック
• 関係抽出のロジック
• 最適化提案のルール

アプリケーション層:

• ドメインサービスの調整
• ユースケースの実行（スキーマ分析、関係取得など）
• インフラストラクチャアダプターの調整

インフラストラクチャ層:

• Cloudflare D1 REST APIの統合
• API呼び出しのためのHTTPクライアント
• キャッシュプロバイダー（インメモリ）

プレゼンテーション層:

• MCPサーバーの初期化
• ツールの登録とルーティング
• リクエスト/レスポンスのフォーマット

セマンティックインテントの原則

このコードベースは、厳格なセマンティックアンカリングルールに従っています。

1. 構造よりもセマンティクス

   // ✅ 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
   

2. インテントの保持

   // ✅ Environment semantics preserved through transformations
   const schema = await fetchSchema(Environment.PRODUCTION)
   // Schema analysis preserves "production" intent - no overrides
   

3. 観測可能なアンカリング

   // ✅ Based on directly observable properties
   const relationships = extractForeignKeys(sqliteMaster)
   
   // ❌ Based on inferred behavior
   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チェックをパスする

クイックリンク:

• Contributing Guide - 詳細なガイドライン
• Code of Conduct - コミュニティ基準
• Architecture Guide - 設計原則
• Security Policy - 脆弱性の報告

コミュニティ

• 💬 Discussions - 質問をする
• 🐛 Issues - バグを報告する
• 🔒 Security - 脆弱性を非公開で報告する

🔒 セキュリティ

セキュリティは最優先事項です。セキュリティポリシーを確認してください。

• APIトークン管理のベストプラクティス
• コミットするもの/除外するもの
• セキュリティ脆弱性の報告
• デプロイのセキュリティチェックリスト

脆弱性を発見した場合：security@semanticintent.devにメールで報告してください。

🔬 研究基盤

この実装は、研究論文**"Semantic Intent as Single Source of Truth: Immutable Governance for AI-Assisted Development"**に基づいています。

適用される核心原則

1. 構造よりもセマンティクス - 指標ではなく、意味に基づくスキーマ分析
2. インテントの保持 - 変換を通じて環境のセマンティクスを維持する
3. 観測可能なアンカリング - 直接観測可能なスキーマプロパティに基づく決定
4. 不変のガバナンス - ランタイムでセマンティックな整合性を保護する

関連リソース

• Research Paper (近日公開予定)
• Semantic Anchoring Governance
• semanticintent.dev (近日公開予定)

📊 プロジェクトロードマップ

✅ フェーズ0: 初期実装 (完了)

• 6つのツールを持つモノリシックなMCPサーバー
• D1 REST APIの統合
• 基本的なスキーマ分析

✅ フェーズ1: ドメイン層 (完了)

• セマンティック検証を持つ10のドメインエンティティ
• 3つのドメインサービス（SchemaAnalyzer、RelationshipAnalyzer、OptimizationService）
• 212の合格したテスト

✅ フェーズ2: インフラストラクチャ層 (完了)

• CloudflareD1Repositoryアダプター
• CloudflareAPIClient HTTPクライアント
• InMemoryCacheProvider
• 64の合格したテスト

✅ フェーズ3: アプリケーション層 (完了)

• 4つのユースケース（AnalyzeSchema、GetRelationships、ValidateSchema、SuggestOptimizations）
• ポートインターフェース（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ファイルを参照してください。

🙏 謝辞

• Model Context Protocol by Anthropicに基づいて構築されています。
• Hexagonal Architecture (Alistair Cockburn)に触発されています。
• Domain-Driven Design原則 (Eric Evans)に基づいています。
• Semantic Intent研究イニシアチブの一部です。

これは、データベースイントロスペクションのためのセマンティックインテントパターンを実証する参照実装です。コードを研究し、パターンを学び、自分のプロジェクトに適用してください。 🏗️