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

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

First, start the server:

just start  # starts on http://localhost:8081

Then create a .vscode/mcp.json file in your project:

{
  "servers": {
    "avatar-mcp": {
      "type": "http",
      "url": "http://localhost:8081/sse",
      "headers": {
        "Authorization": "Bearer octopize_apikey.xxxxxxxxx"
      }
    }
  }
}

Note: Replace octopize_apikey.xxxxxxxxx with your real Avatar API key from avatar.octopize.io. API keys start with octopize_apikey..

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)

curl -X POST http://localhost:8081/mcp/v1/tools/call \
  -H "Authorization: Bearer octopize_apikey.xxxxxxxxx" \
  -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