damischa1/hydropro-mcp

HydroPro MCP Server

A TypeScript-based Model Context Protocol (MCP) server that provides seamless connectivity to MariaDB databases using the mysql2 driver.

Features

• MariaDB Connectivity: Full support for MariaDB databases with connection pooling
• MCP Tools: Comprehensive set of database tools accessible via MCP protocol
• TypeScript: Fully typed implementation with strict type checking
• Connection Management: Automatic connection pooling and graceful shutdown
• Environment Configuration: Flexible configuration via environment variables
• Error Handling: Robust error handling and logging

Tools

The server provides the following MCP tools:

Database Operations

• execute_query - Execute SQL queries with parameter binding support (supports all operations including INSERT, UPDATE, DELETE)
• execute_transaction - Execute multiple SQL queries in a single transaction (all succeed or all fail)
• list_databases - List all available databases on the server
• list_tables - List tables in current or specified database
• describe_table - Get detailed column information for tables
• use_database - Switch to a different database

Server Management

• server_info - Get MariaDB server version and configuration info
• test_connection - Test database connectivity

Resources

The server exposes these MCP resources:

• database://schema - Current database schema information (JSON)
• database://status - Server status and connection details (JSON)

Installation

1. Clone the repository:

git clone <repository-url>
cd hydropro-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Environment Variables

Create a .env file in the project root with your database credentials:

# Copy .env.example to .env and update with your credentials
cp .env.example .env

Required environment variables in .env:

DB_HOST=localhost           # MariaDB host (default: localhost)
DB_PORT=3306               # MariaDB port (default: 3306)
DB_USER=your_username      # Database username (required)
DB_PASSWORD=your_password  # Database password (required)
DB_NAME=your_database      # Default database (optional)
DB_CONNECTION_LIMIT=10     # Connection pool limit (default: 10)

Note: Never commit your .env file to version control as it contains sensitive credentials.

Usage

As a VS Code Extension

1. Ensure your .env file is configured with database credentials
2. The MCP server is already configured in .vscode/mcp.json
3. Restart VS Code to load the MCP server

MCP configuration (.vscode/mcp.json):

{
    "servers": {
        "hydropro-mcp": {
            "type": "stdio",
            "command": "node",
            "args": ["build/index.js"],
            "env": {
                "NODE_ENV": "production"
            }
        }
    }
}

The server automatically loads credentials from your .env file.

Command Line Usage

# Ensure .env file is configured, then run the server
npm start

For development with custom environment:

# Override .env settings temporarily
DB_HOST=localhost DB_USER=myuser npm start

Development

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Run TypeScript compiler in watch mode
• npm start - Start the compiled server
• npm run clean - Clean build directory

Project Structure

src/
├── index.ts      # Main MCP server implementation
├── database.ts   # MariaDB connection and query utilities
└── types/        # TypeScript type definitions

build/            # Compiled JavaScript output
.vscode/          # VS Code configuration

Adding New Tools

1. Add tool definition in the ListToolsRequestSchema handler
2. Implement tool logic in the CallToolRequestSchema handler
3. Update TypeScript types as needed
4. Rebuild and test

Usage Examples

Execute Single Query

// Using execute_query tool
{
  "sql": "SELECT * FROM users WHERE status = ?",
  "params": ["active"]
}

Execute Multiple Queries in Transaction

// Using execute_transaction tool
{
  "queries": [
    {
      "sql": "UPDATE products SET price = ? WHERE id = ?",
      "params": ["29.99", "123"]
    },
    {
      "sql": "INSERT INTO price_history (product_id, old_price, new_price) VALUES (?, ?, ?)",
      "params": ["123", "24.99", "29.99"]
    }
  ]
}

All queries in a transaction will either all succeed or all fail together, ensuring data consistency.

Database Schema

The server can work with any MariaDB database schema. It provides introspection capabilities to:

• Discover available databases and tables
• Examine table structures and column definitions
• Query data with proper type handling
• Execute DDL and DML operations

Error Handling

The server includes comprehensive error handling:

• Database connection errors with retry logic
• SQL execution errors with detailed messages
• Transaction rollback on any query failure
• MCP protocol errors with proper error responses
• Graceful shutdown on process signals

Security Considerations

• Use environment variables for sensitive configuration
• Implement proper database user permissions
• Consider connection limits for production use
• Regular security updates for dependencies

License

MIT License - see LICENSE file for details

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with proper TypeScript types
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

1. Check the documentation
2. Review existing GitHub issues
3. Create a new issue with detailed information
4. Include environment details and error messages