Troubleshooting

Common issues and solutions for the vCon MCP Server.

Installation Issues

Error: "Cannot find module 'dotenv'"

Symptom:

Error: Cannot find module 'dotenv'

Cause: Dependencies not installed

Solution:

npm install

---

Error: "ENOENT: no such file or directory, open 'dist/index.js'"

Symptom:

Error: ENOENT: no such file or directory, open '/path/to/vcon-mcp/dist/index.js'

Cause: Project not built

Solution:

npm run build

---

Error: "Invalid Supabase URL"

Symptom:

Error: Invalid Supabase URL or API key

Cause: Missing or incorrect environment variables

Solution:

1. Check .env file exists:

   cat .env

2. Verify format (no quotes needed):

   SUPABASE_URL=https://your-project.supabase.co
   SUPABASE_ANON_KEY=eyJ...

3. Get correct values from Supabase:

   • Dashboard → Settings → API

   • Copy Project URL and anon public key

---

Database Issues

Error: "relation 'vcons' does not exist"

Symptom:

Error: relation "vcons" does not exist

Cause: Database migrations not applied

Solution:

Option A: Using Supabase CLI

npx supabase db push

Option B: Manual via Dashboard

1. Go to Supabase SQL Editor

2. Run each migration from supabase/migrations/ in order

3. Verify tables created:

   SELECT table_name FROM information_schema.tables 
   WHERE table_schema = 'public';

---

Error: "permission denied for table vcons"

Symptom:

Error: permission denied for table vcons

Cause: RLS policies not configured or using wrong key

Solution:

1. Check you're using the correct key (anon key, not service role key for testing)

2. Verify RLS policies exist:

   SELECT * FROM pg_policies WHERE tablename = 'vcons';

3. If missing, run RLS migration:

   # In Supabase SQL Editor
   -- Run: supabase/migrations/003_rls_policies.sql

---

Database connection timeout

Symptom:

Error: Connection timeout

Cause: Network issues or invalid URL

Solution:

1. Test connection:

   curl "https://your-project.supabase.co/rest/v1/" \
     -H "apikey: your-anon-key"

   Should return 200 OK

2. Check Supabase project is active (not paused)

3. Verify URL format: https://PROJECT_ID.supabase.co

---

Claude Desktop Issues

Claude Desktop doesn't show vCon tools

Symptom: Claude doesn't list vCon tools when asked "What tools do you have?"

Checklist:

1. ✅ Built the project

   npm run build
   ls -la dist/index.js  # Should exist

2. ✅ Used absolute path in config

   # Get absolute path
   cd /path/to/vcon-mcp && pwd
   # Use: /full/path/to/vcon-mcp/dist/index.js

3. ✅ Restarted Claude Desktop completely

   • Quit Claude Desktop (not just close window)

   • Reopen Claude Desktop

   • Start new conversation

4. ✅ .env file in project root

   ls -la /path/to/vcon-mcp/.env  # Should exist

5. ✅ Valid Supabase credentials

   cat .env  # Check values

Debug Steps:

1. Test server directly:

   node dist/index.js

   Should output MCP initialization messages Press Ctrl+C to stop

2. Check config syntax:

   # macOS
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

   Verify valid JSON (no trailing commas, proper brackets)

3. Check logs:

   • Open Claude Desktop

   • Help → View Logs

   • Look for MCP server errors

---

Error: "spawn node ENOENT"

Symptom:

Error: spawn node ENOENT

Cause: Node.js not in PATH for Claude Desktop

Solution:

macOS:

{
  "mcpServers": {
    "vcon": {
      "command": "/usr/local/bin/node",  // Full path to node
      "args": ["/absolute/path/to/vcon-mcp/dist/index.js"]
    }
  }
}

Find node path:

which node

---

Claude can't find vCons

Symptom:

No vCons found

Cause: Empty database

Solution:

Create test vCon:

Create a vCon with subject "Test" and party "Alice"

Verify in database:

SELECT uuid, subject FROM vcons;

---

Runtime Errors

Error: "vCon validation failed"

Symptom:

Error: vCon validation failed: [validation details]

Cause: Invalid vCon data structure

Solution:

1. Check error message for specific field

2. Verify required fields:

   • vcon version (e.g., "0.4.0")

   • uuid (valid UUID)

   • created_at (ISO 8601 timestamp)

   • At least one party

3. Use valid values:

   {
     vcon: "0.4.0",
     uuid: "valid-uuid-here",
     created_at: "2025-01-15T10:00:00Z",
     parties: [{
       name: "Alice"
     }]
   }

---

Error: "Analysis vendor required"

Symptom:

Error: Analysis must have vendor field

Cause: Missing required vendor field in analysis

Solution:

Always include vendor when adding analysis:

Add transcript analysis with vendor "OpenAI"

---

Error: "Invalid UUID format"

Symptom:

Error: Invalid UUID format

Cause: Malformed UUID

Solution:

Use valid UUID v4 format:

abc12345-1234-1234-1234-123456789abc

Get UUID from vCon list:

Show me recent vCons

---

Search Issues

Semantic search not working

Symptom:

Error: Semantic search requires embeddings

Cause: Embeddings not configured or generated

Solution:

1. Enable pgvector extension:

   CREATE EXTENSION IF NOT EXISTS vector;

2. Run vector migrations:

   # In Supabase SQL Editor
   -- Run: supabase/migrations/005_vector_extension.sql
   -- Run: supabase/migrations/006_embeddings_table.sql

3. Add OpenAI API key:

   echo "OPENAI_API_KEY=sk-your-key" >> .env

4. Generate embeddings:

   npm run scripts/generate-embeddings-v2.ts

---

Search returns no results

Symptom: Search finds nothing when data exists

Cause: Various possibilities

Solutions:

1. Check data exists:

   Show me all vCons

2. Try simpler search:

   Find vCons from the last month

3. Check search mode:

   • Basic search: subject/party/dates only

   • Keyword search: full-text in dialog/analysis

   • Semantic search: requires embeddings

4. Verify content is searchable:

   • Dialog must have encoding: "none" for keyword search

   • Attachments not included in search

---

Performance Issues

Slow queries

Symptom: Queries take >2 seconds

Cause: Missing indexes or large dataset

Solution:

1. Check indexes exist:

   SELECT * FROM pg_indexes WHERE tablename IN ('vcons', 'dialog', 'analysis');

2. Run index migration:

   # In Supabase SQL Editor
   -- Run: supabase/migrations/002_indexes.sql

3. Analyze tables:

   ANALYZE vcons;
   ANALYZE dialog;
   ANALYZE analysis;

4. Check database stats:

   Show me database performance stats

---

Out of memory

Symptom:

Error: JavaScript heap out of memory

Cause: Large dataset operations

Solution:

1. Increase Node.js memory:

   node --max-old-space-size=4096 dist/index.js

2. Use pagination in searches:

   Find first 10 vCons from January

3. Use resources for simple reads:

   Read vcon://v1/vcons/abc-123/metadata

---

Testing Issues

Tests fail with "database connection error"

Symptom:

Error: Database connection failed

Cause: Test environment not configured

Solution:

1. Create .env.test file:

   cp .env .env.test

2. Use test database (separate from production):

   SUPABASE_URL=https://test-project.supabase.co
   SUPABASE_ANON_KEY=test-key

3. Run migrations on test database

4. Run tests:

   npm test

---

Tests pass but code fails

Symptom: Tests succeed but actual usage fails

Cause: Different environment (test vs production)

Solution:

1. Verify .env vs .env.test settings

2. Check both databases have same schema

3. Test with production credentials (carefully)

4. Add integration tests:

   npm run test:integration

---

Plugin Issues

Plugin not loading

Symptom:

Error: Could not load plugin: ./my-plugin.js

Cause: Plugin path or format incorrect

Solution:

1. Verify plugin path:

   ls -la ./my-plugin.js  # Should exist

2. Check plugin format:

   export default class MyPlugin {
     name = 'my-plugin';
     version = '1.0.0';
     // ... implementation
   }

3. Check environment variable:

   echo $VCON_PLUGINS_PATH

4. Test plugin loading:

   node -e "require('./my-plugin.js')"

---

Build Issues

TypeScript compilation errors

Symptom:

Error: TypeScript compilation failed

Solution:

1. Check TypeScript version:

   npx tsc --version  # Should be 5.x

2. Clean and rebuild:

   rm -rf dist node_modules
   npm install
   npm run build

3. Fix type errors shown in output

---

Missing dependencies

Symptom:

Error: Cannot find module '@modelcontextprotocol/sdk'

Solution:

npm install

If persists:

rm -rf node_modules package-lock.json
npm install

---

Getting More Help

Debug Mode

Enable detailed logging:

LOG_LEVEL=debug node dist/index.js

Verbose Tests

npm test -- --reporter=verbose

Check System Status

# Node.js
node --version

# npm
npm --version

# Dependencies
npm list --depth=0

# Build status
ls -la dist/

# Environment
cat .env

Report Issues

If you can't resolve an issue:

1. Search existing issues: GitHub Issues

2. Create new issue with:

   • Error message (full text)

   • Steps to reproduce

   • Environment details (OS, Node.js version, etc.)

   • Relevant config (sanitized, no keys)

3. Ask in discussions: GitHub Discussions

---

Quick Fixes

"It just doesn't work"

Try this sequence:

# 1. Clean everything
rm -rf node_modules dist

# 2. Reinstall
npm install

# 3. Rebuild
npm run build

# 4. Test
npm test

# 5. Verify env
cat .env

# 6. Test server
node dist/index.js
# Should see initialization messages
# Press Ctrl+C

# 7. Restart Claude Desktop
# Quit completely and reopen

Reset to fresh state

# Backup first!
cp -r vcon-mcp vcon-mcp.backup

# Clean
git clean -fdx
git reset --hard

# Reinstall
npm install
npm run build

# Reconfigure
cp .env.example .env
# Edit .env with your credentials

---

Still stuck? Ask for help →

Found a bug? Report it →