Getting Started with vCon MCP Server

Quick start guide to understand and build this project

🎯 What Is This Project?

This project provides:

Complete Documentation for building an IETF vCon-compliant MCP server
Corrections to common implementation mistakes in the spec
Step-by-step Build Guide to implement from scratch
Reference Materials from IETF vCon working group

📚 Start Here

New to vCon?

Read in this order:

README.md (5 min)
- Overview of the project
- Documentation structure
- Critical corrections summary
QUICK_REFERENCE.md (5 min)
- Critical field corrections
- Common mistakes to avoid
- Quick checklist
CLAUDE.md (15 min)
- Complete implementation guide for AI-assisted development
- Corrected TypeScript types and patterns
- Database schema and queries

Already Know vCon?

Fast track:

IMPLEMENTATION_CORRECTIONS.md (15 min)
- All 7 critical spec issues
- What was wrong vs. what's correct
- Why each correction matters
CLAUDE.md (30 min)
- Complete implementation guide
- Corrected TypeScript types
- Database schema and queries
- MCP tool definitions

Migrating Existing Code?

MIGRATION_GUIDE.md (30 min)
- Database migration SQL
- Code refactoring steps
- Verification queries
QUICK_REFERENCE.md
- Use as checklist while migrating

🔴 Critical Corrections

⚠️ These are MANDATORY for IETF spec compliance:

1. Analysis Schema Field

// ❌ WRONG
interface Analysis {
  schema_version?: string;
}

// ✅ CORRECT
interface Analysis {
  schema?: string;
}

2. Analysis Vendor Requirement

// ❌ WRONG
interface Analysis {
  vendor?: string;  // Optional
}

// ✅ CORRECT
interface Analysis {
  vendor: string;  // Required
}

3. Analysis Body Type

// ❌ WRONG
interface Analysis {
  body: object;  // Only supports JSON
}

// ✅ CORRECT
interface Analysis {
  body?: string;  // Supports any format
}

See QUICK_REFERENCE.md for all 7 corrections.

🚀 Quick Setup (5 Minutes)

Prerequisites

Node.js 18+ installed
Supabase account (free tier works)
Git installed

Setup Steps

# 1. Clone or create project directory
mkdir vcon-mcp-server && cd vcon-mcp-server

# 2. Initialize project
npm init -y

# 3. Install dependencies
npm install @modelcontextprotocol/sdk @supabase/supabase-js zod
npm install -D typescript @types/node tsx vitest

# 4. Copy example configuration
# Use the tsconfig.json and package.json from the Building Guide

# 5. Create .env file
echo "SUPABASE_URL=your-url" > .env
echo "SUPABASE_ANON_KEY=your-key" >> .env

# 6. Follow the Building Guide from Phase 2 onwards

📖 Documentation Map

Start Here
    ├── README.md ────────────────────► Master index & navigation
    │
    ├── docs/guide/getting-started.md ► You are here!
    │
    └── Choose your path:
        │
        ├── New Implementation ─────────────┐
        │   ├── docs/reference/QUICK_REF    │
        │   ├── CLAUDE.md ──────────────────┼──► Primary path
        │   └── docs/reference/CORRECTED_   │
        │       SCHEMA.md ─────────────────-┘
        │
        ├── Migration ──────────────────────┐
        │   ├── IMPLEMENTATION_CORRECTIONS  │
        │   ├── docs/reference/MIGRATION ───┼──► Fix existing code
        │   └── docs/reference/CORRECTED_   │
        │       SCHEMA.md ─────────────────-┘
        │
        └── Deep Dive ──────────────────────┐
            ├── docs/reference/vcon-spec.md │
            └── background_docs/ ───────────┘

🎓 Learning Paths

Path 1: Complete Beginner (6 hours)

Goal: Build a working vCon MCP server from scratch

Read background material (1 hour)
- background_docs/vcon_quickstart_guide.md
- background_docs/draft-ietf-vcon-vcon-core-02.txt (introduction)
Understand corrections (30 min)
- docs/reference/QUICK_REFERENCE.md
- docs/reference/IMPLEMENTATION_CORRECTIONS.md
Follow the implementation guide (4 hours)
- CLAUDE.md — complete patterns, types, and DB schema
Test and verify (30 min)
- Run npm test
- Test with AI assistant

Path 2: Experienced Developer (2 hours)

Goal: Implement spec-compliant vCon server quickly

Review corrections (15 min)
- docs/reference/QUICK_REFERENCE.md
Study implementation (30 min)
- CLAUDE.md
Build core (1 hour)
- Database schema
- TypeScript types
- Database queries
Add MCP layer (15 min)
- Tool definitions
- Server setup

Path 3: Migration (3 hours)

Goal: Fix existing implementation to match spec

Identify issues (30 min)
- docs/reference/IMPLEMENTATION_CORRECTIONS.md
- Compare with your code
Plan migration (30 min)
- docs/reference/MIGRATION_GUIDE.md
- Backup database and code
Execute migration (1.5 hours)
- Database schema changes
- Code refactoring
- Update tests
Verify (30 min)
- Run verification queries
- Run npm test
- Manual review

Path 4: AI-Assisted Build (30 min + AI time)

Goal: Use Claude Code to build for you

Prepare instructions (15 min)
- Read docs/reference/QUICK_REFERENCE.md
- Set up Supabase

Provide to AI (5 min)

Build an IETF vCon MCP server following the specifications in:
- CLAUDE.md
- docs/reference/CORRECTED_SCHEMA.md
- docs/reference/QUICK_REFERENCE.md (for checklist)

Use the corrected field names and ensure full spec compliance.

Review & test (10 min)
- Verify no schema_version in code
- Check vendor is required
- Run npm test

🛠️ What You'll Build

Core Components

TypeScript Types (src/types/vcon.ts)
- All IETF vCon objects
- Corrected field names
- Type validation helpers
Database Layer (src/db/)
- Supabase client
- CRUD operations
- Search queries
MCP Server (src/index.ts)
- Tool definitions
- Request handlers
- Error handling
Utilities (src/utils/)
- vCon validation
- Privacy helpers
- Serialization

MCP Tools Provided (30 tools)

CRUD: create_vcon, get_vcon, update_vcon, delete_vcon, add_dialog, add_analysis, add_attachment, create_vcon_from_template
Search: search_vcons, search_vcons_content, search_vcons_semantic, search_vcons_hybrid
Tags: manage_tag, get_tags, remove_all_tags, search_by_tags, get_unique_tags
Analytics: get_database_analytics, get_monthly_growth_analytics, get_content_analytics, get_tag_analytics, get_attachment_analytics, get_database_health_metrics
Database: get_database_shape, get_database_stats, analyze_query, get_database_size_info, get_smart_search_limits
Schema: get_schema, get_examples

REST API

All MCP tools are also available as REST endpoints at /api/v1 when running in HTTP transport mode. See the REST API Reference for details.

Database Schema

vcons - Main vCon records
parties - Conversation participants
dialog - Recordings, texts, transfers
analysis - AI/ML analysis results
attachments - File attachments
party_history - Event timeline

📋 Pre-Build Checklist

Before you start building:

⚠️ Common Pitfalls

Mistake #1: Using Wrong Field Names

// ❌ DON'T
const analysis = { schema_version: '1.0' };

// ✅ DO
const analysis = { schema: '1.0' };

Mistake #2: Making Vendor Optional

// ❌ DON'T
interface Analysis { vendor?: string; }

// ✅ DO
interface Analysis { vendor: string; }

Mistake #3: Wrong Body Type

// ❌ DON'T
body: object  // Database: JSONB

// ✅ DO
body?: string  // Database: TEXT

Mistake #4: Adding Default Values

-- ❌ DON'T
encoding TEXT DEFAULT 'json'

-- ✅ DO
encoding TEXT CHECK (encoding IN ('base64url', 'json', 'none'))

Mistake #5: Forgetting New Fields

// ❌ MISSING
interface Party {
  name?: string;
  // missing: uuid, did
}

// ✅ COMPLETE
interface Party {
  name?: string;
  uuid?: string;
  did?: string;
}

🧪 Testing Your Implementation

Quick Compliance Check

# 1. Check for wrong field names
grep -r "schema_version" src/
# Should return nothing

# 2. Check vendor is not optional
grep "vendor?" src/types/vcon.ts
# Should return nothing

# 3. Run tests
npm test
# Should pass

# 4. Check database schema
# Run verification queries from docs/reference/CORRECTED_SCHEMA.md

Integration Test

Create a test vCon:

const vcon: VCon = {
  vcon: '0.4.0',
  uuid: crypto.randomUUID(),
  created_at: new Date().toISOString(),
  parties: [{
    name: 'Alice',
    mailto: 'alice@example.com',
    uuid: crypto.randomUUID()
  }],
  analysis: [{
    type: 'sentiment',
    vendor: 'TestVendor',  // Required
    schema: 'v1.0',        // Correct field name
    body: JSON.stringify({ score: 0.8 }),
    encoding: 'json'
  }]
};

// Validate
const result = validateVCon(vcon);
console.log(result.valid ? '✅ Valid' : '❌ Invalid');

📞 Getting Help

Documentation Questions

Check README.md troubleshooting section
Search for your error in the Building Guide
Review relevant correction in IMPLEMENTATION_CORRECTIONS.md

Spec Questions

Consult background_docs/draft-ietf-vcon-vcon-core-02.txt
Cross-reference section numbers in correction docs
Cross-reference the Implementation Corrections for before/after examples

Implementation Questions

Follow CLAUDE.md step-by-step
Use code examples from the Building Guide
Check MIGRATION_GUIDE.md for specific fixes

🎯 Success Criteria

Your implementation is successful when:

🚀 Next Actions

Choose your path:

I'm Ready to Build

→ Read CLAUDE.md and follow the patterns there

I Need to Understand Corrections First

→ Read IMPLEMENTATION_CORRECTIONS.md

I'm Migrating Existing Code

→ Follow MIGRATION_GUIDE.md

I Want the Quick Version

→ Read QUICK_REFERENCE.md then dive into CLAUDE.md

📊 Project Status

✅ Complete:

Git repository initialized
All documentation created
Build guide written
Example code provided

⏳ Next Steps:

Follow the Building Guide to implement
Run compliance tests
Deploy MCP server

Ready? Start with CLAUDE.md

Questions? Check README.md → Troubleshooting

Need quick reference? Use QUICK_REFERENCE.md

Last Updated: April 2026
Project: vCon MCP Server Documentation v1.2.0
Spec: draft-ietf-vcon-vcon-core-02 (v0.4.0)

FilesExpand file tree

getting-started.md

Latest commit

History