Getting Started

Quick start guide to understand and build this project

🎯 What Is This Project?

This project provides:

1. Complete Documentation for building an IETF vCon-compliant MCP server

2. Corrections to common implementation mistakes in the spec

3. Step-by-step Build Guide to implement from scratch

4. Reference Materials from IETF vCon working group

📚 Start Here

New to vCon?

Read in this order:

1. README.md (5 min)

   • Overview of the project

   • Documentation structure

   • Critical corrections summary

2. QUICK_REFERENCE.md (5 min)

   • Critical field corrections

   • Common mistakes to avoid

   • Quick checklist

3. 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:

1. IMPLEMENTATION_CORRECTIONS.md (15 min)

   • All 7 critical spec issues

   • What was wrong vs. what's correct

   • Why each correction matters

2. CLAUDE.md (30 min)

   • Complete implementation guide

   • Corrected TypeScript types

   • Database schema and queries

   • MCP tool definitions

Migrating Existing Code?

1. MIGRATION_GUIDE.md (30 min)

   • Database migration SQL

   • Code refactoring steps

   • Verification queries

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

1. Read background material (1 hour)

   • background_docs/vcon_quickstart_guide.md

   • background_docs/draft-ietf-vcon-vcon-core-02.txt (introduction)

2. Understand corrections (30 min)

   • docs/reference/QUICK_REFERENCE.md

   • docs/reference/IMPLEMENTATION_CORRECTIONS.md

3. Follow the implementation guide (4 hours)

   • CLAUDE.md — complete patterns, types, and DB schema

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

1. Review corrections (15 min)

   • docs/reference/QUICK_REFERENCE.md

2. Study implementation (30 min)

   • CLAUDE.md

3. Build core (1 hour)

   • Database schema

   • TypeScript types

   • Database queries

4. Add MCP layer (15 min)

   • Tool definitions

   • Server setup

Path 3: Migration (3 hours)

Goal: Fix existing implementation to match spec

1. Identify issues (30 min)

   • docs/reference/IMPLEMENTATION_CORRECTIONS.md

   • Compare with your code

2. Plan migration (30 min)

   • docs/reference/MIGRATION_GUIDE.md

   • Backup database and code

3. Execute migration (1.5 hours)

   • Database schema changes

   • Code refactoring

   • Update tests

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

1. Prepare instructions (15 min)

   • Read docs/reference/QUICK_REFERENCE.md

   • Set up Supabase

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

3. Review & test (10 min)

   • Verify no schema_version in code

   • Check vendor is required

   • Run npm test

🛠️ What You'll Build

Core Components

1. TypeScript Types (src/types/vcon.ts)

   • All IETF vCon objects

   • Corrected field names

   • Type validation helpers

2. Database Layer (src/db/)

   • Supabase client

   • CRUD operations

   • Search queries

3. MCP Server (src/index.ts)

   • Tool definitions

   • Request handlers

   • Error handling

4. Utilities (src/utils/)

   • vCon validation

   • Privacy helpers

   • Serialization

MCP Tools Provided (46 tools)

• CRUD: create_vcon, get_vcon, update_vcon, delete_vcon, add_party, add_dialog, add_analysis, add_attachment, create_vcon_from_template

• Sub-resource update/remove: update_party, remove_party, update_dialog, remove_dialog, update_analysis, remove_analysis, update_attachment, remove_attachment

• Search: search_vcons, search_vcons_content, search_vcons_semantic, search_vcons_hybrid

• Contract: vcon_fetch, vcon_search, vcon_capabilities, vcon_taxonomy, vcon_aggregate, vcon_graph_shape, describe_response_shape

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

• Read README.md

• Read QUICK_REFERENCE.md

• Understand the 7 critical corrections

• Have Supabase account ready

• Have Node.js 18+ installed

• Have code editor ready

• Have 4-6 hours available for first build

⚠️ 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: '[e-mail]',
    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:

• Git repository initialized

• All dependencies installed

• TypeScript compiles without errors

• Database schema matches spec

• No schema_version anywhere in code

• Analysis.vendor is required (not optional)

• Analysis.body is string type

• All compliance tests pass

• MCP server starts and lists tools

• Can create spec-compliant vCons

• Can add analysis with correct fields

• vCons are interoperable

🚀 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: June 2026 Project: vCon MCP Server Documentation v1.2.0 Spec: draft-ietf-vcon-vcon-core-02 (v0.4.0)