# Boxtalk Data MCP Server

A Model Context Protocol (MCP) server that provides SQL Server database operations with pagination, table structure inspection, and record counting capabilities.

## Features

- **Get Table Data**: Retrieve paginated data from any SQL Server table
- **Get Record Count**: Get the total number of records in a table
- **Get Table Structure**: View table schema including columns, data types, primary keys, and foreign keys
- **Configurable Connection**: Easy database configuration via JSON file
- **Enforced Pagination**: Prevents large data dumps with configurable page sizes (max 1000 records per page)

## Prerequisites

- Node.js (v16 or higher)
- SQL Server database (local or remote)
- Database credentials with read access

## Installation

1. Clone or navigate to this directory

2. Install dependencies:
```bash
npm install
```

3. Create your configuration file:
```bash
cp config.example.json config.json
```

4. Edit `config.json` with your database credentials:
```json
{
  "database": {
    "user": "your_username",
    "password": "your_password",
    "server": "localhost",
    "database": "your_database_name",
    "options": {
      "encrypt": true,
      "trustServerCertificate": false,
      "enableArithAbort": true
    },
    "pool": {
      "max": 10,
      "min": 0,
      "idleTimeoutMillis": 30000
    }
  }
}
```

### Configuration Options

- `user`: SQL Server username
- `password`: SQL Server password
- `server`: SQL Server hostname or IP address
- `database`: Database name
- `options.encrypt`: Enable encryption (recommended for production)
- `options.trustServerCertificate`: Set to `true` for local development with self-signed certificates
- `pool.max`: Maximum number of connections in the pool
- `pool.min`: Minimum number of connections in the pool
- `pool.idleTimeoutMillis`: Time before idle connections are closed

### Alternative Configuration

You can also specify a custom configuration file path using the `DB_CONFIG_PATH` environment variable:

```bash
DB_CONFIG_PATH=/path/to/custom/config.json node index.js
```

## Usage with Claude Desktop

To use this MCP server with Claude Desktop, add it to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "boxtalk-data": {
      "command": "node",
      "args": ["/path/to/boxtalk-data-mcp/index.js"],
      "env": {
        "DB_CONFIG_PATH": "/path/to/boxtalk-data-mcp/config.json"
      }
    }
  }
}
```

After adding the configuration, restart Claude Desktop.

## Available Tools

### 1. get_table_data

Retrieve paginated data from a SQL Server table.

**Parameters:**
- `table` (required): Table name (e.g., "Users" or "dbo.Users")
- `page` (optional): Page number, defaults to 1
- `pageSize` (optional): Records per page (1-1000), defaults to 100
- `orderBy` (optional): Column to order by, defaults to first column

**Example:**
```
Get the first 50 records from the Users table, ordered by UserId
```

### 2. get_table_count

Get the total count of records in a table.

**Parameters:**
- `table` (required): Table name (e.g., "Users" or "dbo.Users")

**Example:**
```
How many records are in the Orders table?
```

### 3. get_table_structure

Get the structure/schema of a table including columns, data types, and constraints.

**Parameters:**
- `table` (required): Table name (e.g., "Users" or "dbo.Users")

**Example:**
```
Show me the structure of the Products table
```

## Testing

You can test the server using the MCP inspector:

```bash
npm install -g @modelcontextprotocol/inspector
mcp-inspector node index.js
```

## Security Considerations

- Never commit `config.json` to version control
- Use strong database passwords
- Grant only necessary permissions to the database user
- Enable encryption for production environments
- Consider using environment variables for sensitive credentials

## Troubleshooting

### Connection Errors

If you encounter connection errors:
1. Verify SQL Server is running and accessible
2. Check firewall settings allow connection on SQL Server port (default 1433)
3. Confirm credentials are correct
4. For local development with self-signed certificates, set `trustServerCertificate: true`

### Authentication Issues

For Windows Authentication, modify config.json:
```json
{
  "database": {
    "server": "localhost",
    "database": "your_database_name",
    "options": {
      "trustedConnection": true,
      "encrypt": true,
      "trustServerCertificate": true
    }
  }
}
```

### Table Not Found

Ensure you specify the correct schema (e.g., "dbo.TableName" instead of just "TableName").

## License

MIT