@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/mcp/server.mjs

@@ -1,774 +1,60 @@
 #!/usr/bin/env node
 /**
- * lib/mcp/server.mjs — Construct MCP server exposing workflow, skill, and observability tools.
+ * lib/mcp/server.mjs — Construct MCP server: tool registry and request dispatcher.
  *
- * Provides MCP tools for agent health, workflow management, skill retrieval, and Langfuse telemetry.
+ * Thin dispatcher only — all tool implementations live in lib/mcp/tools/*.mjs.
+ * Registers 40 tools across 7 modules: project, document, storage, skills, workflow, telemetry, memory.
  * Consumed by Claude Code, OpenCode, and any MCP-compatible host.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { homedir } from 'node:os';
-import { execSync } from 'node:child_process';
-import * as langfuse from '../telemetry/backends/langfuse.mjs';
-import { summarizePromptComposition } from '../prompt-composer.mjs';
-import { enrichMetadataWithPrompt } from '../prompt-metadata.mjs';
-import { readCurrentModels, resolveExecutionContractModelMetadata, selectModelTierForWorkCategory } from '../model-router.mjs';
+import { realpathSync } from 'node:fs';
 import { loadToolkitEnv } from '../toolkit-env.mjs';
 import { loadConstructEnv } from '../env-config.mjs';
-import { inspectContextState } from '../context-state.mjs';
 
-const DEFAULT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
-const ROOT_DIR = resolve(process.env.CX_TOOLKIT_DIR || DEFAULT_ROOT_DIR);
-loadToolkitEnv(ROOT_DIR);
-import {
-  addTask,
-  addTaskFromIntent,
-  addTasksFromPlan,
-  alignmentFindings,
-  createNeedsMainInputPacket,
-  initWorkflow,
-  inspectWorkflowHealth,
-  loadWorkflow,
-  summarizeWorkflow,
-  updateTask,
-  validateWorkflowState,
-} from '../workflow-state.mjs';
-import { buildPublicHealthSurface, buildStatus } from '../status.mjs';
-import { routeRequest, requiresExecutiveApproval, TERMINAL_STATES } from '../orchestration-policy.mjs';
-
-const SECRET_PATTERNS = [
-  { name: 'Anthropic API key', pattern: /ANTHROPIC_API_KEY\s*=\s*(sk-ant-[a-zA-Z0-9\-_]{20,})/i },
-  { name: 'OpenAI API key', pattern: /OPENAI_API_KEY\s*=\s*(sk-[a-zA-Z0-9]{40,})/i },
-  { name: 'OpenRouter key', pattern: /(sk-or-v1-[a-zA-Z0-9]{40,})/ },
-  { name: 'AWS access key', pattern: /(AKIA[0-9A-Z]{16})/ },
-  { name: 'Private key (PEM)', pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/ },
-  { name: 'GitHub personal access token', pattern: /(ghp_[a-zA-Z0-9]{36})/ },
-  { name: 'GitHub Actions token', pattern: /(ghs_[a-zA-Z0-9]{36})/ },
-  { name: 'Database URL with credentials', pattern: /DATABASE_URL\s*=\s*(postgresql:\/\/[^@]+:[^@]+@)/i },
-];
-
-const PLACEHOLDER_PATTERNS = [
-  /\.\.\./,
-  /YOUR_KEY/i,
-  /<[^>]+>/,
-  /^sk-\.\.\./,
-  /^pk-lf-\.\.\./,
-  /__[A-Z_]+__/,
-];
-
-function isPlaceholder(value) {
-  return PLACEHOLDER_PATTERNS.some((p) => p.test(value));
-}
-
-function isBinary(buffer) {
-  const len = Math.min(buffer.length, 512);
-  for (let i = 0; i < len; i++) {
-    if (buffer[i] === 0) return true;
-  }
-  return false;
-}
-
-function exec(cmd, cwd) {
-  return execSync(cmd, { stdio: 'pipe', timeout: 10000, cwd }).toString().trim();
-}
-
-function readJSON(filePath) {
-  if (!existsSync(filePath)) return null;
-  try {
-    return JSON.parse(readFileSync(filePath, 'utf8'));
-  } catch {
-    return null;
+// Apply config.env values to process.env, letting config.env win over shell env
+// so telemetry/OpenRouter credentials are always correct regardless of host env.
+{
+  const confEnv = loadConstructEnv({ warn: false });
+  for (const [k, v] of Object.entries(confEnv)) {
+    process.env[k] = v;
   }
 }
 
-// Tool: agent_health
-function agentHealth(args) {
-  const reviewDir = join(homedir(), '.cx', 'performance-reviews');
-
-  if (!existsSync(reviewDir)) {
-    return { error: "No performance reviews found. Run 'construct review' to generate one." };
-  }
-
-  let files;
-  try {
-    files = readdirSync(reviewDir);
-  } catch {
-    return { error: "No performance reviews found. Run 'construct review' to generate one." };
-  }
-
-  const processed = files
-    .filter((f) => f.endsWith('.json') && !f.endsWith('-raw.json'))
-    .sort()
-    .reverse();
-
-  const raw = files
-    .filter((f) => f.endsWith('-raw.json'))
-    .sort()
-    .reverse();
-
-  const candidates = processed.length > 0 ? processed : raw;
-
-  if (candidates.length === 0) {
-    return { error: "No performance reviews found. Run 'construct review' to generate one." };
-  }
-
-  let data;
-  try {
-    const content = readFileSync(join(reviewDir, candidates[0]), 'utf8');
-    data = JSON.parse(content);
-  } catch {
-    return { error: "Failed to parse performance review file." };
-  }
-
-  const reviewDate = data.reviewDate ?? data.generatedAt ?? candidates[0].replace(/\.json$/, '');
-  const period = data.period ?? data.windowDays ?? null;
-
-  let agents = [];
-
-  if (Array.isArray(data.agents)) {
-    agents = data.agents;
-  } else if (data.agentReviews) {
-    agents = Object.entries(data.agentReviews).map(([name, review]) => ({
-      name,
-      status: review.status ?? review.health ?? 'unknown',
-      avgScore: review.avgScore ?? review.averageScore ?? null,
-      trend: review.trend ?? null,
-      failureRate: review.failureRate ?? null,
-      invocations: review.invocations ?? review.totalCalls ?? null,
-    }));
-  } else if (data.summary && Array.isArray(data.summary.agents)) {
-    agents = data.summary.agents;
-  }
-
-  if (args.agent_name) {
-    const target = args.agent_name.toLowerCase();
-    agents = agents.filter((a) => (a.name ?? '').toLowerCase().includes(target));
-  }
-
-  const normalized = agents.map((a) => ({
-    name: a.name ?? 'unknown',
-    status: a.status ?? 'unknown',
-    avgScore: a.avgScore ?? a.averageScore ?? null,
-    trend: a.trend ?? null,
-    failureRate: a.failureRate ?? null,
-    invocations: a.invocations ?? a.totalCalls ?? null,
-  }));
-
-  return { reviewDate, period, agents: normalized };
-}
-
-// Tool: summarize_diff
-function summarizeDiff(args) {
-  const baseRef = args.base_ref ?? 'HEAD~1';
-  const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
-
-  let stat, nameStatus;
-  try {
-    stat = exec(`git diff --stat ${baseRef}`, cwd);
-    nameStatus = exec(`git diff --name-status ${baseRef}`, cwd);
-  } catch {
-    return { error: 'Not a git repository or git not available' };
-  }
-
-  const changes = nameStatus
-    .split('\n')
-    .filter(Boolean)
-    .map((line) => {
-      const [status, ...parts] = line.split('\t');
-      return { status: status.trim(), file: parts.join('\t') };
-    });
-
-  // Parse insertions/deletions from stat summary line
-  const statLines = stat.split('\n');
-  const summaryLine = statLines[statLines.length - 1] ?? '';
-  const filesMatch = summaryLine.match(/(\d+) files? changed/);
-  const insertionsMatch = summaryLine.match(/(\d+) insertions?\(\+\)/);
-  const deletionsMatch = summaryLine.match(/(\d+) deletions?\(-\)/);
-
-  const filesChanged = filesMatch ? parseInt(filesMatch[1], 10) : changes.length;
-  const insertions = insertionsMatch ? parseInt(insertionsMatch[1], 10) : 0;
-  const deletions = deletionsMatch ? parseInt(deletionsMatch[1], 10) : 0;
-
-  const added = changes.filter((c) => c.status === 'A').length;
-  const modified = changes.filter((c) => c.status === 'M').length;
-  const deleted = changes.filter((c) => c.status === 'D').length;
-
-  const parts = [];
-  if (modified > 0) parts.push(`${modified} file${modified > 1 ? 's' : ''} modified`);
-  if (added > 0) parts.push(`${added} file${added > 1 ? 's' : ''} added`);
-  if (deleted > 0) parts.push(`${deleted} file${deleted > 1 ? 's' : ''} deleted`);
-
-  const summary =
-    parts.length > 0
-      ? `${parts.join(', ')} (+${insertions}/-${deletions} lines) vs ${baseRef}.`
-      : `No changes vs ${baseRef}.`;
-
-  return { base_ref: baseRef, files_changed: filesChanged, insertions, deletions, changes, summary };
-}
-
-// Tool: scan_file
-function scanFile(args) {
-  const filePath = resolve(args.file_path);
-
-  let rawBuffer;
-  try {
-    rawBuffer = readFileSync(filePath);
-  } catch (err) {
-    return { error: `Cannot read file: ${err.message}` };
-  }
-
-  if (isBinary(rawBuffer)) {
-    return { file_path: filePath, secrets: [], quality_issues: [], clean: true };
-  }
-
-  const content = rawBuffer.toString('utf8');
-  const lines = content.split('\n');
-
-  // Secret scanning
-  const secrets = [];
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    for (const { name, pattern } of SECRET_PATTERNS) {
-      const match = pattern.exec(line);
-      if (!match) continue;
-      const captured = match[1] ?? match[0];
-      if (isPlaceholder(captured)) continue;
-      secrets.push({
-        pattern: name,
-        line: i + 1,
-        masked_value: captured.slice(0, 20) + '...',
-      });
-    }
-  }
-
-  // Quality scanning
-  const quality_issues = [];
-
-  if (lines.length > 800) {
-    quality_issues.push({ type: 'file_too_long', detail: `File has ${lines.length} lines (limit: 800)` });
-  }
-
-  // Detect oversized functions via simple heuristic
-  const funcKeywords = /^\s*(function\s+\w+|async\s+function\s+\w+|\w+\s*=\s*(?:async\s+)?\(|def\s+\w+|func\s+\w+)/;
-  let funcStart = null;
-  let braceDepth = 0;
-  let inBlock = false;
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-
-    if (funcKeywords.test(line)) {
-      funcStart = i + 1;
-      braceDepth = 0;
-      inBlock = false;
-    }
-
-    if (funcStart !== null) {
-      for (const ch of line) {
-        if (ch === '{') { braceDepth++; inBlock = true; }
-        else if (ch === '}') { braceDepth--; }
-      }
-      if (inBlock && braceDepth <= 0) {
-        const funcLen = i + 1 - funcStart + 1;
-        if (funcLen > 50) {
-          quality_issues.push({
-            type: 'function_too_long',
-            detail: `Function starting at line ${funcStart} is ${funcLen} lines (limit: 50)`,
-            line: funcStart,
-          });
-        }
-        funcStart = null;
-        inBlock = false;
-        braceDepth = 0;
-      }
-    }
-
-    // TODO/FIXME/HACK comments
-    const todoMatch = /\/\/\s*(TODO|FIXME|HACK)\b|#\s*(TODO|FIXME|HACK)\b/i.exec(line);
-    if (todoMatch) {
-      const tag = (todoMatch[1] ?? todoMatch[2]).toUpperCase();
-      quality_issues.push({
-        type: 'comment_marker',
-        detail: `${tag} comment`,
-        line: i + 1,
-      });
-    }
-  }
-
-  return {
-    file_path: filePath,
-    secrets,
-    quality_issues,
-    clean: secrets.length === 0 && quality_issues.length === 0,
-  };
-}
-
-// Tool: project_context
-function projectContext(args) {
-  const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
-  const contextInspection = inspectContextState(cwd);
-  const context_state = contextInspection.state;
-  const context = context_state?.markdown || null;
-  const has_context_file = contextInspection.hasFile;
-  const workflow = loadWorkflow(cwd);
-  const mergedEnv = loadConstructEnv({ rootDir: ROOT_DIR, homeDir: homedir(), env: process.env });
-  const registry = readJSON(join(ROOT_DIR, 'agents', 'registry.json')) ?? {};
-  const executionContractModel = resolveExecutionContractModelMetadata({
-    envValues: mergedEnv,
-    registryModels: registry.models ?? {},
-    requestedTier: selectModelTierForWorkCategory(workflow?.tasks?.find((task) => task.key === workflow?.currentTaskKey)?.workCategory),
-    workCategory: null,
-  });
-  const publicHealth = buildPublicHealthSurface({
-    cwd,
-    contextInspection,
-    workflow,
-    executionContractModel,
-  });
-
-  let recent_commits = [];
-  let working_tree_status = 'clean';
-  let changed_files = [];
-
-  try {
-    const log = exec('git log --oneline -10', cwd);
-    recent_commits = log.split('\n').filter(Boolean);
-  } catch {
-    // not a git repo or no commits
-  }
-
-  try {
-    const status = exec('git status --short', cwd);
-    const statusLines = status.split('\n').filter(Boolean);
-    changed_files = statusLines.map((l) => l.trim());
-    working_tree_status = statusLines.length > 0 ? 'dirty' : 'clean';
-  } catch {
-    // not a git repo
-  }
-
-  return { cwd, has_context_file, context, context_state, recent_commits, working_tree_status, changed_files, publicHealth };
-}
-
-function orchestrationPolicy(args) {
-  const route = routeRequest(args || {});
-  const approvalRequired = requiresExecutiveApproval(args?.approval || {});
-  return {
-    ...route,
-    approvalRequired,
-    terminalStates: TERMINAL_STATES,
-  };
-}
-
-// Tool: list_skills
-function listSkills() {
-  const skillsDir = join(ROOT_DIR, 'skills');
-  if (!existsSync(skillsDir)) return { error: 'Skills directory not found.' };
-
-  const listDirRecursive = (dir, prefix = '') => {
-    let results = [];
-    const entries = readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        results = results.concat(listDirRecursive(join(dir, entry.name), `${prefix}${entry.name}/`));
-      } else if (entry.name.endsWith('.md') && entry.name !== 'SKILL.md') {
-        results.push(`${prefix}${entry.name.replace('.md', '')}`);
-      }
-    }
-    return results;
-  };
-
-  const skills = listDirRecursive(skillsDir).sort();
-  return { skills };
-}
-
-// Tool: get_skill
-function getSkill(args) {
-  const { path: skillPath } = args;
-  if (!skillPath) return { error: 'Missing path argument' };
-
-  const fullPath = join(ROOT_DIR, 'skills', `${skillPath}.md`);
-
-  if (!existsSync(fullPath)) {
-    return { error: `Skill not found: ${skillPath}` };
-  }
-  const content = readFileSync(fullPath, 'utf8');
-  return { content };
-}
-
-// Tool: get_template
-function getTemplate(args) {
-  const { name } = args;
-  if (!name) return { error: 'Missing name argument' };
-  const safe = String(name).replace(/[^a-zA-Z0-9._-]/g, '');
-  if (!safe) return { error: 'Invalid template name' };
-
-  const cwd = process.cwd();
-  const candidates = [
-    { source: 'project-override', path: join(cwd, '.cx', 'templates', 'docs', `${safe}.md`) },
-    { source: 'shipped-default', path: join(ROOT_DIR, 'templates', 'docs', `${safe}.md`) },
-  ];
-  for (const { source, path: p } of candidates) {
-    if (existsSync(p)) {
-      return { source, path: p, content: readFileSync(p, 'utf8') };
-    }
-  }
-  return { error: `Template not found: ${safe}`, available: listTemplatesRaw() };
-}
-
-function listTemplatesRaw() {
-  const shipped = [];
-  const override = [];
-  const shippedDir = join(ROOT_DIR, 'templates', 'docs');
-  if (existsSync(shippedDir)) {
-    for (const f of readdirSync(shippedDir)) {
-      if (f.endsWith('.md')) shipped.push(f.replace(/\.md$/, ''));
-    }
-  }
-  const overrideDir = join(process.cwd(), '.cx', 'templates', 'docs');
-  if (existsSync(overrideDir)) {
-    for (const f of readdirSync(overrideDir)) {
-      if (f.endsWith('.md')) override.push(f.replace(/\.md$/, ''));
-    }
-  }
-  return { shipped: shipped.sort(), overridden: override.sort() };
-}
-
-// Tool: list_templates
-function listTemplates() {
-  return listTemplatesRaw();
-}
-
-// Tool: search_skills
-function searchSkills(args) {
-  const { pattern } = args;
-  if (!pattern) return { error: 'Missing pattern argument' };
-  const skillsDir = join(ROOT_DIR, 'skills');
-
-  try {
-    // Try ripgrep first
-    const output = execSync(`rg -i "${pattern.replace(/"/g, '\\"')}" "${skillsDir}"`, { encoding: 'utf8' });
-    return { results: output.split('\n').filter(Boolean) };
-  } catch (err) {
-    // Fallback to basic grep
-    try {
-      const output = execSync(`grep -ri "${pattern.replace(/"/g, '\\"')}" "${skillsDir}"`, { encoding: 'utf8' });
-      return { results: output.split('\n').filter(Boolean) };
-    } catch (err2) {
-      return { results: [], note: 'No matches found or grep error' };
-    }
-  }
-}
-
-function workflowStatus(args) {
-  const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
-  const workflow = loadWorkflow(cwd);
-  const workflowHealth = inspectWorkflowHealth(workflow, { cwd });
-  const mergedEnv = loadConstructEnv({ rootDir: ROOT_DIR, homeDir: homedir(), env: process.env });
-  const registry = readJSON(join(ROOT_DIR, 'agents', 'registry.json')) ?? {};
-  const executionContractModel = resolveExecutionContractModelMetadata({
-    envValues: mergedEnv,
-    registryModels: registry.models ?? {},
-    requestedTier: selectModelTierForWorkCategory(workflow?.tasks?.find((task) => task.key === workflow?.currentTaskKey)?.workCategory),
-    workCategory: null,
-  });
-  const publicHealth = buildPublicHealthSurface({
-    cwd,
-    workflow,
-    executionContractModel,
-  });
-  return {
-    cwd,
-    exists: Boolean(workflow),
-    summary: summarizeWorkflow(workflow),
-    workflow,
-    alignment: {
-      status: workflowHealth.alignment.status,
-      findings: workflowHealth.alignment.findings,
-    },
-    publicHealth,
-  };
-}
-
-function workflowInit(args) {
-  const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
-  const title = args.title || 'Untitled workflow';
-  const { workflow, created } = initWorkflow(cwd, title, args.spec_ref ?? null);
-  return { cwd, created, workflow, summary: summarizeWorkflow(workflow) };
-}
-
-// Tool: list_teams
-function listTeams() {
-  const teamsPath = join(ROOT_DIR, 'agents', 'teams.json');
-  if (!existsSync(teamsPath)) return { error: 'agents/teams.json not found' };
-  const { templates } = JSON.parse(readFileSync(teamsPath, 'utf8'));
-  return {
-    teams: Object.entries(templates).map(([name, t]) => ({
-      name,
-      description: t.description,
-      members: t.members,
-      focus: t.focus,
-      skills: t.skills,
-      promotionGates: t.promotionGates,
-    })),
-  };
-}
-
-// Tool: get_team
-function getTeam(args) {
-  const { name } = args;
-  if (!name) return { error: 'Missing name argument' };
-  const teamsPath = join(ROOT_DIR, 'agents', 'teams.json');
-  if (!existsSync(teamsPath)) return { error: 'agents/teams.json not found' };
-  const { templates } = JSON.parse(readFileSync(teamsPath, 'utf8'));
-  const team = templates[name];
-  if (!team) return { error: `Team not found: ${name}`, available: Object.keys(templates) };
-  return { name, ...team };
-}
-
-function workflowAddTask(args) {
-  const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
-  if (args.request) {
-    const workflow = addTaskFromIntent(cwd, args.request, {
-      key: args.key,
-      title: args.title,
-      phase: args.phase,
-      owner: args.owner,
-      files: args.files,
-      readFirst: args.readFirst,
-      doNotChange: args.doNotChange,
-      acceptanceCriteria: args.acceptanceCriteria,
-      verification: args.verification,
-      overlays: args.overlays,
-      challengeRequired: args.challengeRequired,
-      challengeStatus: args.challengeStatus,
-      tokenBudget: args.tokenBudget,
-      status: args.status,
-    });
-    if (!workflow) return { ok: true, skipped: true, reason: 'immediate-track' };
-    return { cwd, workflow, summary: summarizeWorkflow(workflow), source: 'intent' };
-  }
-  const workflow = addTask(cwd, {
-    key: args.key,
-    title: args.title,
-    phase: args.phase,
-    owner: args.owner,
-    files: args.files,
-    readFirst: args.readFirst,
-    doNotChange: args.doNotChange,
-    acceptanceCriteria: args.acceptanceCriteria,
-    verification: args.verification,
-    dependsOn: args.dependsOn,
-    overlays: args.overlays,
-    challengeRequired: args.challengeRequired,
-    challengeStatus: args.challengeStatus,
-  });
-  return { cwd, workflow, summary: summarizeWorkflow(workflow), source: 'manual' };
-}
-
-function workflowUpdateTask(args) {
-  const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
-  const workflow = updateTask(cwd, args.key, {
-    status: args.status,
-    owner: args.owner,
-    phase: args.phase,
-    note: args.note,
-    verification: args.verification,
-    overlays: args.overlays,
-    challengeRequired: args.challengeRequired,
-    challengeStatus: args.challengeStatus,
-  });
-  return { cwd, workflow, summary: summarizeWorkflow(workflow) };
-}
-
-function workflowNeedsMainInput(args) {
-  const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
-  const packet = createNeedsMainInputPacket(args);
-  const workflow = updateTask(cwd, args.taskKey, {
-    status: 'blocked_needs_user',
-    note: `${packet.worker}: ${packet.blocker} | question: ${packet.question}`,
-  });
-  return { cwd, packet, workflow, summary: summarizeWorkflow(workflow) };
-}
-
-function workflowValidate(args) {
-  const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
-  const workflow = loadWorkflow(cwd);
-  const result = validateWorkflowState(workflow);
-  return { cwd, ...result };
-}
-
-function workflowImportPlan(args) {
-  const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
-  const markdown = args.markdown ?? '';
-  const { workflow, count } = addTasksFromPlan(cwd, markdown, {
-    phase: args.phase,
-    owner: args.owner,
-    readFirst: Array.isArray(args.readFirst) ? args.readFirst : undefined,
-    doNotChange: Array.isArray(args.doNotChange) ? args.doNotChange : undefined,
-    acceptanceCriteria: Array.isArray(args.acceptanceCriteria) ? args.acceptanceCriteria : undefined,
-    workflowTitle: args.title,
-    specRef: args.spec_ref,
-  });
-  return { cwd, count, workflow, summary: summarizeWorkflow(workflow) };
-}
-
-function resolveReleaseTag(cwd) {
-  try {
-    return execSync('git rev-parse --short HEAD', { stdio: 'pipe', cwd, timeout: 2000 }).toString().trim() || undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function resolveSessionContext() {
-  const cwd = process.cwd();
-  let workflowId;
-  let workflowPhase;
-  let workflowOwner;
-  try {
-    const wf = loadWorkflow(cwd);
-    if (wf) {
-      workflowId = wf.id;
-      workflowPhase = wf.phase;
-      const active = (wf.tasks || []).find((t) => t.status === 'in-progress' || t.status === 'in_progress');
-      if (active) workflowOwner = active.owner;
-    }
-  } catch { /* best effort */ }
-  const sessionId = process.env.CLAUDE_SESSION_ID
-    || process.env.CX_SESSION_ID
-    || process.env.OPENCODE_SESSION_ID
-    || workflowId;
-  const userId = process.env.USER || process.env.USERNAME || process.env.LOGNAME;
-  return { cwd, sessionId, userId, release: resolveReleaseTag(cwd), workflowPhase, workflowOwner, workflowId };
-}
-
-function langfuseHeaders() {
-  const key = process.env.LANGFUSE_PUBLIC_KEY;
-  const secret = process.env.LANGFUSE_SECRET_KEY;
-  if (!key || !secret) throw new Error('LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY must be set.');
-  return {
-    Authorization: `Basic ${Buffer.from(`${key}:${secret}`).toString('base64')}`,
-    'Content-Type': 'application/json',
-  };
-}
-
-function langfuseBaseUrl() {
-  return (process.env.LANGFUSE_BASEURL ?? 'https://cloud.langfuse.com').replace(/\/$/, '');
-}
-
-async function cxTrace(args) {
-  const ctx = resolveSessionContext();
-  const registry = readJSON(join(ROOT_DIR, 'agents', 'registry.json')) ?? {};
-  const registryModels = registry.models ?? {};
-  const currentModels = readCurrentModels(join(ROOT_DIR, '.env'), registryModels, process.env);
-  const route = typeof args.input === 'string' ? routeRequest({ request: args.input }) : null;
-  const executionContractModel = resolveExecutionContractModelMetadata({
-    envValues: currentModels,
-    registryModels,
-    requestedTier: selectModelTierForWorkCategory(route?.workCategory),
-    workCategory: route?.workCategory || null,
-  });
-  const runtimePromptMetadata = summarizePromptComposition(args.name, {
-    rootDir: ROOT_DIR,
-    request: typeof args.input === 'string' ? args.input : '',
-    route,
-    registryModels,
-    envValues: currentModels,
-    executionContractModel,
-    hostConstraints: {
-      runtime: 'mcp',
-      providerAgnostic: true,
-      telemetryBackend: 'langfuse',
-    },
-  });
-  const metadata = enrichMetadataWithPrompt(args.name, {
-    ...(args.metadata && typeof args.metadata === 'object' ? args.metadata : {}),
-    ...runtimePromptMetadata,
-    workflowId: ctx.workflowId,
-    workflowPhase: ctx.workflowPhase,
-    workflowOwner: ctx.workflowOwner,
-    release: ctx.release,
-  }, { rootDir: ROOT_DIR });
-  const traceId = args.id ?? crypto.randomUUID();
-  try {
-    const available = await langfuse.isAvailable();
-    if (!available) return { ok: false, error: 'Langfuse credentials not configured', id: traceId };
-    const teamId = args.metadata?.teamId ?? metadata.teamId;
-    const body = {
-      id: traceId,
-      name: args.name,
-      metadata: {
-        ...metadata,
-        agentName: args.name,
-        goal: typeof args.input === 'string' ? args.input : JSON.stringify(args.input ?? ''),
-        teamId,
-      },
-      tags: [args.name, teamId].filter(Boolean),
-      userId: ctx.userId,
-      sessionId: args.session_id || ctx.sessionId,
-      input: args.input,
-      output: args.output,
-      timestamp: args.timestamp ?? new Date().toISOString(),
-      release: ctx.release,
-    };
-    const res = await fetch(`${langfuseBaseUrl()}/api/public/traces`, {
-      method: 'POST',
-      headers: langfuseHeaders(),
-      body: JSON.stringify(body),
-    });
-    if (!res.ok) {
-      const text = await res.text().catch(() => '');
-      return { ok: false, error: `Langfuse API error ${res.status}: ${text}`, id: traceId };
-    }
-    return { ok: true, id: traceId };
-  } catch (err) {
-    return { ok: false, error: err.message, id: traceId };
-  }
-}
+import {
+  agentHealth, summarizeDiff, scanFile, projectContext, workflowStatus,
+} from './tools/project.mjs';
+import {
+  extractDocumentText, ingestDocument, inferDocumentSchemaTool, listSchemaArtifactsTool,
+} from './tools/document.mjs';
+import {
+  storageStatus, storageSync, storageReset, deleteIngestedArtifactsTool,
+} from './tools/storage.mjs';
+import {
+  listSkills, getSkill, searchSkills, getTemplate, listTemplates,
+  agentContract, brokerCheck, orchestrationPolicy, workerRun, listTeams, getTeam,
+} from './tools/skills.mjs';
+import {
+  workflowInit, workflowAddTask, workflowUpdateTask,
+  workflowNeedsMainInput, workflowValidate, workflowImportPlan,
+} from './tools/workflow.mjs';
+import {
+  cxTrace, cxTraceUpdate, cxScore, sessionUsage, efficiencySnapshot,
+} from './tools/telemetry.mjs';
+import {
+  memorySearch, memoryAddObservations, memoryCreateEntities, memoryRecent,
+  sessionList, sessionLoad, sessionSearch, sessionSave, rovoSearch,
+} from './tools/memory.mjs';
 
-async function cxScore(args) {
-  const traceId = args.trace_id ?? '';
-  try {
-    const available = await langfuse.isAvailable();
-    if (!available) return { ok: false, error: 'Langfuse credentials not configured' };
-    const body = {
-      id: crypto.randomUUID(),
-      traceId,
-      name: args.name ?? 'quality',
-      value: args.value,
-      dataType: 'NUMERIC',
-      comment: args.comment,
-    };
-    const res = await fetch(`${langfuseBaseUrl()}/api/public/scores`, {
-      method: 'POST',
-      headers: langfuseHeaders(),
-      body: JSON.stringify(body),
-    });
-    if (!res.ok) {
-      const text = await res.text().catch(() => '');
-      return { ok: false, error: `Langfuse API error ${res.status}: ${text}` };
-    }
-    return { ok: true, traceId };
-  } catch (err) {
-    return { ok: false, error: err.message };
-  }
-}
+const DEFAULT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const ROOT_DIR = resolve(process.env.CX_TOOLKIT_DIR || DEFAULT_ROOT_DIR);
+loadToolkitEnv(ROOT_DIR);
 
-async function sessionUsage(args) {
-  const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
-  const homeDir = args.home_dir ? resolve(args.home_dir) : homedir();
-  const status = await buildStatus({ rootDir: ROOT_DIR, cwd, homeDir, env: process.env });
-  return {
-    cwd,
-    sessionUsage: status.sessionUsage,
-  };
-}
+const opts = { ROOT_DIR };
 
-// Server setup
 const server = new Server(
   { name: 'construct-mcp', version: '1.0.0' },
   { capabilities: { tools: {} } }
@@ -820,6 +106,198 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['file_path'],
       },
     },
+    {
+      name: 'extract_document_text',
+      description: 'Extracts readable text from a local document path. Supports PDF on macOS plus common text and office document formats.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file_path: {
+            type: 'string',
+            description: 'Absolute or relative path to the document file.',
+          },
+          max_chars: {
+            type: 'number',
+            description: 'Maximum characters to return (default 20000, hard cap 200000).',
+          },
+        },
+        required: ['file_path'],
+      },
+    },
+    {
+      name: 'ingest_document',
+      description: 'Converts a local document into a normalized markdown file, placing it into an indexed project path by default.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file_path: {
+            type: 'string',
+            description: 'Absolute or relative path to the source document.',
+          },
+          out_path: {
+            type: 'string',
+            description: 'Optional explicit markdown output path.',
+          },
+          out_dir: {
+            type: 'string',
+            description: 'Optional directory for generated markdown output files.',
+          },
+          target: {
+            type: 'string',
+            description: 'Output mode: knowledge/internal, knowledge/external, knowledge/decisions, knowledge/how-tos, knowledge/reference, or sibling. Defaults to knowledge/internal.',
+          },
+          cwd: {
+            type: 'string',
+            description: 'Project root used to resolve default output paths and storage sync.',
+          },
+          sync: {
+            type: 'boolean',
+            description: 'When true, sync file-state into configured SQL/vector storage after writing output.',
+          },
+        },
+        required: ['file_path'],
+      },
+    },
+    {
+      name: 'infer_document_schema',
+      description: 'Infers a structured field schema from a local document using AI. Returns field names, types, formats, examples, and confidence. Supports all document types handled by extract_document_text. Pass multiple file_paths to get a reconciled unified schema across documents.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file_path: {
+            type: 'string',
+            description: 'Absolute or relative path to the document file. For unified inference across multiple documents, use file_paths instead.',
+          },
+          file_paths: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Multiple document paths for unified schema inference. Reconciles fields across all documents.',
+          },
+          max_chars: {
+            type: 'number',
+            description: 'Maximum characters of document text to send to the model (default 40000, hard cap 200000).',
+          },
+          save: {
+            type: 'boolean',
+            description: 'When true, write the schema result as a .schema.json artifact under .cx/knowledge/reference/schemas/.',
+          },
+          cwd: {
+            type: 'string',
+            description: 'Project root used to resolve output paths when save is true.',
+          },
+          sample_size: {
+            type: 'number',
+            description: 'For unified inference: max number of documents to sample (default 10).',
+          },
+          threshold: {
+            type: 'number',
+            description: 'For unified inference: minimum fraction of documents a field must appear in to be included (default 0.5).',
+          },
+        },
+      },
+    },
+    {
+      name: 'list_schema_artifacts',
+      description: 'Lists all inferred schema artifacts (.schema.json files) in the project.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: {
+            type: 'string',
+            description: 'Project directory to search (default: process.cwd()).',
+          },
+        },
+      },
+    },
+    {
+      name: 'storage_status',
+      description: 'Returns SQL, local vector index, and ingested-artifact status for the current project.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: {
+            type: 'string',
+            description: 'Project directory to inspect.',
+          },
+          project: {
+            type: 'string',
+            description: 'Optional explicit project key for SQL document counts.',
+          },
+        },
+      },
+    },
+    {
+      name: 'storage_sync',
+      description: 'Syncs file-state documents into the local vector index and configured SQL storage.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: {
+            type: 'string',
+            description: 'Project directory to sync.',
+          },
+          project: {
+            type: 'string',
+            description: 'Optional explicit project key.',
+          },
+        },
+      },
+    },
+    {
+      name: 'storage_reset',
+      description: 'Resets SQL/vector storage state for a project. Requires explicit confirm=true.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: {
+            type: 'string',
+            description: 'Project directory whose storage should be reset.',
+          },
+          project: {
+            type: 'string',
+            description: 'Optional explicit project key.',
+          },
+          reset_sql: {
+            type: 'boolean',
+            description: 'Set false to keep SQL state intact.',
+          },
+          reset_vector: {
+            type: 'boolean',
+            description: 'Set false to keep the local vector index intact.',
+          },
+          reset_ingested: {
+            type: 'boolean',
+            description: 'Set true to also delete ingested markdown artifacts under .cx/knowledge/.',
+          },
+          confirm: {
+            type: 'boolean',
+            description: 'Must be true or the reset is rejected.',
+          },
+        },
+      },
+    },
+    {
+      name: 'delete_ingested_artifacts',
+      description: 'Deletes ingested markdown artifacts. Requires explicit confirm=true and only allows files under the ingested artifact directory.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: {
+            type: 'string',
+            description: 'Project directory whose ingested artifacts should be deleted.',
+          },
+          files: {
+            type: 'array',
+            description: 'Optional relative file paths under .cx/knowledge/. Omit to delete all ingested markdown artifacts.',
+            items: { type: 'string' },
+          },
+          confirm: {
+            type: 'boolean',
+            description: 'Must be true or deletion is rejected.',
+          },
+        },
+      },
+    },
     {
       name: 'project_context',
       description: 'Returns project context: .cx/context.md content, recent commits, and working tree status.',
@@ -846,7 +324,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'orchestration_policy',
-      description: 'Classifies a request into intent, execution track, specialists, and approval boundaries.',
+      description: 'Classifies a request into intent, execution track, specialists, approval boundaries, and the contract chain that applies. The contractChain field names the typed producer→consumer handoffs expected for this dispatch plan. When `candidates` is supplied, also returns `contextPackets` keyed by specialist with the role-filtered artifact bundle each specialist should receive (omitted artifacts include the reason they were dropped).',
       inputSchema: {
         type: 'object',
         properties: {
@@ -866,6 +344,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
               blockedDependency: { type: 'boolean' },
             },
           },
+          candidates: {
+            type: 'array',
+            description: 'Pre-retrieved artifacts to consider for each specialist. Each item: {id, path, title, kind, summary, score}. When supplied, the response includes `contextPackets` keyed by specialist.',
+            items: { type: 'object' },
+          },
+          budget: {
+            type: 'object',
+            description: 'Token budget for the per-specialist context packet (default: 6000).',
+            properties: { maxTokens: { type: 'number' } },
+          },
+          triage: {
+            type: 'object',
+            description: 'Optional R&D triage block from a related intake packet — surfaced in each specialist\'s taskSummary.',
+          },
+          intakeId: {
+            type: 'string',
+            description: 'Optional id of a pending intake packet. When supplied, the tool generates a task graph from the packet\'s triage, persists it to .cx/task-graphs/, emits a task_graph.created trace event correlated by traceId, and returns the graph in `taskGraph`.',
+          },
+          project: {
+            type: 'string',
+            description: 'Project scope for the generated task graph (defaults to basename(cwd)).',
+          },
+          traceId: {
+            type: 'string',
+            description: 'Optional traceId to link task_graph.created with the originating intake.received event.',
+          },
         },
       },
     },
@@ -877,6 +381,59 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: {},
       },
     },
+    {
+      name: 'worker_run',
+      description: 'Runs a bounded shell command via the worker plane: timeout, path-policy denial, restricted env, stdout/stderr artifacts under `.cx/runtime/worker/<jobId>.{stdout,stderr}.log`. When `graphId` + `nodeId` are supplied, an evidence record is appended to that task graph node so it can transition to `done`. Emits `worker.started` / `worker.completed` / `evidence.recorded` trace events correlated by `traceId`.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          command: { type: 'string', description: 'Shell command to run (e.g. `npm test`).' },
+          args: { type: 'array', items: { type: 'string' }, description: 'Argv to pass alongside the command (when not embedded in the command string).' },
+          workspaceRef: { type: 'string', description: 'Absolute path the job runs in. Must be inside `allowedPaths` (default: cwd).' },
+          allowedPaths: { type: 'array', items: { type: 'string' }, description: 'Absolute path allowlist for the workspace. Default: [cwd] so the job can\'t reach outside the project.' },
+          timeoutSeconds: { type: 'number', description: 'Hard timeout. Default: 300.' },
+          envPolicy: { type: 'string', description: 'restricted (default — only PATH/HOME/USER/TZ/LANG/LC_ALL/TMPDIR plus allowedEnvKeys) | inherit.' },
+          allowedEnvKeys: { type: 'array', items: { type: 'string' }, description: 'Additional env keys allowed through under restricted policy.' },
+          graphId: { type: 'string', description: 'Optional task graph id — when present with `nodeId`, evidence is recorded on that node.' },
+          nodeId: { type: 'string', description: 'Optional task graph node id — when present with `graphId`, evidence is recorded.' },
+          evidenceType: { type: 'string', description: 'Evidence type (e.g. `test-result`, `lint-result`, `build-result`). Default: test-result.' },
+          evidenceSummary: { type: 'string', description: 'Optional override for the evidence summary string.' },
+          traceId: { type: 'string', description: 'Optional traceId to correlate with the rest of the agent\'s trace.' },
+          taskId: { type: 'string', description: 'Optional task id (used when graphId/nodeId aren\'t supplied — purely for trace context).' },
+          project: { type: 'string', description: 'Optional project scope.' },
+          jobId: { type: 'string', description: 'Optional job id. Default: worker-<ts>-<rand>.' },
+        },
+        required: ['command'],
+      },
+    },
+    {
+      name: 'broker_check',
+      description: 'Queries the MCP broker policy gate for a pending action without executing it. Agents call this BEFORE attempting a high-risk action so the response (allowed / approvalRequired / reason / source) can be surfaced to the user in the agent\'s voice rather than triggering a denial after the fact. In solo mode the broker is off by default — returns `brokerActive: false` with `allowed: true` so the call is cheap and agents don\'t waste tokens on an inactive gate. Always emits a `tool.called` trace event for audit-trail parity. Reads agents/role-manifests.json fence rules in team / enterprise mode.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          role: { type: 'string', description: 'Persona name (e.g. `engineer`, `security`). Must match a key in agents/role-manifests.json for team / enterprise mode.' },
+          project: { type: 'string', description: 'Optional project scope for the decision.' },
+          tool: { type: 'string', description: 'The tool the agent wants to invoke (e.g. `github`, `fs`).' },
+          action: { type: 'string', description: 'The action on that tool (e.g. `create_pr`, `edit:lib/foo.mjs`).' },
+          risk: { type: 'string', description: 'low | medium | high. high actions need approval for non-autonomous roles.' },
+          traceId: { type: 'string', description: 'Optional traceId to correlate this check with the rest of the agent\'s trace.' },
+        },
+        required: ['role', 'tool', 'action'],
+      },
+    },
+    {
+      name: 'agent_contract',
+      description: 'Looks up explicit agent-to-agent service contracts (from agents/contracts.json). Specialists should call this at the start of a handoff to see the expected input shape, preconditions, and what postconditions they must satisfy. Use without args to get all contracts; pass producer/consumer to narrow; pass id for a specific contract.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'Exact contract id (e.g. "architect-to-engineer")' },
+          producer: { type: 'string', description: 'Producer agent name (e.g. "cx-architect"). Returns outgoing contracts.' },
+          consumer: { type: 'string', description: 'Consumer agent name (e.g. "cx-engineer"). Returns incoming contracts.' },
+        },
+      },
+    },
     {
       name: 'get_template',
       description: 'Reads a doc template by name (e.g. "prd", "meta-prd", "prfaq", "evidence-brief", "adr", "runbook"). Resolves .cx/templates/docs/{name}.md first, then templates/docs/{name}.md.',
@@ -905,162 +462,230 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       },
     },
     {
-      name: 'workflow_status',
-      description: 'Returns Construct .cx/workflow.json state and alignment findings.',
+      name: 'list_teams',
+      description: 'Lists all available Construct team templates with members, focus, and promotion gates.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'get_team',
+      description: 'Returns the full definition of a named team template including members, skills, and promotion gates.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'Team template name (e.g. feature, incident, architecture).' },
+        },
+        required: ['name'],
+      },
+    },
+    {
+      name: 'cx_trace',
+      description: 'Records an agent trace for observability. Call at the start of every significant task with your agent name and the user goal.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'Agent name (e.g. cx-engineer)' },
+          id: { type: 'string', description: 'Optional trace UUID — auto-generated if omitted' },
+          session_id: { type: 'string', description: 'Session ID to group related spans' },
+          metadata: { type: 'object', description: 'Extra metadata (teamId, workflowId, etc.)' },
+          input: { type: ['string', 'object'], description: 'Agent goal or user request' },
+          output: { type: ['string', 'object'], description: 'Agent deliverable or response' },
+          timestamp: { type: 'string', description: 'ISO start time (default: now)' },
+        },
+        required: ['name'],
+      },
+    },
+    {
+      name: 'cx_score',
+      description: 'Attaches a quality score to a trace. Call after producing a significant deliverable.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          trace_id: { type: 'string', description: 'The trace ID returned by cx_trace' },
+          name: { type: 'string', description: 'Score name — use "quality"' },
+          value: { type: 'number', description: 'Score from 0.0 (poor) to 1.0 (excellent)' },
+          comment: { type: 'string', description: 'Brief explanation of the score' },
+        },
+        required: ['trace_id', 'name', 'value'],
+      },
+    },
+    {
+      name: 'cx_trace_update',
+      description: 'Updates an existing trace with output and metadata. Use when a trace was created early but the result becomes available later.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          trace_id: { type: 'string', description: 'The trace ID returned by cx_trace' },
+          output: { type: ['string', 'object'], description: 'Final output / deliverable content' },
+          metadata: { type: 'object', description: 'Additional metadata to merge into the trace' },
+        },
+        required: ['trace_id'],
+      },
+    },
+    {
+      name: 'session_list',
+      description: 'List construct sessions for the current project. Returns distilled session index entries with id, project, status, and summary.',
       inputSchema: {
         type: 'object',
         properties: {
           cwd: { type: 'string', description: 'Project directory (default: process.cwd()).' },
+          status: { type: 'string', description: 'Filter by status: active, completed, closed.' },
+          limit: { type: 'number', description: 'Max results (default: 20).' },
         },
       },
     },
     {
-      name: 'workflow_init',
-      description: 'Creates .cx/workflow.json if missing and returns the workflow state.',
+      name: 'session_load',
+      description: 'Load a full distilled session record by ID. Returns summary, decisions, files changed, open questions, and task snapshot.',
       inputSchema: {
         type: 'object',
         properties: {
           cwd: { type: 'string', description: 'Project directory (default: process.cwd()).' },
-          title: { type: 'string', description: 'Workflow title.' },
-          spec_ref: { type: 'string', description: 'Path to the governing spec/plan document (e.g. .cx/plans/feature-x.md).' },
+          session_id: { type: 'string', description: 'The session ID to load.' },
         },
+        required: ['session_id'],
       },
     },
     {
-      name: 'workflow_add_task',
-      description: 'Adds a Construct task packet to .cx/workflow.json.',
+      name: 'session_search',
+      description: 'Search sessions by keyword in summary or project name.',
       inputSchema: {
         type: 'object',
         properties: {
-          cwd: { type: 'string' },
-          key: { type: 'string' },
-          title: { type: 'string' },
-          phase: { type: 'string' },
-          owner: { type: 'string' },
-          files: { type: 'array', items: { type: 'string' } },
-          readFirst: { type: 'array', items: { type: 'string' } },
-          doNotChange: { type: 'array', items: { type: 'string' } },
-          acceptanceCriteria: { type: 'array', items: { type: 'string' } },
-          verification: { type: 'array', items: { type: 'string' } },
-          dependsOn: { type: 'array', items: { type: 'string' } },
-          overlays: { type: 'array', items: { type: 'string' } },
-          challengeRequired: { type: 'boolean' },
-          challengeStatus: { type: 'string' },
+          cwd: { type: 'string', description: 'Project directory (default: process.cwd()).' },
+          query: { type: 'string', description: 'Search keyword.' },
         },
-        required: ['title', 'owner', 'acceptanceCriteria'],
+        required: ['query'],
       },
     },
     {
-      name: 'workflow_update_task',
-      description: 'Updates a task status, owner, phase, note, or verification evidence in .cx/workflow.json.',
+      name: 'session_save',
+      description: 'Update the active session with distilled context: summary, decisions, files changed, open questions, task snapshot.',
       inputSchema: {
         type: 'object',
         properties: {
-          cwd: { type: 'string' },
-          key: { type: 'string' },
-          status: { type: 'string' },
-          owner: { type: 'string' },
-          phase: { type: 'string' },
-          note: { type: 'string' },
-          verification: { type: 'array', items: { type: 'string' } },
-          overlays: { type: 'array', items: { type: 'string' } },
-          challengeRequired: { type: 'boolean' },
-          challengeStatus: { type: 'string' },
+          cwd: { type: 'string', description: 'Project directory (default: process.cwd()).' },
+          session_id: { type: 'string', description: 'The session ID to update.' },
+          summary: { type: 'string', description: 'Brief summary of what happened (2-3 sentences).' },
+          decisions: { type: 'array', items: { type: 'string' }, description: 'Key decisions made during the session.' },
+          files_changed: { type: 'array', items: { type: 'object', properties: { path: { type: 'string' }, reason: { type: 'string' } } }, description: 'Files modified with reasons.' },
+          open_questions: { type: 'array', items: { type: 'string' }, description: 'Unresolved questions or blockers.' },
+          task_snapshot: { type: 'array', items: { type: 'object', properties: { id: { type: 'string' }, subject: { type: 'string' }, status: { type: 'string' } } }, description: 'Current task state.' },
+          status: { type: 'string', description: 'Session status: active, completed, closed.' },
         },
-        required: ['key'],
+        required: ['session_id'],
       },
     },
     {
-      name: 'workflow_needs_main_input',
-      description: 'Records a blocked_needs_user task and returns a NEEDS_MAIN_INPUT packet for the primary persona.',
+      name: 'memory_search',
+      description: 'Search the observation store for patterns, decisions, and insights learned by specialists across sessions. Returns semantically matched observations scoped by role, category, or project.',
       inputSchema: {
         type: 'object',
         properties: {
-          cwd: { type: 'string' },
-          taskKey: { type: 'string' },
-          worker: { type: 'string' },
-          blocker: { type: 'string' },
-          question: { type: 'string' },
-          safeDefault: { type: 'string' },
-          context: { type: 'array', items: { type: 'string' } },
+          query: { type: 'string', description: 'Semantic search query (e.g., project name, pattern, component).' },
+          role: { type: 'string', description: 'Filter by specialist role (e.g., cx-engineer, cx-architect).' },
+          category: { type: 'string', description: 'Filter by category: pattern, anti-pattern, dependency, decision, insight, session-summary.' },
+          project: { type: 'string', description: 'Filter by project name.' },
+          limit: { type: 'number', description: 'Max results (default: 10).' },
         },
-        required: ['taskKey', 'worker', 'blocker', 'question'],
+        required: ['query'],
       },
     },
     {
-      name: 'workflow_validate',
-      description: 'Validates .cx/workflow.json schema and high-severity alignment findings.',
+      name: 'memory_add_observations',
+      description: 'Record observations (patterns, insights, decisions, anti-patterns) that specialists discover during work. These are indexed for semantic search and surface in future sessions.',
       inputSchema: {
         type: 'object',
         properties: {
-          cwd: { type: 'string' },
+          observations: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                role: { type: 'string', description: 'Specialist role (e.g., cx-engineer).' },
+                category: { type: 'string', description: 'Category: pattern, anti-pattern, dependency, decision, insight.' },
+                summary: { type: 'string', description: 'Brief summary (max 500 chars).' },
+                content: { type: 'string', description: 'Detailed observation (max 2000 chars).' },
+                tags: { type: 'array', items: { type: 'string' }, description: 'Tags for filtering.' },
+                confidence: { type: 'number', description: 'Confidence 0.0-1.0 (default: 0.8).' },
+              },
+              required: ['summary'],
+            },
+            description: 'Observations to record (max 10 per call).',
+          },
         },
+        required: ['observations'],
       },
     },
     {
-      name: 'workflow_import_plan',
-      description: 'Parses a plan document (markdown) into structured workflow task packets and writes them to .cx/workflow.json. Supports rich ### T1 — Title sections with Owner/Phase/Files/Depends on/Read first/Do not change/Acceptance criteria fields.',
+      name: 'memory_create_entities',
+      description: 'Track recurring entities (components, services, APIs, dependencies) that specialists encounter. Enables "what do we know about X?" queries.',
       inputSchema: {
         type: 'object',
         properties: {
-          markdown: { type: 'string', description: 'The plan document markdown to parse into tasks' },
-          cwd: { type: 'string', description: 'Project directory (default: cwd)' },
-          title: { type: 'string', description: 'Workflow title if creating a new workflow' },
-          spec_ref: { type: 'string', description: 'Path to the governing spec/plan document (e.g. .cx/plans/feature-x.md)' },
-          phase: { type: 'string', description: 'Default phase for tasks without an explicit phase (default: implement)' },
-          owner: { type: 'string', description: 'Default owner for tasks without an explicit owner (default: cx-engineer)' },
-          readFirst: { type: 'array', items: { type: 'string' }, description: 'Default readFirst list applied to tasks without one' },
-          doNotChange: { type: 'array', items: { type: 'string' }, description: 'Default doNotChange list applied to all tasks' },
-          acceptanceCriteria: { type: 'array', items: { type: 'string' }, description: 'Extra acceptance criteria appended to each task' },
+          entities: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                name: { type: 'string', description: 'Entity name (normalized to lowercase).' },
+                type: { type: 'string', description: 'Type: component, service, dependency, api, concept, file-group.' },
+                summary: { type: 'string', description: 'Brief description (max 500 chars).' },
+                observation_ids: { type: 'array', items: { type: 'string' }, description: 'Link to observation IDs.' },
+              },
+              required: ['name'],
+            },
+            description: 'Entities to create or update (max 10 per call).',
+          },
         },
-        required: ['markdown'],
+        required: ['entities'],
       },
     },
     {
-      name: 'list_teams',
-      description: 'Lists all available Construct team templates with members, focus, and promotion gates.',
-      inputSchema: { type: 'object', properties: {} },
+      name: 'memory_recent',
+      description: 'Returns the most recent observations for the current project, deduplicated by (role, summary). Use this when the session-start hint indicates prior observations are available — fetch them on demand instead of paying for them every session.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project directory (default: process.cwd()).' },
+          project: { type: 'string', description: 'Filter by project name (default: inferred from cwd).' },
+          limit: { type: 'number', description: 'Max distinct observations (default: 10, max: 50).' },
+        },
+      },
     },
     {
-      name: 'get_team',
-      description: 'Returns the full definition of a named team template including members, skills, and promotion gates.',
+      name: 'rovo_search',
+      description: 'Cross-system semantic search via Atlassian Rovo. Searches Jira, Confluence, and other accessible sources. Returns excerpts with source attribution. Does NOT store results in the observation store. Use for broad queries across all sources, not just focal projects.',
       inputSchema: {
         type: 'object',
         properties: {
-          name: { type: 'string', description: 'Team template name (e.g. feature, incident, architecture).' },
+          query: { type: 'string', description: 'Search query (e.g., "Iverson reliability", "DR failover").' },
+          top_k: { type: 'number', description: 'Max results (default: 10, max: 50).' },
+          sources: { type: 'string', description: 'Comma-separated source filter (e.g., "jira,confluence").' },
         },
-        required: ['name'],
+        required: ['query'],
       },
     },
     {
-      name: 'cx_trace',
-      description: 'Records an agent trace in Langfuse for observability. Call at the start of every significant task with your agent name and the user goal.',
+      name: 'rovo_search',
+      description: 'Cross-system semantic search via Atlassian Rovo. Searches Jira, Confluence, and other accessible sources. Returns excerpts with source attribution. Does NOT store results in the observation store. Use for broad queries across all sources, not just focal projects.',
       inputSchema: {
         type: 'object',
         properties: {
-          name: { type: 'string', description: 'Agent name (e.g. cx-engineer)' },
-          id: { type: 'string', description: 'Optional trace UUID — auto-generated if omitted' },
-          session_id: { type: 'string', description: 'Session ID to group related spans' },
-          metadata: { type: 'object', description: 'Extra metadata (teamId, workflowId, etc.)' },
-          input: { type: ['string', 'object'], description: 'Agent goal or user request' },
-          output: { type: ['string', 'object'], description: 'Agent deliverable or response' },
-          timestamp: { type: 'string', description: 'ISO start time (default: now)' },
+          query: { type: 'string', description: 'Search query (e.g., "Iverson reliability", "DR failover").' },
+          top_k: { type: 'number', description: 'Max results (default: 10, max: 50).' },
+          sources: { type: 'string', description: 'Comma-separated source filter (e.g., "jira,confluence").' },
         },
-        required: ['name'],
+        required: ['query'],
       },
     },
     {
-      name: 'cx_score',
-      description: 'Attaches a quality score to a trace in Langfuse. Call after producing a significant deliverable.',
+      name: 'efficiency_snapshot',
+      description: 'Returns the read-efficiency snapshot for the current session — repeated reads, large reads, hot-spot files, and recommendations. Use this when investigating why a session feels slow or to surface optimization opportunities.',
       inputSchema: {
         type: 'object',
         properties: {
-          trace_id: { type: 'string', description: 'The trace ID returned by cx_trace' },
-          name: { type: 'string', description: 'Score name — use "quality"' },
-          value: { type: 'number', description: 'Score from 0.0 (poor) to 1.0 (excellent)' },
-          comment: { type: 'string', description: 'Brief explanation of the score' },
+          home_dir: { type: 'string', description: 'Home directory override (default: os.homedir()).' },
         },
-        required: ['trace_id', 'name', 'value'],
       },
     },
     {
@@ -1074,6 +699,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'provider_fetch',
+      description: 'Look up current data for a configured repo, project, or team. This is an internal lookup against sources the operator has already authorized (set in config.env). Call this immediately — no user approval needed — whenever the user asks about a specific repo, project, or team name (e.g. "what is project iverson", "cloud-reliability status", "PLAT issues"). Pass the user\'s query and the tool resolves the right source automatically. Returns repo metadata, README, docs, open PRs, issues, and recent commits, then stores them as observations.',
+      inputSchema: {
+        type: 'object',
+        required: ['query'],
+        properties: {
+          query: { type: 'string', description: 'The user\'s question or the project/repo name (e.g. "project iverson", "hashicorp/project-iverson", "PLAT"). The tool matches this against configured GITHUB_REPOS, JIRA_PROJECTS, LINEAR_TEAMS.' },
+          root_dir: { type: 'string', description: 'Data root dir override (default: homedir()). Use CX_DATA_DIR value if set.' },
+        },
+      },
+    },
+    {
+      name: 'knowledge_search',
+      description: 'Search Construct\'s own documentation, knowledge base, and distilled embed observations. Call this immediately — no approval needed — when the user asks what Construct is, how a feature works, what commands exist, or anything about Construct\'s architecture or configuration. Also searches embed observations from GitHub, Jira, and other configured sources. Returns relevant excerpts with source file and heading.',
+      inputSchema: {
+        type: 'object',
+        required: ['query'],
+        properties: {
+          query: { type: 'string', description: 'Natural-language question or keyword (e.g. "what is construct", "how does embed mode work", "provider authority guard", "slack configuration", "open Jira issues").' },
+          top_k: { type: 'number', description: 'Max excerpts to return (default: 5).' },
+          repo_root: { type: 'string', description: 'Repo root override (default: auto-detected from server location).' },
+          root_dir: { type: 'string', description: 'Data directory where .cx/observations/ lives (default: home directory). Pass this to search embed observations from a custom data dir.' },
+        },
+      },
+    },
   ],
 }));
 
@@ -1085,25 +736,56 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (name === 'agent_health') result = agentHealth(args);
     else if (name === 'summarize_diff') result = summarizeDiff(args);
     else if (name === 'scan_file') result = scanFile(args);
-    else if (name === 'project_context') result = projectContext(args);
-    else if (name === 'orchestration_policy') result = orchestrationPolicy(args);
-    else if (name === 'list_skills') result = listSkills();
-    else if (name === 'get_skill') result = getSkill(args);
-    else if (name === 'search_skills') result = searchSkills(args);
-    else if (name === 'get_template') result = getTemplate(args);
-    else if (name === 'list_templates') result = listTemplates();
-    else if (name === 'workflow_status') result = workflowStatus(args);
+    else if (name === 'extract_document_text') result = extractDocumentText(args);
+    else if (name === 'ingest_document') result = await ingestDocument(args);
+    else if (name === 'infer_document_schema') result = await inferDocumentSchemaTool(args);
+    else if (name === 'list_schema_artifacts') result = listSchemaArtifactsTool(args);
+    else if (name === 'storage_status') result = await storageStatus(args);
+    else if (name === 'storage_sync') result = await storageSync(args);
+    else if (name === 'storage_reset') result = await storageReset(args);
+    else if (name === 'delete_ingested_artifacts') result = deleteIngestedArtifactsTool(args);
+    else if (name === 'project_context') result = projectContext(args, opts);
+    else if (name === 'orchestration_policy') result = await orchestrationPolicy(args);
+    else if (name === 'list_skills') result = listSkills(opts);
+    else if (name === 'get_skill') result = getSkill(args, opts);
+    else if (name === 'search_skills') result = searchSkills(args, opts);
+    else if (name === 'get_template') result = getTemplate(args, opts);
+    else if (name === 'list_templates') result = listTemplates(opts);
+    else if (name === 'agent_contract') result = await agentContract(args);
+    else if (name === 'broker_check') result = await brokerCheck(args);
+    else if (name === 'worker_run') result = await workerRun(args);
+    else if (name === 'workflow_status') result = workflowStatus(args, opts);
     else if (name === 'workflow_init') result = workflowInit(args);
     else if (name === 'workflow_add_task') result = workflowAddTask(args);
     else if (name === 'workflow_update_task') result = workflowUpdateTask(args);
     else if (name === 'workflow_needs_main_input') result = workflowNeedsMainInput(args);
     else if (name === 'workflow_validate') result = workflowValidate(args);
     else if (name === 'workflow_import_plan') result = workflowImportPlan(args);
-    else if (name === 'list_teams') result = listTeams();
-    else if (name === 'get_team') result = getTeam(args);
-    else if (name === 'cx_trace') result = await cxTrace(args);
+    else if (name === 'list_teams') result = listTeams(opts);
+    else if (name === 'get_team') result = getTeam(args, opts);
+    else if (name === 'cx_trace_telemetry') { const m = await import('./tools/telemetry.mjs'); result = await m.cxTrace(args, opts); }
+    else if (name === 'cx_trace') result = await cxTrace(args, opts);
     else if (name === 'cx_score') result = await cxScore(args);
-    else if (name === 'session_usage') result = await sessionUsage(args);
+    else if (name === 'cx_trace_update') result = await cxTraceUpdate(args);
+    else if (name === 'session_list') result = sessionList(args);
+    else if (name === 'session_load') result = sessionLoad(args);
+    else if (name === 'session_search') result = sessionSearch(args);
+    else if (name === 'session_save') result = sessionSave(args);
+    else if (name === 'memory_search') result = await memorySearch(args);
+    else if (name === 'memory_add_observations') result = memoryAddObservations(args);
+    else if (name === 'memory_create_entities') result = memoryCreateEntities(args);
+    else if (name === 'memory_recent') result = memoryRecent(args);
+    else if (name === 'rovo_search') result = await rovoSearch(args);
+    else if (name === 'efficiency_snapshot') result = efficiencySnapshot(args);
+    else if (name === 'session_usage') result = await sessionUsage(args, opts);
+    else if (name === 'provider_fetch') {
+      const { demandFetch } = await import('../embed/demand-fetch.mjs');
+      result = await demandFetch({ query: args.query, rootDir: args.root_dir });
+    }
+    else if (name === 'knowledge_search') {
+      const { knowledgeSearch } = await import('../knowledge/search.mjs');
+      result = knowledgeSearch({ query: args.query, topK: args.top_k, repoRoot: args.repo_root, rootDir: args.root_dir });
+    }
     else result = { error: `Unknown tool: ${name}` };
   } catch (err) {
     result = { error: err.message ?? String(err) };
@@ -1114,9 +796,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   };
 });
 
-export { cxTrace, projectContext, workflowStatus };
-
-if (import.meta.url === `file://${process.argv[1]}`) {
+const cxTraceBound = (args) => cxTrace(args, opts);
+const projectContextBound = (args) => projectContext(args, opts);
+const workflowStatusBound = (args) => workflowStatus(args, opts);
+
+export {
+  cxTraceBound as cxTrace,
+  projectContextBound as projectContext,
+  workflowStatusBound as workflowStatus,
+  extractDocumentText,
+  ingestDocument,
+  inferDocumentSchemaTool,
+  listSchemaArtifactsTool,
+  storageStatus,
+  storageSync,
+  storageReset,
+  deleteIngestedArtifactsTool,
+  agentContract,
+};
+
+const argv1Real = (() => { try { return realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (fileURLToPath(import.meta.url) === argv1Real) {
   console.error('[construct-mcp] server started');
   const transport = new StdioServerTransport();
   await server.connect(transport);