mcp-dbtools 0.1.1

# MCP Database Tools

A Model Context Protocol (MCP) server that provides secure database access through MCP Server and other MCP-compatible clients.

## 🚀 Features

- **YAML Configuration**: Load database configurations from `~/.mcp-dbtools/config.yml`
- **Environment Variable Support**: Use `${VAR_NAME}` syntax for secure credential management
- **Multiple Server Support**: Configure and switch between different database connections
- **SQL Execution**: Execute SQL queries safely through the MCP protocol
- **Fallback Support**: Automatic fallback to environment variables if YAML config fails
- **Comment-Safe Parsing**: Environment variables in YAML comments are ignored

## 📋 Prerequisites

- Rust 1.70 or later
- A supported SQL database
- MCP Server (for MCP integration)

## 🛠️ Installation

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

2. **Build the project:**
   ```bash
   cargo build --release
   ```

3. **Create configuration directory:**
   ```bash
   mkdir -p ~/.mcp-dbtools
   ```

## ⚙️ Configuration

### YAML Configuration File

Create `~/.mcp-dbtools/config.yml`:

```yaml
# Configuration for MCP DB Tools
# Use ${VAR_NAME} to load sensitive values from environment variables.

servers:
  # Local development database
  test_db:
    adapter: "postgres"
    enabled: true
    host: "localhost"
    port: 5432
    username: "postgres"
    password: "postgres"  # WARNING: Use env vars for production
    dbname: "pocket_db"
    read_only: false
    
  # Production database
  prod_db:
    adapter: "mysql"
    enabled: true
    host: "prod.example.com"
    port: 3306
    username: "produser"
    password: "${PROD_DB_PASSWORD}"
    dbname: "production_db"
    read_only: true
```

### Environment Variables

Set required environment variables:

```bash
export PROD_DB_PASSWORD="your-secure-password"
```

## 🏃‍♂️ Usage

### Command Line

```bash
# Run with specific server configuration
cargo run --bin mcp-dbtools test_db

# Run with default server (test_db)
cargo run --bin mcp-dbtools

# Use release build
./target/release/mcp-dbtools prod_db
```

### MCP Server Integration

Add to your MCP Server settings file:

**macOS:** `~/Library/Application Support/MCP Server/mcp_server_config.json`
**Windows:** `%APPDATA%\MCP Server\mcp_server_config.json`

```json
{
  "mcpServers": {
    "db-tools-pocket": {
      "command": "cargo",
      "args": ["run", "--bin", "mcp-dbtools", "--", "test_db"],
      "cwd": "/path/to/mcp-dbtools",
      "env": {}
    }
  }
}
```

Or with pre-built binary:

```json
{
  "mcpServers": {
    "db-tools-pocket": {
      "command": "/path/to/mcp-dbtools/target/release/mcp-dbtools",
      "args": ["test_db"],
      "env": {}
    }
  }
}
```

## 🧪 Testing

### Test Database Connection

```bash
# Test database schema and data
cargo run --bin test_db

# Explore database content
cargo run --bin explore_data
```

### Test MCP Server

```bash
# Test server with YAML config
cargo run --bin mcp-dbtools test_db
```

## 🔧 Configuration Options

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `adapter` | string | Yes | Database type (e.g., "postgres", "mysql") |
| `enabled` | boolean | No | Enable/disable this server config |
| `host` | string | Yes | Database hostname |
| `port` | number | Yes | Database port |
| `username` | string | Yes | Database username |
| `password` | string | No | Database password (use env vars!) |
| `dbname` | string | Yes | Database name |
| `read_only` | boolean | No | Restrict to read-only operations |

## 🔒 Security Best Practices

1. **Never hardcode sensitive data** in YAML files
2. **Use environment variables** for passwords:
   ```yaml
   password: "${DB_PASSWORD}"
   ```
3. **Set appropriate file permissions** on config files:
   ```bash
   chmod 600 ~/.mcp-dbtools/config.yml
   ```
4. **Use read-only mode** for production databases when possible

## 📊 Available SQL Operations

Through MCP Server, you can:

- **Query tables**: "Show me all records from the users table"
- **Describe schema**: "What columns does the products table have?"
- **Run aggregations**: "Calculate total sales by month"
- **Join tables**: "Join users and orders tables"
- **Filter data**: "Find all orders from last week"

## 🐛 Troubleshooting

### Common Issues

1. **"Failed to load YAML config"**
   - Check if `~/.mcp-dbtools/config.yml` exists
   - Verify YAML syntax is correct
   - Ensure environment variables are set

2. **"Environment variable not found"**
   - Set required environment variables before running
   - Check variable names match exactly (case-sensitive)

3. **"Failed to connect to database"**
   - Verify database is running
   - Check host, port, username, and password
   - Ensure database exists

4. **"Server 'xyz' not found in config"**
   - Check server name spelling in YAML file
   - Verify the server section exists under `servers:`

### Debug Mode

Run with verbose output:

```bash
RUST_LOG=debug cargo run --bin mcp-dbtools test_db
```

## 🏗️ Development

### Project Structure

```
mcp-dbtools/
├── src/
│   ├── main.rs          # MCP server entry point
│   ├── config.rs        # Configuration management
│   ├── test_db.rs       # Database testing utility
│   └── explore_data.rs  # Data exploration utility
├── mcp-rust-sdk/        # MCP SDK dependency
├── ~/.mcp-dbtools/      # Configuration directory
│   └── config.yml       # Database configurations
└── README.md
```

### Building

```bash
# Development build
cargo build

# Release build
cargo build --release

# Run tests
cargo test

# Check code quality
cargo clippy
cargo fmt
```

## 📄 License

[Add your license information here]

## 🤝 Contributing

[Add contribution guidelines here]

## 📞 Support

[Add support contact information here]