Metadata-Version: 2.4
Name: mcp-db-navigator
Version: 0.0.2
Summary: A powerful MySQL/MariaDB database navigation tool using MCP (Model Control Protocol).
Author-email: "Ahmed S. Said-ahmed" <ahmed@pharoslab.net>
License: MIT License
        
        Copyright (c) 2024 
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/Medsaad/mcp-db-navigator
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: mysql-connector-python>=8.0.26
Requires-Dist: pydantic>=2.0.0
Requires-Dist: cryptography>=3.4.7
Requires-Dist: typing-extensions>=4.0.0
Dynamic: license-file

# MySQL Navigator MCP

A powerful MySQL/MariaDB database navigation tool using MCP (Model Control Protocol) for easy database querying and management.

## Features

- Connect to MySQL/MariaDB databases
- Switch between different databases dynamically
- Execute SQL queries with type safety
- Retrieve database schema information
- Pydantic model validation for query parameters
- Secure credential management
- Comprehensive logging system
- Connection pooling and retry mechanisms
- SSL/TLS support for secure connections

## Log File Location (Cross-Platform)

By default, all logs are written to:

- **Windows:** `C:\Users\<YourUsername>\.mcp\mcp-db.log`
- **macOS/Linux:** `/home/<yourusername>/.mcp/mcp-db.log` or `/Users/<yourusername>/.mcp/mcp-db.log`

If the `.mcp` folder does not exist in your home directory, the application will automatically create it. If you run into any issues, you can manually create the folder:

**Windows:**
```powershell
mkdir $env:USERPROFILE\.mcp
```
**macOS/Linux:**
```bash
mkdir -p ~/.mcp
```

## Installation

### From PyPI (recommended for most users):
```bash
pip install mcp-db-navigator
```

### From source (for development):
```bash
git clone <your-repo-url>
cd mcp-db
pip install -e .
```

3. Create a `.env` file with your database credentials:
```env
DB_HOST=your_host
DB_PORT=your_port
DB_NAME=your_database_name
DB_USER=your_username
DB_PASSWORD=your_password
DB_SSL_CA=/path/to/ssl/ca.pem  # Optional: for SSL/TLS connections
DB_MAX_RETRIES=3  # Optional: number of connection retries
DB_RETRY_DELAY=1.0  # Optional: delay between retries in seconds
```

## Usage Examples

### 1. Command Line
Run the MCP server directly from your terminal:
```bash
mcp-db --config /path/to/your/project/.env
```

### 2. In Cursor
To use this MCP server in [Cursor](https://www.cursor.so):
- Open Cursor settings and add a new MCP server.
- Use the following configuration (example):

```json
{
  "mcpServers": {
    "mysql-navigator": {
      "command": "mcp-db",
      "args": [
        "--config",
        "/absolute/path/to/your/.env"
      ]
    }
  }
}
```
- Make sure the path to your `.env` file is absolute.

### 3. In Claude Desktop
If Claude Desktop supports MCP servers:
- Add a new MCP server and point it to the `mcp-db` command with the `--config` argument as above.
- Refer to Claude Desktop's documentation for details on adding custom MCP servers.

## Query Parameters

The query dictionary supports the following parameters:

- `table_name` (required): Name of the table to query
- `select_fields` (optional): List of fields to select (defaults to ["*"])
- `where_conditions` (optional): Dictionary of field-value pairs for WHERE clause
- `order_by` (optional): List of fields to order by
- `order_direction` (optional): Sort direction "ASC" or "DESC" (default: "ASC")
- `limit` (optional): Number of records to return
- `offset` (optional): Number of records to skip
- `group_by` (optional): List of fields to group by
- `having` (optional): Dictionary of field-value pairs for HAVING clause
- `join_table` (optional): Name of the table to join with
- `join_type` (optional): Type of JOIN operation (default: "INNER")
- `join_conditions` (optional): Dictionary of join conditions

## Security Features

- Database credentials are managed through a config file
- Passwords are stored as SecretStr in Pydantic models
- Input validation for all query parameters
- SQL injection prevention through parameterized queries
- SSL/TLS support for encrypted connections
- Connection string sanitization
- Rate limiting for queries
- Query parameter sanitization

## Production Features

### Error Handling
- Comprehensive error handling for database operations
- Connection timeout handling
- Automatic retry mechanism for failed connections
- Input validation for all parameters

### Performance
- Connection pooling for optimal resource usage
- Query execution time logging
- Connection pool statistics
- Performance metrics collection

### Monitoring
- Structured logging with different log levels
- Query execution tracking
- Connection state monitoring
- Error rate tracking

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details. 
