@tacitai/mcp-server 0.6.32 → 0.6.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -43,6 +43,7 @@ import { registerAnnotationTools } from './tools/annotations.js';
43
43
  import { registerExportTools } from './tools/export.js';
44
44
  import { registerMoveTools } from './tools/move.js';
45
45
  import { registerAgentTools } from './tools/agents.js';
46
+ import { registerExecRouteTool } from './tools/exec-route.js';
46
47
  import { registerPyramidTools } from './tools/pyramid.js';
47
48
  import { registerSharingTools } from './tools/sharing.js';
48
49
  import { registerKbTools } from './tools/kb.js';
@@ -92,6 +93,45 @@ const gate = new WorkflowGate({
92
93
  }
93
94
  },
94
95
  });
96
+ // F-12: convert workflow guidance constants to human-readable sentences
97
+ const GUIDANCE_MAP = {
98
+ GM_WORKFLOW: 'Active GM workflow. Next: call tacit_gm_approve to confirm content placement, or tacit_gm_reset to cancel.',
99
+ COS_SUB_WORKFLOWS: 'Chief of Staff coordinating. Use tacit_agent_delegate to hand off sub-tasks to the appropriate role.',
100
+ PYR_EXEC_SUB_WORKFLOWS: 'Pyramid operations active. Use tacit_pyramid_list_* tools to explore structure before making changes.',
101
+ COO_SUB_WORKFLOWS: 'COO operations active. Delegate sub-tasks to specialized roles via tacit_agent_delegate.',
102
+ CMO_INTAKE: 'CMO pipeline: intake phase. Describe the marketing objective and target audience.',
103
+ CMO_BRAND_LOAD: 'CMO pipeline: loading brand context. The system will pull voice profiles and brand guidelines.',
104
+ CMO_PRODUCE: 'CMO pipeline: production phase. Creating marketing content.',
105
+ CMO_LINT: 'CMO pipeline: lint phase. Call tacit_cmo_lint to check brand and compliance rules.',
106
+ CMO_JUDGE_RECEIPT: 'CMO pipeline: judge/receipt phase. Content is being evaluated for quality.',
107
+ CMO_HANDOFF: 'CMO pipeline: handoff. Route final content through tacit_gm_ingest for placement.',
108
+ CMO_MARKETING_PIPELINE: 'CMO marketing pipeline active. Follow the phase sequence: intake → brand → produce → lint → judge → handoff.',
109
+ SALES_CONTEXT: 'Sales pipeline: context phase. Gather client context before discovery.',
110
+ SALES_DISCOVERY: 'Sales pipeline: discovery phase. Run discovery analysis.',
111
+ SALES_PROPOSAL: 'Sales pipeline: proposal phase. Draft the proposal.',
112
+ SALES_REVIEW: 'Sales pipeline: review phase. Review and refine the proposal.',
113
+ SALES_QUOTE: 'Sales pipeline: quote phase. Generate pricing.',
114
+ SALES_PILOT: 'Sales pipeline: pilot phase. Set up a pilot engagement.',
115
+ SALES_PIPELINE: 'Sales pipeline: pipeline management. Track deal status.',
116
+ SALES_FULL_PIPELINE: 'Sales pipeline active. Follow phase sequence: context → discovery → proposal → review → quote → pilot → pipeline.',
117
+ RESEARCH_PREPARE: 'Research: prepare phase. Call tacit_research_prepare to set up the research plan.',
118
+ RESEARCH_PLAN_APPROVAL: 'Research: awaiting plan approval before launching.',
119
+ RESEARCH_DISPATCH: 'Research: dispatch phase. Call tacit_research_launch to start execution.',
120
+ RESEARCH_SYNTHESIS: 'Research: synthesis in progress.',
121
+ RESEARCH_PLACEMENT: 'Research: placement phase. Call tacit_research_place to file the results.',
122
+ RESEARCH_EXEC: 'Research workflow active. Follow: prepare → approve → launch → synthesize → place.',
123
+ WIKI_AUTHORING: 'Wiki authoring active. Follow: classify → validate → author. Write/override require approval.',
124
+ KB_MANAGEMENT: 'KB management active. Browse the KB structure first, then curate content.',
125
+ LAKE_OPERATIONS: 'Data lake operations active. Explore catalog first, then ingest/classify, then propose structure.',
126
+ };
127
+ function expandGuidance(raw, _typeName, phase) {
128
+ const expanded = GUIDANCE_MAP[raw];
129
+ if (expanded)
130
+ return expanded;
131
+ if (phase)
132
+ return `Workflow phase: ${phase}. Check tacit_workflow_prereqs for required next steps.`;
133
+ return `Active workflow. Check tacit_workflow_prereqs for required next steps.`;
134
+ }
95
135
  // MV-1539 W1 Step 3: preCall hook — wraps every tool handler to record calls centrally.
96
136
  const PRECALL_EXEMPT = new Set(['tacit_cmo_lint']);
97
137
  function installPreCallHook(server) {
@@ -132,7 +172,21 @@ function installPreCallHook(server) {
132
172
  }
133
173
  }
134
174
  }
135
- return originalHandler(...callArgs);
175
+ // F-12: inject post-call guidance from active workflows
176
+ const handlerResult = await originalHandler(...callArgs);
177
+ if (handlerResult && !handlerResult['isError']) {
178
+ const allGuidance = gate.getGuidanceAll(principal);
179
+ if (allGuidance.length > 0) {
180
+ const guidanceText = allGuidance.map((g) => expandGuidance(g.guidance, g.typeName, g.phase)).filter(Boolean);
181
+ if (guidanceText.length > 0) {
182
+ const content = handlerResult['content'];
183
+ if (Array.isArray(content)) {
184
+ content.push({ type: 'text', text: `\n--- Workflow guidance ---\n${guidanceText.join('\n')}` });
185
+ }
186
+ }
187
+ }
188
+ }
189
+ return handlerResult;
136
190
  };
137
191
  return originalTool(...registerArgs);
138
192
  };
@@ -293,6 +347,7 @@ async function run() {
293
347
  registerWorkflowTypeTools(server, getClient, gate.getRegistry());
294
348
  registerWorkflowPrereqsTool(server, gate.getRegistry());
295
349
  registerCmoTools(server);
350
+ registerExecRouteTool(server);
296
351
  registerPrompts(server, getClient);
297
352
  if (process.env['MCP_TRANSPORT'] === 'http') {
298
353
  await startHttpTransport(server);
@@ -106,7 +106,7 @@ export const agentDelegateInputSchema = z.object({
106
106
  target_ids: z.array(z.string()).optional().describe('Target entity UUIDs for the task'),
107
107
  program_ids: z.array(z.string()).optional().describe('Program UUIDs to scope the task'),
108
108
  dossier_ids: z.array(z.string()).optional().describe('Dossier UUIDs to scope the task'),
109
- wait: z.boolean().optional().default(true).describe('Wait for the run to complete and return results inline (default: true)'),
109
+ wait: z.boolean().optional().default(false).describe('Return immediately with run_id (default: false). Set true to wait for results inline.'),
110
110
  wait_timeout: z.number().int().positive().optional().default(120).describe('Max seconds to wait for completion (default: 120)'),
111
111
  }).refine((d) => d.agent_id || d.role_slug, { message: 'Either agent_id or role_slug is required' });
112
112
  export const AGENT_DELEGATE_TOOL_DEF = {
@@ -125,7 +125,7 @@ export const AGENT_DELEGATE_TOOL_DEF = {
125
125
  target_ids: { type: 'array', items: { type: 'string' }, description: 'Target entity UUIDs' },
126
126
  program_ids: { type: 'array', items: { type: 'string' }, description: 'Program UUIDs to scope the task' },
127
127
  dossier_ids: { type: 'array', items: { type: 'string' }, description: 'Dossier UUIDs to scope the task' },
128
- wait: { type: 'boolean', description: 'Wait for run completion and return results inline (default: true)' },
128
+ wait: { type: 'boolean', description: 'Return immediately with run_id (default: false). Set true to wait for results inline.' },
129
129
  wait_timeout: { type: 'number', description: 'Max seconds to wait for completion (default: 120)' },
130
130
  },
131
131
  required: ['task'],
@@ -286,6 +286,20 @@ export function buildAgentDelegateRequest(client, input) {
286
286
  : 'timeout',
287
287
  messages,
288
288
  };
289
+ // A5: if delegation produced artifacts, guide toward GM placement
290
+ if (poll.completed && Array.isArray(messages) && messages.length > 0) {
291
+ const hasArtifact = messages.some((m) => {
292
+ const msg = m;
293
+ const content = (msg['content'] ?? msg['text'] ?? '');
294
+ return content.includes('artifact') || content.includes('draft') || content.includes('produced');
295
+ });
296
+ if (hasArtifact) {
297
+ combined['_next_steps'] = [
298
+ 'The delegate produced content. Route it through tacit_gm_ingest for proper placement in the data lake, KB, or pyramid.',
299
+ 'Call tacit_exec_route with role_hint="general_manager" to get the placement workflow script.',
300
+ ];
301
+ }
302
+ }
289
303
  return { content: [{ type: 'text', text: JSON.stringify(combined) }] };
290
304
  }
291
305
  catch (err) {
@@ -470,7 +484,7 @@ export function registerAgentTools(server, getClientFn) {
470
484
  const client = await getClientFn();
471
485
  return buildAgentListRequest(client, args).execute();
472
486
  });
473
- server.tool('tacit_agent_delegate', 'Delegate a task to a business agent and wait for results. Accepts agent_id or role_slug. Returns the agent\'s output inline by default.', {
487
+ server.tool('tacit_agent_delegate', 'Delegate a task to a business agent. Accepts agent_id or role_slug. Returns run_id immediately by default; set wait=true to get results inline.', {
474
488
  agent_id: z.string().min(1).optional().describe('UUID of the agent to delegate to (provide this OR role_slug)'),
475
489
  role_slug: z.string().min(1).optional().describe('Role template slug (e.g. "wiki_editor"). Creates instance on first use'),
476
490
  task: z.string().min(1).describe('Task description to delegate'),
@@ -478,7 +492,7 @@ export function registerAgentTools(server, getClientFn) {
478
492
  target_ids: z.array(z.string()).optional().describe('Target entity UUIDs'),
479
493
  program_ids: z.array(z.string()).optional().describe('Program UUIDs'),
480
494
  dossier_ids: z.array(z.string()).optional().describe('Dossier UUIDs'),
481
- wait: z.boolean().optional().default(true).describe('Wait for completion and return results (default: true)'),
495
+ wait: z.boolean().optional().default(false).describe('Return immediately with run_id (default: false). Set true to wait for results inline.'),
482
496
  wait_timeout: z.number().int().positive().optional().default(120).describe('Max seconds to wait (default: 120)'),
483
497
  }, async (args) => {
484
498
  const client = await getClientFn();
@@ -512,4 +526,18 @@ export function registerAgentTools(server, getClientFn) {
512
526
  const client = await getClientFn();
513
527
  return buildAgentTimelineRequest(client, args).execute();
514
528
  });
529
+ // A4: tacit_agent_status — check status of a delegation run
530
+ server.tool('tacit_agent_status', 'Check status of an agent delegation run. Returns run status, progress, and output messages if complete.', {
531
+ run_id: z.string().min(1).describe('Run ID from a prior tacit_agent_delegate call'),
532
+ }, async (args) => {
533
+ const client = await getClientFn();
534
+ try {
535
+ const result = await client.request('GET', `/api/v1/agents/mcp/runs/${args.run_id}`);
536
+ return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
537
+ }
538
+ catch (err) {
539
+ const msg = err instanceof Error ? err.message : String(err);
540
+ return { content: [{ type: 'text', text: JSON.stringify({ error: msg }) }], isError: true };
541
+ }
542
+ });
515
543
  }
@@ -0,0 +1,10 @@
1
+ /**
2
+ * tacit_exec_route — Route a natural-language request to the correct executive role.
3
+ *
4
+ * Under tool deferral (163+ deferred tools), the LLM sees only tool names.
5
+ * `tacit_agent_delegate` doesn't signal "ask your CMO about marketing."
6
+ * This tool bridges natural language intent → correct executive role →
7
+ * imperative next-step script the LLM can follow deterministically.
8
+ */
9
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
10
+ export declare function registerExecRouteTool(server: McpServer): void;
@@ -0,0 +1,157 @@
1
+ /**
2
+ * tacit_exec_route — Route a natural-language request to the correct executive role.
3
+ *
4
+ * Under tool deferral (163+ deferred tools), the LLM sees only tool names.
5
+ * `tacit_agent_delegate` doesn't signal "ask your CMO about marketing."
6
+ * This tool bridges natural language intent → correct executive role →
7
+ * imperative next-step script the LLM can follow deterministically.
8
+ */
9
+ import { z } from 'zod';
10
+ const ROLE_ROUTES = [
11
+ {
12
+ slug: 'general_manager',
13
+ present_as: 'General Manager',
14
+ workflow_type: 'gm_operations',
15
+ keywords: ['file this', 'save this', 'ingest', 'place this', 'store', 'catalog', 'route content', 'gm'],
16
+ description: 'Routes and places content into the data lake, KB, or pyramid. The default for "do something with this content."',
17
+ },
18
+ {
19
+ slug: 'chief_of_staff',
20
+ present_as: 'Chief of Staff',
21
+ workflow_type: 'cos_operations',
22
+ keywords: ['morning brief', 'daily brief', 'triage', 'email', 'meeting prep', 'agenda', 'schedule', 'priorities'],
23
+ description: 'Daily operations, briefings, meeting prep, email triage, priority management.',
24
+ },
25
+ {
26
+ slug: 'coo_operator',
27
+ present_as: 'COO Operator',
28
+ workflow_type: 'coo_operations',
29
+ keywords: ['operational status', 'team coordination', 'process review', 'ops', 'workflow', 'capacity', 'resource'],
30
+ description: 'Operational oversight, team coordination, process reviews, capacity planning.',
31
+ },
32
+ {
33
+ slug: 'pyramid_executor',
34
+ present_as: 'Pyramid Executor',
35
+ workflow_type: 'pyramid_operations',
36
+ keywords: ['portfolio', 'program', 'value stream', 'dossier', 'alignment', 'strategic', 'pyramid'],
37
+ description: 'Manages the organizational pyramid: portfolios, programs, value streams, dossiers.',
38
+ },
39
+ {
40
+ slug: 'cmo_marketer',
41
+ present_as: 'CMO Marketer',
42
+ workflow_type: 'cmo_operations',
43
+ keywords: ['marketing', 'campaign', 'brand', 'content strategy', 'social media', 'positioning', 'messaging'],
44
+ description: 'Marketing campaigns, brand strategy, content creation, positioning.',
45
+ },
46
+ {
47
+ slug: 'sales_executor',
48
+ present_as: 'Sales Executor',
49
+ workflow_type: 'sales_operations',
50
+ keywords: ['sales', 'pipeline', 'proposal', 'discovery', 'prospect', 'lead', 'deal', 'quote', 'revenue'],
51
+ description: 'Sales pipeline, proposals, discovery calls, prospecting, deal management.',
52
+ },
53
+ {
54
+ slug: 'wiki_editor',
55
+ present_as: 'Wiki Editor',
56
+ workflow_type: 'wiki_operations',
57
+ keywords: ['wiki', 'article', 'publish to wiki', 'documentation', 'wiki write'],
58
+ description: 'Authors and publishes wiki articles. Wiki writes require approval.',
59
+ },
60
+ {
61
+ slug: 'kb_curator',
62
+ present_as: 'KB Curator',
63
+ workflow_type: 'kb_operations',
64
+ keywords: ['knowledge base', 'kb article', 'organize knowledge', 'kb collection', 'kb category'],
65
+ description: 'Manages the knowledge base: articles, collections, categories, source registration.',
66
+ },
67
+ {
68
+ slug: 'lake_operator',
69
+ present_as: 'Lake Operator',
70
+ workflow_type: 'lake_operations',
71
+ keywords: ['data source', 'data lake', 'classify', 'taxonomy', 'catalog', 'connector', 'sync'],
72
+ description: 'Manages the data lake: sources, classification, taxonomy, connectors, sync.',
73
+ },
74
+ ];
75
+ function matchRole(request) {
76
+ const lower = request.toLowerCase();
77
+ const scores = [];
78
+ for (const route of ROLE_ROUTES) {
79
+ let score = 0;
80
+ for (const kw of route.keywords) {
81
+ if (lower.includes(kw)) {
82
+ score += kw.split(' ').length; // multi-word matches score higher
83
+ }
84
+ }
85
+ if (score > 0) {
86
+ scores.push({ route, score });
87
+ }
88
+ }
89
+ scores.sort((a, b) => b.score - a.score);
90
+ if (scores.length === 0) {
91
+ // Default to GM — it can triage
92
+ return {
93
+ primary: ROLE_ROUTES[0],
94
+ alternatives: [],
95
+ };
96
+ }
97
+ const primary = scores[0].route;
98
+ const alternatives = scores.slice(1, 3).map((s) => ({
99
+ role_slug: s.route.slug,
100
+ reason: s.route.description,
101
+ }));
102
+ return { primary, alternatives };
103
+ }
104
+ function buildScript(role) {
105
+ const steps = [];
106
+ steps.push(`Call tacit_agent_delegate with role_slug="${role.slug}" and your task description.`);
107
+ steps.push('The delegation returns a run_id. Use tacit_agent_status to check progress if wait=false.');
108
+ if (role.workflow_type === 'gm_operations') {
109
+ steps.push('For content placement: call tacit_gm_ingest first, then tacit_gm_approve to confirm placement.');
110
+ }
111
+ else if (role.workflow_type === 'wiki_operations') {
112
+ steps.push('Wiki writes require approval. The workflow enforces: draft → review → approve → publish.');
113
+ }
114
+ else if (role.workflow_type === 'pyramid_operations') {
115
+ steps.push('Use tacit_pyramid_list_portfolios to see the current structure before making changes.');
116
+ }
117
+ steps.push('Check tacit_workflow_prereqs if a tool returns a workflow block — it shows required prior steps.');
118
+ return steps;
119
+ }
120
+ export function registerExecRouteTool(server) {
121
+ server.tool('tacit_exec_route', 'Route a business request to the right executive role. Returns the role, workflow type, and a step-by-step script of tools to call. Use this as the first step for any business request.', {
122
+ request: z.string().min(1).describe('Natural language description of what you want to do'),
123
+ role_hint: z.string().optional().describe('If you already know the role slug, pass it here to skip matching'),
124
+ }, async (args) => {
125
+ const { request, role_hint } = args;
126
+ let primary;
127
+ let alternatives = [];
128
+ if (role_hint) {
129
+ const found = ROLE_ROUTES.find((r) => r.slug === role_hint);
130
+ if (!found) {
131
+ const slugs = ROLE_ROUTES.map((r) => r.slug).join(', ');
132
+ return {
133
+ content: [{ type: 'text', text: JSON.stringify({ error: `Unknown role_hint: ${role_hint}. Available: ${slugs}` }) }],
134
+ isError: true,
135
+ };
136
+ }
137
+ primary = found;
138
+ }
139
+ else {
140
+ const match = matchRole(request);
141
+ primary = match.primary;
142
+ alternatives = match.alternatives;
143
+ }
144
+ const result = {
145
+ role_slug: primary.slug,
146
+ present_as: primary.present_as,
147
+ workflow_type: primary.workflow_type,
148
+ description: primary.description,
149
+ first_tool: 'tacit_agent_delegate',
150
+ script: buildScript(primary),
151
+ ...(alternatives.length > 0 ? { alternatives } : {}),
152
+ };
153
+ return {
154
+ content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
155
+ };
156
+ });
157
+ }
@@ -331,7 +331,7 @@ export const KB_TYPE_DEF = {
331
331
  kind: 'phased',
332
332
  phases: [
333
333
  { name: 'browse', requiredTools: ['tacit_kb_browse_tree', 'tacit_kb_list_collections', 'tacit_kb_list_categories'], gatedTools: [], approvalGate: false, guidance: 'Browse the knowledge base structure before making changes.' },
334
- { name: 'curate', requiredTools: [], gatedTools: ['tacit_kb_create_article', 'tacit_kb_update_article', 'tacit_kb_create_category', 'tacit_kb_create_collection', 'tacit_kb_update_collection', 'tacit_kb_delete_collection', 'tacit_kb_promote_from_artifact', 'tacit_kb_promote_from_catalog'], approvalGate: false, guidance: 'Create, update, or promote KB content. Browse phase must complete first.' },
334
+ { name: 'curate', requiredTools: [], gatedTools: ['tacit_kb_create_article', 'tacit_kb_update_article', 'tacit_kb_create_category', 'tacit_kb_create_collection', 'tacit_kb_update_collection', 'tacit_kb_delete_collection', 'tacit_kb_promote_from_artifact', 'tacit_kb_promote_from_catalog', 'tacit_artifact_create'], approvalGate: false, guidance: 'Create, update, or promote KB content. Browse phase must complete first.' },
335
335
  { name: 'source_admin', requiredTools: [], gatedTools: ['tacit_kb_pull_source'], approvalGate: true, guidance: 'Source administration requires approval. Note: tacit_kb_register_source is ADMIN_ONLY transport and bypasses this gate.' },
336
336
  ],
337
337
  },
@@ -347,7 +347,7 @@ export const LAKE_TYPE_DEF = {
347
347
  kind: 'phased',
348
348
  phases: [
349
349
  { name: 'explore', requiredTools: ['tacit_lake_browse_catalog', 'tacit_lake_folder_list', 'tacit_lake_taxonomy_browse'], gatedTools: [], approvalGate: false, guidance: 'Explore the data lake catalog and taxonomy before operations.' },
350
- { name: 'ingest', requiredTools: [], gatedTools: ['tacit_lake_ingest', 'tacit_lake_classify', 'tacit_lake_classify_subject', 'tacit_lake_reclassify', 'tacit_lake_reclassify_subjects', 'tacit_lake_folder_add', 'tacit_lake_folder_rename'], approvalGate: false, guidance: 'Ingest and classify content. Explore phase must complete first.' },
350
+ { name: 'ingest', requiredTools: [], gatedTools: ['tacit_lake_ingest', 'tacit_lake_classify', 'tacit_lake_classify_subject', 'tacit_lake_reclassify', 'tacit_lake_reclassify_subjects', 'tacit_lake_folder_add', 'tacit_lake_folder_rename', 'tacit_move'], approvalGate: false, guidance: 'Ingest and classify content. Explore phase must complete first.' },
351
351
  { name: 'structure', requiredTools: [], gatedTools: ['tacit_lake_propose_structure', 'tacit_lake_confirm_proposal'], approvalGate: true, guidance: 'Structure proposals require approval before confirmation.' },
352
352
  ],
353
353
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tacitai/mcp-server",
3
- "version": "0.6.32",
3
+ "version": "0.6.33",
4
4
  "description": "stdio MCP server wrapping Tacit /api/v1 REST/SSE API",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -40,5 +40,7 @@
40
40
  "typescript": "^5.4.0",
41
41
  "vitest": "^4.1.7"
42
42
  },
43
- "private": false
43
+ "publishConfig": {
44
+ "access": "restricted"
45
+ }
44
46
  }