octopize.avatar-mcp 0.1.0

Avatar MCP server for privacy-preserving data anonymization and augmentation. It is built on octopize.avatar (Official Octopize Avatar Python SDK)

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

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

{
  "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.

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 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