MCP Tools Reference

Complete reference for all Model Context Protocol (MCP) tools provided by the vCon MCP Server.

Overview

The vCon MCP Server provides 30 tools organized into these functional groups:

Core Operations - Create, read, update, delete vCons
Component Management - Add dialog, analysis, attachments
Search & Query - Four search modes with different capabilities
Tag Management - Organize with key-value metadata
Database Tools - Inspect and optimize database
Database Analytics - Comprehensive database analytics and insights
Database Size Tools - Smart limits and size awareness for large databases
Schema & Examples - Get schemas and example vCons

Tool Categories

Tools are organized into 5 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

Enabling/Disabling Categories

Configure via environment variables:

# Use a preset profile
MCP_TOOLS_PROFILE=readonly   # Options: full, readonly, user, admin, minimal

# Or enable specific categories only
MCP_ENABLED_CATEGORIES=read,write,schema

# Or disable specific categories (starts with all enabled)
MCP_DISABLED_CATEGORIES=analytics,infra

# Disable individual tools
MCP_DISABLED_TOOLS=delete_vcon,analyze_query

Deployment Profiles

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

See the Configuration Guide for more details.

Core Operations

create_vcon

Create a new vCon (Virtual Conversation) record.

Input Parameters:

{
  vcon_data: {
    vcon: "0.4.0",           // vCon version
    uuid?: string,           // Auto-generated if not provided
    subject?: string,        // Conversation subject
    parties: Party[],        // At least one party required
    dialog?: Dialog[],       // Optional conversation content
    analysis?: Analysis[],   // Optional AI analysis
    attachments?: Attachment[], // Optional files
    extensions?: string[],   // Optional extensions
    critical?: string[]      // Optional: extensions that must be supported (v0.4.0)
  },
  metadata?: {
    basename?: string,
    filename?: string,
    tags?: object
  },
  validate_before_insert?: boolean  // Default: true
}

Response:

{
  success: boolean,
  uuid: string,           // UUID of created vCon
  vcon?: object          // Full vCon if requested
}

Example:

{
  "vcon_data": {
    "vcon": "0.4.0",
    "subject": "Customer Support Call",
    "parties": [
      {
        "name": "Agent Smith",
        "mailto": "smith@company.com",
        "role": "agent"
      },
      {
        "name": "John Doe",
        "tel": "+1-555-1234",
        "role": "customer"
      }
    ]
  }
}

get_vcon

Retrieve a vCon by UUID.

Input Parameters:

{
  uuid: string,              // vCon UUID (required)
  include_components?: string[], // ["parties", "dialog", "analysis", "attachments", "all"]
  include_metadata?: boolean  // Default: true
}

Response:

{
  success: boolean,
  vcon: {
    vcon: "0.4.0",
    uuid: string,
    created_at: string,
    updated_at?: string,
    subject?: string,
    parties: Party[],
    dialog?: Dialog[],
    analysis?: Analysis[],
    attachments?: Attachment[]
  }
}

Example:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000"
}

update_vcon

Update vCon metadata and top-level fields.

Input Parameters:

{
  uuid: string,           // vCon UUID (required)
  updates: {
    subject?: string,
    extensions?: string[],
    critical?: string[],
    [key: string]: any
  },
  merge_strategy?: "replace" | "merge" | "append",  // Default: "merge"
  validate_after_update?: boolean  // Default: true
}

Response:

{
  success: boolean,
  message: string,
  updated_vcon?: object
}

Example:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "updates": {
    "subject": "Updated: Customer Support Call - Resolved"
  }
}

delete_vcon

Delete a vCon and all related data.

Input Parameters:

{
  uuid: string,           // vCon UUID (required)
  confirm: boolean,       // Must be true (safety check)
  cascade_delete?: boolean  // Default: true (deletes all components)
}

Response:

{
  success: boolean,
  message: string,
  deleted_uuid: string
}

Example:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "confirm": true
}

create_vcon_from_template

Create a vCon from a predefined template.

Input Parameters:

{
  template_name: "phone_call" | "chat_conversation" | "email_thread" | "video_meeting" | "custom",
  subject?: string,
  parties: Party[],      // At least 2 parties required
  metadata?: object,
  template_params?: object  // Template-specific parameters
}

Templates Available:

phone_call - Phone conversation with duration tracking
chat_conversation - Text-based chat with timestamps
email_thread - Email chain with threading
video_meeting - Video conference with participants
custom - Blank template with custom fields

Response:

{
  success: boolean,
  uuid: string,
  vcon: object
}

Example:

{
  "template_name": "phone_call",
  "subject": "Sales Call",
  "parties": [
    { "name": "Sales Rep", "mailto": "rep@company.com" },
    { "name": "Prospect", "mailto": "prospect@client.com" }
  ]
}

Component Management

add_dialog

Add a dialog entry (conversation segment) to a vCon.

Input Parameters:

{
  vcon_uuid: string,      // vCon UUID (required)
  dialog: {
    type: "recording" | "text" | "transfer" | "incomplete",  // Required
    start?: string,       // ISO 8601 timestamp
    duration?: number,    // Duration in seconds
    parties?: number[],   // Array of party indices
    originator?: number,  // Party index of originator
    mediatype?: string,   // MIME type
    filename?: string,
    body?: string,        // Dialog content
    encoding?: "none" | "base64url" | "json",
    url?: string,         // External URL
    session_id?: string,
    application?: string,
    message_id?: string
  }
}

Response:

{
  success: boolean,
  message: string,
  dialog_index: number
}

Example:

{
  "vcon_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "dialog": {
    "type": "text",
    "start": "2025-10-14T10:30:00Z",
    "parties": [0, 1],
    "originator": 1,
    "body": "Hello, I need help with my account.",
    "encoding": "none"
  }
}

add_analysis

Add AI/ML analysis results to a vCon.

Input Parameters:

{
  vcon_uuid: string,      // vCon UUID (required)
  analysis: {
    type: string,         // Analysis type (e.g., "sentiment", "summary")
    dialog?: number | number[],  // Associated dialog indices
    vendor: string,       // REQUIRED - Analysis vendor
    product?: string,     // Product/model name
    schema?: string,      // Schema version
    body?: string,        // Analysis content
    encoding?: "none" | "json" | "base64url",
    url?: string,
    mediatype?: string
  }
}

Common Analysis Types:

sentiment - Sentiment analysis
summary - Conversation summary
transcript - Transcription
translation - Translation
keywords - Keyword extraction
entities - Named entity recognition
topics - Topic classification
action_items - Action item extraction

Response:

{
  success: boolean,
  message: string,
  analysis_index: number
}

Example:

{
  "vcon_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "analysis": {
    "type": "sentiment",
    "vendor": "OpenAI",
    "product": "GPT-4",
    "schema": "v1.0",
    "body": "{\"sentiment\": \"positive\", \"score\": 0.85, \"confidence\": 0.92}",
    "encoding": "json",
    "dialog": [0]
  }
}

add_attachment

Add an attachment (file, document, etc.) to a vCon.

Input Parameters:

{
  vcon_uuid: string,      // vCon UUID (required)
  attachment: {
    type: string,         // Attachment type
    start?: string,       // ISO 8601 timestamp
    party?: number,       // Associated party index
    dialog?: number,      // Associated dialog index
    mediatype?: string,   // MIME type
    filename?: string,
    body?: string,        // Attachment content
    encoding?: "none" | "base64url" | "json",
    url?: string         // External URL
  }
}

Response:

{
  success: boolean,
  message: string,
  attachment_index: number
}

Example:

{
  "vcon_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "attachment": {
    "type": "invoice",
    "mediatype": "application/pdf",
    "filename": "invoice-12345.pdf",
    "body": "base64-encoded-pdf-content",
    "encoding": "base64url"
  }
}

Search & Query

search_vcons

Basic search with filtering by metadata (subject, parties, dates).

Input Parameters:

{
  subject?: string,       // Subject text search
  party_name?: string,    // Party name search
  party_email?: string,   // Party email search
  party_tel?: string,     // Party phone search
  start_date?: string,    // ISO 8601 date
  end_date?: string,      // ISO 8601 date
  limit?: number,         // Default: 50, Max: 1000
  offset?: number         // For pagination
}

Response:

{
  success: boolean,
  count: number,
  vcons: VCon[],
  has_more: boolean
}

Example:

{
  "subject": "support",
  "start_date": "2025-10-01T00:00:00Z",
  "limit": 20
}

search_vcons_content

Full-text keyword search across dialog, analysis, and party content.

Input Parameters:

{
  query: string,          // Search query (required)
  tags?: object,          // Tag filters
  start_date?: string,
  end_date?: string,
  limit?: number,         // Default: 50
  include_snippets?: boolean  // Default: true
}

Response:

{
  success: boolean,
  count: number,
  results: [{
    vcon_id: string,
    content_type: "subject" | "dialog" | "analysis" | "party",
    content_index?: number,
    relevance_score: number,
    snippet?: string,     // Highlighted match
    vcon?: object
  }]
}

Example:

{
  "query": "billing issue refund",
  "tags": { "department": "support" },
  "limit": 25
}

search_vcons_semantic

AI-powered semantic search using embeddings.

Input Parameters:

{
  query?: string,         // Natural language query
  embedding?: number[],   // Or provide embedding directly (384 dims)
  threshold?: number,     // Similarity threshold (0-1), default: 0.7
  tags?: object,          // Tag filters
  limit?: number          // Default: 20
}

Response:

{
  success: boolean,
  count: number,
  results: [{
    vcon_id: string,
    similarity_score: number,
    matched_content: {
      subject?: string,
      dialog_excerpts?: Array<{
        dialog_index: number,
        text: string,
        relevance: number
      }>
    },
    vcon?: object
  }]
}

Example:

{
  "query": "customer frustrated about late delivery",
  "threshold": 0.75,
  "tags": { "priority": "high" },
  "limit": 15
}

search_vcons_hybrid

Combined keyword + semantic search for comprehensive results.

Input Parameters:

{
  query: string,          // Search query (required)
  semantic_weight?: number,  // 0-1, default: 0.6 (60% semantic, 40% keyword)
  tags?: object,
  start_date?: string,
  end_date?: string,
  limit?: number          // Default: 30
}

Response:

{
  success: boolean,
  count: number,
  results: [{
    vcon_id: string,
    combined_score: number,
    keyword_score: number,
    semantic_score: number,
    vcon?: object
  }]
}

Example:

{
  "query": "pricing discussion discount",
  "semantic_weight": 0.5,
  "tags": { "department": "sales" },
  "limit": 20
}

Tag Management

add_tag

Add or update a single tag on a vCon.

Input Parameters:

{
  vcon_uuid: string,      // vCon UUID (required)
  key: string,            // Tag key (required)
  value: string | number | boolean,  // Tag value (required)
  overwrite?: boolean     // Default: true
}

Response:

{
  success: boolean,
  message: string,
  key: string,
  value: any
}

Example:

{
  "vcon_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "key": "department",
  "value": "sales"
}

get_tag

Retrieve a specific tag value.

Input Parameters:

{
  vcon_uuid: string,      // vCon UUID (required)
  key: string,            // Tag key (required)
  default_value?: any     // Return if tag doesn't exist
}

Response:

{
  success: boolean,
  key: string,
  value: any,
  exists: boolean
}

get_all_tags

Get all tags for a vCon.

Input Parameters:

{
  vcon_uuid: string       // vCon UUID (required)
}

Response:

{
  success: boolean,
  vcon_uuid: string,
  tags: {
    [key: string]: string | number | boolean
  },
  count: number
}

Example Response:

{
  "success": true,
  "tags": {
    "department": "sales",
    "priority": "high",
    "status": "open",
    "customer_id": "CUST-12345"
  },
  "count": 4
}

remove_tag

Remove a tag from a vCon.

Input Parameters:

{
  vcon_uuid: string,      // vCon UUID (required)
  key: string             // Tag key to remove (required)
}

search_by_tags

Find vCons by tag criteria (all tags must match).

Input Parameters:

{
  tags: {                 // Tag key-value pairs (required)
    [key: string]: string
  },
  limit?: number,         // Default: 50, Max: 100 - Maximum number of UUIDs to return
  return_full_vcons?: boolean,  // Default: auto (true for ≤20 results, false for >20)
  max_full_vcons?: number      // Default: 20 - Max full vCon objects to return (prevents size limits)
}

Response:

{
  success: boolean,
  count: number,
  tags_searched: object,
  vcon_uuids: string[],   // Always returned (all matching UUIDs)
  vcons?: VCon[],         // Only included if return_full_vcons=true
  message?: string        // Helpful message about result size
}

Behavior:

Always returns vcon_uuids for all matching vCons (up to limit)
For large result sets (>20), only UUIDs are returned by default to prevent response size limits
Use return_full_vcons: true to get full vCon objects (limited to max_full_vcons to prevent size issues)
For small result sets (≤20), full vCon objects are returned by default

Example:

{
  "tags": {
    "department": "support",
    "priority": "high",
    "status": "open"
  },
  "limit": 25
}

get_unique_tags

Discover all available tags across all vCons.

Input Parameters:

{
  include_counts?: boolean,   // Include usage statistics
  key_filter?: string,        // Filter by key substring
  min_count?: number          // Minimum occurrence count
}

Response:

{
  success: boolean,
  unique_keys: string[],
  unique_key_count: number,
  tags_by_key: {
    [key: string]: string[]   // All values for each key
  },
  counts_per_value?: {        // If include_counts=true
    [key: string]: {
      [value: string]: number
    }
  },
  total_vcons_with_tags: number
}

Example:

{
  "include_counts": true,
  "key_filter": "department"
}

update_tags

Update multiple tags at once.

Input Parameters:

{
  vcon_uuid: string,      // vCon UUID (required)
  tags: {                 // Tags to add/update (required)
    [key: string]: string | number | boolean
  },
  merge?: boolean         // Merge with existing (true) or replace all (false)
}

Example:

{
  "vcon_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "tags": {
    "status": "closed",
    "resolution": "resolved",
    "resolved_at": "2025-10-14T15:30:00Z"
  },
  "merge": true
}

remove_all_tags

Remove all tags from a vCon.

Input Parameters:

{
  vcon_uuid: string       // vCon UUID (required)
}

Database Tools

get_database_shape

Get database structure, sizes, and indexes.

Input Parameters:

{
  include_counts?: boolean,   // Default: true
  include_sizes?: boolean,    // Default: true
  include_indexes?: boolean,  // Default: true
  include_columns?: boolean   // Default: false
}

Response:

{
  success: boolean,
  database_shape: {
    timestamp: string,
    tables: [{
      name: string,
      schema: string,
      row_count: number,
      total_size: string,
      table_size: string,
      indexes_size: string,
      indexes?: Array<{
        indexname: string,
        index_type: string,
        index_size: string
      }>,
      columns?: Array<{
        column_name: string,
        data_type: string,
        is_nullable: string
      }>
    }],
    relationships: Array<{
      from_table: string,
      from_column: string,
      to_table: string,
      to_column: string
    }>
  }
}

get_database_stats

Get performance metrics and usage statistics.

Input Parameters:

{
  include_query_stats?: boolean,   // Default: true
  include_index_usage?: boolean,   // Default: true
  include_cache_stats?: boolean,   // Default: true
  table_name?: string               // Specific table
}

Response:

{
  success: boolean,
  database_stats: {
    timestamp: string,
    cache_stats: {
      hit_ratio: string,
      heap_blocks_hit: number,
      heap_blocks_read: number
    },
    table_stats: Array<{
      table_name: string,
      sequential_scans: number,
      index_scans: number,
      inserts: number,
      updates: number,
      deletes: number,
      live_rows: number,
      dead_rows: number
    }>,
    index_usage: Array<{
      table_name: string,
      index_name: string,
      scans: number,
      rows_read: number
    }>,
    unused_indexes: Array<{
      table_name: string,
      index_name: string,
      index_size: string
    }>
  }
}

analyze_query

Analyze SQL query execution plan (limited support).

Input Parameters:

{
  query: string,          // SELECT query (required)
  analyze_mode?: "explain" | "explain_analyze"  // Default: "explain"
}

Note: Has limited support due to RPC constraints. Use direct database access for full EXPLAIN capabilities.

Database Analytics

get_database_analytics

Get comprehensive database analytics including size, growth trends, content distribution, and health metrics.

Input Parameters:

{
  include_growth_trends?: boolean,      // Include monthly growth trends (default: true)
  include_content_analytics?: boolean,  // Include content analysis (default: true)
  include_attachment_stats?: boolean,   // Include attachment statistics (default: true)
  include_tag_analytics?: boolean,      // Include tag usage patterns (default: true)
  include_health_metrics?: boolean,     // Include health metrics (default: true)
  months_back?: number                  // Months to analyze (default: 12)
}

Response:

{
  success: true,
  database_analytics: {
    timestamp: string,
    summary: {
      total_vcons: number,
      total_parties: number,
      total_dialogs: number,
      total_analysis: number,
      total_attachments: number,
      total_size_bytes: number,
      total_size_pretty: string,
      database_health_score: number
    },
    tables: {
      [table_name]: {
        row_count: number,
        total_size: string,
        table_size: string
      }
    },
    growth: {
      monthly_data: Array<{
        month: string,
        vcon_count: number,
        total_size: number
      }>,
      summary: {
        total_growth: number,
        avg_monthly_growth: number,
        growth_percentage: number
      }
    },
    content: {
      dialog_types: Array<{
        type: string,
        count: number,
        avg_duration: number
      }>,
      analysis_types: Array<{
        type: string,
        vendor: string,
        count: number
      }>,
      party_roles: Array<{
        role: string,
        count: number,
        unique_names: number
      }>
    },
    attachments: {
      type_breakdown: Array<{
        type: string,
        count: number,
        total_size: number,
        percentage: number
      }>,
      size_distribution: Array<{
        size_bucket: string,
        count: number,
        percentage: number
      }>
    },
    tags: {
      tag_frequency: Array<{
        key: string,
        usage_count: number,
        unique_values: number
      }>,
      value_distribution: Array<{
        key: string,
        value: string,
        count: number,
        percentage: number
      }>
    },
    health: {
      table_performance: Array<{
        table_name: string,
        sequential_scans: number,
        index_scans: number,
        dead_row_percentage: number
      }>,
      index_usage: Array<{
        table_name: string,
        index_name: string,
        scans: number,
        health_status: string
      }>
    }
  }
}

Example:

{
  "include_growth_trends": true,
  "include_content_analytics": true,
  "months_back": 6
}

get_monthly_growth_analytics

Get detailed monthly growth analytics with trends and projections.

Input Parameters:

{
  months_back?: number,           // Months to analyze (default: 12)
  include_projections?: boolean,  // Include growth projections (default: true)
  granularity?: 'monthly' | 'weekly' | 'daily'  // Time granularity (default: 'monthly')
}

Response:

{
  success: true,
  monthly_growth_analytics: {
    timestamp: string,
    period: string,
    granularity: string,
    trends: {
      vcon_creation: Array<{
        period: string,
        vcon_count: number,
        unique_vcons: number
      }>,
      size_growth: Array<{
        period: string,
        dialog_size: number,
        attachment_size: number,
        total_size: number
      }>,
      content_volume: Array<{
        period: string,
        vcon_count: number,
        dialog_count: number,
        analysis_count: number,
        attachment_count: number
      }>
    },
    growth_rates: {
      vcon_growth_rate: number,
      size_growth_rate: number
    },
    projections: {
      next_3_months: {
        projected_vcons: number,
        projected_size: number,
        projected_size_pretty: string
      },
      growth_rates: {
        vcon_growth_rate: number,
        size_growth_rate: number
      }
    }
  }
}

get_attachment_analytics

Get comprehensive attachment analytics including file type distribution and size analysis.

Input Parameters:

{
  include_size_distribution?: boolean,  // Include size distribution (default: true)
  include_type_breakdown?: boolean,     // Include file type breakdown (default: true)
  include_temporal_patterns?: boolean,  // Include temporal patterns (default: false)
  top_n_types?: number                  // Top N file types to analyze (default: 10)
}

Response:

{
  success: true,
  attachment_analytics: {
    timestamp: string,
    summary: {
      total_attachments: number,
      total_size: number,
      avg_size: number,
      unique_types: number,
      vcons_with_attachments: number
    },
    type_breakdown: Array<{
      type: string,
      count: number,
      total_size: number,
      avg_size: number,
      percentage: number
    }>,
    size_distribution: Array<{
      size_bucket: string,
      count: number,
      total_size: number,
      percentage: number
    }>,
    temporal_patterns: Array<{
      month: string,
      attachment_count: number,
      total_size: number,
      avg_size: number
    }>
  }
}

get_tag_analytics

Get comprehensive tag analytics including usage patterns and value distribution.

Input Parameters:

{
  include_frequency_analysis?: boolean,  // Include frequency analysis (default: true)
  include_value_distribution?: boolean,  // Include value distribution (default: true)
  include_temporal_trends?: boolean,     // Include temporal trends (default: false)
  top_n_keys?: number,                   // Top N tag keys to analyze (default: 20)
  min_usage_count?: number               // Minimum usage count filter (default: 1)
}

Response:

{
  success: true,
  tag_analytics: {
    timestamp: string,
    summary: {
      unique_keys: number,
      unique_values: number,
      vcons_with_tags: number,
      total_tag_assignments: number
    },
    frequency_analysis: Array<{
      key: string,
      usage_count: number,
      unique_values: number,
      vcons_with_tag: number,
      avg_values_per_key: number
    }>,
    value_distribution: Array<{
      key: string,
      value: string,
      count: number,
      percentage: number
    }>,
    temporal_trends: Array<{
      month: string,
      key: string,
      usage_count: number
    }>
  }
}

get_content_analytics

Get comprehensive content analytics including dialog types, analysis breakdown, and conversation metrics.

Input Parameters:

{
  include_dialog_analysis?: boolean,     // Include dialog analysis (default: true)
  include_analysis_breakdown?: boolean,  // Include analysis breakdown (default: true)
  include_party_patterns?: boolean,      // Include party patterns (default: true)
  include_conversation_metrics?: boolean, // Include conversation metrics (default: true)
  include_temporal_content?: boolean     // Include temporal content patterns (default: false)
}

Response:

{
  success: true,
  content_analytics: {
    timestamp: string,
    summary: {
      total_vcons: number,
      total_parties: number,
      total_dialogs: number,
      total_analysis: number,
      total_attachments: number,
      total_duration_seconds: number,
      avg_duration_seconds: number
    },
    dialog_analysis: Array<{
      type: string,
      count: number,
      avg_duration: number,
      total_duration: number,
      total_size: number,
      unique_vcons: number
    }>,
    analysis_breakdown: Array<{
      type: string,
      vendor: string,
      count: number,
      avg_confidence: number,
      unique_vcons: number
    }>,
    party_patterns: Array<{
      role: string,
      count: number,
      unique_names: number,
      unique_emails: number,
      unique_phones: number,
      unique_vcons: number
    }>,
    conversation_metrics: {
      total_conversations: number,
      avg_parties_per_conversation: number,
      avg_dialogs_per_conversation: number,
      avg_analysis_per_conversation: number,
      avg_attachments_per_conversation: number,
      avg_duration_per_conversation: number,
      avg_size_per_conversation: number,
      max_parties_in_conversation: number,
      max_dialogs_in_conversation: number
    },
    temporal_content: Array<{
      month: string,
      vcon_count: number,
      dialog_count: number,
      analysis_count: number,
      attachment_count: number,
      total_duration: number
    }>
  }
}

get_database_health_metrics

Get database health metrics including performance indicators and optimization recommendations.

Input Parameters:

{
  include_performance_metrics?: boolean,  // Include performance metrics (default: true)
  include_storage_efficiency?: boolean,   // Include storage efficiency (default: true)
  include_index_health?: boolean,         // Include index health (default: true)
  include_connection_metrics?: boolean,   // Include connection metrics (default: true)
  include_recommendations?: boolean       // Include recommendations (default: true)
}

Response:

{
  success: true,
  database_health_metrics: {
    timestamp: string,
    overall_score: number,
    metrics: {
      performance: Array<{
        table_name: string,
        sequential_scans: number,
        index_scans: number,
        inserts: number,
        updates: number,
        deletes: number,
        live_rows: number,
        dead_rows: number,
        dead_row_percentage: number,
        index_usage_ratio: number
      }>,
      storage: Array<{
        table_name: string,
        total_size: string,
        table_size: string,
        index_size: string,
        index_size_percentage: number
      }>,
      indexes: Array<{
        table_name: string,
        index_name: string,
        scans: number,
        rows_read: number,
        rows_fetched: number,
        index_size: string,
        health_status: 'UNUSED' | 'LOW_USAGE' | 'ACTIVE'
      }>,
      connections: {
        heap_read: number,
        heap_hit: number,
        cache_hit_ratio: number,
        idx_read: number,
        idx_hit: number,
        idx_cache_hit_ratio: number
      }
    },
    recommendations: string[],
    alerts: string[]
  }
}

Database Size Tools

get_database_size_info

Get database size information and smart recommendations for query limits. Essential for large databases to prevent memory exhaustion.

Input Parameters:

{
  include_recommendations?: boolean  // Include smart recommendations (default: true)
}

Response:

{
  success: true,
  database_size_info: {
    total_vcons: number,
    total_size_bytes: number,
    total_size_pretty: string,
    size_category: 'small' | 'medium' | 'large' | 'very_large',
    recommendations: {
      max_basic_search_limit: number,
      max_content_search_limit: number,
      max_semantic_search_limit: number,
      max_analytics_limit: number,
      recommended_response_format: string,
      memory_warning: boolean
    },
    table_sizes: {
      [table_name]: {
        row_count: number,
        size_bytes: number,
        size_pretty: string
      }
    }
  }
}

Example:

{
  "include_recommendations": true
}

get_smart_search_limits

Get smart search limits based on database size and query complexity. Helps prevent memory exhaustion by suggesting appropriate limits.

Input Parameters:

{
  query_type: 'basic' | 'content' | 'semantic' | 'hybrid' | 'analytics',
  estimated_result_size?: 'small' | 'medium' | 'large' | 'unknown'  // Default: 'unknown'
}

Response:

{
  success: true,
  smart_limits: {
    query_type: string,
    estimated_result_size: string,
    recommended_limit: number,
    recommended_response_format: string,
    memory_warning: boolean,
    explanation: string
  }
}

Example:

{
  "query_type": "content",
  "estimated_result_size": "large"
}

Schema & Examples

get_schema

Get vCon schema definition.

Input Parameters:

{
  format?: "json_schema" | "typescript" | "openapi",  // Default: "json_schema"
  version?: string        // vCon version, default: "latest"
}

Response:

{
  success: boolean,
  format: string,
  version: string,
  schema: object | string
}

get_examples

Get example vCons.

Input Parameters:

{
  example_type: "minimal" | "phone_call" | "chat" | "email" | "video" | "full_featured",
  format?: "json" | "yaml"  // Default: "json"
}

Response:

{
  success: boolean,
  example_type: string,
  format: string,
  vcon: object | string
}

Example Types:

minimal - Bare minimum required fields
phone_call - Phone conversation example
chat - Text chat example
email - Email thread example
video - Video meeting example
full_featured - All features demonstrated

Error Responses

All tools return errors in this format:

{
  success: false,
  error: string,
  details?: any
}

Common Error Codes:

VALIDATION_ERROR - Invalid input parameters
NOT_FOUND - vCon or resource not found
DATABASE_ERROR - Database operation failed
PERMISSION_DENIED - Insufficient permissions
RATE_LIMIT_EXCEEDED - Too many requests

Usage Notes

Best Practices

Always validate - Use validate_before_insert for create operations
Use appropriate search - Choose the right search tool for your use case
Tag consistently - Establish a tagging schema
Monitor performance - Use database tools regularly
Handle errors - Check success field in all responses

Rate Limits

Search operations: 100 requests/minute
Create operations: 50 requests/minute
Other operations: 200 requests/minute

Pagination

For search results:

Use limit and offset parameters
Check has_more in response
Maximum limit is 1000

Next Steps

See Resources for URI-based access
See Prompts for query templates
See TypeScript Types for type definitions
See Examples for practical usage

FilesExpand file tree

tools.md

Latest commit

History

tools.md

File metadata and controls

MCP Tools Reference

Overview

Tool Categories

Enabling/Disabling Categories

Deployment Profiles

Core Operations

create_vcon

get_vcon

update_vcon

delete_vcon

create_vcon_from_template

Component Management

add_dialog

add_analysis

add_attachment

Search & Query

search_vcons

search_vcons_content

search_vcons_semantic

search_vcons_hybrid

Tag Management

add_tag

get_tag

get_all_tags

remove_tag

search_by_tags

get_unique_tags

update_tags

remove_all_tags

Database Tools

get_database_shape

get_database_stats

analyze_query

Database Analytics

get_database_analytics

get_monthly_growth_analytics

get_attachment_analytics

get_tag_analytics

get_content_analytics

get_database_health_metrics

Database Size Tools

get_database_size_info

get_smart_search_limits

Schema & Examples

get_schema

get_examples

Error Responses

Usage Notes

Best Practices

Rate Limits

Pagination

Next Steps