vcon-mcp CLAUDE.md

Claude Code Instructions for vCon MCP Server

This document provides comprehensive instructions for coding agents working with the vCon MCP Server codebase.

Project Overview

This is an MCP (Model Context Protocol) server for managing vCon (Virtual Conversation) data stored in Supabase. vCon is an IETF standard (draft-ietf-vcon-vcon-core-02, spec version 0.4.0) for representing conversation data.

Key Technologies:

• TypeScript
• MCP SDK (@modelcontextprotocol/sdk)
• Koa v3 (koa, @koa/router) for REST API
• Supabase (PostgreSQL)
• Zod for validation

---

Critical IETF Spec Compliance

Analysis Object - MUST READ

// CORRECT
interface Analysis {
  type: string;
  vendor: string;           // REQUIRED - not optional!
  schema?: string;          // CORRECT field name
  body?: string;            // String type (not object)
  encoding?: 'base64url' | 'json' | 'none';
}

// WRONG - DO NOT USE
interface AnalysisWrong {
  schema_version?: string;  // WRONG - use 'schema'
  vendor?: string;          // WRONG - vendor is required
  body?: object;            // WRONG - body is string
}

Field Name Corrections (spec -02 / v0.4.0)

Wrong	Correct	Notes
schema_version	schema	Analysis object field
vendor?: string	vendor: string	Required in Analysis
body: object	body: string	JSON.stringify objects before storing
mimetype	mediatype	dialog, analysis, attachments (since v0.0.2)
appended	amended	vCon top-level (renamed in v0.4.0)
must_support	critical	vCon top-level (renamed in v0.4.0)
session_id: string	session_id: {local, remote}	Dialog (changed in v0.4.0)

Import note: Real-world vCon files (e.g. Strolid) may use v0.0.1 field names (mimetype, appended, must_support). The import script handles both old and new field names transparently.

Encoding Field

• Valid values: 'base64url', 'json', 'none'
• NO default value - must be explicitly set
• Applied to: Dialog, Analysis, Attachment objects