Complete TypeScript type definitions for the vCon MCP Server.
The vCon MCP Server provides full type safety through TypeScript and Zod validation. All types comply with IETF vCon Core specification.
Main vCon object representing a complete virtual conversation.
interface VCon {
// Core Metadata (Section 4.1)
vcon: string; // vCon version (e.g., "0.4.0")
uuid: string; // vCon UUID (RFC 4122)
created_at: string; // ISO 8601 timestamp
updated_at?: string; // ISO 8601 timestamp
subject?: string; // Conversation subject/title
// Extensions (Section 4.1.3)
extensions?: string[]; // Extension identifiers
must_support?: string[]; // Required extension support
// Components
parties: Party[]; // Participants (at least 1 required)
dialog?: Dialog[]; // Conversation segments
analysis?: Analysis[]; // AI/ML analysis results
attachments?: Attachment[]; // Additional files/data
// Advanced Features
group?: Group[]; // vCon grouping (Section 4.6)
redacted?: Record<string, any>; // Redaction tracking
appended?: Record<string, any>; // Append-only modifications
}Represents a participant in a conversation (Section 4.2).
interface Party {
// Contact Information
tel?: string; // Phone number (E.164 format)
sip?: string; // SIP URI
mailto?: string; // Email address
name?: string; // Display name
// Identity & Verification (Section 4.2.3-4.2.6)
stir?: string; // STIR/SHAKEN PASSporT
did?: string; // Decentralized Identifier
uuid?: string; // UUID for this party (RFC 4122)
validation?: string; // Identity validation info
// Location (Section 4.2.7-4.2.9)
timezone?: string; // IANA timezone
gmlpos?: string; // GML position
civicaddress?: object; // RFC 5139 civic address
// vCard (Section 4.2.10)
jcard?: object; // JSON vCard (RFC 7095)
// At least one contact method required
}Party Examples:
// Phone party
{
tel: "+1-555-1234",
name: "John Doe",
timezone: "America/New_York"
}
// Email party
{
mailto: "support@example.com",
name: "Support Agent",
uuid: "550e8400-e29b-41d4-a716-446655440000"
}
// SIP party
{
sip: "sip:user@example.com",
name: "Alice Smith",
stir: "eyJhbGciOiJFUzI1NiIsInR5cCI6InBhc3Nwb3J0..."
}Represents a segment of conversation content (Section 4.3).
interface Dialog {
// Required
type: "recording" | "text" | "transfer" | "incomplete";
// Timing (Section 4.3.2-4.3.3)
start?: string; // ISO 8601 timestamp
duration?: number; // Duration in seconds
// Participants (Section 4.3.4-4.3.5)
parties?: number | number[]; // Party index or array of indexes
originator?: number; // Party index of originator
// Content
body?: string; // Dialog content
encoding?: "none" | "base64url" | "json";
url?: string; // External URL
// Media (Section 4.3.6-4.3.7)
mediatype?: string; // MIME type
filename?: string; // Original filename
// Call Disposition (Section 4.3.9)
disposition?:
| "no-answer"
| "congestion"
| "failed"
| "busy"
| "hung-up"
| "voicemail-no-message";
// Session Tracking (Section 4.3.10, 4.3.13, 4.3.14)
session_id?: string; // Session identifier
application?: string; // Application that created dialog
message_id?: string; // Message identifier
// Integrity
content_hash?: string | string[]; // SHA-256 hash
}Dialog Examples:
// Text message
{
type: "text",
start: "2025-10-14T10:30:00Z",
parties: [0, 1],
originator: 1,
body: "Hello, I need help with my account.",
encoding: "none"
}
// Audio recording
{
type: "recording",
start: "2025-10-14T10:30:00Z",
duration: 185.5,
parties: [0, 1],
mediatype: "audio/mpeg",
filename: "call-recording.mp3",
url: "https://storage.example.com/recordings/abc123.mp3",
encoding: "none"
}
// Video call
{
type: "recording",
start: "2025-10-14T14:00:00Z",
duration: 3600,
parties: [0, 1, 2],
mediatype: "video/mp4",
session_id: "video-call-abc123",
application: "Zoom",
disposition: "hung-up"
}AI/ML analysis results for conversation content (Section 4.5).
interface Analysis {
// Required
type: string; // Analysis type (see types below)
vendor: string; // REQUIRED: Vendor/producer
// References (Section 4.5.2)
dialog?: number | number[]; // Dialog index(es) analyzed
// Product Info (Section 4.5.6-4.5.7)
product?: string; // Product/model name
schema?: string; // Schema identifier/version
// Content (Section 4.5.8)
body?: string; // Analysis content (any format)
encoding?: "none" | "json" | "base64url";
url?: string; // External URL
// Media
mediatype?: string; // MIME type of body
filename?: string; // Filename if applicable
// Integrity
content_hash?: string | string[]; // SHA-256 hash
}Common Analysis Types:
| Type | Description | Body Format |
|---|---|---|
summary |
Conversation summary | Text or JSON |
transcript |
Speech-to-text | Text or JSON with timestamps |
translation |
Language translation | Text or JSON |
sentiment |
Sentiment analysis | JSON with scores |
keywords |
Keyword extraction | JSON array |
entities |
Named entity recognition | JSON |
topics |
Topic classification | JSON |
action_items |
Action item extraction | JSON array |
pii_detection |
PII identification | JSON |
Analysis Examples:
// Sentiment analysis
{
type: "sentiment",
vendor: "OpenAI",
product: "GPT-4",
schema: "v1.0",
dialog: [0],
body: JSON.stringify({
sentiment: "positive",
score: 0.85,
confidence: 0.92
}),
encoding: "json"
}
// Transcript
{
type: "transcript",
vendor: "Google Cloud",
product: "Speech-to-Text",
dialog: [0],
body: JSON.stringify({
transcript: "Hello, I need help with my account.",
confidence: 0.98,
language: "en-US"
}),
encoding: "json"
}
// Summary
{
type: "summary",
vendor: "Anthropic",
product: "Claude-3.5",
body: "Customer called about billing issue. Agent provided refund.",
encoding: "none"
}Additional files or data associated with a conversation (Section 4.4).
interface Attachment {
// Type & Timing
type?: string; // Attachment type
start?: string; // ISO 8601 timestamp
// References (Section 4.4.3-4.4.4)
party?: number; // Associated party index
dialog?: number; // Associated dialog index
// Content
body?: string; // Attachment content
encoding?: "none" | "json" | "base64url";
url?: string; // External URL
// Media
mediatype?: string; // MIME type
filename?: string; // Original filename
// Integrity
content_hash?: string | string[]; // SHA-256 hash
}Special Attachment Types:
// Tags attachment (for metadata)
{
type: "tags",
encoding: "json",
body: JSON.stringify([
"department:sales",
"priority:high",
"customer_id:12345"
])
}
// PDF document
{
type: "invoice",
party: 0,
mediatype: "application/pdf",
filename: "invoice-12345.pdf",
body: "base64-encoded-content",
encoding: "base64url"
}
// Screenshot
{
type: "screenshot",
dialog: 0,
mediatype: "image/png",
filename: "error-screenshot.png",
url: "https://storage.example.com/screenshots/abc.png",
encoding: "none"
}Reference to other vCons for grouping (Section 4.6).
interface Group {
// Reference
uuid?: string; // UUID of referenced vCon
url?: string; // External URL to vCon
// Inline Content
body?: string; // Inline vCon content
encoding: "json"; // Must be 'json' per spec
// Integrity
content_hash?: string | string[]; // SHA-256 hash
// Exactly one of: uuid, url, or body+encoding required
}interface CreateVConInput {
vcon_data: {
vcon?: string; // Default: "0.4.0"
uuid?: string; // Auto-generated if not provided
subject?: string;
parties: Party[]; // At least 1 required
dialog?: Dialog[];
analysis?: Analysis[];
attachments?: Attachment[];
extensions?: string[];
must_support?: string[];
};
metadata?: {
basename?: string;
filename?: string;
tags?: Record<string, string>;
};
validate_before_insert?: boolean; // Default: true
}interface SearchVConsInput {
// Metadata Filters
subject?: string; // Subject text search
party_name?: string; // Party name search
party_email?: string; // Party email search
party_tel?: string; // Party phone search
// Date Filters
start_date?: string; // ISO 8601
end_date?: string; // ISO 8601
// Pagination
limit?: number; // Default: 50, Max: 1000
offset?: number; // For pagination
}interface SearchVConsContentInput {
query: string; // REQUIRED: Search query
tags?: Record<string, string>; // Tag filters
start_date?: string; // ISO 8601
end_date?: string; // ISO 8601
limit?: number; // Default: 50
include_snippets?: boolean; // Default: true
}interface SearchVConsSemanticInput {
query?: string; // Natural language query
embedding?: number[]; // Or provide embedding (384 dims)
threshold?: number; // Similarity threshold (0-1), default: 0.7
tags?: Record<string, string>; // Tag filters
limit?: number; // Default: 20
}interface SearchVConsHybridInput {
query: string; // REQUIRED: Search query
semantic_weight?: number; // 0-1, default: 0.6
tags?: Record<string, string>; // Tag filters
start_date?: string; // ISO 8601
end_date?: string; // ISO 8601
limit?: number; // Default: 30
}interface ManageTagInput {
vcon_uuid: string; // UUID (RFC 4122)
action: "set" | "remove"; // Action to perform
key: string; // Tag key
value?: string | number | boolean; // Tag value (required for "set")
}
interface GetTagsInput {
vcon_uuid: string; // UUID (RFC 4122)
key?: string; // Specific tag key (optional)
default_value?: any; // Default if key not found
}
interface SearchByTagsInput {
tags: Record<string, string>; // REQUIRED: Tag key-value pairs
limit?: number; // Default: 50, Max: 100
}
interface GetUniqueTagsInput {
include_counts?: boolean; // Include usage statistics
key_filter?: string; // Filter by key substring
min_count?: number; // Minimum occurrence count
}interface StandardResponse {
success: boolean;
message?: string;
error?: string;
details?: any;
}interface CreateVConResponse extends StandardResponse {
uuid: string;
vcon?: VCon;
}interface GetVConResponse extends StandardResponse {
vcon: VCon;
}interface SearchResponse<T> extends StandardResponse {
count: number;
results: T[];
has_more?: boolean;
}interface SearchContentResult {
vcon_id: string;
content_type: "subject" | "dialog" | "analysis" | "party";
content_index?: number;
relevance_score: number;
snippet?: string;
vcon?: VCon;
}interface SearchSemanticResult {
vcon_id: string;
similarity_score: number;
matched_content: {
subject?: string;
dialog_excerpts?: Array<{
dialog_index: number;
text: string;
relevance: number;
}>;
};
vcon?: VCon;
}interface SearchHybridResult {
vcon_id: string;
combined_score: number;
keyword_score: number;
semantic_score: number;
vcon?: VCon;
}interface GetTagsResponse extends StandardResponse {
vcon_uuid: string;
tags: Record<string, string | number | boolean>;
count: number;
}
interface GetTagResponse extends StandardResponse {
key: string;
value: any;
exists: boolean;
}
interface UniqueTagsResponse extends StandardResponse {
unique_keys: string[];
unique_key_count: number;
tags_by_key: Record<string, string[]>;
counts_per_value?: Record<string, Record<string, number>>;
total_vcons_with_tags: number;
}All types are validated using Zod schemas. Example:
import { z } from 'zod';
const PartySchema = z.object({
tel: z.string().optional(),
sip: z.string().optional(),
mailto: z.string().email().optional(),
name: z.string().optional(),
did: z.string().optional(),
uuid: z.string().uuid().optional(),
validation: z.string().optional(),
timezone: z.string().optional(),
jcard: z.any().optional(),
gmlpos: z.string().optional(),
civicaddress: z.any().optional()
}).refine(
data => data.tel || data.sip || data.mailto,
{ message: "At least one contact method required" }
);// Check if vCon is valid
function isValidVCon(obj: any): obj is VCon {
return (
typeof obj.vcon === 'string' &&
typeof obj.uuid === 'string' &&
Array.isArray(obj.parties) &&
obj.parties.length > 0
);
}
// Check dialog type
function isTextDialog(dialog: Dialog): boolean {
return dialog.type === 'text';
}
// Check if analysis has JSON body
function hasJsonAnalysis(analysis: Analysis): boolean {
return analysis.encoding === 'json' && !!analysis.body;
}// vCon Version
export const VCON_VERSION = '0.4.0';
// Dialog Types
export const DIALOG_TYPES = ['recording', 'text', 'transfer', 'incomplete'] as const;
// Encoding Types
export const ENCODING_TYPES = ['none', 'base64url', 'json'] as const;
// Disposition Values
export const DISPOSITIONS = [
'no-answer',
'congestion',
'failed',
'busy',
'hung-up',
'voicemail-no-message'
] as const;
// Common Analysis Types
export const ANALYSIS_TYPES = [
'summary',
'transcript',
'translation',
'sentiment',
'keywords',
'entities',
'topics',
'action_items',
'pii_detection'
] as const;- See Tools Reference for tool definitions
- See Database Schema for database structure
- See Examples for usage examples
- See vCon Spec for full specification