@geraldmaron/construct 1.0.5 → 1.0.7

package/lib/mcp/memory-bridge.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+/**
+ * lib/mcp/memory-bridge.mjs — stdio MCP bridge for cass-memory (cm).
+ *
+ * Editor MCP clients (OpenCode, Claude Code) expect a host to satisfy the MCP
+ * HTTP+SSE handshake — GET with `Accept: text/event-stream`, POST `initialize`,
+ * `notifications/initialized`, `ping`. cass-memory v0.2.x ships an HTTP server
+ * that answers `tools/list`, `tools/call`, `resources/list`, `resources/read`
+ * over POST but rejects the handshake calls (405 on GET, "Unsupported method"
+ * on POST initialize/ping). That single gap surfaces in editors as
+ * "memory SSE error: Non-200 status code (405)" and the memory tools never
+ * register.
+ *
+ * Sits between editor and cm. Speaks the canonical 2026 MCP stdio transport
+ * (newline-delimited JSON-RPC on stdin/stdout, logs on stderr), answers the
+ * handshake natively, and forwards real work (tools/resources) to cm over its
+ * existing HTTP API. Stays up across cm restarts; surfaces backend outages as
+ * JSON-RPC `-32603` errors rather than crashing, so the editor can retry
+ * without losing the channel.
+ *
+ * Env:
+ *   CONSTRUCT_MEMORY_BRIDGE_URL       cm base URL (default http://127.0.0.1:8765/)
+ *   CONSTRUCT_MEMORY_BRIDGE_AUTOSTART set to 1 to spawn `cm serve` if unreachable
+ *   CONSTRUCT_MEMORY_BRIDGE_TIMEOUT_MS   per-request timeout (default 5000)
+ *
+ * Stdout is reserved for protocol frames. All diagnostic output goes to stderr.
+ */
+
+import { createInterface } from 'node:readline';
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_NAME = 'construct-memory-bridge';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function readPackageVersion() {
+  try {
+    const pkgPath = join(__dirname, '..', '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+const SERVER_VERSION = readPackageVersion();
+
+function normalizeBackendUrl(raw) {
+  const value = (raw && String(raw).trim()) || 'http://127.0.0.1:8765/';
+  return value.endsWith('/') ? value : `${value}/`;
+}
+
+const BACKEND_URL = normalizeBackendUrl(process.env.CONSTRUCT_MEMORY_BRIDGE_URL);
+const REQUEST_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.CONSTRUCT_MEMORY_BRIDGE_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 5000;
+})();
+const AUTOSTART = process.env.CONSTRUCT_MEMORY_BRIDGE_AUTOSTART === '1';
+
+const FORWARDED_METHODS = new Set([
+  'tools/list',
+  'tools/call',
+  'resources/list',
+  'resources/read',
+  'prompts/list',
+  'prompts/get',
+]);
+
+function log(...parts) {
+  process.stderr.write(`[memory-bridge] ${parts.join(' ')}\n`);
+}
+
+function writeFrame(frame) {
+  process.stdout.write(`${JSON.stringify(frame)}\n`);
+}
+
+function jsonRpcResult(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+function jsonRpcError(id, code, message, data) {
+  const err = { code, message };
+  if (data !== undefined) err.data = data;
+  return { jsonrpc: '2.0', id, error: err };
+}
+
+// cm forwarding uses fetch with an AbortController so a stuck backend never
+// strands the editor. Failed call returns a JSON-RPC -32603 error frame, not a
+// thrown exception, so the bridge process stays available for retries.
+
+async function forwardToBackend(method, params, id) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const body = { jsonrpc: '2.0', id: id ?? 0, method, params: params ?? {} };
+    const res = await fetch(BACKEND_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return jsonRpcError(
+        id,
+        -32603,
+        `memory backend returned HTTP ${res.status} for ${method}`,
+        { backend: BACKEND_URL, status: res.status },
+      );
+    }
+    const text = await res.text();
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      return jsonRpcError(id, -32603, `memory backend returned non-JSON for ${method}`, { backend: BACKEND_URL });
+    }
+    if (parsed && Object.prototype.hasOwnProperty.call(parsed, 'error')) {
+      return { jsonrpc: '2.0', id, error: parsed.error };
+    }
+    return jsonRpcResult(id, parsed && parsed.result !== undefined ? parsed.result : parsed);
+  } catch (err) {
+    const reason = err?.name === 'AbortError' ? 'timeout' : (err?.message || String(err));
+    return jsonRpcError(id, -32603, `memory backend unreachable at ${BACKEND_URL} (${reason})`, { backend: BACKEND_URL });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Autostart only fires when CONSTRUCT_MEMORY_BRIDGE_AUTOSTART=1. Detached
+// spawn keeps cm alive after the editor disconnects.
+
+let autostartAttempted = false;
+
+function maybeAutostartCm() {
+  if (!AUTOSTART || autostartAttempted) return;
+  autostartAttempted = true;
+  try {
+    const port = (() => {
+      try {
+        const u = new URL(BACKEND_URL);
+        return u.port || '8765';
+      } catch {
+        return '8765';
+      }
+    })();
+    const child = spawn('cm', ['serve', '--port', String(port)], {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
+    log(`autostart: spawned cm serve --port ${port}`);
+  } catch (err) {
+    log(`autostart failed: ${err?.message || err}`);
+  }
+}
+
+// Handshake methods resolve natively. cm cannot answer them; forwarding would
+// return the same "Unsupported method" surface that triggered this bug.
+
+function handleInitialize(id) {
+  return jsonRpcResult(id, {
+    protocolVersion: PROTOCOL_VERSION,
+    capabilities: { tools: {}, resources: {} },
+    serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+  });
+}
+
+function handlePing(id) {
+  return jsonRpcResult(id, {});
+}
+
+async function handleShutdown(id) {
+  try { process.stderr.write(''); } catch { /* stderr already closed */ }
+  if (id !== undefined && id !== null) writeFrame(jsonRpcResult(id, null));
+  setImmediate(() => process.exit(0));
+}
+
+async function dispatch(message) {
+  if (!message || typeof message !== 'object') return null;
+  if (message.jsonrpc !== '2.0') return null;
+
+  const { id, method, params } = message;
+  const isNotification = id === undefined || id === null;
+
+  if (method === 'notifications/initialized' || method === 'notifications/cancelled') {
+    return null;
+  }
+  if (method === 'initialize') return handleInitialize(id);
+  if (method === 'ping') return handlePing(id);
+  if (method === 'shutdown') return handleShutdown(id);
+
+  if (FORWARDED_METHODS.has(method)) {
+    maybeAutostartCm();
+    return forwardToBackend(method, params, id);
+  }
+
+  if (isNotification) return null;
+  return jsonRpcError(id, -32601, `Method not found: ${method}`);
+}
+
+async function handleLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  let message;
+  try {
+    message = JSON.parse(trimmed);
+  } catch (err) {
+    writeFrame(jsonRpcError(null, -32700, `Parse error: ${err?.message || err}`));
+    return;
+  }
+  try {
+    const response = await dispatch(message);
+    if (response) writeFrame(response);
+  } catch (err) {
+    if (message && message.id !== undefined && message.id !== null) {
+      writeFrame(jsonRpcError(message.id, -32603, `Internal bridge error: ${err?.message || err}`));
+    } else {
+      log(`unhandled error on notification: ${err?.message || err}`);
+    }
+  }
+}
+
+export function startBridge({ input = process.stdin, output = process.stdout } = {}) {
+  if (output !== process.stdout) {
+    const writer = (frame) => output.write(`${JSON.stringify(frame)}\n`);
+    return runLoop(input, writer);
+  }
+  return runLoop(input, (frame) => process.stdout.write(`${JSON.stringify(frame)}\n`));
+}
+
+function runLoop(input, writer) {
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  rl.on('line', async (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let message;
+    try {
+      message = JSON.parse(trimmed);
+    } catch (err) {
+      writer(jsonRpcError(null, -32700, `Parse error: ${err?.message || err}`));
+      return;
+    }
+    try {
+      const response = await dispatch(message);
+      if (response) writer(response);
+    } catch (err) {
+      if (message && message.id !== undefined && message.id !== null) {
+        writer(jsonRpcError(message.id, -32603, `Internal bridge error: ${err?.message || err}`));
+      } else {
+        log(`unhandled error on notification: ${err?.message || err}`);
+      }
+    }
+  });
+  rl.on('close', () => process.exit(0));
+  return rl;
+}
+
+const isMain = (() => {
+  try { return import.meta.url === `file://${process.argv[1]}`; } catch { return false; }
+})();
+
+if (isMain) {
+  log(`starting (backend=${BACKEND_URL}, autostart=${AUTOSTART ? 'on' : 'off'})`);
+  startBridge();
+}
+
+export const _testing = {
+  dispatch,
+  handleLine,
+  BACKEND_URL,
+  SERVER_VERSION,
+};

package/lib/mcp/server.mjs

@@ -3,7 +3,7 @@
  * lib/mcp/server.mjs — Construct MCP server: tool registry and request dispatcher.
  *
  * 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.
+ * Registers 52 tools across 8 modules: project, document, storage, skills, workflow, telemetry, memory, profile.
  * Consumed by Claude Code, OpenCode, and any MCP-compatible host.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -40,6 +40,7 @@ import {
 import {
   workflowInit, workflowAddTask, workflowUpdateTask,
   workflowNeedsMainInput, workflowValidate, workflowImportPlan,
+  workflowContractValidate,
 } from './tools/workflow.mjs';
 import {
   cxTrace, cxTraceUpdate, cxScore, sessionUsage, efficiencySnapshot,
@@ -48,6 +49,12 @@ import {
   memorySearch, memoryAddObservations, memoryCreateEntities, memoryRecent,
   sessionList, sessionLoad, sessionSearch, sessionSave, rovoSearch,
 } from './tools/memory.mjs';
+import {
+  profileShow, profileList, profileDrafts, profileHealthTool,
+  outcomesSummary, outcomesRecord, knowledgeAdd,
+  profileCreate, profileArchive, sandboxList, learningStatus,
+  knowledgeGraphAsk,
+} from './tools/profile.mjs';
 
 const DEFAULT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ROOT_DIR = resolve(process.env.CX_TOOLKIT_DIR || DEFAULT_ROOT_DIR);
@@ -711,6 +718,174 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'profile_show',
+      description: 'Return the active Construct org profile (id, displayName, roles, departments, intake taxonomy, doc templates). Use when a specialist needs to know which role set, classification taxonomy, or doc templates apply before drafting work.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          id: { type: 'string', description: 'Force a specific profile id instead of resolving from config.' },
+        },
+      },
+    },
+    {
+      name: 'profile_list',
+      description: 'List the curated org profile catalog (rnd, operations, creative, research) with role/department counts. Use to discover which profiles are available before suggesting `construct profile set`.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'profile_drafts',
+      description: 'List in-progress draft profiles under `.cx/profiles/draft-*` and any user-defined custom profile at `.cx/profile.json`. Use to see what profile work is pending before scaffolding another draft.',
+      inputSchema: {
+        type: 'object',
+        properties: { cwd: { type: 'string', description: 'Project root (default: server cwd).' } },
+      },
+    },
+    {
+      name: 'profile_health',
+      description: 'Per-profile health rollup over a window: observation count, per-role outcome runs and success rates. Use to check whether a profile is producing data before recommending changes or archive.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          id: { type: 'string', description: 'Profile id (default: active profile).' },
+          window_days: { type: 'number', description: 'Window in days (default 30).' },
+        },
+      },
+    },
+    {
+      name: 'outcomes_summary',
+      description: 'Read `.cx/outcomes/_summary.json` (per-role success rate, 30-day trend). Pass `aggregate=true` to rebuild the summary from JSONL outcome files first. Use to ground tiebreakers and improvement suggestions in real specialist performance.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          aggregate: { type: 'boolean', description: 'Rebuild `_summary.json` before reading (default false).' },
+        },
+      },
+    },
+    {
+      name: 'outcomes_record',
+      description: 'Append a specialist outcome line to `.cx/outcomes/<role>.jsonl` (writes durable state — requires `confirm=true`). Use when a specialist wants to self-report success/failure outside the automatic agent-tracker path.',
+      inputSchema: {
+        type: 'object',
+        required: ['confirm', 'role', 'success'],
+        properties: {
+          confirm: { type: 'boolean', description: 'Must be true.' },
+          cwd: { type: 'string' },
+          role: { type: 'string', description: 'Specialist id (e.g. cx-engineer, product-manager).' },
+          success: { type: 'boolean' },
+          intake_id: { type: 'string' },
+          profile: { type: 'string', description: 'Override active profile id stamp.' },
+          escalated: { type: 'boolean' },
+          duration_ms: { type: 'number' },
+          notes: { type: 'string', description: 'Trimmed to 500 chars.' },
+          source: { type: 'string', description: 'Origin tag (default: "mcp").' },
+        },
+      },
+    },
+    {
+      name: 'knowledge_add',
+      description: 'Persist a research finding as `.cx/knowledge/external/research/<slug>.md` with research-specific frontmatter (topic, confidence, sources, expiresAt, profile). Writes durable state — requires `confirm=true`. `confidence=confirmed` requires at least one source.',
+      inputSchema: {
+        type: 'object',
+        required: ['confirm', 'slug', 'topic', 'body'],
+        properties: {
+          confirm: { type: 'boolean', description: 'Must be true.' },
+          cwd: { type: 'string' },
+          slug: { type: 'string', description: 'Lowercase hyphenated, max 60 chars.' },
+          topic: { type: 'string' },
+          body: { type: 'string', description: 'Findings / inferences / gaps / recommendation block. Capped at 50KB total file.' },
+          confidence: { type: 'string', enum: ['confirmed', 'inferred', 'weak'], description: 'Default: inferred.' },
+          sources: {
+            type: 'array',
+            description: 'Required when confidence=confirmed.',
+            items: {
+              type: 'object',
+              required: ['url'],
+              properties: {
+                url: { type: 'string' },
+                accessedAt: { type: 'string', description: 'ISO timestamp; default now.' },
+                span: { type: 'string', description: 'Citation locator; trimmed to 200 chars.' },
+              },
+            },
+          },
+          ttl_days: { type: 'number', description: 'Default 90.' },
+        },
+      },
+    },
+    {
+      name: 'profile_create',
+      description: 'Scaffold a draft org profile under `.cx/profiles/draft-<id>/` (requirements.md + profile.json + persona stubs + department charters). Writes durable state — requires `confirm=true`. For curated catalog work, follow `docs/concepts/profile-lifecycle.md` after creation.',
+      inputSchema: {
+        type: 'object',
+        required: ['confirm', 'id'],
+        properties: {
+          confirm: { type: 'boolean', description: 'Must be true.' },
+          cwd: { type: 'string' },
+          id: { type: 'string', description: 'Profile id (^[a-z][a-z0-9-]{1,30}$).' },
+          display_name: { type: 'string' },
+          seed_roles: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Role ids to scaffold persona files for (cap 80).',
+          },
+          seed_departments: {
+            type: 'array',
+            items: {
+              type: 'object',
+              required: ['id'],
+              properties: {
+                id: { type: 'string' },
+                displayName: { type: 'string' },
+              },
+            },
+            description: 'Departments to scaffold charters for (cap 12).',
+          },
+        },
+      },
+    },
+    {
+      name: 'profile_archive',
+      description: 'Archive a curated profile: moves `profiles/<id>.json` and its intake table into `archive/profiles/<id>/` with an archive note. Destructive — requires `confirm=true` and a substantive `reason` (>=8 chars). Observations and outcomes are preserved.',
+      inputSchema: {
+        type: 'object',
+        required: ['confirm', 'id', 'reason'],
+        properties: {
+          confirm: { type: 'boolean', description: 'Must be true.' },
+          id: { type: 'string' },
+          reason: { type: 'string', description: 'Substantive reason (>= 8 chars).' },
+        },
+      },
+    },
+    {
+      name: 'sandbox_list',
+      description: 'List Construct sandboxes under `~/.cx/sandboxes/` (id, path, createdAt). Use to find an isolated environment for QA or dry-runs without polluting the active project.',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'knowledge_graph_ask',
+      description: 'GraphRAG-style global query over the entity graph in `.cx/observations/`. Detects communities via label propagation, ranks them by BM25 against the query, and returns each top community with its central members and extractive summary. Use for "tell me about how X relates across the project" questions that pure semantic retrieval handles poorly.',
+      inputSchema: {
+        type: 'object',
+        required: ['query'],
+        properties: {
+          query: { type: 'string', description: 'Natural-language question.' },
+          cwd: { type: 'string', description: 'Project root (default: server cwd).' },
+          top_k: { type: 'number', description: 'Max communities to return (default 5).' },
+          min_size: { type: 'number', description: 'Skip communities smaller than this (default 2).' },
+        },
+      },
+    },
+    {
+      name: 'learning_status',
+      description: 'One-shot mirror of `npm run learning:status`: active profile, observation counts (last 24h + total), research finding count, per-role outcome rollup. Use to answer "is Construct learning?" without spawning a shell.',
+      inputSchema: {
+        type: 'object',
+        properties: { cwd: { type: 'string', description: 'Project root (default: server cwd).' } },
+      },
+    },
     {
       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.',
@@ -760,6 +935,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     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_contract_validate') result = await workflowContractValidate(args);
     else if (name === 'workflow_import_plan') result = workflowImportPlan(args);
     else if (name === 'list_teams') result = listTeams(opts);
     else if (name === 'get_team') result = getTeam(args, opts);
@@ -786,6 +962,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       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 if (name === 'profile_show') result = profileShow(args);
+    else if (name === 'profile_list') result = profileList();
+    else if (name === 'profile_drafts') result = profileDrafts(args);
+    else if (name === 'profile_health') result = profileHealthTool(args);
+    else if (name === 'outcomes_summary') result = outcomesSummary(args);
+    else if (name === 'outcomes_record') result = outcomesRecord(args);
+    else if (name === 'knowledge_add') result = await knowledgeAdd(args);
+    else if (name === 'profile_create') result = profileCreate(args);
+    else if (name === 'profile_archive') result = profileArchive(args);
+    else if (name === 'sandbox_list') result = sandboxList();
+    else if (name === 'learning_status') result = learningStatus(args);
+    else if (name === 'knowledge_graph_ask') result = knowledgeGraphAsk(args);
     else result = { error: `Unknown tool: ${name}` };
   } catch (err) {
     result = { error: err.message ?? String(err) };