@velaro/mcp-server 0.6.102 → 0.6.104

package/tool-annotations.js

@@ -0,0 +1,138 @@
+// Derives the MCP `title` and `annotations` (readOnlyHint, destructiveHint, idempotentHint,
+// openWorldHint) for every tool from its name, so no tool can ship without them.
+// Claude and ChatGPT directory reviews require all four hints set explicitly to true/false.
+// Fail-safe: a name matching no rule is treated as a non-read-only, destructive, non-idempotent write.
+// Guard: scripts/validate-mcp-tool-annotations.js (CI) asserts every tool resolves and spot-checks the rules.
+
+const tokens = (name) => name.split('_');
+
+// Tokens that mark a tool as read-only unless the name is in MUTATING.
+const READ_TOKENS = new Set([
+  'list', 'get', 'search', 'status', 'diagnose', 'diagnostics', 'health', 'preview', 'lookup',
+  'timeline', 'explain', 'audit', 'check', 'verify', 'summary', 'snapshot', 'benchmarks', 'stats',
+  'usage', 'errors', 'insights', 'report', 'overview', 'runbook', 'evidence', 'calculator', 'eligible',
+  'config', 'urls',
+]);
+
+// Names that contain a read-looking token but change state (checked before READ_TOKENS).
+const MUTATING = new Set([
+  'report_schedule_upsert', 'report_subscription_update', 'report_subscription_delete', 'report_export_start',
+  'report_backfill', 'report_data_export', 'executive_insights_subscribe', 'velaro_diagnostic_start',
+  'apple_test_control', 'kb_capture_screenshot', 'business_action_route', 'business_action_execute',
+  'netsuite_cti_generate_url', 'netsuite_m2m_init', 'netsuite_m2m_save', 'index_integrity_repair',
+  'klaviyo_migration_run', 'sitesync_blob_push', 'sitesync_blob_import', 'chat_intelligence_draft_article',
+  'teams_phone_set_config', 'webflow_set_config', 'notion_set_config', 'monday_set_field_mapping',
+  'teams_push_settings_update', 'teams_channel_config_update', 'routing_team_update_config',
+  'pickup_update_config', 'payment_recovery_update_config', 'recruiting_sync_jobs',
+  'ai_config_set_reply_format', 'ai_model_set_site_thinking', 'ai_model_set_site_pin',
+  'entitlement_reconcile', 'entitlement_sync_stripe', 'entitlement_backfill_subscriptions',
+  'calendly_configure', 'acuity_configure', 'ms_bookings_configure',
+]);
+
+// Names that look like writes but only read (checked before the write rules).
+const READ_ONLY_EXPLICIT = new Set([
+  'appointments_find_open_slots', 'appointments_list', 'compliance_redaction_test', 'compliance_status',
+  'compliance_signatures', 'compliance_redaction_events', 'compliance_redaction_status',
+  'shopify_widget_activation_url', 'klaviyo_savings_calculator', 'routing_simulate_inactivity',
+  'outlook_calendar_get_available_range', 'ms_bookings_check_availability_range', 'copilot_studio_test',
+  'notion_test_token', 'teams_phone_test_config', 'webflow_test_config', 'magento_test_connection',
+  'outlook_calendar_test_connection', 'scraper_verify_token', 'bigcommerce_check_refundable',
+  'sitesync_blob_list', 'kb_advise_knowledge_strategy', 'index_move_status', 'index_mixed_content',
+  'index_search', 'netsuite_m2m_verify', 'bot_skill_usage', 'bot_full_diagnostic', 'bot_recent_errors',
+  'logs_loggly_search', 'logs_appinsights_query', 'velaro_logs_search', 'executive_brief', 'friction_radar',
+  'tour_insights', 'kpi_snapshot', 'site_info', 'case_board', 'case_list_types', 'ai_spend_report',
+  'agent_availability_report', 'missed_chat_diagnostics', 'sse_visitor_diagnostic', 'signalr_diagnostics',
+  'ivr_agent_availability', 'contactlist_get', 'ai_model_resolver_map', 'ai_model_effective_for_site',
+  'calendly_get_status', 'acuity_get_status', 'outlook_calendar_status', 'ms_bookings_status',
+  'service_level_report', 'call_activity_report', 'callrail_get_attributions',
+  'product_sync_status', 'report_export_status', 'report_data_export', 'coupon_grant_list', 'coupon_grant_get',
+  'automation_draft_list', 'focus_get_draft_pregeneration_report', 'teams_push_settings_get',
+  'call_center_team_breakdown', 'call_center_channel_breakdown', 'outbound_activity_for_contact',
+  'integration_skill_logs', 'support_integration_logs', 'site_integration_logs', 'magento_activity_logs',
+  'support_site_deployments', 'support_schedule_adherence', 'support_site_agents', 'support_site_activity',
+  'chat_intelligence_themes', 'chat_intelligence_recommendations', 'index_move_preview', 'index_split_preview',
+  'canned_learning_suggestions', 'canned_learning_teams', 'canned_learning_edit_summary',
+  'chat_topics_group_suggestions', 'chat_topics_suggestions', 'enterprise_reports', 'image_analysis_limits',
+  'avatar_session_readiness', 'recruiting_ats_failures', 'jobboard_application_history',
+  'recruiting_download_resume', 'routing_inactivity_transfers', 'entitlement_enterprise_reports_package',
+  'compliance_attestation', 'livefluence_conversion_advisor', 'copilot_studio_ask',
+]);
+
+// Write tools that are additive even though their name carries a destructive-looking token.
+const NON_DESTRUCTIVE_EXPLICIT = new Set([
+  'safety_settings_test', 'safety_need_help', 'canned_learning_record_edit', 'hangfire_retry_job',
+  'netsuite_suiteapp_download', 'chat_topics_reclassify',
+]);
+
+const DESTRUCTIVE_TOKENS = new Set([
+  'delete', 'remove', 'revoke', 'disconnect', 'deprovision', 'reset', 'cancel', 'expire', 'purge',
+  'rollback', 'dismiss', 'update', 'set', 'upsert', 'edit', 'toggle', 'replace', 'restore', 'adjust',
+  'execute', 'push', 'move', 'split', 'repair', 'lock', 'override', 'configure', 'reschedule', 'migrate',
+  'backfill', 'reconcile', 'ingest', 'reindex', 'manage', 'control', 'apply',
+]);
+
+// Write tools that only add or trigger; they never remove or overwrite existing data.
+const ADDITIVE_TOKENS = new Set([
+  'create', 'add', 'send', 'notify', 'book', 'start', 'run', 'trigger', 'generate', 'invite', 'init',
+  'retry', 'replay', 'route', 'grant', 'capture', 'draft', 'seed', 'sync', 'mark', 'subscribe', 'request',
+  'crawl', 'provision', 'approve', 'comp', 'export', 'import', 'sign', 'card',
+]);
+
+const NOT_IDEMPOTENT_TOKENS = new Set([
+  'create', 'add', 'send', 'notify', 'book', 'start', 'run', 'trigger', 'generate', 'toggle', 'execute',
+  'route', 'retry', 'replay', 'push', 'grant', 'init', 'invite', 'capture', 'draft', 'crawl', 'card',
+  'subscribe', 'request', 'import', 'sign', 'approve', 'adjust', 'migrate', 'ingest', 'apply', 'rollback',
+  'reschedule', 'cancel',
+]);
+
+// Tools that reach a system outside the caller's Velaro account (third-party APIs, email/SMS/chat delivery, CRMs).
+const OPEN_WORLD = new RegExp('^(' + [
+  'calendly', 'acuity', 'outlook', 'ms_bookings', 'bigcommerce', 'shopify', 'magento', 'sap', 'netsuite',
+  'monday', 'notion', 'teams', 'slack', 'webflow', 'klaviyo', 'callrail', 'copilot_studio', 'scraper',
+  'site_scraper', 'apple', 'mobile_ota', 'code_push', 'jobboard', 'recruiting', 'payment_recovery',
+  'pickup_notify', 'email_queue_replay', 'email_inbox', 'entitlement_sync_stripe', 'logs_loggly',
+  'logs_appinsights', 'livefluence', 'telephony', 'kb_capture_screenshot', 'business_action',
+  'sitesync', 'email_delivery', 'campaign_sender_auth', 'ivr_update_line',
+].join('|') + ')');
+
+const ACRONYMS = {
+  kb: 'KB', ai: 'AI', ivr: 'IVR', sap: 'SAP', crm: 'CRM', sse: 'SSE', api: 'API', cti: 'CTI', m2m: 'M2M',
+  ota: 'OTA', url: 'URL', urls: 'URLs', id: 'ID', roi: 'ROI', kpi: 'KPI', ms: 'Microsoft', csat: 'CSAT',
+  sms: 'SMS', qa: 'QA', mcp: 'MCP', uuid: 'UUID', cli: 'CLI', smtp: 'SMTP', dns: 'DNS', oauth: 'OAuth',
+  netsuite: 'NetSuite', hangfire: 'Hangfire', signalr: 'SignalR', bigcommerce: 'BigCommerce',
+  livefluence: 'Livefluence', sitesync: 'SiteSync', jobboard: 'Job Board', callrail: 'CallRail',
+  wa: 'WhatsApp', velaro: 'Velaro', loggly: 'Loggly', appinsights: 'App Insights', sla: 'SLA',
+};
+
+export function titleFor(name) {
+  return tokens(name)
+    .map((t) => ACRONYMS[t] ?? t.charAt(0).toUpperCase() + t.slice(1))
+    .join(' ');
+}
+
+export function annotationsFor(name) {
+  const t = tokens(name);
+  const has = (set) => t.some((x) => set.has(x));
+  const readOnly = READ_ONLY_EXPLICIT.has(name)
+    || (!MUTATING.has(name) && has(READ_TOKENS) && !has(DESTRUCTIVE_TOKENS) && !has(ADDITIVE_TOKENS));
+  const openWorldHint = OPEN_WORLD.test(name);
+  if (readOnly) {
+    return { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint };
+  }
+  const additive = NON_DESTRUCTIVE_EXPLICIT.has(name) || (has(ADDITIVE_TOKENS) && !has(DESTRUCTIVE_TOKENS));
+  return {
+    readOnlyHint: false,
+    destructiveHint: !additive,
+    idempotentHint: !has(NOT_IDEMPOTENT_TOKENS),
+    openWorldHint,
+  };
+}
+
+// Returns the tool with `title` and `annotations` filled in; a hand-written value on the tool wins.
+export function withAnnotations(tool) {
+  return {
+    ...tool,
+    title: tool.title ?? titleFor(tool.name),
+    annotations: { ...annotationsFor(tool.name), ...(tool.annotations ?? {}) },
+  };
+}