Metadata-Version: 2.4
Name: octopize.avatar-mcp
Version: 0.1.0
Summary: Avatar MCP server for privacy-preserving data anonymization and augmentation. It is built on octopize.avatar (Official Octopize Avatar Python SDK)
Author-email: Octopize <pypi-octopize@octopize.io>
License-Expression: Apache-2.0
Requires-Python: >=3.12
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: chardet>=5.0.0
Requires-Dist: fastmcp>=2.20
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: mypy>=1.8.0
Requires-Dist: octopize-avatar>=1.22.0
Requires-Dist: pandas<3.0,>=2.3.1
Requires-Dist: pyarrow>=23.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pytest-asyncio>=0.23.0
Requires-Dist: pytest>=8.0.0
Requires-Dist: ruff>=0.1.0
Requires-Dist: typer>=0.15.1
Description-Content-Type: text/markdown

# Avatar MCP Server

MCP server for the Avatar data anonymization platform with multi-tenant authentication and secure file handling.

## Features

- 🔐 **Multi-Tenant Auth**: Bearer token authentication with per-user data isolation
- 📁 **Secure File Upload**: Path-based uploads, file content never exposed to LLM
- 📊 **Avatar Tools**: Create projects, anonymize data, generate synthetic data, download reports
- ⚡ **Performance Profiling**: Optional timing analysis for optimization
- 🧪 **184 Tests**: Comprehensive test coverage for reliability

See `specs/` directory for detailed feature specifications.

## Roadmap

Upcoming features:
- 🔄 **Data Augmentation**: Generate synthetic data variations
- 🔗 **Multi-Table Support**: Handle relational datasets with foreign keys
- ⏰ **Time-Series**: Specialized anonymization for temporal data

## Quick Start

```bash
just install    # Install dependencies
just start      # Start server on port 8081
just test       # Run all 184 tests
just lci        # Run full CI (lint + typecheck + test)
```

Run `just` without arguments to see all available commands.

## VSCode Configuration

Add this to your `.vscode/settings.json` to use the Avatar MCP server with GitHub Copilot:

```json
{
  "github.copilot.chat.mcp.enabled": true,
  "github.copilot.chat.mcp.servers": {
    "avatar": {
      "command": "uv",
      "args": ["run", "python", "src/server.py", "--http", "8081"],
      "cwd": "/absolute/path/to/avatar-mcp.git",
      "env": {
        "AVATAR_API_KEY": "ak_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "PYTHONPATH": "."
      }
    }
  }
}
```

**Note**: Replace `/absolute/path/to/avatar-mcp.git` with the actual path to this repository, and use your real Avatar API key from [avatar.octopize.io](https://avatar.octopize.io).

## Usage Examples

### Using MCP Tools

Once configured in VSCode, ask Copilot to use Avatar tools:

```
"Create a new Avatar project called 'patient-data' with the file ./data/patients.csv"
"Anonymize the data with k=5 and epsilon=1.0"
"Download the anonymized dataset to ./output/patients_avatarized.csv"
"Show me the privacy metrics"
```

### HTTP API (Programmatic Access)

```bash
curl -X POST http://localhost:8081/mcp/v1/tools/call \
  -H "Authorization: Bearer ak_a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_project",
    "arguments": {
      "project_name": "patient-data",
      "primary_table_path": "./data/patients.csv"
    }
  }'
```

## Architecture

- **Multi-Tenant**: Each API key gets isolated session storage (`/tmp/avatar-mcp/{tenant_id}/`)
- **File Security**: Files uploaded via path reference, content never exposed to LLM (<2KB responses)
- **Tool → Core → SDK**: Tools validate params, core modules handle logic, Avatar SDK does anonymization
- **Resource URIs**: All artifacts use `avatar://` URIs served via MCP resource protocol

See `.github/copilot-instructions.md` for detailed conventions.

## Development

This is a **development repository** for feature specifications and experimental implementations. Production code lives in `avatar.git/services/mcp/`.

**Workflow**:
1. Write spec in `specs/{number}-{feature}/`
2. Implement in `src/` with tests in `tests/`
3. Validate with `just lci`
4. Integrate into production codebase

## Project Structure

```
specs/                # Feature specifications
src/
  ├── tools/          # MCP tool definitions
  ├── core/           # Business logic
  ├── auth/           # Authentication & tenant management
  ├── storage/        # File handling
  └── resources/      # MCP resource handlers
tests/
  ├── unit/           # Unit tests
  └── integration/    # Integration tests
```

## Related

- **Production**: `avatar.git/services/mcp/` - Production MCP server with HTTPS support
- **Avatar SDK**: `avatar.git/services/client/` - Python SDK for avatarization
- **Avatar Engine**: `avatar.git/avatar/` - Core anonymization engine

