CoreMCP

CoreMCP

Model Context Protocol (MCP) server for database operations

CoreMCP by CoreBaseHQ provides a secure, extensible bridge between AI assistants (like Claude Desktop) and your databases through the Model Context Protocol.

🚀 Features

⚠️ Safety First: CoreMCP is designed to be Read-Only by default. We strongly recommend creating a specific database user with SELECT permissions only.

• 🔌 Multiple Database Support: MSSQL, Firebird (coming soon), and extensible adapter system
• 🧠 Automatic Schema Discovery: CoreMCP automatically scans your database tables, columns, foreign keys, and descriptions to provide AI context
• 📝 Column Comments Support: Extracts and presents database column comments/descriptions to the AI for better query understanding
• 🛠️ Dynamic Tool Generation: Built-in tools for common operations (list tables, describe schema) plus custom tool support
• 🎯 Custom Query Tools: Define reusable SQL queries as MCP tools in your config file
• 🛡️ NOLOCK / Read Uncommitted: Per-source option to run all SELECT queries under READ UNCOMMITTED isolation (MSSQL WITH (NOLOCK) equivalent) for zero-locking reads on busy OLTP databases
• 🛡️ Secure: Read-only mode support, connection string isolation
• 🎯 MCP Native: Built specifically for Model Context Protocol
• 🔧 Easy Configuration: Simple YAML-based setup
• 📦 Lightweight: Single binary, no runtime dependencies

📋 Requirements

• Go 1.23 or higher (for building from source)
• Database drivers are embedded in the binary

🔧 Installation

From Source

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

Binary Release

Download the latest release from the Releases page.

⚙️ Configuration

Create a coremcp.yaml file in your working directory:

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

See coremcp.example.yaml for more examples.

DSN Format

Microsoft SQL Server:

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

Dummy (for testing):

dummy://test

Security Configuration

CoreMCP includes enterprise-grade security features:

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

Security Features:

• AST-Based Query Validation: Uses sqlparser to analyze SQL queries and block dangerous operations (DROP, ALTER, UPDATE, DELETE, TRUNCATE, EXEC, etc.)
• Automatic Row Limiting: Adds LIMIT clause to prevent accidentally returning millions of rows
• PII Data Masking: Automatically masks sensitive data like credit cards, emails, SSNs, Turkish IDs, IBANs
• Configurable Patterns: Define custom regex patterns for your specific PII requirements

Source Options

Example: MSSQL with NOLOCK enabled

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

Example: Legacy Turkish ERP Database

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'

How Turkish normalization works:

Mojibake correction (incoming results):

🎯 Usage

CoreMCP has two operation modes:

1. Local Mode (serve) - For Claude Desktop

Start the MCP Server locally:

coremcp serve --config coremcp.yaml

Or use stdio transport (default):

coremcp serve -t stdio

Use with Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

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

2. Remote Mode (connect) - For SaaS & Factory Deployments 🚇

Connect to CoreBase Cloud Platform for remote management:

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

Perfect for:

• 🏭 Factory Deployments: No need to open inbound ports
• 🌐 Remote Management: Control databases from anywhere
• 🔐 Secure: Agent initiates connection from inside your network
• 🔄 Auto-Reconnect: Automatic reconnection on network failures
• ⚙️ Remote Config: Update database connections without redeployment

Connect Command Options

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)

Example: Factory Deployment

# 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

How it works:

1. 🔌 Agent connects to CoreBase Cloud via WebSocket (outbound only)
2. 🔐 Authenticates with your API token
3. 📡 Receives commands from your CoreBase dashboard
4. 🎯 Executes SQL queries on local databases
5. 📤 Sends results back through the secure tunnel
6. 🔄 Auto-reconnects on connection loss

Remote Commands Supported:

• run_sql: Execute SQL queries remotely
• get_schema: Retrieve database schema
• list_sources: List connected databases
• health_check: Check agent status
• config_sync: Update database configurations remotely

No Port Forwarding Required! 🎉

🏗️ Architecture

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

🔌 Available Tools & Prompts

Built-in Tools

query_database

Executes arbitrary SQL queries on configured database sources.

Parameters:

• source_name (required): Name of the database source from config
• query (required): SQL query to execute

Example:

SELECT * FROM users WHERE id = 1

list_tables

Lists all tables in a database with summary information.

Parameters:

• source_name (required): Name of the database source

Returns: List of tables with column counts, primary keys, and foreign key counts.

describe_table

Shows detailed schema information for a specific table.

Parameters:

• source_name (required): Name of the database source
• table_name (required): Name of the table to describe

Returns: Complete table schema including:

• Column names and data types
• Nullable information
• Primary keys
• Foreign key relationships
• Column descriptions/comments

list_views

Lists all views in a database with their column definitions.

Parameters:

• source_name (required): Name of the database source

Returns: Each view with its column names, types, and nullability.

list_procedures

Lists all stored procedures in a database with parameter details.

Parameters:

• source_name (required): Name of the database source

Returns: Each procedure with parameter names, types, modes (IN/OUT/INOUT) and a ready-to-copy example call.

execute_procedure

Executes a stored procedure by name with optional named parameters.

⚠️ Only available on sources where readonly: false.

Parameters:

• source_name (required): Name of the database source
• procedure_name (required): Stored procedure name (e.g. sp_CiroHesapla)
• params (optional): JSON string of parameter name/value pairs

Security:

• Procedure name validated against ^[a-zA-Z_][a-zA-Z0-9_#@.]*$
• All values passed as named SQL parameters (sql.Named) — no string interpolation
• Parameter names also validated (alphanumeric + underscore only)
• Completely blocked when source is readonly: true

Example:

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

Custom Tools

You can define reusable SQL queries as custom MCP tools in your 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"

Benefits:

• Encapsulate complex queries
• Provide simple interfaces for common operations
• Parameters are automatically validated
• AI can discover and use these tools automatically

database_schema Prompt

Automatically provides complete database schema context to the AI, including:

• Table names
• Column names with data types
• Primary keys
• Foreign key relationships
• Column descriptions/comments from the database

When CoreMCP starts, it automatically:

1. Connects to all configured databases
2. Scans the schema (tables, columns, keys, relationships)
3. Extracts column comments/descriptions (e.g., MS_Description in MSSQL)
4. Creates a comprehensive context prompt for the AI

This allows Claude to understand your database structure and write accurate queries without you having to explain the schema manually.

Example:When you ask Claude "Show me all sales", Claude can see that you have a TBLSATIS table with specific columns and automatically write the correct query.

🛠️ Adding Custom Adapters

1. Create a new package in pkg/adapter/yourdb/
2. Implement the core.Source interface
3. Register in pkg/adapter/factory.go

See pkg/adapter/dummy/dummy.go for a simple example.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

🔒 Security

For security concerns, please see SECURITY.md.

📄 License

Apache License 2.0 - see LICENSE for details.

🌟 Roadmap

• Automatic Schema Discovery - Load database structure on startup
• Column Comments/Descriptions - Extract and display database metadata
• Dynamic Tool Generation - list_tables, describe_table tools
• Custom Query Tools - Define reusable queries in config
• AST-Based Query Sanitization - Block dangerous SQL operations
• PII Data Masking - Mask sensitive information in results
• Automatic Row Limiting - Prevent database overload
• WebSocket Connect Mode - Remote management via CoreBase Cloud 🎉
• Auto-Reconnection Logic - Resilient agent connections
• Remote Configuration Sync - Update database configs remotely
• NOLOCK / Read Uncommitted - Per-source zero-locking reads for MSSQL
• Turkish Character Normalization - SQL literal normalization + mojibake fix for legacy Turkish ERP databases
• View & Stored Procedure Discovery - list_views, list_procedures, execute_procedure tools; auto-included in schema context
• PostgreSQL adapter
• MySQL adapter
• Firebird adapter (in progress)
• Query result caching
• HTTP transport support
• Write operation support (with strict safety guards)
• Audit logging
• Multi-tenant agent management
• Real-time monitoring dashboard

💬 Support

• 🐛 Report a bug
• 💡 Request a feature
• 📧 Email: [email protected]

Made with ❤️ by CoreBaseHQ