A Model Context Protocol (MCP) server for storing, managing, and analyzing IETF vCon (Virtual Conversation) data with AI assistants.
This MCP server provides a standardized way for AI assistants like Claude to interact with conversation data using the IETF vCon (Virtual Conversation) format. It combines the Model Context Protocol's tool-based interaction model with Supabase's powerful PostgreSQL backend to create a fully spec-compliant conversation data management system.
vCon (Virtual Conversation) is an IETF standard for representing conversations in a portable, interoperable format. Think of it as "PDF for conversations" - a standardized container for:
- Conversations from any medium (voice, video, text, email)
- Participants with identity and privacy controls
- AI Analysis from transcription, sentiment, summarization, etc.
- Attachments like documents, images, or related files
- Privacy markers for consent and redaction
The Model Context Protocol (MCP) enables AI assistants to use external tools and data sources. This server implements MCP to give AI assistants the ability to create, search, analyze, and manage conversation data.
- ✅ IETF vCon Compliant - Implements
draft-ietf-vcon-vcon-core-00specification - ✅ MCP Integration - 27+ tools for AI assistants to manage conversation data
- ✅ Database Analytics - Comprehensive analytics for size, growth, content patterns, and health monitoring
- ✅ Large Database Support - Smart response limiting, metadata-only options, and memory-safe queries
- ✅ OpenTelemetry Observability - Full traces, metrics, and structured logs with console or OTLP export
- ✅ Query Prompts - 9 pre-built prompts to guide effective searching and retrieval:
- Exact tag matching (e.g., "find angry customers from June")
- Semantic search (e.g., "find frustrated users")
- Keyword search (e.g., "find conversations mentioning refund")
- Multi-criteria queries with step-by-step guidance
- ✅ Supabase Backend - Powerful PostgreSQL database with REST API
- ✅ Redis Caching - Optional high-performance cache layer for 20-50x faster reads
- ✅ Type-Safe - Full TypeScript implementation with Zod validation
- ✅ Plugin Architecture - Extensible plugin system for custom functionality
- ✅ Privacy-Ready - Plugin hooks for implementing consent, redaction, and compliance
- ✅ Advanced Search - Four search tools for different use cases:
- Basic filtering (subject, parties, dates)
- Full-text keyword search (dialog, analysis, parties)
- Semantic search (AI embeddings for meaning-based search)
- Hybrid search (combines keyword and semantic)
- ✅ Tag Filtering - Filter search results by tags via
attachmentsof typetags - ✅ Content Indexing - Searches dialog bodies and analysis content (encoding='none')
- ✅ Real-time - Supabase realtime subscriptions for live updates
- ✅ Conserver Integration - Compatible with vCon conserver for chain processing
- Node.js 18+
- npm or yarn
- Supabase account (sign up free)
# Clone the repository
git clone https://github.com/vcon-dev/vcon-mcp.git
cd vcon-mcp
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env
# Edit .env with your Supabase credentials
# Build the project
npm run build
# Run tests
npm test
# Start the server
npm run devAdd to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"vcon": {
"command": "node",
"args": ["/path/to/vcon-mcp/dist/index.js"],
"env": {
"SUPABASE_URL": "your-project-url",
"SUPABASE_ANON_KEY": "your-anon-key",
"REDIS_URL": "redis://localhost:6379"
}
}
}
}Note: REDIS_URL is optional. If provided, enables high-performance caching for 20-50x faster reads. See Redis-Supabase Integration Guide.
Restart Claude Desktop and start using vCon tools!
The vCon MCP Server is available as a Docker image for easy deployment.
# Pull the image
docker pull public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main
# Run the server (using service role key for full access)
docker run -p 3000:3000 \
-e SUPABASE_URL=https://your-project.supabase.co \
-e SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
-e SUPABASE_ANON_KEY=your-anon-key \
-e MCP_HTTP_STATELESS=true \
public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:mainNote: You need either
SUPABASE_SERVICE_ROLE_KEY(recommended for full access) orSUPABASE_ANON_KEY(for restricted access). The service role key bypasses Row Level Security.
| Tag | Description |
|---|---|
main |
Latest stable build from main branch |
main-<sha> |
Specific commit (e.g., main-abc1234) |
1.2.3 |
Semantic version release |
The Docker image includes all utility scripts:
# Show available commands
docker run --rm public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main help
# Check database status
docker run --rm \
-e SUPABASE_URL=your-url \
-e SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
-e SUPABASE_ANON_KEY=your-anon-key \
public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main script check-db-status
# Run embeddings with OpenAI
docker run --rm \
-e SUPABASE_URL=your-url \
-e SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
-e SUPABASE_ANON_KEY=your-anon-key \
-e OPENAI_API_KEY=your-openai-key \
public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main script embed-vcons --provider=openai
# Run embeddings with Azure OpenAI
docker run --rm \
-e SUPABASE_URL=your-url \
-e SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
-e SUPABASE_ANON_KEY=your-anon-key \
-e AZURE_OPENAI_EMBEDDING_ENDPOINT=https://your-resource.openai.azure.com \
-e AZURE_OPENAI_EMBEDDING_API_KEY=your-azure-key \
public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main script embed-vcons --provider=azureversion: '3.8'
services:
vcon-mcp:
image: public.ecr.aws/r4g1k2s3/vcon-dev/vcon-mcp:main
ports:
- "3000:3000"
environment:
- SUPABASE_URL=${SUPABASE_URL}
- SUPABASE_SERVICE_ROLE_KEY=${SUPABASE_SERVICE_ROLE_KEY}
- SUPABASE_ANON_KEY=${SUPABASE_ANON_KEY}
- MCP_HTTP_STATELESS=trueEnable stateless mode for multiple simultaneous client connections:
-e MCP_HTTP_STATELESS=trueWhen connecting to services on your host machine (like local Supabase), use host.docker.internal:
-e SUPABASE_URL=http://host.docker.internal:54321See Docker Deployment Guide for complete documentation.
The project includes npm scripts for common database and data management operations:
# Comprehensive database status (recommended)
npm run db:status
# Quick vCon count check
npm run db:check
# Daily count analysis to identify gaps
npm run db:analyze# Load recent vCons from S3
npm run load:s3:recent
# Load from S3 with default settings
npm run load:s3
# Load from local directory
npm run load:local# Backup database
npm run db:backup
# Restore from backup
npm run db:restore# Backfill missing embeddings
npm run embeddings:backfill
# Generate embeddings locally
npm run embeddings:generate
# Check embedding coverage
npm run embeddings:check# Test database tools
npm run test:db
# Test search functionality
npm run test:search
# Test tag system
npm run test:tagsFor more details on scripts and advanced options, see scripts/README.md.
The vCon MCP Server supports multiple transport mechanisms for connecting AI assistants:
Standard input/output transport for CLI-based AI assistants like Claude Desktop.
# Default mode - no configuration needed
npm run devOr explicitly in .env:
MCP_TRANSPORT=stdioHTTP server mode enables browser-based clients and remote connections using the MCP Streamable HTTP specification (2025-03-26).
Features:
- ✅ Stateful or stateless session management
- ✅ SSE streaming for real-time responses
- ✅ JSON-only mode for simple request/response
- ✅ CORS support for browser clients
- ✅ DNS rebinding protection for security
- ✅ Session resumability (optional)
Configuration:
# .env
MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=3000
# Optional: Stateless mode (no session tracking)
# MCP_HTTP_STATELESS=true
# Optional: JSON-only responses (no SSE streaming)
# MCP_HTTP_JSON_ONLY=true
# Optional: CORS for browser clients
# MCP_HTTP_CORS=true
# MCP_HTTP_CORS_ORIGIN=*
# Optional: DNS rebinding protection
# MCP_HTTP_DNS_PROTECTION=true
# MCP_HTTP_ALLOWED_HOSTS=localhost,127.0.0.1
# MCP_HTTP_ALLOWED_ORIGINS=http://localhost:3000Starting the HTTP Server:
npm run devThe server will start on http://127.0.0.1:3000 (default) and log:
✅ vCon MCP Server running on HTTP
🌐 Listening on: http://127.0.0.1:3000
📡 Mode: Stateful
Client Connection:
# Step 1: Initialize MCP connection
curl -i -X POST http://127.0.0.1:3000 \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'
# Extract the Mcp-Session-Id from response headers
# Step 2: Send MCP requests with session ID
curl -X POST http://127.0.0.1:3000 \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Mcp-Session-Id: <session-id-from-step-1>" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
# GET request to establish SSE stream (for notifications)
curl -X GET http://127.0.0.1:3000 \
-H "Mcp-Session-Id: <your-session-id>"
# DELETE request to close session
curl -X DELETE http://127.0.0.1:3000 \
-H "Mcp-Session-Id: <your-session-id>"Session Management:
- Stateful mode (default): Server generates and tracks session IDs
- Stateless mode (
MCP_HTTP_STATELESS=true): No session tracking, each request is independent
See MCP Streamable HTTP Specification for protocol details.
When running in HTTP transport mode, the server also exposes a RESTful HTTP API for vCon operations, designed for programmatic integration with external systems.
| Method | Endpoint | Description |
|---|---|---|
GET |
/api/v1/health |
Health check (no auth required) |
POST |
/api/v1/vcons |
Create/ingest a single vCon |
POST |
/api/v1/vcons/batch |
Batch ingest up to 100 vCons |
GET |
/api/v1/vcons |
List recent vCons |
GET |
/api/v1/vcons/:uuid |
Get a vCon by UUID |
DELETE |
/api/v1/vcons/:uuid |
Delete a vCon |
# REST API settings (optional - defaults work for most cases)
REST_API_BASE_PATH=/api/v1 # Base path for endpoints
REST_API_ENABLED=true # Enable/disable REST API
# API Key Authentication
VCON_API_KEYS=key1,key2 # Comma-separated valid API keys
API_AUTH_REQUIRED=true # Set to false to disable auth# Health check
curl http://localhost:3000/api/v1/health
# Create a vCon (requires API key)
curl -X POST http://localhost:3000/api/v1/vcons \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-d '{"vcon":"0.3.0","subject":"Support Call","parties":[{"name":"Agent","tel":"+1111"}]}'
# Batch create
curl -X POST http://localhost:3000/api/v1/vcons/batch \
-H "Content-Type: application/json" \
-H "x-api-key: your-api-key" \
-d '[{"vcon":"0.3.0","parties":[{"name":"A","tel":"+1"}]},{"vcon":"0.3.0","parties":[{"name":"B","tel":"+2"}]}]'See the complete REST API Reference for detailed documentation.
Create a new vCon with parties and optional initial data.
Create a vCon for a customer support call between Alice and Bob
Retrieve a complete vCon by UUID.
Get the vCon with UUID abc-123-def
Search vCons by subject, party name, or date range (basic filtering).
Find all vCons from last week about billing
Full-text keyword search across dialog, analysis, and party content.
Search for conversations mentioning "refund request"
AI-powered semantic search to find conversations by meaning (requires embeddings).
Find conversations where customers were frustrated with delivery times
Combined keyword and semantic search for comprehensive results.
Search for billing disputes using both exact matches and similar concepts
Add AI/ML analysis results to a vCon.
Add sentiment analysis showing positive sentiment to vCon abc-123
Add a conversation segment (recording, text, video, etc.).
Add a text dialog from Alice saying "Hello, how can I help you?"
Attach files, documents, or supporting materials.
Attach the customer's invoice PDF to this vCon
Delete a vCon and all related data.
Delete the vCon abc-123
Get comprehensive database analytics including size, growth trends, and content distribution.
Get database analytics for the last 6 months
Get detailed monthly growth patterns and projections.
Show me monthly growth trends for the past year
Analyze attachment types, sizes, and storage patterns.
What types of files are being stored and how much space do they use?
Analyze tag usage patterns and value distribution.
Show me the most commonly used tags and their values
Get insights into conversation content, dialog types, and party patterns.
Analyze the types of conversations and content being stored
Monitor database performance and get optimization recommendations.
Check database health and performance metrics
Get database size information and smart recommendations for large datasets.
Get database size info and recommendations for query limits
Get smart search limits based on database size to prevent memory issues.
Get recommended limits for content search on this large database
Update top-level vCon metadata (subject, extensions, must_support).
Update vCon 01f3-... with subject "Updated Subject"
Create a new vCon from a predefined template (phone_call, chat_conversation, email_thread, video_meeting, custom).
Create a phone_call vCon with two parties and subject "Onboarding"
Get vCon schema (json_schema or typescript).
Get the vCon JSON Schema
Get example vCons (minimal, phone_call, chat, email, video, full_featured) in JSON or YAML.
Get comprehensive database structure information including tables, indexes, sizes, and relationships. Useful for debugging and understanding your database schema.
Get database performance and usage statistics including cache hit ratios, table access patterns, and index usage. Essential for performance monitoring and optimization.
Analyze SQL query execution plans for performance optimization (limited support).
Show a minimal example vCon as JSON
Tools are organized into categories that can be enabled or disabled for different deployment scenarios. By default, all categories are enabled.
| Category | Tools | Description |
|---|---|---|
read |
get_vcon, search_vcons, search_vcons_content, search_vcons_semantic, search_vcons_hybrid, get_tags, search_by_tags, get_unique_tags |
All read operations |
write |
create_vcon, update_vcon, delete_vcon, add_analysis, add_dialog, add_attachment, create_vcon_from_template, manage_tag, remove_all_tags |
All mutating operations |
schema |
get_schema, get_examples |
Documentation helpers |
analytics |
get_database_analytics, get_monthly_growth_analytics, get_attachment_analytics, get_tag_analytics, get_content_analytics, get_database_health_metrics |
Business intelligence |
infra |
get_database_shape, get_database_stats, analyze_query, get_database_size_info, get_smart_search_limits |
Admin/debugging |
Configure via environment variables:
# Option 1: Use a preset profile
MCP_TOOLS_PROFILE=readonly # Options: full, readonly, user, admin, minimal
# Option 2: Enable specific categories only
MCP_ENABLED_CATEGORIES=read,write,schema
# Option 3: Disable specific categories (starts with all enabled)
MCP_DISABLED_CATEGORIES=analytics,infra
# Option 4: Disable individual tools
MCP_DISABLED_TOOLS=delete_vcon,analyze_query| Profile | Categories | Use Case |
|---|---|---|
full |
All | Development, full access |
readonly |
read, schema | Read-only deployments |
user |
read, write, schema | End-user facing |
admin |
read, analytics, infra, schema | Admin dashboards |
minimal |
read, write | Basic CRUD only |
{
"mcpServers": {
"vcon": {
"command": "node",
"args": ["/path/to/vcon-mcp/dist/index.js"],
"env": {
"SUPABASE_URL": "your-project-url",
"SUPABASE_ANON_KEY": "your-anon-key",
"MCP_TOOLS_PROFILE": "readonly"
}
}
}
}The server exposes URI-based resources for direct reads:
vcon://v1/vcons/{uuid}– full vCon JSONvcon://v1/vcons/{uuid}/metadata– metadata onlyvcon://v1/vcons/{uuid}/parties– parties arrayvcon://v1/vcons/{uuid}/dialog– dialog arrayvcon://v1/vcons/{uuid}/attachments– attachments arrayvcon://v1/vcons/{uuid}/analysis– analysis arrayvcon://v1/vcons/{uuid}/transcript– transcript analysis (filtered)vcon://v1/vcons/{uuid}/summary– summary analysis (filtered)vcon://v1/vcons/{uuid}/tags– tags as object (parsed)
- Capture and analyze customer calls
- Generate automatic transcripts
- Track agent performance and sentiment
- Maintain compliance audit trails
- Record sales conversations
- Extract action items and follow-ups
- Analyze conversation patterns
- Generate meeting summaries
- Collect conversation datasets
- Analyze communication patterns
- Generate insights from dialogue
- Build ML training data
- Maintain conversation archives
- Apply redaction for privacy
- Track consent and permissions
- Generate audit reports
┌─────────────────────┐
│ AI Assistant │ (Claude, ChatGPT, etc.)
│ (Client) │
└──────────┬──────────┘
│ MCP Protocol (stdio)
│
┌──────────▼──────────┐
│ vCon MCP Server │ (This project)
│ │
│ ┌───────────────┐ │
│ │ MCP Tools │ │ - create_vcon
│ │ │ │ - add_analysis
│ └───────┬───────┘ │ - search_vcons
│ │ │ - etc.
│ ┌───────▼───────┐ │
│ │ vCon Queries │ │ - CRUD operations
│ │ │ │ - Validation
│ └───────┬───────┘ │ - Type checking
│ │ │
└──────────┼──────────┘
│ Supabase Client
│
┌──────────▼──────────┐
│ Supabase │
│ (PostgreSQL) │
│ │
│ ┌───────────────┐ │
│ │ vCon Tables │ │ - vcons
│ │ │ │ - parties
│ └───────────────┘ │ - dialog
│ ┌───────────────┐ │ - analysis
│ │ pgvector │ │ - attachments
│ │ (embeddings) │ │
│ └───────────────┘ │
└─────────────────────┘
For high-performance deployments, add Redis as a cache layer:
┌─────────────────────────────────────────────────┐
│ AI Assistant │
└─────────────────────┬───────────────────────────┘
│ MCP Protocol
┌─────────────────────▼───────────────────────────┐
│ vCon MCP Server │
│ │
│ ┌───────────────────────────────────────────┐ │
│ │ Cache-First Reads │ │
│ │ Redis (hot) → Supabase (cold fallback) │ │
│ └───────────────────────────────────────────┘ │
└─────────────┬───────────────────┬───────────────┘
│ │
┌───────▼───────┐ ┌───────▼───────┐
│ Redis Cache │ │ Supabase │
│ (Optional) │ │ (Permanent) │
│ │ │ │
│ - Fast reads │ │ - Source of │
│ - TTL expiry │ │ truth │
│ - Auto cache │ │ - Full CRUD │
└───────────────┘ └───────────────┘
Enable caching by setting REDIS_URL environment variable. See Redis-Supabase Integration Guide for details.
Performance: Redis caching provides 20-50x faster reads for frequently accessed vCons.
Built-in OpenTelemetry instrumentation provides production-ready monitoring:
- Distributed Tracing: Full request lifecycle tracing with spans for every operation
- Business Metrics: Track vCon operations, search patterns, and usage
- Performance Metrics: Monitor query duration, cache hit rates, and latency
- Structured Logging: JSON logs with automatic trace context correlation
- Flexible Export: Console (development) or OTLP (production) exporters
# Development (console export)
OTEL_ENABLED=true
OTEL_EXPORTER_TYPE=console
# Production (OTLP collector)
OTEL_ENABLED=true
OTEL_EXPORTER_TYPE=otlp
OTEL_ENDPOINT=http://localhost:4318vcon.created.count- vCons createdvcon.deleted.count- vCons deletedvcon.search.count- Searches performed (by type)tool.execution.duration- Tool execution timedb.query.count- Database queriescache.hit/cache.miss- Cache performance
Testing Setup (Recommended):
# Start Jaeger backend using docker-compose
./jaeger/start-jaeger.sh
# Configure .env
OTEL_ENABLED=true
OTEL_EXPORTER_TYPE=otlp
OTEL_ENDPOINT=http://localhost:4318
# View traces at http://localhost:16686Manual Docker Setup:
# Jaeger (all-in-one)
docker run -d -p 4318:4318 -p 16686:16686 jaegertracing/all-in-one:latest
# View traces at http://localhost:16686See Observability Guide for complete documentation.
vcon-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── types/
│ │ └── vcon.ts # IETF vCon type definitions
│ ├── db/
│ │ ├── client.ts # Supabase client
│ │ └── queries.ts # Database operations
│ ├── tools/
│ │ └── vcon-crud.ts # MCP tool definitions
│ └── utils/
│ └── validation.ts # vCon validation
├── supabase/
│ └── migrations/ # Database migrations
├── tests/
│ └── vcon-compliance.test.ts
├── docs/
│ └── reference/ # Technical reference docs
│ ├── QUICK_REFERENCE.md
│ ├── IMPLEMENTATION_CORRECTIONS.md
│ ├── CORRECTED_SCHEMA.md
│ └── MIGRATION_GUIDE.md
├── background_docs/ # IETF specs & references
├── BUILD_GUIDE.md # Step-by-step implementation guide
├── GETTING_STARTED.md # Quick start for developers
├── OPEN_SOURCE_FEATURES.md # Open source feature set
├── PORPRIETARY_FEATURES.md # Enterprise features
├── SUPABASE_SEMANTIC_SEARCH_GUIDE.md
└── README.md # This file
- Getting Started - Quick start guide for using the server
- Docker Deployment - Complete Docker deployment guide
- Query Prompts Guide - How to use search and retrieval prompts
- Search Tools Guide - Search strategies and tools
- Tag Management Guide - Tagging and organization
- RLS Multi-Tenant Guide - Row Level Security setup for multi-tenant isolation
- Open Source Features - Complete feature reference
- Proprietary Features - Enterprise and advanced features
- Build Guide - Step-by-step implementation from scratch
- Supabase Semantic Search - Vector search setup
- Plugin Development - Creating custom plugins
- Database Documentation Index - Start here - Overview of all LLM documentation
- Database Architecture for LLMs - Complete database design and structure
- Database Quick Start for LLMs - Practical code examples and patterns
- Database Schema Visual Reference - Visual entity relationship diagrams
- REST API - HTTP REST API for vCon ingestion
- Tools API - MCP tools reference
- Prompts API - MCP prompts reference
- Resources API - MCP resources reference
- Types - TypeScript type definitions
- Quick Reference - Critical spec corrections checklist
- Implementation Corrections - Detailed spec compliance guide
- Corrected Schema - Database schema reference
- Migration Guide - Migrating existing code
- IETF vCon Core Spec - Official specification
- vCon Consent Draft - Privacy and consent
- vCon Lifecycle Draft - Lifecycle management
- vCon Quick Start - vCon basics
- vCon Adapter Guide - Building adapters
# Start Supabase (if using local)
supabase start
# Run in development mode
npm run dev
# Run tests
npm test
# Run spec compliance tests
npm run test:compliance
# Launch MCP test console (interactive)
npm run test:console
# Build for production
npm run build
# Lint code
npm run lintThe project includes comprehensive tests:
- Unit tests - Type validation, query functions
- Integration tests - End-to-end vCon operations
- Compliance tests - IETF spec conformance
# Run all tests
npm test
# Run with coverage
npm test -- --coverage
# Run specific test file
npm test tests/vcon-compliance.test.tsThe project uses Supabase with a carefully designed schema:
- 8 tables for vCon data model
- 25 indexes for query performance
- Row Level Security for multi-tenancy (configurable tenant extraction from attachments)
- pgvector for semantic search
- Realtime subscriptions enabled
See BUILD_GUIDE.md for complete database setup instructions. See RLS Multi-Tenant Guide for enabling multi-tenant isolation.
This implementation is fully compliant with draft-ietf-vcon-vcon-core-00, including:
- ✅ vCon container with all required fields
- ✅ Party objects with complete metadata
- ✅ Dialog objects (recording, text, transfer, incomplete)
- ✅ Analysis objects with vendor and schema fields
- ✅ Attachment objects with proper references
- ✅ Group objects for multi-party conversations
- ✅ Correct field names (e.g.,
schemanotschema_version) - ✅ Required vs optional fields properly enforced
- ✅ String-based body fields (not object types)
- ✅ No default encoding values
- ✅ Proper type constraints
- ✅ Redaction support
- ✅ Consent tracking
- ✅ Party privacy markers
- ✅ Secure attachment handling
const vcon = await createVCon({
subject: "Customer Support Call",
parties: [
{
name: "Alice Agent",
mailto: "alice@support.example.com",
role: "agent"
},
{
name: "Bob Customer",
tel: "+1-555-0100",
role: "customer"
}
]
});await addAnalysis(vconUuid, {
type: "transcript",
vendor: "OpenAI",
product: "Whisper-1",
schema: "v1.0",
body: "Full transcript text...",
encoding: "none",
dialog: [0] // References first dialog
});const results = await searchVCons({
subject: "billing",
partyName: "Alice",
startDate: "2025-01-01",
endDate: "2025-01-31"
});- IETF vCon type definitions
- Supabase database schema
- Basic CRUD operations
- MCP server implementation
- Validation and testing
- Semantic search with pgvector
- Real-time subscriptions
- Batch operations
- Export/import formats
- Multi-tenant support (RLS with configurable tenant extraction)
- Advanced privacy controls
- Audit logging
- Performance optimization
- Twilio adapter
- Zoom adapter
- Slack adapter
- Microsoft Teams adapter
The vCon MCP Server is highly extensible, supporting multiple ways to add custom functionality:
| Extension Type | Purpose | Use Case | Packaging |
|---|---|---|---|
| Resources | Discoverable data access | Browse recent vCons, statistics | Direct or plugin |
| Prompts | Guided query templates | Help users search effectively | Direct only |
| Tools | Executable operations | Analytics, exports, custom searches | Direct or plugin |
| Plugins | Package multiple features | Privacy suite, compliance module | Plugin |
| Hooks | Modify core behavior | Audit logging, access control | Plugin only |
// src/resources/index.ts
export function getCoreResources(): ResourceDescriptor[] {
return [
// ... existing resources ...
{
uri: 'vcon://v1/analytics/summary',
name: 'Analytics Summary',
description: 'Overall conversation analytics',
mimeType: 'application/json'
}
];
}// src/tools/analytics-tools.ts
export const analyticsTool = {
name: 'get_analytics',
description: 'Get conversation analytics',
inputSchema: {
type: 'object' as const,
properties: {
period: { type: 'string', enum: ['7d', '30d', '90d'] }
},
required: ['period']
}
};
export async function handleGetAnalytics(input: any): Promise<ToolResponse> {
// Implementation
}import { VConPlugin, RequestContext } from '@vcon/mcp-server/hooks';
export default class MyPlugin implements VConPlugin {
name = 'my-plugin';
version = '1.0.0';
// Register custom tools
registerTools(): Tool[] {
return [/* your tools */];
}
// Register custom resources
registerResources(): Resource[] {
return [/* your resources */];
}
// Lifecycle hook example
async afterCreate(vcon: VCon, context: RequestContext): Promise<void> {
console.log(`Created vCon: ${vcon.uuid}`);
}
}# Set environment variable
VCON_PLUGINS_PATH=@mycompany/vcon-plugin,./local-plugin.js
VCON_LICENSE_KEY=your-license-key-if-required
# Run server with plugins
npm run dev- Extension Guide - Comprehensive guide with examples
- Extension Quick Reference - Fast lookup and decision guide
- Plugin Development - Complete plugin documentation
- Custom Tools - Tool development guide
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests (
npm test) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow the existing code style
- Add tests for new features
- Update documentation
- Ensure IETF spec compliance
- Reference spec sections in comments
MIT License - see LICENSE file for details
- GitHub: vcon-mcp
- Issues: Bug reports & feature requests
- Discussions: Community discussions
- IETF vCon Working Group: datatracker.ietf.org/wg/vcon
- Model Context Protocol: modelcontextprotocol.io
- Supabase: supabase.com
- vCon GitHub: github.com/vcon-dev
- 📧 Email: ohjesus@doesanyoneemail.anymore
- 💬 Discord: Join our community
- 📖 Documentation: Full docs
- 🐛 Bug Reports: GitHub Issues
- IETF vCon Working Group for the specification
- Anthropic for the Model Context Protocol
- Supabase for the amazing PostgreSQL platform
- Contributors who helped build and improve this project
Built with ❤️ for the conversation intelligence community
Making conversations accessible, analyzable, and actionable with AI