# KDB MCP Service

A Model Context Protocol (MCP) service for interacting with KDB+ databases. This service allows AI agents to query, insert, update, and delete data from KDB+ databases through a standardized MCP interface.

## Features

- **Multiple Database Support**: Connect to multiple KDB+ databases simultaneously
- **Connection Pooling**: Efficient connection management with configurable pool sizes
- **Full CRUD Operations**: Query, insert, update, and delete data
- **Schema Introspection**: List tables and get schema information
- **Environment Variable Support**: Secure credential management via environment variables
- **Async Operations**: Non-blocking database operations for better performance

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd kdb-mcp
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Configure your databases (see Configuration section)

## Configuration

### Environment Variables

Copy `.env.example` to `.env` and fill in your database credentials:

```bash
cp .env.example .env
```

Edit `.env` with your actual database details:
```env
KDB_PROD_HOST=your-prod-host.com
KDB_PROD_PORT=5000
KDB_PROD_USERNAME=your-username
KDB_PROD_PASSWORD=your-password
```

### Configuration File

The service uses a YAML configuration file located at `config/kdb_config.yaml`. You can customize:

- Database connections
- Connection pool sizes
- Logging settings
- Server configuration

Example configuration:
```yaml
databases:
  production:
    host: ${KDB_PROD_HOST:localhost}
    port: ${KDB_PROD_PORT:5000}
    username: ${KDB_PROD_USERNAME:}
    password: ${KDB_PROD_PASSWORD:}
    pool_size: 10
    description: Production KDB+ database
```

## Usage

### Running the Server

Start the MCP server:
```bash
python main.py
```

Or with a custom config file:
```bash
python main.py /path/to/custom/config.yaml
```

### Available MCP Tools

The service provides the following MCP tools:

#### 1. `kdb_query`
Execute any Q query on a KDB+ database.
```json
{
  "database": "production",
  "query": "select from trades where date=.z.d"
}
```

#### 2. `kdb_list_tables`
List all tables in a database.
```json
{
  "database": "production"
}
```

#### 3. `kdb_get_schema`
Get schema information for a specific table.
```json
{
  "database": "production",
  "table": "trades"
}
```

#### 4. `kdb_select`
Execute a SELECT query with optional filtering.
```json
{
  "database": "production",
  "table": "trades",
  "columns": ["symbol", "price", "volume"],
  "where": "symbol=`AAPL",
  "limit": 100
}
```

#### 5. `kdb_insert`
Insert data into a table.
```json
{
  "database": "production",
  "table": "trades",
  "data": {
    "symbol": "AAPL",
    "price": 150.25,
    "volume": 1000
  }
}
```

#### 6. `kdb_update`
Update existing records in a table.
```json
{
  "database": "production",
  "table": "trades",
  "updates": {
    "price": 151.00
  },
  "where": "symbol=`AAPL"
}
```

#### 7. `kdb_delete`
Delete records from a table.
```json
{
  "database": "production",
  "table": "trades",
  "where": "date<.z.d-30"
}
```

#### 8. `kdb_list_databases`
List all configured databases.
```json
{}
```

## Integration with AI Agents

This MCP service can be integrated with any AI agent that supports the Model Context Protocol. The agent can use the provided tools to:

1. Query real-time market data
2. Analyze historical trading patterns
3. Update trading strategies
4. Manage data pipelines
5. Generate reports from KDB+ data

### Example Agent Workflow

```python
# Agent pseudocode
async def analyze_trading_data():
    # List available databases
    databases = await call_tool("kdb_list_databases", {})

    # Get today's trades
    trades = await call_tool("kdb_select", {
        "database": "production",
        "table": "trades",
        "where": "date=.z.d",
        "limit": 1000
    })

    # Analyze and generate insights
    insights = analyze(trades)

    # Store insights back to KDB+
    await call_tool("kdb_insert", {
        "database": "analytics",
        "table": "insights",
        "data": insights
    })
```

## Project Structure

```
kdb-mcp/
├── src/
│   └── kdb_mcp/
│       ├── __init__.py           # Package initialization
│       ├── kdb_connection.py     # KDB+ connection handling
│       ├── mcp_server.py         # MCP server implementation
│       └── config.py             # Configuration management
├── config/
│   └── kdb_config.yaml          # Database configuration
├── main.py                       # Entry point
├── requirements.txt              # Python dependencies
├── .env.example                  # Environment variables template
└── README.md                     # This file
```

## Security Considerations

- Never commit `.env` files with actual credentials
- Use environment variables for sensitive information
- Implement proper authentication for production deployments
- Consider using SSL/TLS for database connections
- Regularly rotate database credentials
- Limit database permissions to minimum required

## Troubleshooting

### Connection Issues
- Verify KDB+ server is running and accessible
- Check firewall rules for the KDB+ port
- Ensure credentials are correct
- Test connectivity with `telnet host port`

### Query Errors
- Verify Q syntax is correct
- Check table and column names exist
- Ensure proper data types are used
- Review KDB+ server logs for detailed errors

## Contributing

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

[Your License Here]

## Support

For issues and questions, please create an issue in the repository or contact your system administrator.