# Quick Start Guide

## Prerequisites

- Python 3.9+
- Access to Neo4j, Snowflake, MySQL databases
- AWS credentials configured (via environment variables or ~/.aws/credentials)

## Installation

1. **Create and activate virtual environment:**
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

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

3. **Configure environment variables:**
```bash
cp .env.example .env
# Edit .env with your actual database credentials and AWS configuration
```

4. **Create local MCP client config:**
```bash
cp .mcp.example.json .mcp.json
# Optionally edit .mcp.json for your local Python path/client requirements
```

Example .env configuration:
```
# Neo4j Configuration
NEO4J_URI=neo4j+ssc://qa-neo4j-cluster.theorchard.io:7687
NEO4J_USERNAME=your_username
NEO4J_PASSWORD=your_password

# Snowflake Configuration
SNOWFLAKE_ACCOUNT=orchard
SNOWFLAKE_USER=QA_OWS_SOUND_RECORDINGS
SNOWFLAKE_KEY=your_private_key
SNOWFLAKE_PASSPHRASE=your_passphrase
SNOWFLAKE_PASSWORD=your_password
SNOWFLAKE_DATABASE=FACTS
SNOWFLAKE_WAREHOUSE=QA_OWS_WAREHOUSE
SNOWFLAKE_SCHEMA=QA

# MySQL Configuration
MYSQL_HOST=localhost
MYSQL_USER=root
MYSQL_PASSWORD=your_password

# AWS Configuration
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_SESSION_TOKEN=your_session_token  # Optional, for temporary credentials
AWS_REGION=us-east-1

```

## Running the Server

```bash
python src/mcp_server.py
```

The server starts in stdio mode by default and is ready to accept MCP tool calls.

To run over SSE for `mcp-inspector` or another HTTP-capable client:

```bash
python src/mcp_server.py --transport sse --host 127.0.0.1 --port 55392
```

This exposes:

- `GET /health`
- `GET /sse`
- `POST /messages`

## Using with Claude Code

Configure Claude Code to use this MCP server:

1. Use your local `.mcp.json` (created from `.mcp.example.json`) to register the server in Claude Code.
   - The repo tracks `.mcp.example.json` as a template.
   - Keep `.mcp.json` local because it may contain machine-specific paths.

2. Once connected, you'll have access to all the tools in Claude conversations.

## Available Tools

### Database Query Tools
- `query_neo4j` - Execute Cypher queries
- `find_neo4j_nodes` - Find nodes by label and filters
- `query_snowflake` - Execute SQL queries
- `get_snowflake_table_info` - Get table metadata
- `query_mysql` - Execute SQL queries
- `get_mysql_table_schema` - Get table schema

### AWS Integration Tools

- `invoke_lambda` - Invoke a Lambda function
- `list_lambda_functions` - List Lambda functions
- `get_lambda_info` - Get Lambda function details
- `start_sfn_execution` - Start a Step Functions execution
- `describe_sfn_execution` - Describe a Step Functions execution
- `list_sfn_state_machines` - List Step Functions state machines
- `get_sfn_execution_history` - Get Step Functions execution history
- `list_s3_buckets` - List S3 buckets
- `list_s3_objects` - List objects in an S3 bucket
- `get_s3_object` - Read an object from S3
- `get_s3_bucket_size` - Get bucket size statistics

### Sound Recording Tools
- `get_delivery_history` - Query sound recording delivery history from Snowflake

> Note: this code base currently exposes only the tools listed above. Older tools referenced in previous docs are not implemented in the current server.

## Extending the Server

To add new tools:

1. Create a function in the appropriate tool file (neo4j_tools.py, snowflake_tools.py, mysql_tools.py, aws_tools.py, or sound_recording_tools.py)
2. Add a Tool definition in mcp_server.py's `list_tools()` function
3. Add a handler in the `call_tool()` function
4. Restart the server

Example tool function:
```python
def my_new_tool(param: str) -> Dict[str, Any]:
    """Tool description."""
    try:
        result = do_something(param)
        return {"status": "success", "result": result}
    except Exception as e:
        return {"status": "error", "message": str(e)}
```

## Troubleshooting

### Connection Errors
- Verify all database credentials in .env
- Check that databases are accessible from your network
- Ensure AWS credentials are properly configured

### Import Errors
- Make sure you're running from the project root directory
- Verify virtual environment is activated
- Check that all dependencies are installed: `pip list`

### Tool Not Found
- Ensure tool is defined in both `list_tools()` and `call_tool()` functions
- Check tool name matches exactly (case-sensitive)
- Restart the server after adding new tools

## Development

For local development with hot reload:
```bash
pip install watchdog
watchmedo auto-restart -d . -p '*.py' python src/mcp_server.py
```

Or use your IDE's debug configuration to run `src/mcp_server.py` directly.