# Configuration Guide

This guide explains how to configure the Sound Recording MCP server for your databases and AWS environment.

## Environment Variables

All configuration is done via environment variables. Copy `.env.example` to `.env` and customize for your environment.

### Neo4j Configuration

```env
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
```

- **NEO4J_URI**: Connection URI to your Neo4j instance
  - Format: `bolt://[host]:[port]` for local or `neo4j://[host]:[port]` for cluster
  - Default: `bolt://localhost:7687`
- **NEO4J_USERNAME**: Neo4j authentication username
  - Default: `neo4j`
- **NEO4J_PASSWORD**: Neo4j authentication password
  - Default: `password`

### Snowflake Configuration

```env
SNOWFLAKE_ACCOUNT=account_name
SNOWFLAKE_USER=username
SNOWFLAKE_KEY=base64_encoded_private_key_bytes
SNOWFLAKE_PASSWORD=password
SNOWFLAKE_ROLE=optional_role
SNOWFLAKE_DATABASE=database_name
SNOWFLAKE_WAREHOUSE=warehouse_name
SNOWFLAKE_SCHEMA=public
```

- **SNOWFLAKE_ACCOUNT**: Your Snowflake account identifier
  - Find it in your Snowflake URL: `https://[account].snowflakecomputing.com`
- **SNOWFLAKE_USER**: Snowflake user login
- **SNOWFLAKE_KEY**: Optional base64-encoded private key bytes for key-pair authentication
- **SNOWFLAKE_PASSWORD**: Snowflake user password if you are not using `SNOWFLAKE_KEY`
- **SNOWFLAKE_ROLE**: Optional role to use for the session
- **SNOWFLAKE_DATABASE**: Default database to use
- **SNOWFLAKE_WAREHOUSE**: Default warehouse for queries
- **SNOWFLAKE_SCHEMA**: Default schema (optional, defaults to `public`)

The current client reads the variables above. The `.env.example` file also includes `SNOWFLAKE_PASSPHRASE` and `SNOWFLAKE_HOME`, but the current code does not use them.

### MySQL Configuration

```env
MYSQL_HOST=localhost
MYSQL_USER=root
MYSQL_PASSWORD=password
```

- **MYSQL_HOST**: MySQL host or IP address
  - Default: `localhost`
- **MYSQL_USER**: MySQL user
  - Default: `root`
- **MYSQL_PASSWORD**: MySQL user password
  - Default: `password`

### AWS Configuration

```env
AWS_REGION=us-east-1
```

- **AWS_REGION**: AWS region for services
  - Default: `us-east-1`
  - Common values: `us-east-1`, `us-west-2`, `eu-west-1`

AWS authentication uses the standard boto3 credential chain, so you can use environment variables, `~/.aws/credentials`, or an IAM role. If `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are present, boto3 will pick them up automatically.

### Transport Configuration

```env
MCP_TRANSPORT=stdio
MCP_HOST=127.0.0.1
MCP_PORT=55392
MCP_SSE_PATH=/sse
MCP_MESSAGE_PATH=/messages
```

- **MCP_TRANSPORT**: Default transport to use when no `--transport` flag is passed (`stdio` or `sse`)
- **MCP_HOST**: Host to bind when using HTTP transport
- **MCP_PORT**: Port to bind when using HTTP transport
- **MCP_SSE_PATH**: GET endpoint for the SSE stream
- **MCP_MESSAGE_PATH**: POST endpoint for MCP client messages

The current code does not read `MCP_SERVER_NAME` or `DEBUG`, even though they appear in `.env.example`.

## AWS Credential Configuration

The server supports multiple ways to authenticate with AWS (in order of priority):

1. **Environment variables** (most direct)
   ```env
   AWS_ACCESS_KEY_ID=your_key
   AWS_SECRET_ACCESS_KEY=your_secret
   ```

2. **AWS credentials file** (`~/.aws/credentials`)
   ```ini
   [default]
   aws_access_key_id = your_key
   aws_secret_access_key = your_secret
   ```

3. **AWS config file** (`~/.aws/config`)
   ```ini
   [default]
   region = us-east-1
   ```

4. **IAM Role** (when running on EC2 or within AWS)
   - Automatically uses the instance's IAM role

## Database Connection String Formats

### Neo4j Connection URIs

- **Local Bolt**: `bolt://localhost:7687`
- **Local HTTP**: `http://localhost:7474`
- **Remote Bolt**: `bolt://database.example.com:7687`
- **Cluster**: `neo4j+s://cluster.example.com:7687`
- **Aura**: `neo4j+s://xxxxxxxx.databases.neo4j.io`

### Snowflake Account Identifier

Snowflake account identifiers vary by region and cloud provider:

- **Standard**: `xy12345` (from `xy12345.snowflakecomputing.com`)
- **Vanity URL**: `mycompany`
- **Government Region**: `xy12345.us-gov-west-1` (with region)

## Testing Connections

To verify your configuration works:

1. **Neo4j**: Run a simple Cypher query
   ```
   MATCH (n) RETURN count(n) LIMIT 1
   ```

2. **Snowflake**: Run a test query
   ```
   SELECT CURRENT_DATE()
   ```

3. **MySQL**: Run a test query
   ```
   SELECT VERSION()
   ```

4. **AWS**: List functions (Lambda), buckets (S3), or state machines (Step Functions)

## Production Recommendations

1. **Credentials Management**
   - Never commit `.env` file to version control
   - Use AWS Secrets Manager or Parameter Store for sensitive credentials
   - Rotate credentials regularly
   - Use IAM roles instead of access keys where possible

2. **Database Performance**
   - Use connection pooling (implemented in each client)
   - Set appropriate query timeouts
   - Use read replicas for read-heavy workloads

3. **Network Security**
   - Use VPN/bastion hosts for database access
   - Enable SSL/TLS for all connections
   - Restrict database access by IP

4. **Monitoring**
   - Enable database query logging
   - Monitor AWS CloudTrail for API calls
   - Set up alerts for long-running queries

## Troubleshooting

### "Connection refused" errors
- Verify host and port are correct
- Check firewall rules
- Ensure database is running and accessible
- Test with `telnet` or similar utility

### "Authentication failed" errors
- Verify username and password
- Check character encoding (especially special characters)
- Verify user has appropriate permissions

### "SSL/TLS certificate error"
- Verify certificate is valid
- Update Python's certificate bundle: `pip install --upgrade certifi`
- For Neo4j: Add `--encrypted=false` if testing without encryption

### Timeout errors
- Increase query timeout in database configuration
- Check network latency
- Reduce query complexity
- Scale database resources

## Advanced Configuration

### Connection Pooling

Each database client uses connection pooling:

- **Neo4j**: Maintains a connection pool (default: 50 connections)
- **Snowflake**: Uses connector-managed connection pool
- **MySQL**: Creates new connections as needed

To adjust pool settings, edit the respective client file in `src/db/`.

### Query Logging

The current code configures logging in `src/mcp_server.py` at `INFO` level and does not expose an environment-variable toggle for verbose query logging.

## Environment-Specific Setup

### Local Development

```env
NEO4J_URI=bolt://localhost:7687
SNOWFLAKE_ACCOUNT=dev_account
MYSQL_HOST=localhost
AWS_REGION=us-east-1
```

### Staging

```env
NEO4J_URI=bolt://neo4j-staging.internal:7687
SNOWFLAKE_ACCOUNT=staging_account
MYSQL_HOST=mysql-staging.internal
AWS_REGION=us-east-1
```

### Production

```env
NEO4J_URI=neo4j+s://neo4j-prod.internal:7687
SNOWFLAKE_ACCOUNT=prod_account
MYSQL_HOST=mysql-prod.internal
AWS_REGION=us-east-1
```