语义 perch 智能 MCP（注：Perch在此处可能是一个特定品牌、项目或技术的名称，由于没有具体上下文，直接音译为“佩奇”，但实际翻译可能需根据具体情境调整；MCP通常指“Machine Control Protocol”或“Multi-Controller Protocol”等，具体含义需结合上下文确定）

![License: MIT](https://opensource.org/licenses/MIT) ![CI](https://github.com/semanticintent/semantic-perch-intelligence-mcp/actions/workflows/ci.yml) ![TypeScript](https://www.typescriptlang.org/) ](https://nodejs.org/) ![Tests](https://github.com/semanticintent/semantic-perch-intelligence-mcp)

![Semantic Intent](https://github.com/semanticintent) ![Hexagonal Architecture](ARCHITECTURE.md) ![PRs Welcome](CONTRIBUTING.md)

PerchIQX - 深度洞察。数据库智能。 一个用于Cloudflare D1数据库内省的模型上下文协议（MCP）服务器。该服务器实现了语义意图模式的参考实现，展示了语义锚定、可观测属性以及面向领域驱动的设计在AI辅助数据库开发中的应用。

🎯 什么让这与众不同

这不仅仅是一个普通的数据库内省工具——它是一个 参考实现 已验证的语义意图模式：

✅ 语义锚定基于意义（表格目的、关系）的模式分析，而非技术指标（行数、大小）
✅ 可观测属性基于可直接观察的模式标记（外键、索引、约束）的决策
✅ 意图保持（或意图保存）数据库语义在所有转换过程中（开发→测试→生产）均得到维护
✅ 领域边界明确的语义归属（模式域 ≠ 查询优化域 ≠ MCP协议域）

基于……的研究成果构建语义意图作为唯一真实来源这一实现展示了如何构建可维护、对AI友好的数据库工具，同时保留设计意图。

______________________________________________________________________

🚀 快速入门

先决条件

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

安装

克隆仓库

   git clone https://github.com/semanticintent/semantic-perch-intelligence-mcp.git
   cd semantic-perch-intelligence-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 （可选）：为特定表过滤关系

返回：

具有基数（一对多、多对一）的外键关系
引用完整性规则（级联、设为空值等）
关系元数据和统计信息

示例：

{
  "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 Desktop，以进行AI辅助的数据库开发。

配置

编辑Claude桌面配置 - 前往设置 → 开发者 → 编辑配置

添加MCP服务器配置：

{
  "mcpServers": {
    "semantic-perch": {
      "command": "node",
      "args": [
        "/absolute/path/to/semantic-perch-intelligence-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 Desktop中：

“分析我的生产数据库模式，并为包含外键的表提出优化建议”

克劳德将使用 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格式的文件，但在中文语境下，我们通常只提及文件名“ARCHITECTURE”和其格式“.md”，不直接翻译“md”本身，因为它是一个特定文件格式的标识）。不过，为了更贴近原文的表述方式，也可以保留“ARCHITECTURE.md”不变，直接说明这是一个文件名，即“架构设计文件（.md格式）”。但根据您的要求，这里提供了一个较为直接的翻译：“架构.md” 用于详细的设计文档。

层职责

领域层:

数据库模式实体（模式、表、关系、索引）
模式分析业务逻辑
关系抽取逻辑
优化推荐规则

应用层：

协调域服务
执行用例（分析模式、获取关系等）
协调基础设施适配器

基础设施层：

Cloudflare D1 REST API 集成
API调用的HTTP客户端
缓存提供程序（内存中）

表示层（或译为“表现层”）：

MCP服务器初始化
工具注册和路由
请求/响应格式化

语义意图原则

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

“Semantic Over Structural”可以翻译为“语义优于结构”或“结构之上重语义”。这里，“Semantic”指的是语义，即意义或含义；“Structural”指的是结构，即组织或构造；“Over”则表示一种优先关系或强调。因此，整个短语强调的是在考虑或设计时，语义的重要性应超过或优先于结构

   // ✅ 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是一个用于测试JavaScript/TypeScript项目的工具，直接翻译为中文即“维特斯”，但在此上下文中，通常保留其原名以指代该工具）快速单元测试框架
@vitest/coverage-v8（注：这通常指的是一个用于vitest的代码覆盖率工具，基于V8引擎，直接翻译为中文可能保持原名不变，因为它是技术术语）代码覆盖率报告
模拟策略通过接口实现模拟Cloudflare D1 API响应

______________________________________________________________________

📖 从这次实施中学习

这个代码库作为 参考实现 用于数据库工具中的语义意图模式。

需研究的关键文件

六边形架构的实现:

src/index.ts 翻译为中文是：“源代码目录下的索引 TypeScript 文件”。不过，通常我们不会直接翻译文件名，而是根据上下文说明其用途或位置，比如“这是项目源代码中的入口 TypeScript 文件”或者“这是位于 src 目录下的主索引文件，使用 TypeScript 编写” - 带有依赖注入的组合根
src/域/实体/ - 具有语义验证的领域实体
src/（源代码目录）/domain/（领域）/services/（服务） - 纯业务逻辑服务
src/应用程序/用例/ - 编排层
src/infrastructure/adapters/ 翻译为中文是：源代码/基础设施/适配器/ - 外部适配器
src/presentation/mcp/ 翻译为中文可以是：“源代码/展示层/MCP（多渠道平台/模块/控制器等，具体含义需根据上下文确定）/” - MCP协议层

参考文档：

D1_MCP重构计划.md - 完整的重构计划
《语义锚定治理.md》 - 治理规则
ARCHITECTURE.md 翻译为中文是：“架构.md”（或“架构文件.md”，具体翻译可能根据上下文有所调整，但“md”通常表示Markdown格式的文件） - 建筑细节

🤝 贡献

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

如何贡献（或如何投稿/参与）

阅读指南: \CONTRIBUTING.md\ 翻译为中文是：“贡献指南文件”或“贡献规范文件”。这个文件通常用于说明如何为项目做出贡献，包括提交代码、报告问题、参与讨论等方面的指导原则和流程
检查重构计划: D1_MCP重构计划.md
遵循架构保持层边界和语义锚定
添加测试所有变更都需要全面的测试覆盖
文档意图解释“为什么”，而不仅仅是“是什么”

贡献标准

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

快速链接：

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

社区

💬 讨论 - 提问
🐛 蝇（或：虫子）问题 - 报告错误
🔒（锁形符号，常用于表示安全、保密或锁定状态）安全 - 私下报告漏洞

______________________________________________________________________

🔒 安全

安全是首要任务。请查阅我们的安全策略对于：

API令牌管理最佳实践
要提交什么/要排除什么
报告安全漏洞
部署安全检查清单

发现了漏洞？ 电子邮箱：security@semanticintent.dev

______________________________________________________________________

🔬 研究基金会

这个实现是基于一篇研究论文的 “语义意图作为单一真实来源：为AI辅助开发提供不可变的治理”.

应用的核心原则

语义优先于结构 - 基于意义而非度量的模式分析
意图保持（或意图保留） - 通过转换维护环境语义
可观察锚定 - 基于直接可观察模式属性的决策
不可变治理 - 在运行时保护语义完整性

📊 项目路线图

✅ 第0阶段：初步实施（已完成）

带有6种工具的单片MCP服务器
D1 REST API 集成
基本模式分析

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

具有语义验证的10个领域实体
3个领域服务（模式分析器、关系分析器、优化服务）
212项测试通过

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

Cloudflare D1 数据库适配器
Cloudflare API 客户端 HTTP 客户端
内存缓存提供程序
64项测试通过

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

4个用例（分析模式、获取关系、验证模式、建议优化）
端口接口（ICloudflareD1Repository，ICacheProvider）
35项测试通过

✅ 第四阶段：表示层（完成）

D1数据库MCP服务器，配备4个MCP工具
请求/响应数据传输对象（DTOs）
13项测试通过

✅ 第五阶段：集成与组合根（完成）

在 index.ts 中进行依赖注入
环境配置
15个集成测试

✅ 第六阶段：持续集成/持续交付（CI/CD）与文档编写（已完成）

TypeScript 构建验证
README已更新
总共有398项测试通过

🎯 第七阶段：生产准备（计划中）

GitHub Actions CI/CD 工作流
Dependabot 自动化
安全扫描
GitHub仓库设置

见 D1_MCP重构计划.md 以获取详细路线图。

______________________________________________________________________

📄 许可证

这个项目采用MIT许可证授权——详见许可证文件中有关于详细信息。

______________________________________________________________________

🙏 致谢

建立在模型上下文协议由Anthropic开发
受……的启发六边形架构（阿利斯泰尔·科克伯恩）
基于领域驱动设计原则（埃里克·埃文斯）
部分的语义意图研究倡议

______________________________________________________________________

这是一个参考实现，展示了用于数据库内省的语义意图模式。研究这段代码，学习这些模式，并将它们应用到你的项目中。 🏗️ 翻译为中文是“建筑工地”或“正在建造中”。这个表情符号通常用来表示与建筑、施工或建造相关的场景。

Semantic Perch Intelligence MCP

快速接入

详细介绍

📚 目录

🎯 什么让这与众不同

🚀 快速入门

先决条件

安装

获取Cloudflare API令牌

获取D1数据库ID

🛠️ MCP 工具

1. 分析数据库架构

2. 获取表之间的关系

3. 验证数据库模式

4. 建议进行数据库优化

🔌 连接至Claude桌面版

配置

使用示例

🏗️ 建筑学

实施状态

层职责

语义意图原则

🧪 测试

测试覆盖率

运行测试

测试框架

📖 从这次实施中学习

需研究的关键文件

相关项目

🤝 贡献

如何贡献（或如何投稿/参与）

贡献标准

社区

🔒 安全

🔬 研究基金会

应用的核心原则

相关资源

📊 项目路线图

✅ 第0阶段：初步实施（已完成）

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

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

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

✅ 第四阶段：表示层（完成）

✅ 第五阶段：集成与组合根（完成）

✅ 第六阶段：持续集成/持续交付（CI/CD）与文档编写（已完成）

🎯 第七阶段：生产准备（计划中）

📄 许可证

🙏 致谢

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP