feat: vCon v0.4.0 spec compliance, bulk importer, and doc updates

.gitignore

@@ -38,6 +38,8 @@ out/
 # Logs
 logs/
 *.log
+verif_log.txt
+verif_analytics_log.txt
 
 # Temporary files
 tmp/
@@ -49,3 +51,24 @@ backups/
 docs/.vitepress/cache/
 docs/.vitepress/dist/
 
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Executables
+*.exe
+*.dll
+
+# Local/Secret files
+test_output.txt
+secrets.json
+*.local
+
+# Hackathon runtime files
+hackathon/watch/processed/
+hackathon/watch/failed/
+hackathon/sample-data/demo-call.mp3
+__pycache__/
+*.pyc

CLAUDE.md

@@ -4,7 +4,7 @@ This document provides comprehensive instructions for coding agents working with
 
 ## 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-00) for representing conversation data.
+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
@@ -36,13 +36,19 @@ interface AnalysisWrong {
 }
 ```
 
-### Field Name Corrections
+### 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` | Supports JSON, CSV, XML, plain text |
+| `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
 
@@ -62,7 +68,7 @@ Must be one of: `'recording'`, `'text'`, `'transfer'`, `'incomplete'`
 
 | Table | Description |
 |-------|-------------|
-| `vcons` | Main vCon container (uuid, subject, created_at, extensions, must_support) |
+| `vcons` | Main vCon container (uuid, subject, created_at, extensions, critical, amended) |
 | `parties` | Participants (tel, sip, mailto, name, uuid, did) |
 | `dialog` | Conversation segments (type, start_time, duration, body, encoding) |
 | `analysis` | AI/ML results (type, vendor, schema, body, dialog_indices) |
@@ -268,16 +274,21 @@ npm run lint      # ESLint
 
 - [ ] `analysis.schema` NOT `analysis.schema_version`
 - [ ] `analysis.vendor` is required (no `?`)
-- [ ] `analysis.body` is string type
+- [ ] `analysis.body` is string type (JSON.stringify objects)
 - [ ] No default values for `encoding` fields
 - [ ] Dialog `type` is one of: recording, text, transfer, incomplete
-- [ ] Tags stored as attachment with `type: "tags"`
+- [ ] Use `mediatype` NOT `mimetype` (dialog, analysis, attachments)
+- [ ] Use `amended` NOT `appended` (vCon top-level)
+- [ ] Use `critical` NOT `must_support` (vCon top-level)
+- [ ] `session_id` is `{local: string, remote: string}` NOT a plain string
+- [ ] Tags stored as attachment with `type: "tags"`, `encoding: "json"`
+- [ ] vcon version field is `"0.4.0"`
 
 ---
 
 ## References
 
-- IETF vCon Spec: `background_docs/draft-ietf-vcon-vcon-core-00.txt`
+- IETF vCon Spec: `background_docs/draft-ietf-vcon-vcon-core-00.txt` (v0.3.0 baseline in repo) — v0.4.0 spec available at IETF datatracker: https://datatracker.ietf.org/doc/draft-ietf-vcon-vcon-core/
 - Schema Details: `docs/reference/CORRECTED_SCHEMA.md`
 - Implementation Notes: `docs/reference/IMPLEMENTATION_CORRECTIONS.md`
 - Python vCon Library: `background_docs/LLM_GUIDE.md`

DEMO.md

@@ -0,0 +1,138 @@
+# vCon MCP Demo Guide
+
+How to load customer conversations and query them with Claude Desktop.
+
+---
+
+## 1. Import Sample Conversations
+
+Run the import script to load the sample conversations from `hackathon/sample-data/` into Supabase:
+
+```bash
+npx tsx scripts/import-demo-conversations.ts
+```
+
+To import your own folder of conversations:
+```bash
+npx tsx scripts/import-demo-conversations.ts /path/to/your/conversations/
+```
+
+**Supported formats:**
+- Plain-text call transcripts (`Agent Name: ...` / `Customer Name: ...` lines)
+- WhatsApp chat exports (`M/D/YY, H:MM AM - Name: message` format)
+- Teams JSON exports (with `_simulated.transcript` field)
+
+---
+
+## 2. Configure Claude Desktop
+
+The MCP server is already configured in `~/Library/Application Support/Claude/claude_desktop_config.json`.
+
+**Restart Claude Desktop** after any config change. You should see a hammer icon (🔨) in the chat input indicating MCP tools are available.
+
+If the server isn't connecting, test it from the terminal first:
+```bash
+node dist/index.js
+# Should output: vCon MCP Server running on stdio
+```
+
+---
+
+## 3. Demo Prompts
+
+Paste these into Claude Desktop to demonstrate the full capability of the vCon MCP server.
+
+### Explore what's in the database
+```
+How many conversations are in the vCon database? Give me a breakdown by department and channel.
+```
+
+```
+List the most recent 5 conversations with their subjects and tags.
+```
+
+### Search by topic
+```
+Find all conversations related to billing or charges. Summarize the issues customers were having.
+```
+
+```
+Search for conversations where a customer was frustrated or escalated their issue.
+```
+
+### Semantic search (requires OpenAI key)
+```
+Find conversations where customers had login or account access problems.
+```
+
+```
+Search semantically for conversations about VPN or remote work issues.
+```
+
+### Tag-based filtering
+```
+Show me all high-priority conversations. What did they have in common?
+```
+
+```
+Find all WhatsApp conversations and summarize the customer sentiment in each.
+```
+
+### Add AI analysis to a conversation
+```
+Get the billing complaint conversation. Analyze the customer sentiment, identify the root cause of the issue, and add that analysis to the vCon record.
+```
+
+### Cross-conversation insights
+```
+Look at all the support conversations in the database. What are the top 3 recurring customer pain points? Which conversations are related to the same underlying issue?
+```
+
+### Create a new vCon on the fly
+```
+Create a vCon for this conversation:
+  Customer: Alex Kim, alex.kim@example.com
+  Agent: Support Rep Jordan
+
+  Alex: I can't export my data to CSV, the button is grayed out.
+  Jordan: That feature requires the Business plan. I can upgrade you or export it manually.
+  Alex: Please export it manually for now, I'll consider the upgrade.
+  Jordan: Done, I've emailed you the CSV. Here's info on the Business plan upgrade.
+
+Tag it with department:technical-support and priority:medium.
+```
+
+### Database health check
+```
+Check the database stats and tell me if there are any performance concerns or missing indexes.
+```
+
+---
+
+## 4. What the MCP Server Can Do
+
+| Capability | Example prompt |
+|---|---|
+| Search by metadata | "Find all billing calls from March" |
+| Full-text search | "Find conversations mentioning 'refund'" |
+| Semantic search | "Find calls about frustrated customers" |
+| Tag management | "Tag the VPN call as priority:high" |
+| Add AI analysis | "Summarize this call and save it as analysis" |
+| Create vCons | "Create a vCon for this transcript I'll paste" |
+| Analytics | "What's the most common issue type?" |
+| Database inspection | "How many vCons have embeddings?" |
+
+---
+
+## 5. Troubleshooting
+
+**"No tools available" in Claude Desktop**
+- Rebuild: `npm run build` (fix pre-existing TS errors first or use the existing dist)
+- Check logs: `~/Library/Logs/Claude/mcp-server-vcon.log`
+
+**Import script fails with auth error**
+- Check `.env` has valid `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY`
+
+**Semantic search returns nothing**
+- OpenAI key required in `.env` as `OPENAI_API_KEY`
+- Run embeddings sync: `npm run sync:embeddings`

README.md

@@ -3,7 +3,7 @@
 > A Model Context Protocol (MCP) server for storing, managing, and analyzing IETF vCon (Virtual Conversation) data with AI assistants.
 
 ![Version](https://img.shields.io/badge/version-1.0.1-blue)
-![IETF Spec](https://img.shields.io/badge/IETF%20vCon-draft--00-green)
+![IETF Spec](https://img.shields.io/badge/IETF%20vCon-draft--02%20v0.4.0-green)
 ![License](https://img.shields.io/badge/license-MIT-blue)
 
 ## Overview
@@ -26,7 +26,7 @@ The Model Context Protocol (MCP) enables AI assistants to use external tools and
 
 ## Key Features
 
-- ✅ **IETF vCon Compliant** - Implements `draft-ietf-vcon-vcon-core-00` specification
+- ✅ **IETF vCon Compliant** - Implements `draft-ietf-vcon-vcon-core-02` specification (v0.4.0)
 - ✅ **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
@@ -95,8 +95,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
       "args": ["/path/to/vcon-mcp/dist/index.js"],
       "env": {
         "SUPABASE_URL": "your-project-url",
+        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key",
         "SUPABASE_ANON_KEY": "your-anon-key",
-        "REDIS_URL": "redis://localhost:6379"
+        "OPENAI_API_KEY": "your-openai-key"
       }
     }
   }