coreMCP (Core Base Hq)

CoreMCP

用于数据库操作的模型上下文协议（MCP）服务器

CoreBaseHQ的CoreMCP通过模型上下文协议在AI助手（如Claude Desktop）和数据库之间提供了一个安全、可扩展的桥梁。

🚀 特性

⚠️ 安全第一：CoreMCP默认为只读模式——省略 readonly 在你的配置中是安全的。我们强烈建议创建仅具有SELECT权限的特定数据库用户。

• 🔌 多数据库支持：MSSQL、Firebird（即将推出）和可扩展适配器系统
• 🧠 自动架构发现：CoreMCP会自动扫描您的数据库表、列、外键和描述，以提供AI上下文
• 📝 专栏评论支持：提取并向人工智能呈现数据库列注释/描述，以更好地理解查询
• 🛠️ 动态工具生成：用于常见操作的内置工具（列表表、描述模式）以及自定义工具支持
• 🎯 自定义查询工具：在配置文件中将可重用的SQL查询定义为MCP工具
• 🛡️ NOLOCK/读取未提交：按源选项运行所有SELECT查询 READ UNCOMMITTED 隔离（MSSQL WITH (NOLOCK) 等效）用于繁忙OLTP数据库上的零锁定读取
• 🛡️ 安全：只读模式支持，连接字符串隔离
• 🎯 MCP本地：专为模型上下文协议构建
• 🔧 易于配置：基于YAML的简单设置
• 📦 轻量级：单个二进制文件，无运行时依赖关系

📋 需求

• 达到1.23或更高（从源代码构建）
• 数据库驱动程序嵌入在二进制文件中

🔧 安装

来源

git clone https://github.com/corebasehq/coremcp.git
cd coremcp
go build -o coremcp ./cmd/coremcp

二进制发布

从下载最新版本 发布页面.

⚙️ 配置

创建一个 coremcp.yaml 工作目录中的文件：

server:
  name: "coremcp-agent"
  version: "0.1.0"
  transport: "stdio"
  port: 8080

logging:
  level: "info"
  format: "json"

sources:
  - name: "my_database"
    type: "mssql"
    dsn: "sqlserver://username:password@localhost:1433?database=mydb&encrypt=disable"
    readonly: true
    no_lock: true            # Optional: READ UNCOMMITTED isolation (WITH (NOLOCK) equivalent)
    normalize_turkish: true  # Optional: Turkish character normalization for legacy ERP databases

看 coremcp.example.yaml 更多示例。

DSN格式

Microsoft SQL Server：

sqlserver://username:password@host:port?database=dbname&encrypt=disable

假人（用于测试）：

dummy://test

安全配置

CoreMCP包括企业级安全功能：

security:
  # Maximum rows to return (prevents DB overload)
  max_row_limit: 1000
  
  # Enable PII masking
  enable_pii_masking: true
  
  # PII patterns to mask
  pii_patterns:
    - name: "credit_card"
      pattern: '\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b'
      replacement: "****-****-****-****"
      enabled: true
    - name: "email"
      pattern: '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
      replacement: "***@***.***"
      enabled: true
    - name: "turkish_id"
      pattern: '\b[1-9]\d{10}\b'
      replacement: "***********"
      enabled: true

安全功能：

• 基于AST的查询验证：使用sqlparser分析SQL查询并阻止危险操作（DROP、ALTER、UPDATE、DELETE、TRUNCATE、EXEC等）
• 自动行限制：添加LIMIT子句以防止意外返回数百万行
• PII数据屏蔽：自动屏蔽敏感数据，如信用卡、电子邮件、SSN、土耳其ID、IBAN
• 可配置模式：为您的特定PII要求定义自定义正则表达式模式

源选项

示例：启用NOLOCK的MSSQL

sources:
  - name: "oltp_db"
    type: "mssql"
    dsn: "sqlserver://user:pass@localhost:1433?database=production&encrypt=disable"
    readonly: true
    no_lock: true

示例：传统土耳其ERP数据库

sources:
  - name: "erp_db"
    type: "mssql"
    dsn: "sqlserver://user:pass@localhost:1433?database=LOGO&encrypt=disable"
    readonly: true
    no_lock: true           # Avoid locking on busy OLTP
    normalize_turkish: true # AI can now search 'Hüseyin' and it matches 'HUSEYIN'

土耳其正常化如何运作：

Mojibake校正（传入结果）：

🎯 用法

CoreMCP有两种操作模式：

1.本地模式（服务）-适用于克劳德桌面

在本地启动MCP服务器：

coremcp serve --config coremcp.yaml

或者使用stdio传输（默认）：

coremcp serve -t stdio

与Claude Desktop一起使用

添加到您的Claude桌面配置(claude_desktop_config.json):

{
  "mcpServers": {
    "coremcp": {
      "command": "/path/to/coremcp",
      "args": ["serve", "-c", "/path/to/coremcp.yaml"],
      "env": {}
    }
  }
}

2.远程模式（连接）-用于SaaS和工厂部署🚇

连接到CoreBase云平台进行远程管理：

coremcp connect --server="wss://api.corebase.com/ws/agent" --token="sk_fabrika_123"

非常适合：

• 🏭 工厂部署：无需打开入站端口
• 🌐 远程管理：从任何地方控制数据库
• 🔐 安全：代理从您的网络内部启动连接
• 🔄 自动重新连接：网络故障时自动重新连接
• ⚙️ 远程配置：更新数据库连接而不重新部署

连接命令选项

Flags:
  -s, --server string              CoreBase Cloud WebSocket URL (required)
  -t, --token string               Authentication token (required)
  -a, --agent-id string            Agent ID (optional, auto-generated if not provided)
  -r, --max-reconnect int          Maximum reconnection attempts (default: 10, 0 for infinite)
  -d, --reconnect-delay duration   Delay between reconnection attempts (default: 5s)

示例：工厂部署

# Factory IT admin runs this command
./coremcp connect \
  --server="wss://api.corebasehq.com/ws/agent" \
  --token="sk_fabrika_xyz" \
  --agent-id="factory-istanbul-001" \
  --max-reconnect=0  # Infinite reconnection

它是如何工作的：

1. 🔌 代理通过WebSocket连接到CoreBase Cloud（仅限出站）
2. 🔐 使用API令牌进行身份验证
3. 📡 从CoreBase仪表板接收命令
4. 🎯 在本地数据库上执行SQL查询
5. 📤 通过安全隧道将结果发送回
6. 🔄 连接丢失时自动重新连接

支持的远程命令：

• run_sql：远程执行SQL查询
• get_schema：检索数据库架构
• list_sources：列出连接的数据库
• health_check：检查代理状态
• config_sync：远程更新数据库配置

无需端口转发！ 🎉

🏗️ 建筑

coremcp/
├── cmd/coremcp/       # CLI application entry point
│   ├── main.go        # Main entry
│   ├── root.go        # Root command
│   ├── serve.go       # Serve command (stdio mode for Claude Desktop)
│   └── connect.go     # Connect command (WebSocket mode for Cloud)
├── pkg/
│   ├── adapter/       # Database adapters
│   │   ├── factory.go # Adapter factory pattern
│   │   ├── dummy/     # Dummy adapter (for testing)
│   │   └── mssql/     # MSSQL adapter
│   ├── config/        # Configuration management
│   ├── core/          # Core type definitions
│   ├── security/      # Security features (PII masking, query validation)
│   └── server/        # MCP server implementation
└── coremcp.yaml       # Configuration file

🔌 可用工具和提示

内置工具

query_database

对配置的数据库源执行任意SQL查询。

参数：

• source_name （必填）：配置中的数据库源名称
• query （必填）：要执行的SQL查询

例子：

SELECT * FROM users WHERE id = 1

list_tables

列出数据库中包含摘要信息的所有表。

参数：

• source_name （必填）：数据库源的名称

退货： 包含列计数、主键和外键计数的表列表。

describe_table

显示特定表的详细架构信息。

参数：

• source_name （必填）：数据库源的名称
• table_name （必填）：要描述的表的名称

退货： 完整的表架构包括：

• 列名和数据类型
• 无效信息
• 主键
• 外键关系
• 专栏描述/评论

list_views

列出数据库中的所有视图及其列定义。

参数：

• source_name （必填）：数据库源的名称

退货： 每个视图及其列名、类型和可空性。

list_procedures

列出数据库中包含参数详细信息的所有存储过程。

参数：

• source_name （必填）：数据库源的名称

退货： 每个程序都有参数名称、类型、模式(IN/OUT/INOUT)以及一个准备复制的示例调用。

execute_procedure

按名称执行具有可选命名参数的存储过程。

⚠️ 仅适用于以下来源 readonly: false.

参数：

• source_name （必填）：数据库源的名称
• procedure_name （必填）：存储过程名称（例如。 sp_CiroHesapla)
• params （可选）：参数名称/值对的JSON字符串

安全：

• 程序名称已验证 ^[a-zA-Z_][a-zA-Z0-9_#@.]*$
• 所有作为命名SQL参数传递的值(sql.Named)--无字符串插值
• 参数名称也经过验证（仅限字母数字+下划线）
• 当源被完全阻止时 readonly: true

例子：

{
  "source_name": "erp_db",
  "procedure_name": "sp_CiroHesapla",
  "params": "{\"StartDate\":\"2024-01-01\",\"EndDate\":\"2024-12-31\"}"
}

自定义工具

您可以将可重用的SQL查询定义为您的自定义MCP工具 coremcp.yaml:

custom_tools:
  - name: "get_daily_sales"
    description: "Retrieves daily sales summary for a specific date"
    source: "production_db"
    query: "SELECT * FROM orders WHERE DATE(created_at) = '{{date}}'"
    parameters:
      - name: "date"
        description: "Date in YYYY-MM-DD format"
        required: true

  - name: "get_top_customers"
    description: "Lists top N customers by order count"
    source: "production_db"
    query: "SELECT user_id, COUNT(*) as order_count FROM orders GROUP BY user_id ORDER BY order_count DESC LIMIT {{limit}}"
    parameters:
      - name: "limit"
        description: "Number of customers to return"
        required: true
        default: "10"

优点：

• 封装复杂的查询
• 为常见操作提供简单的界面
• 参数自动验证
• AI可以自动发现和使用这些工具

database_schema 提示

自动为AI提供完整的数据库模式上下文，包括：

• 表名
• 带数据类型的列名
• 主键
• 外键关系
• 数据库中的列描述/注释

当CoreMCP启动时，它会自动：

1. 连接到所有已配置的数据库
2. 扫描架构（表、列、键、关系）
3. 提取列注释/描述（例如。， MS_Description 在MSSQL中）
4. 为AI创建全面的上下文提示

这使Claude能够理解您的数据库结构并编写准确的查询，而无需手动解释模式。

例子： 当你问克劳德“给我看看所有的销售额”时，克劳德可以看出你有一个 TBLSATIS 表中有特定的列，并自动编写正确的查询。

🛠️ 添加自定义适配器

1. 在中创建新包 pkg/adapter/yourdb/
2. 实施 core.Source 接口
3. 注册于 pkg/adapter/factory.go

看 pkg/adapter/dumy/dummy.go 举个简单的例子。

🤝 贡献

欢迎投稿！请阅读 贡献.md 了解详情。

🔒 安全

有关安全问题，请参阅 安全.md.

📄 许可证

Apache许可证2.0-请参阅 许可证 了解详情。

🌟 路线图

• \[x\] 自动架构发现 -启动时加载数据库结构
• \[x\] 专栏评论/描述 -提取并显示数据库元数据
• \[x\] 动态工具生成 -list_tables，describe_table工具
• \[x\] 自定义查询工具 -在配置中定义可重用的查询
• \[x\] 基于AST的查询净化 -阻止危险的SQL操作
• \[x\] PII数据屏蔽 -在结果中隐藏敏感信息
• \[x\] 自动行限制 -防止数据库过载
• \[x\] WebSocket连接模式 -通过CoreBase Cloud进行远程管理🎉
• \[x\] 自动重新连接逻辑 -弹性代理连接
• \[x\] 远程配置同步 -远程更新数据库配置
• \[x\] NOLOCK/读取未提交 -MSSQL的每源零锁定读取
• \[x\] 土耳其语字符规范化 -针对传统土耳其ERP数据库的SQL文字规范化+mojibake修复
• \[x\] 查看和存储过程发现 - list_views, list_procedures, execute_procedure 工具；自动包含在模式上下文中
• \[\]PostgreSQL适配器
• \[\]MySQL适配器
• \[\]Firebird适配器（正在进行中）
• \[\]查询结果缓存
• \[\]HTTP传输支持
• \[\]写操作支持（有严格的安全防护）
• \[\]审核日志记录
• \[\]多租户代理管理
• \[\]实时监控仪表板

💬 支持

• 🐛 报告错误
• 💡 请求功能
• 📧 电子邮件：support@corebasehq.com

______________________________________________________________________

制作❤️ 通过 CoreBaseHQ