# Claude Data Buddy 

> Your friendly data analysis assistant powered by Claude!

A Model Context Protocol (MCP) server for analyzing CSV and Parquet files with natural language interface support. Claude Data Buddy makes data analysis conversational and accessible through Claude Desktop integration - just ask questions about your data!

##  Features

- **CSV Analysis**: Summarize, describe, and analyze CSV files
- **Parquet Support**: Full support for Parquet file format
- **Comprehensive Analysis**: Multi-step analysis including statistics, data types, null counts, and sample data
- **Natural Language Interface**: Works seamlessly with Claude Desktop for conversational data analysis
- **MCP Client**: Full-featured asynchronous client with demo and interactive modes
- **Error Handling**: Robust error handling and validation

##  Requirements

- Python 3.8+
- CUDA-compatible GPU (optional, for certain operations)

##  Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd claude-data-buddy
```

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

##  Usage

### Running the MCP Server

The server can be run directly or integrated with Claude Desktop.

#### Direct Execution:
```bash
python main.py
```

#### Claude Desktop Integration:

1. Use the provided launcher script:
```bash
./run_mcp_server.sh
```

2. Configure Claude Desktop by adding to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "claude-data-buddy": {
      "command": "python",
      "args": ["/path/to/claude-data-buddy/main.py"]
    }
  }
}
```

### Using the MCP Client

#### Demo Mode:
```python
from client import MCPFileAnalyzerClient

async def main():
    client = MCPFileAnalyzerClient()
    await client.connect()
    await client.demo_mode()
    await client.disconnect()

asyncio.run(main())
```

#### Interactive Mode:
```python
from client import MCPFileAnalyzerClient

async def main():
    client = MCPFileAnalyzerClient()
    await client.connect()
    await client.interactive_mode()
    await client.disconnect()

asyncio.run(main())
```

##  Project Structure

```
claude-data-buddy/
├── main.py                      # MCP server implementation
├── client.py                    # MCP client with demo/interactive modes
├── requirements.txt             # Python dependencies
├── run_mcp_server.sh            # Server launcher script
├── claude_desktop_config.json   # Claude Desktop configuration example
├── data_files/                  # Sample data files
│   ├── sample.csv
│   ├── sample.parquet
│   └── ...
└── README.md                    # This file
```

## Available Tools

### `list_data_files`
Lists all available CSV and Parquet files in the data directory.

### `summarize_csv`
Provides a comprehensive summary of a CSV file including:
- Row and column counts
- Column names and data types
- Sample data (head)
- Basic statistics

### `summarize_parquet`
Similar to `summarize_csv` but for Parquet files.

### `analyze_csv`
Performs various analysis operations:
- `describe`: Statistical summary
- `head`: First few rows
- `columns`: Column information
- `info`: Dataset information
- `shape`: Dimensions
- `nulls`: Null value counts

### `comprehensive_analysis`
Performs a complete multi-step analysis including:
- Summary statistics
- Data types
- Null value analysis
- Sample data
- Memory usage

##  MCP Integration

This server implements the Model Context Protocol, allowing it to work with:
- Claude Desktop
- Custom MCP clients
- Any MCP-compatible application

##  Example Usage

### Via Claude Desktop:
```
User: "Summarize sample.csv as a CSV file"
Claude: [Calls summarize_csv tool and returns results]
```

### Via Python Client:
```python
result = await client.call_tool("summarize_csv", {"file_name": "sample.csv"})
print(result)
```



##  Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Uses [Model Context Protocol](https://modelcontextprotocol.io/)