Semantic D1

Reference implementation of Semantic Intent patterns for Cloudflare D1 database introspection via MCP. Hexagonal architecture with 398 tests demonstrating semantic anchoring, observable properties, and domain-driven design.

typescript

GitHub Stars

typescript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "semanticintent-semantic-d1-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/semantic-d1-mcp/dist/index.js"
      ],
      "env": {
        "D1_DEV_DATABASE_ID": "YOUR_DEV_DB_ID",
        "D1_PROD_DATABASE_ID": "YOUR_PROD_DB_ID",
        "CLOUDFLARE_API_TOKEN": "YOUR_API_TOKEN",
        "D1_DEV_DATABASE_NAME": "YOUR_DEV_DB_NAME",
        "CLOUDFLARE_ACCOUNT_ID": "YOUR_ACCOUNT_ID",
        "D1_PROD_DATABASE_NAME": "YOUR_PROD_DB_NAME",
        "D1_STAGING_DATABASE_ID": "YOUR_STAGING_DB_ID",
        "D1_STAGING_DATABASE_NAME": "YOUR_STAGING_DB_NAME"
      }
    }
  }
}

You have access to a dedicated MCP server for Cloudflare D1 database introspection that preserves intent, anchors decisions to observable schema properties, and supports AI-assisted development. This server analyzes schemas, maps relationships, validates design choices, and offers optimization recommendations to help you work with D1 databases across development, staging, and production environments.

How to use

Connect with your MCP client to perform schema analysis, relationship extraction, validation, and optimization recommendations. You can run the server locally and invoke the four MCP tools to analyze a development, staging, or production environment. Use the tools to explore how your D1 schema behaves, discover relationships between tables, catch schema issues early, and get actionable optimization tips for indexing, keys, and overall schema design.

How to install

# Prerequisites
# - Node.js 20.x or higher
# - npm (comes with Node.js)

# 1. Install dependencies and build
npm install
npm run build

# 2. Start the MCP server using the provided runtime command
npm start

# Optional: or start via the provided shell script when available
./start-d1-mcp.sh

Configuration and usage notes

Configure environment variables to enable Cloudflare and D1 access. The server expects credentials and database identifiers for development, staging, and production. You can set these in a .env file or your environment accordingly. The MCP server runtime will read these values at startup and expose four tools for schema analysis, relationships, validation, and optimizations.

Security considerations

Protect your Cloudflare API token and account identifiers. Use least-privilege tokens and rotate credentials regularly. Ensure your environment is secured and that access to the MCP server is restricted to trusted clients and automation pipelines.

Tools overview

This MCP server provides four core tools for D1 database introspection. Use them in combination to build a complete picture of your schema and its evolution across environments.

Troubleshooting tips

If the MCP server fails to start, check your environment variables and ensure the required D1 database identifiers are valid. Verify that Node.js is running in a compatible version and that dependencies were installed correctly. Review startup logs for any authentication or network-related errors.

Available tools

analyze_database_schema

Analyze complete database schema structure with metadata and optional sample data, returning tables, columns, constraints, indexes, relationships, and optional samples.

get_table_relationships

Extract and analyze foreign key relationships between tables, including cardinality and referential integrity rules.

validate_database_schema

Validate schema for common issues such as missing primary keys, unindexed foreign keys, naming convention violations, and orphaned tables.

suggest_database_optimizations

Generate prioritized optimization recommendations, including missing indexes, primary key suggestions, and schema improvement opportunities.

Built by

VeilStrat

AI signals for GTM teams