Metadata-Version: 2.4
Name: personas-mcp
Version: 0.1.0
Summary: MCP server for NVIDIA personas database
Project-URL: Homepage, https://github.com/yourusername/personas-mcp
Project-URL: Repository, https://github.com/yourusername/personas-mcp
Project-URL: Issues, https://github.com/yourusername/personas-mcp/issues
Author-email: Ben <benschool01@gmail.com>
License: MIT
Keywords: mcp,model-context-protocol,nvidia,personas
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=14.0.0
Description-Content-Type: text/markdown

# Personas MCP Server

An MCP (Model Context Protocol) server that provides access to the NVIDIA personas database through various tools.

## Features

The server exposes the following tools:

- **get_random_persona**: Retrieve a random persona from the database
- **get_persona_by_id**: Get a specific persona by UUID
- **search_personas**: Search personas by various criteria (age, sex, state, occupation, education, etc.)
- **get_persona_stats**: Get statistics about the personas database

## Installation and Usage

This MCP server is designed to be run with `uvx`:

```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# From the personas-mcp directory
uvx --from . personas-mcp

# Or from the parent personas directory
uvx --from ./personas-mcp personas-mcp
```

## Configuration for Claude Desktop

Add this to your Claude Desktop configuration file:

### macOS
Location: `~/Library/Application Support/Claude/claude_desktop_config.json`

### Windows
Location: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "personas": {
      "command": "uvx",
      "args": ["--from", "/path/to/personas-mcp", "personas-mcp"]
    }
  }
}
```

Make sure to replace `/path/to/personas-mcp` with the actual path to the `personas-mcp` directory.

## Tool Usage Examples

### Get Random Persona
```
Use the get_random_persona tool
```

### Search Personas
```
Use the search_personas tool with:
- age_min: 25
- age_max: 35
- state: "CA"
- limit: 5
```

### Get Persona by ID
```
Use the get_persona_by_id tool with:
- uuid: "df6b2b96-a938-48b0-83d8-75bfed059a3d"
```

### Get Database Statistics
```
Use the get_persona_stats tool
```

## Development

The server expects the `personas.parquet` file to be in the parent directory (relative to the personas-mcp folder). If the file is not found, it will automatically download it from the NVIDIA Nemotron-Personas dataset on Hugging Face.

Directory structure:
```
personas/
├── personas.parquet (auto-downloaded if missing)
├── personas-mcp/
│   ├── src/
│   │   └── server.py
│   ├── pyproject.toml
│   └── README.md
```

### Auto-download Feature

If `personas.parquet` is not found, the server will automatically download it from:
https://huggingface.co/datasets/nvidia/Nemotron-Personas/

The download is approximately 37MB and will show progress during download.