Database Schema MCP

数据库架构MCP服务器

英语 | 中文

______________________________________________________________________

用于从多种数据库类型中提取数据库模式信息的模型上下文协议（MCP）服务器。旨在为LLM提供全面的数据库结构信息，以更好地生成SQL、数据分析和理解数据库。

特性

• 多数据库支持：连接到14种以上的数据库类型

- 关系型：MySQL、PostgreSQL、OpenGauss、SQLite、Oracle、ClickHouse - NoSQL：MongoDB、Redis、Memcached - 消息队列：Kafka、RabbitMQ - 搜索/分析：Elasticsearch - 键值存储：etcd - 矢量数据库：Milvus

• 全面的模式提取:

- 表、列、数据类型 - 主键、索引、唯一约束 - 外键关系 - 视图和存储过程 - MongoDB字段类型推断（基于采样） - Redis密钥模式分析 - Kafka主题配置

• LLM优化输出：所有模式信息的格式都是干净、结构化的Markdown

• 可扩展架构：易于添加对新数据库类型（Pulsar、etcd、Cassandra等）的支持

• 环境变量支持：通过以下方式进行安全密码管理 ${VAR_NAME} 语法

安装

npm install
npm run build

配置

1.创建配置文件

复制示例配置并对其进行自定义：

cp config.example.json config.json

2.配置数据库

编辑 config.json 要添加数据库连接，请执行以下操作：

{
  "databases": {
    "my_mysql": {
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "database": "myapp",
      "user": "root",
      "password": "${MYSQL_PASSWORD}"
    },
    "my_postgres": {
      "type": "postgresql",
      "connectionString": "postgresql://user:pass@localhost:5432/mydb"
    },
    "my_mongodb": {
      "type": "mongodb",
      "uri": "mongodb://localhost:27017",
      "database": "myapp",
      "sampleSize": 1000
    }
  }
}

3.设置环境变量

对于敏感凭据，请使用环境变量：

export MYSQL_PASSWORD="your_password"
export POSTGRES_PASSWORD="your_password"
export REDIS_PASSWORD="your_password"

用法

此工具提供了两种访问数据库模式信息的方法：

1. CLI工具 -用于快速提取模式的命令行界面
2. MCP服务器 -用于与Claude Desktop和其他MCP客户端集成的模型上下文协议服务器

使用CLI工具

构建并链接包后，您可以使用 db-schema 命令：

# Install and link the package
npm install
npm run build
npm link

# Get complete database schema
db-schema --config config.json --database my_mysql

# List all tables
db-schema --config config.json --database my_mysql --list-tables

# Get details for a specific table
db-schema --config config.json --database my_mysql --table users

# Export schema to a file
db-schema --config config.json --database my_mysql --output schema.md

# Use environment variable for config path
export DB_SCHEMA_CONFIG=config.json
db-schema --database my_mysql

CLI选项：

• `-c, --config

` -配置文件的路径（除非设置了DB_SCHEMA_CONFIG，否则是必需的）

• -d, --database -配置中的数据库名称（必填）
• -l, --list-tables -列出所有表格/集合/主题
• -t, --table -获取特定表格的详细信息
• `-o, --output

` -输出文件路径（默认：stdout）

运行MCP服务器

npm start

或者设置自定义配置路径：

DB_SCHEMA_CONFIG=/path/to/config.json npm start

可用的MCP工具

1. get_database_schema

获取Markdown格式的完整数据库模式。

参数：

• databaseName （string）：config.json中的数据库名称

例子：

{
  "databaseName": "my_mysql"
}

2. list_tables

列出数据库中的所有表/集合/主题。

参数：

• databaseName （string）：config.json中的数据库名称

3. get_table_details

获取特定表格的详细信息。

参数：

• databaseName （string）：config.json中的数据库名称
• tableName （string）：表的名称

数据库特定配置

MySQL

{
  "type": "mysql",
  "host": "localhost",
  "port": 3306,
  "database": "mydb",
  "user": "root",
  "password": "password"
}

PostgreSQL

{
  "type": "postgresql",
  "host": "localhost",
  "port": 5432,
  "database": "mydb",
  "user": "postgres",
  "password": "password",
  "schema": "public"
}

或者使用连接字符串：

{
  "type": "postgresql",
  "connectionString": "postgresql://user:pass@localhost:5432/mydb"
}

OpenGauss 的

OpenGauss与PostgreSQL协议兼容：

{
  "type": "opengauss",
  "host": "localhost",
  "port": 5433,
  "database": "mydb",
  "user": "gaussdb",
  "password": "password",
  "schema": "public"
}

SQLite

{
  "type": "sqlite",
  "database": "/path/to/database.db"
}

甲骨文

{
  "type": "oracle",
  "host": "localhost",
  "port": 1521,
  "user": "system",
  "password": "password",
  "serviceName": "ORCL"
}

注： 需要在您的系统上安装Oracle Instant Client。

MongoDB

{
  "type": "mongodb",
  "uri": "mongodb://localhost:27017",
  "database": "mydb",
  "sampleSize": 1000
}

现场推断： MongoDB连接器示例最多 sampleSize 文档（默认值：1000），用于推断字段类型和出现率。

瑞迪斯

{
  "type": "redis",
  "host": "localhost",
  "port": 6379,
  "password": "password",
  "db": 0,
  "maxKeys": 1000,
  "keyPattern": "*"
}

关键模式分析： 扫描至 maxKeys 密钥匹配 keyPattern 以识别命名模式和数据类型。

内存缓存

{
  "type": "memcached",
  "servers": ["localhost:11211"]
}

备注：Memcached不支持密钥枚举。连接器仅提供缓存统计信息。

卡夫卡

{
  "type": "kafka",
  "brokers": ["localhost:9092"],
  "clientId": "database-schema-mcp"
}

RabbitMQ 的

{
  "type": "rabbitmq",
  "host": "localhost",
  "port": 5672,
  "user": "guest",
  "password": "password",
  "vhost": "/"
}

备注：要求启用RabbitMQ管理API以获得完整的队列/交换列表。

弹性搜索

{
  "type": "elasticsearch",
  "node": "http://localhost:9200"
}

通过身份验证：

{
  "type": "elasticsearch",
  "nodes": ["http://localhost:9200"],
  "auth": {
    "username": "elastic",
    "password": "password"
  }
}

弹性云：

{
  "type": "elasticsearch",
  "cloudId": "your-cloud-id",
  "auth": {
    "apiKey": "your-api-key"
  }
}

etcd

{
  "type": "etcd",
  "hosts": ["localhost:2379"],
  "prefix": "/",
  "maxKeysToScan": 1000
}

通过身份验证：

{
  "type": "etcd",
  "hosts": ["localhost:2379"],
  "username": "root",
  "password": "password"
}

ClickHouse

{
  "type": "clickhouse",
  "host": "localhost",
  "port": 8123,
  "database": "default",
  "username": "default",
  "password": "password"
}

米尔维斯

{
  "type": "milvus",
  "address": "localhost:19530"
}

通过身份验证：

{
  "type": "milvus",
  "address": "localhost:19530",
  "username": "root",
  "password": "password",
  "secure": false
}

添加新数据库类型

该架构的设计便于扩展。要添加新的数据库类型，请执行以下操作：

1. 创建连接器 在 src/connectors/:

// src/connectors/etcd.ts
import { DatabaseConnector } from './base.js';
import { registerConnector } from './factory.js';

export class EtcdConnector extends DatabaseConnector {
  async connect() { /* implementation */ }
  async disconnect() { /* implementation */ }
  async getSchema() { /* implementation */ }
  // ... implement other required methods
}

registerConnector('etcd', EtcdConnector);

1. 导入连接器 在 src/index.ts:

import './connectors/etcd.js';

1. 重建和使用:

npm run build

建筑

database-schema-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types/schema.ts       # Type definitions
│   ├── config/loader.ts      # Config file loader
│   ├── connectors/
│   │   ├── base.ts           # Abstract base class
│   │   ├── factory.ts        # Connector registry & factory
│   │   ├── mysql.ts          # MySQL implementation
│   │   ├── postgresql.ts     # PostgreSQL implementation
│   │   ├── sqlite.ts         # SQLite implementation
│   │   ├── oracle.ts         # Oracle implementation
│   │   ├── mongodb.ts        # MongoDB implementation
│   │   ├── redis.ts          # Redis implementation
│   │   └── kafka.ts          # Kafka implementation
│   ├── schema/formatter.ts   # Markdown formatter
│   └── tools/schema-tools.ts # MCP tool handlers
└── config.json               # Your database configuration

发展

使用Makefile（推荐）

该项目包括一个用于常见开发任务的Makefile：

# View all available commands
make help

# Install dependencies
make install

# Build the project
make build

# Run in watch mode (auto-rebuild on changes)
make dev

# Quick start (install + build + start)
make start

直接使用npm

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (auto-rebuild on changes)
npm run dev

测试

使用Makefile进行快速测试

# Run all tests (unit + integration)
make test

# Run only unit tests (fast, no databases required)
make test-unit

# Run integration tests with test databases
make test-integration

# Run tests in watch mode
make test-watch

# Run tests with coverage report
make test-coverage

管理测试数据库

该项目使用Docker Compose提供测试数据库：

# Start all test databases (MySQL, PostgreSQL, MongoDB, Redis, Kafka)
make test-db-up

# Stop and remove test databases
make test-db-down

# View test database logs
make test-db-logs

# Check test database status
make test-db-status

直接使用npm

# Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run only integration tests (requires databases)
npm run test:integration

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

测试覆盖率

该项目包括综合测试：

• 单元测试：配置加载器、连接器工厂、模式格式化器
• 集成测试：所有具有真实数据库操作的数据库连接器

- MySQL连接器 - PostgreSQL连接器 - SQLite连接器 - MongoDB连接器 - Redis连接器 - Kafka连接器

看 测试.md 获取详细的测试文档。

安全考虑

• 永不承诺 config.json 持有真实证件
• 对敏感数据使用环境变量
• 仅授予必要的数据库权限（建议只读）
• 对于生产使用，考虑加密配置文件

故障排除

Oracle连接问题

确保已安装Oracle Instant Client：

• 从Oracle网站下载
• 集 LD_LIBRARY_PATH （Linux）或 PATH （Windows）到即时客户端目录

MongoDB采样性能

对于非常大的收藏，减少 sampleSize 在配置中提高性能：

{
  "sampleSize": 100
}

Redis密钥扫描

如果Redis有数百万个密钥，请限制扫描 maxKeys 并使用特定的模式：

{
  "maxKeys": 500,
  "keyPattern": "user:*"
}

许可证

麻省理工学院

贡献

欢迎投稿！要添加对其他数据库的支持，请执行以下操作：

1. 分叉存储库
2. 按照现有图案创建新连接器
3. 添加测试和文档
4. 提交拉取请求

计划数据库支持

• Pulsar（消息队列）
• etcd（键值存储）
• Cassandra（宽栏商店）
• ElasticSearch（搜索引擎）
• ClickHouse（OLAP数据库）
• TiDB（分布式SQL）