@indemn/cli 1.6.0 → 1.7.0

package/src/mcp/tool-meta.ts

@@ -0,0 +1,241 @@
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Metadata for every MCP tool. The host (Claude Code, Jarvis) reads the
+ * annotations to decide when to ask the user. `guard` makes the registry
+ * require a confirmation before the tool runs; each area switches it on for
+ * its own tools together with a precise `describe` preview.
+ */
+export interface ToolMeta {
+  title: string;
+  annotations: ToolAnnotations;
+  /** Ask before running: elicitation, else `confirm: true`, else a dry run. */
+  guard?: boolean;
+  /** One sentence naming exactly what the call would change, for the confirmation. */
+  describe?: (args: Record<string, unknown>) => string;
+  /** False for tools that never touch an org-scoped route. Default true. */
+  orgScoped?: boolean;
+  /** List tool: the registry adds limit/page and returns { items, page, limit, total, has_more }. */
+  paginate?: boolean;
+}
+
+const read = (title: string): ToolMeta => ({
+  title,
+  annotations: { title, readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+});
+
+const write = (title: string, extra: Partial<ToolAnnotations> = {}): ToolMeta => ({
+  title,
+  annotations: { title, readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false, ...extra },
+});
+
+/** Overwrites or removes something that cannot be restored from the tool itself. */
+const destroy = (title: string, extra: Partial<ToolAnnotations> = {}): ToolMeta => ({
+  title,
+  annotations: { title, readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false, ...extra },
+});
+
+export const TOOL_META: Record<string, ToolMeta> = {
+  // Login and organizations
+  whoami: { ...read('Who am I'), orgScoped: false },
+  list_organizations: { ...read('List my organizations'), orgScoped: false },
+  list_org_members: { ...read('List organization members'), paginate: true },
+  list_channels: read('List channels'),
+
+  // Agents
+  list_agents: { ...read('List agents'), paginate: true },
+  get_agent: read('Get agent'),
+  create_agent: write('Create agent'),
+  update_agent: { ...write('Update agent', { idempotentHint: true }), guard: true, describe: (a) => `This will change agent ${a.agent_id}.` },
+  delete_agent: { ...destroy('Delete agent'), guard: true, describe: (a) => `This will delete agent ${a.agent_id}. It cannot be restored from the CLI.` },
+  agent_summary: read('Summarize agent'),
+  agent_stats: read('Agent conversation metrics'),
+  set_agent_lifecycle: {
+    ...write('Change agent lifecycle', { idempotentHint: true }),
+    guard: true,
+    describe: (a) => `This will move agent ${a.agent_id} to lifecycle "${a.lifecycle}". Published means live for customers.`,
+  },
+  transfer_agent_owner: {
+    ...write('Transfer agent ownership', { idempotentHint: true }),
+    guard: true,
+    describe: (a) => `This will make user ${a.owner_id} the owner of agent ${a.agent_id}.`,
+  },
+  clone_agent: write('Clone agent'),
+  export_agent: read('Export agent bundle'),
+  import_agent: {
+    ...write('Import agent bundle'),
+    guard: true,
+    describe: (a) => `This will create a new agent "${String(a.name ?? (a.bundle as { agent?: { name?: string } } | undefined)?.agent?.name ?? '')}" with ${((a.bundle as { skills?: unknown[] } | undefined)?.skills ?? []).length} skill(s).`,
+  },
+
+  // Prompt and configuration
+  get_config: read('Get agent configuration'),
+  set_config: { ...destroy('Change agent prompt, greeting or model', { idempotentHint: true }), guard: true },
+  get_prompt: read('Get agent prompt'),
+  set_prompt: { ...destroy('Replace agent prompt', { idempotentHint: true }), guard: true },
+
+  // Skills (the CLI still calls them functions)
+  list_functions: { ...read('List skills'), paginate: true },
+  create_function: write('Create skill'),
+  update_function: { ...write('Update skill', { idempotentHint: true }), guard: true, describe: (a) => `This will change skill ${a.function_id} of agent ${a.agent_id}.` },
+  delete_function: { ...destroy('Delete skill'), guard: true, describe: (a) => `This will delete skill ${a.function_id} from agent ${a.agent_id}.` },
+  test_function: write('Test skill', { openWorldHint: true }),
+  export_functions: read('Export skills'),
+  import_functions: {
+    ...destroy('Import skills, replacing existing ones', { openWorldHint: true }),
+    guard: true,
+    describe: (a) => `This will DELETE every skill of agent ${a.agent_id}, including the built-in handoff and FAQ retriever, and replace them with the skills in ${a.url}. There is no undo.`,
+  },
+  generate_skills_from_doc: write('Propose skills from a document', { openWorldHint: true }),
+  bulk_create_skills: {
+    ...write('Create several skills'),
+    guard: true,
+    describe: (a) => `This will create ${((a.functions as unknown[] | undefined) ?? []).length} skill(s) on agent ${a.agent_id}.`,
+  },
+  list_function_parameters: read('List skill parameters'),
+  add_function_parameter: write('Add skill parameter'),
+  update_function_parameter: write('Update skill parameter', { idempotentHint: true }),
+  delete_function_parameter: { ...destroy('Delete skill parameter'), guard: true, describe: (a) => `This will delete parameter ${a.parameter_id} of skill ${a.function_id} on agent ${a.agent_id}.` },
+  list_master_functions: { ...read('List skill templates'), paginate: true },
+  list_llm_models: { ...read('List LLM models'), paginate: true },
+
+  // Knowledge bases
+  list_knowledge_bases: { ...read('List knowledge bases'), paginate: true },
+  get_knowledge_base: read('Get knowledge base'),
+  create_knowledge_base: write('Create knowledge base'),
+  update_knowledge_base: write('Update knowledge base', { idempotentHint: true }),
+  delete_knowledge_base: { ...destroy('Delete knowledge base'), guard: true, describe: (a) => `This will delete knowledge base ${a.kb_id} with all its sources and vectors.` },
+  list_kb_data: read('List knowledge base entries'),
+  add_kb_data: write('Add knowledge base entry'),
+  scrape_url: write('Scrape a website into a knowledge base', { openWorldHint: true }),
+  upload_kb_file: write('Upload file to knowledge base'),
+  update_kb_data: write('Update knowledge base entry', { idempotentHint: true }),
+  delete_kb_data: { ...destroy('Delete knowledge base entry'), guard: true, describe: (a) => `This will delete source ${a.source_id} from knowledge base ${a.kb_id}, with its vectors.` },
+  link_kb: write('Link knowledge bases to agent', { idempotentHint: true }),
+  unlink_kb: { ...destroy('Unlink knowledge base from agent'), guard: true, describe: (a) => `This will unlink knowledge base ${a.kb_id} from agent ${a.agent_id}; the agent stops using it immediately.` },
+  export_kb: read('Export knowledge base'),
+  import_kb: { ...destroy('Import into knowledge base'), guard: true, describe: (a) => `This will import new content into knowledge base ${a.kb_id}.` },
+  kb_chunks: read('Show what the agent learned from a source'),
+  reimport_kb_source: {
+    ...write('Re-crawl a website source', { openWorldHint: true }),
+    guard: true,
+    describe: (a) => `This will re-crawl source ${a.source_id} of knowledge base ${a.kb_id}; its chunks are replaced when done.`,
+  },
+  kb_scrape_status: read('Crawl and import progress'),
+  kb_gaps: read('Unanswered questions'),
+  kb_check: read('Check if knowledge answers a question'),
+
+  // Conversations
+  list_conversations: read('List conversations of an agent'),
+  get_conversation: read('Get a conversation with its messages'),
+  mark_conversation_test: {
+    ...write('Mark conversations as test', { idempotentHint: true }),
+    guard: true,
+    describe: (a) => `This will mark ${(a.conversation_ids as string[] | undefined)?.length ?? 0} conversation(s) of agent ${a.agent_id} as test: removed from analytics, usage billing reversed.`,
+  },
+
+  // Voice
+  list_voices: { ...read('List voices'), orgScoped: false },
+  list_voice_models: read('List speech models'),
+  get_agent_voice: read('Get agent voice settings'),
+  set_agent_voice: { ...write('Change agent voice', { idempotentHint: true }), guard: true, describe: (a) => `This will change the voice of agent ${a.agent_id} to ${a.name ? `"${a.name}"` : a.voice_id}; callers hear it on the next call.` },
+  set_agent_transcriber: { ...write('Change agent transcriber', { idempotentHint: true }), guard: true, describe: (a) => `This will change how agent ${a.agent_id} hears callers to ${a.provider}/${a.model} (${a.language}); it applies from the next call.` },
+  list_agent_numbers: read('List phone numbers'),
+  attach_phone_number: { ...write('Attach phone number'), guard: true, describe: (a) => `This will attach ${a.phone_number} to agent ${a.agent_id}; its voice settings reset to the defaults. Numbers the org does not own are refused (never bought).` },
+  search_phone_numbers: read('Search phone numbers to buy'),
+  get_phone_number: read('Get phone number details'),
+  buy_phone_number: { ...write('Buy phone number'), guard: true, describe: (a) => `This will BUY ${a.phone_number} from Twilio and attach it to agent ${a.agent_id}. The org pays for it every month, and it cannot be undone from here.` },
+  detach_phone_number: { ...destroy('Detach phone number'), guard: true, describe: (a) => `This will detach ${a.phone_number} from agent ${a.agent_id}; calls to it stop reaching the agent.` },
+  voice_preview: write('Start a test voice call'),
+
+  // Distributions, templates, solutions
+  list_distributions: read('List website distributions'),
+  get_embed_code: read('Get embed code of an agent'),
+  create_distribution: { ...write('Open agent on a website path'), guard: true, describe: (a) => `This will open agent ${a.agent_id} on ${a.host}${a.path_expression ?? a.path}; visitors of that page see it.` },
+  update_distribution: { ...write('Change a website distribution', { idempotentHint: true }), guard: true, describe: (a) => `This will change distribution ${a.distribution_id}; visitors see it immediately.` },
+  list_templates: { ...read('List agent templates'), paginate: true },
+  create_template: { ...write('Publish agent as template'), guard: true, describe: (a) => `This will publish agent ${a.agent_id} as template "${a.name}"; every org on the platform can copy its prompt and skills.` },
+  delete_template: { ...destroy('Remove template'), guard: true, describe: (a) => `This will remove template ${a.template_id} for every org.` },
+  create_agent_from_template: write('Create agent from template'),
+  list_solutions: read('List solutions'),
+
+  // Analytics, org settings, audit
+  get_analytics: read('Get analytics'),
+  list_analytics_conversations: read('Conversations behind an analytics number'),
+  list_custom_charts: read('List custom charts'),
+  get_custom_chart: read('Get custom chart data'),
+  get_org_settings: read('Get org settings'),
+  set_org_timezone: { ...write('Set org timezone', { idempotentHint: true }), guard: true, describe: (a) => `This will set the org timezone to ${a.timezone}.` },
+  set_business_hours: { ...destroy('Replace business hours', { idempotentHint: true }), guard: true, describe: (a) => `This will replace the org business hours (enabled: ${a.enabled}).` },
+  add_holiday: { ...write('Add holiday'), guard: true, describe: (a) => `This will close the org on ${a.date} (${a.name}).` },
+  set_org_admin_settings: { ...write('Change org admin settings', { idempotentHint: true }), guard: true },
+  list_audit_logs: read('List audit log'),
+
+  // Tickets
+  list_tickets: read('List tickets'),
+  get_ticket: read('Get ticket'),
+  create_ticket: write('Create ticket'),
+  update_ticket: write('Update, assign or close a ticket'),
+  archive_ticket: { ...destroy('Archive ticket'), guard: true, describe: (a) => `This will archive ticket ${a.ticket_id}.` },
+  list_ticket_rules: read('List ticket rules'),
+  save_ticket_rule: write('Create or change a ticket rule'),
+  delete_ticket_rule: { ...destroy('Delete ticket rule'), guard: true, describe: (a) => `This will delete ticket rule ${a.rule_id}; agents stop opening tickets for it.` },
+
+  // Billing (read-only)
+  get_billing: read('Billing status, invoices, usage or plans'),
+
+  // Campaigns (read-only)
+  get_campaigns: read('Read campaigns and templates'),
+
+  // V2 platform and Jarvis (Darwin)
+  platform_list: read('List V2 platform items'),
+  platform_get: read('Get a V2 platform item'),
+  platform_save: { ...write('Create or change a V2 platform item'), guard: true, describe: (a) => `This will ${a.id ? `change ${a.resource} ${a.id}` : `create a ${a.resource}`} on the V2 platform.` },
+  platform_delete: { ...destroy('Delete a V2 platform item'), guard: true, describe: (a) => `This will delete ${a.resource} ${a.id} from the V2 platform.` },
+  validate_platform_template: read('Validate a V2 template'),
+  run_simulation: { ...write('Run V2 simulations (paid)'), guard: true, describe: (a) => `This will run simulations for V2 agent ${a.agent_id} with paid model calls.` },
+  simulation_status: read('Simulation jobs and results'),
+  org_evaluations: read('Baseline evaluation coverage'),
+  jarvis_create_job: { ...write('Ask Jarvis for baseline evaluations (paid)'), guard: true, describe: (a) => `This will ask Jarvis to generate baseline evaluations for ${((a.bot_ids as unknown[]) ?? []).length} agent(s) with paid model calls.` },
+  jarvis_jobs: read('Jarvis jobs'),
+  jarvis_chat: { ...write('Chat with Jarvis', { openWorldHint: true }), guard: true, describe: () => 'This sends a message to Jarvis, which may create or change templates, agents or connectors in the org.' },
+
+  // Chat
+  chat_with_agent: write('Chat with agent (test conversation)'),
+
+  // Evaluations
+  run_evaluation: {
+    ...write('Run evaluation (paid, cannot be cancelled)'),
+    guard: true,
+    describe: (a) => `This will evaluate agent ${a.agent_id ?? a.bot_id} on test set ${a.test_set_id}${a.limit ? ` (first ${a.limit} items)` : ''}${a.date_from ? ` against real conversations from ${a.date_from} to ${a.date_to}` : ''} with concurrency ${a.concurrency ?? 1}. It uses paid model calls and cannot be cancelled.`,
+  },
+  eval_gate_verdict: read('Judge a run like the CI gate'),
+  eval_trends: read('Evaluation trends'),
+  compare_eval_runs: read('Compare two evaluation runs'),
+  eval_report_link: write('Render evaluation report on the server', { idempotentHint: true }),
+  eval_quality_metrics: { ...read('Voice quality metric names'), orgScoped: false },
+  list_prod_calls: read('List production voice calls'),
+  promote_prod_call: { ...write('Promote a call to a regression test', { idempotentHint: true }), guard: true, describe: (a) => `This will add call ${a.session_id} to the agent's "Regressions (review)" test set.` },
+  evaluate_transcript: { ...write('Grade a transcript (paid)'), guard: true, describe: (a) => `This will grade a replayed transcript for agent ${a.agent_id} with paid model calls.` },
+  list_evaluator_configs: { ...read('List evaluator configs'), paginate: true },
+  get_eval_status: read('Get evaluation status'),
+  get_eval_results: read('Get evaluation results'),
+  get_bot_context: read('Get agent context for evaluation'),
+  list_rubrics: { ...read('List rubrics'), paginate: true },
+  get_rubric: read('Get rubric'),
+  create_rubric: write('Create rubric'),
+  update_rubric: write('Update rubric', { idempotentHint: true }),
+  delete_rubric: { ...destroy('Delete rubric'), guard: true, describe: (a) => `This will delete rubric ${a.rubric_id}.` },
+  list_rubric_versions: read('List rubric versions'),
+  list_test_sets: { ...read('List test sets'), paginate: true },
+  get_test_set: read('Get test set'),
+  create_test_set: write('Create test set'),
+  update_test_set: write('Update test set', { idempotentHint: true }),
+  delete_test_set: { ...destroy('Delete test set'), guard: true, describe: (a) => `This will delete test set ${a.test_set_id}.` },
+  list_test_set_versions: read('List test set versions'),
+
+  // Reports (write local files)
+  export_eval_markdown: { ...write('Export evaluation as Markdown file', { idempotentHint: true }), orgScoped: false },
+  export_eval_report: { ...write('Export evaluation PDF report', { idempotentHint: true }), orgScoped: false },
+  export_agent_card: write('Export agent card PDF', { idempotentHint: true }),
+};