@smartmemory/compose 0.1.0

package/server/compose-mcp.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+/**
+ * Compose MCP Server — stdio transport
+ *
+ * Exposes Compose tracker state as MCP tools for Claude Code agents running
+ * inside this project. Claude Code launches this process on-demand and
+ * communicates via stdin/stdout JSON-RPC. No port, no supervisor entry.
+ *
+ * Register in .mcp.json:
+ *   { "mcpServers": { "compose": { "command": "node", "args": ["server/compose-mcp.js"] } } }
+ *
+ * Tools:
+ *   get_vision_items     — query items by phase/status/type/keyword
+ *   get_item_detail      — single item with its connections
+ *   get_current_session  — active session: tool count, items touched, summaries
+ *   get_phase_summary    — status distribution for a given phase
+ *   get_blocked_items    — items blocked by non-complete dependencies
+ *
+ * Token budget (per docs/features/mcp-connector/design.md Decision 6):
+ *   Baseline (2026-02-24): ~519 tokens for all 5 tool definitions combined
+ *   Soft cap: 2,000 tokens. Add typed tools for new operations; avoid proliferation.
+ *   Per-tool: get_vision_items 235, get_phase_summary 104,
+ *   get_item_detail 72, get_current_session 62, get_blocked_items 44
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import {
+  toolGetVisionItems,
+  toolGetItemDetail,
+  toolGetPhasesSummary,
+  toolGetBlockedItems,
+  toolGetCurrentSession,
+  toolGetFeatureLifecycle,
+  toolKillFeature,
+  toolCompleteFeature,
+  toolAssessFeatureArtifacts,
+  toolScaffoldFeature,
+  toolApproveGate,
+  toolGetPendingGates,
+  toolBindSession,
+  toolIterationStart,
+  toolIterationReport,
+  toolIterationAbort,
+} from './compose-mcp-tools.js';
+
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+
+const TOOLS = [
+  {
+    name: 'get_vision_items',
+    description: 'Query Compose tracker items. Filter by phase, status, type, or keyword. Returns id, title, type, phase, status, confidence, description.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        phase: {
+          type: 'string',
+          description: 'Filter by phase: vision, requirements, design, planning, implementation, verification, release',
+        },
+        status: {
+          type: 'string',
+          description: 'Filter by status (comma-separated for multiple): planned, in_progress, complete, blocked, parked, killed',
+        },
+        type: {
+          type: 'string',
+          description: 'Filter by type: task, decision, evaluation, idea, spec, thread, artifact, question, feature, track',
+        },
+        keyword: {
+          type: 'string',
+          description: 'Search keyword matched against title and description',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results to return (default 30)',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_item_detail',
+    description: 'Get full detail for a single tracker item including all its connections.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Item ID (UUID) or semanticId/slug',
+        },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'get_phase_summary',
+    description: 'Get status and type distribution for a phase (or all phases). Useful for understanding overall project health.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        phase: {
+          type: 'string',
+          description: 'Phase to summarize: vision, requirements, design, planning, implementation, verification, release. Omit for all phases.',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_blocked_items',
+    description: 'List all tracker items that are blocked by non-complete items.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'get_current_session',
+    description: 'Get the most recent session: tool count, items touched, error count, and recent Haiku summaries of what was accomplished.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        featureCode: { type: 'string', description: 'Optional: get context for a specific feature' },
+      },
+    },
+  },
+  {
+    name: 'bind_session',
+    description: 'Bind the current agent session to a lifecycle feature. Call once per session after creating/identifying the feature. Binding is one-shot — calling again on a bound session returns already_bound.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        featureCode: { type: 'string', description: 'The feature code (e.g., "gate-ui")' },
+      },
+      required: ['featureCode'],
+    },
+  },
+  {
+    name: 'get_feature_lifecycle',
+    description: 'Get the lifecycle state of a feature: current phase, phase history, artifacts, warnings.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Item ID (UUID) or slug' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'kill_feature',
+    description: 'Kill a feature from any phase. Records reason and sets status to killed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Item ID' },
+        reason: { type: 'string', description: 'Why the feature is being killed' },
+      },
+      required: ['id', 'reason'],
+    },
+  },
+  {
+    name: 'complete_feature',
+    description: 'Mark a feature as complete. Only callable from the ship phase.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Item ID' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'start_iteration_loop',
+    description: 'Start a review or coverage iteration loop on a feature. Returns loop state.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Item ID or semanticId' },
+        loopType: { type: 'string', enum: ['review', 'coverage'], description: 'Type of iteration loop' },
+        maxIterations: { type: 'number', description: 'Override max iterations (optional, defaults from settings)' },
+      },
+      required: ['id', 'loopType'],
+    },
+  },
+  {
+    name: 'report_iteration_result',
+    description: 'Report one iteration result. Compose evaluates exit criteria and returns whether to continue.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Item ID or semanticId' },
+        result: { type: 'object', description: 'Iteration result. Review: {clean: bool, findings: []}, Coverage: {passing: bool, failures: []}' },
+      },
+      required: ['id', 'result'],
+    },
+  },
+  {
+    name: 'abort_iteration_loop',
+    description: 'Abort the current iteration loop early.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Item ID or semanticId' },
+        reason: { type: 'string', description: 'Why the loop was aborted' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'assess_feature_artifacts',
+    description: 'Assess quality signals for all artifacts of a feature: section completeness, word count, last modified.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        featureCode: { type: 'string', description: 'Feature folder name (e.g. "artifact-awareness")' },
+      },
+      required: ['featureCode'],
+    },
+  },
+  {
+    name: 'scaffold_feature',
+    description: 'Create feature folder with template stubs for all phase artifacts. Existing files are never overwritten.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        featureCode: { type: 'string', description: 'Feature folder name' },
+        only: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Limit to specific artifacts (e.g. ["design.md", "blueprint.md"]). Omit for all.',
+        },
+      },
+      required: ['featureCode'],
+    },
+  },
+  {
+    name: 'approve_gate',
+    description: 'Resolve a pending policy gate. Outcomes: approved (proceed), revised (stay in phase), killed (abandon feature).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        gateId: { type: 'string', description: 'Gate ID' },
+        outcome: { type: 'string', enum: ['approved', 'revised', 'killed'], description: 'Resolution outcome' },
+        comment: { type: 'string', description: 'Optional human feedback' },
+      },
+      required: ['gateId', 'outcome'],
+    },
+  },
+  {
+    name: 'get_pending_gates',
+    description: 'List pending policy gates. Optionally filter by item ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        itemId: { type: 'string', description: 'Filter to gates for a specific item (optional)' },
+      },
+    },
+  },
+  // Note: `agent_run` tool removed 2026-04-18 (STRAT-DEDUP-AGENTRUN v1).
+  // LLM-facing agent dispatch now goes through `mcp__stratum__stratum_agent_run`.
+  // `toolAgentRun` (and the Node connectors it uses) remain exported for Compose's
+  // internal callers (build.js, vision-server, pipelines).
+];
+
+// ---------------------------------------------------------------------------
+// MCP Server setup
+// ---------------------------------------------------------------------------
+
+const server = new Server(
+  { name: 'compose', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS,
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  try {
+    let result;
+    switch (name) {
+      case 'get_vision_items':    result = toolGetVisionItems(args); break;
+      case 'get_item_detail':     result = toolGetItemDetail(args); break;
+      case 'get_phase_summary':   result = toolGetPhasesSummary(args); break;
+      case 'get_blocked_items':   result = toolGetBlockedItems(); break;
+      case 'get_current_session': result = await toolGetCurrentSession(args); break;
+      case 'bind_session':             result = await toolBindSession(args); break;
+      case 'get_feature_lifecycle':    result = toolGetFeatureLifecycle(args); break;
+      case 'kill_feature':             result = await toolKillFeature(args); break;
+      case 'complete_feature':         result = await toolCompleteFeature(args); break;
+      case 'start_iteration_loop':     result = await toolIterationStart(args); break;
+      case 'report_iteration_result':  result = await toolIterationReport(args); break;
+      case 'abort_iteration_loop':     result = await toolIterationAbort(args); break;
+      case 'assess_feature_artifacts': result = toolAssessFeatureArtifacts(args); break;
+      case 'scaffold_feature':         result = toolScaffoldFeature(args); break;
+      case 'approve_gate':             result = await toolApproveGate(args); break;
+      case 'get_pending_gates':        result = toolGetPendingGates(args); break;
+      // agent_run removed — STRAT-DEDUP-AGENTRUN v1. Use mcp__stratum__stratum_agent_run.
+      default:
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Error: ${err.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// Server runs until stdin closes — no explicit exit needed

package/server/connectors/agent-connector.js

@@ -0,0 +1,78 @@
+/**
+ * AgentConnector — base class for all agent connectors.
+ *
+ * @implements {ConnectorDiscovery} — see connector-discovery.js
+ * @implements {ConnectorRuntime}  — see connector-runtime.js
+ *
+ * Subclasses implement run(), interrupt(), and isRunning.
+ * Duck typing — no enforcement at runtime beyond the throw in run().
+ *
+ * Message envelope (yielded by run()):
+ *   { type: 'system',    subtype: 'init' | 'complete', agent: string, model?: string }
+ *   { type: 'assistant', content: string }
+ *   { type: 'tool_use',          tool: string, input: object }
+ *   { type: 'tool_use_summary',  summary: string, output?: string }
+ *   { type: 'error',             message: string }
+ *
+ * Schema mode: if opts.schema is provided, the connector injects it into the
+ * prompt as instructions and yields text output. JSON.parse() happens at the
+ * MCP layer (agent-mcp.js), never inside connectors.
+ */
+
+export class AgentConnector {
+  // ── Discovery ──────────────────────────────────────────────────────────────
+
+  /** @returns {string[]} */
+  listModels() { return []; }
+
+  /** @param {string} _modelId @returns {boolean} */
+  supportsModel(_modelId) { return false; }
+
+  /** @param {string} _sessionId @returns {Promise<object[]>} */
+  async loadHistory(_sessionId) { return []; }
+
+  // ── Runtime ────────────────────────────────────────────────────────────────
+
+  /**
+   * Run a prompt against the agent.
+   *
+   * @param {string} prompt
+   * @param {object} [opts]
+   * @param {object}   [opts.schema]     — JSON Schema → structured output mode
+   * @param {string}   [opts.modelID]    — override model for this run
+   * @param {string}   [opts.providerID] — provider ID (OpenCode subclasses only)
+   * @param {string}   [opts.cwd]        — working directory
+   * @param {string[]} [opts.tools]      — restrict available tools
+   * @returns {AsyncGenerator}
+   */
+  // eslint-disable-next-line require-yield
+  async *run(_prompt, _opts = {}) {
+    throw new Error(`${this.constructor.name}.run() not implemented`);
+  }
+
+  /** Stop the active run cleanly. No-op if not running. */
+  interrupt() {}
+
+  /** Whether a run is currently active. */
+  get isRunning() { return false; }
+}
+
+/**
+ * Inject a JSON schema into a prompt so the agent knows to return structured JSON.
+ * Used by both ClaudeSDKConnector and OpencodeConnector — parsing happens at call site.
+ *
+ * @param {string} prompt
+ * @param {object} schema  JSON Schema object
+ * @returns {string}
+ */
+export function injectSchema(prompt, schema) {
+  return (
+    `${prompt}\n\n` +
+    `IMPORTANT: After completing the task, include a JSON code block at the very end ` +
+    `of your response matching this schema:\n` +
+    '```json\n' +
+    `${JSON.stringify(schema, null, 2)}\n` +
+    '```\n' +
+    `The JSON block must be the last thing in your response.`
+  );
+}

package/server/connectors/claude-sdk-connector.js

@@ -0,0 +1,198 @@
+/**
+ * ClaudeSDKConnector — wraps @anthropic-ai/claude-agent-sdk query().
+ *
+ * All Anthropic model execution goes through this connector.
+ * Yields the same typed message envelope as the other connectors.
+ */
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { AgentConnector, injectSchema } from './agent-connector.js';
+
+const DEFAULT_MODEL = process.env.CLAUDE_MODEL || 'claude-sonnet-4-6';
+
+export class ClaudeSDKConnector extends AgentConnector {
+  // ── Discovery ──────────────────────────────────────────────────────────────
+  // No overrides — inherits stubs from AgentConnector. See agent-connector.js.
+
+  #model;
+  #cwd;
+  #query = null;
+
+  #allowedTools;
+  #disallowedTools;
+  #thinking;
+  #effort;
+
+  /**
+   * @param {object} [opts]
+   * @param {string}   [opts.model]            — default model (env CLAUDE_MODEL or claude-sonnet-4-6)
+   * @param {string}   [opts.cwd]              — default working directory
+   * @param {string[]} [opts.allowedTools]     — restrict to these tools (overrides preset)
+   * @param {string[]} [opts.disallowedTools]  — deny these tools (used alongside allowedTools or preset)
+   * @param {object|null} [opts.thinking]      — Claude thinking config, e.g. { type: 'adaptive' } or { type: 'disabled' }
+   * @param {string|null} [opts.effort]        — effort level: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+   */
+  constructor({ model = DEFAULT_MODEL, cwd = process.cwd(), allowedTools, disallowedTools, thinking, effort } = {}) {
+    super();
+    this.#model = model;
+    this.#cwd = cwd;
+    this.#allowedTools = allowedTools ?? null;
+    this.#disallowedTools = disallowedTools ?? null;
+    this.#thinking = thinking ?? null;
+    this.#effort = effort ?? null;
+  }
+
+  // ── Runtime ────────────────────────────────────────────────────────────────
+
+  async *run(prompt, { schema, modelID, cwd, thinking, effort } = {}) {
+    if (this.#query) {
+      throw new Error('ClaudeSDKConnector: run() already active. Call interrupt() first.');
+    }
+
+    const actualPrompt = schema ? injectSchema(prompt, schema) : prompt;
+
+    // Strip CLAUDECODE env var to allow spawning inside a Claude Code session
+    const cleanEnv = { ...process.env };
+    delete cleanEnv.CLAUDECODE;
+
+    // Build tools config: prefer explicit allow/deny lists if provided,
+    // otherwise fall back to the default claude_code preset (backward compat).
+    let toolsConfig;
+    if (this.#allowedTools !== null) {
+      toolsConfig = { type: 'allowed', allowedTools: this.#allowedTools };
+      if (this.#disallowedTools !== null) {
+        toolsConfig.disallowedTools = this.#disallowedTools;
+      }
+    } else if (this.#disallowedTools !== null) {
+      toolsConfig = { type: 'preset', preset: 'claude_code', disallowedTools: this.#disallowedTools };
+    } else {
+      toolsConfig = { type: 'preset', preset: 'claude_code' };
+    }
+
+    // Resolve thinking/effort: per-run override beats constructor default.
+    const resolvedThinking = thinking !== undefined ? thinking : this.#thinking;
+    const resolvedEffort   = effort   !== undefined ? effort   : this.#effort;
+
+    const sdkOptions = {
+      cwd: cwd ?? this.#cwd,
+      model: modelID ?? this.#model,
+      permissionMode: 'acceptEdits',
+      tools: toolsConfig,
+      env: cleanEnv,
+    };
+    if (resolvedThinking !== null && resolvedThinking !== undefined) {
+      sdkOptions.thinking = resolvedThinking;
+    }
+    if (resolvedEffort !== null && resolvedEffort !== undefined) {
+      sdkOptions.effort = resolvedEffort;
+    }
+
+    const q = query({
+      prompt: actualPrompt,
+      options: sdkOptions,
+    });
+    this.#query = q;
+
+    yield { type: 'system', subtype: 'init', agent: 'claude', model: modelID ?? this.#model };
+
+    const activeModel = modelID ?? this.#model;
+    try {
+      for await (const msg of q) {
+        if (process.env.COMPOSE_DEBUG) {
+          process.stderr.write(`  [sdk] ${msg?.type ?? typeof msg}\n`);
+        }
+        for (const event of _normalizeAll(msg)) {
+          // Inject model into usage events extracted from result messages
+          if (event.type === 'usage' && event._from_result) {
+            const { _from_result: _, ...usageEvent } = event;
+            yield { ...usageEvent, model: activeModel };
+          } else {
+            yield event;
+          }
+        }
+      }
+      yield { type: 'system', subtype: 'complete', agent: 'claude' };
+    } catch (err) {
+      if (err?.name !== 'AbortError') {
+        yield { type: 'error', message: err.message || String(err) };
+      }
+    } finally {
+      this.#query = null;
+    }
+  }
+
+  interrupt() {
+    if (this.#query) {
+      try { this.#query.interrupt(); } catch { /* already done */ }
+      this.#query = null;
+    }
+  }
+
+  get isRunning() {
+    return this.#query !== null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Normalize Claude SDK message → shared envelope
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize an SDK message into one or more envelope events.
+ * Returns an array because a single assistant message can contain
+ * multiple content blocks (text + tool_use).
+ */
+function _normalizeAll(msg) {
+  if (!msg || typeof msg !== 'object') {
+    return [{ type: 'assistant', content: String(msg) }];
+  }
+  if (msg.type === 'system' || msg.type === 'error') return [msg];
+
+  // SDK assistant message — extract content blocks from msg.message
+  if (msg.type === 'assistant' && msg.message?.content) {
+    const events = [];
+    for (const block of msg.message.content) {
+      if (block.type === 'text' && block.text) {
+        events.push({ type: 'assistant', content: block.text });
+      } else if (block.type === 'tool_use') {
+        events.push({ type: 'tool_use', tool: block.name, input: block.input ?? {} });
+      }
+    }
+    return events.length > 0 ? events : [msg];
+  }
+
+  // SDK result message — contains the final aggregated text and usage metadata
+  if (msg.type === 'result' && msg.result) {
+    const events = [{ type: 'result', content: msg.result }];
+    // Extract usage from msg.usage or msg.message.usage
+    const usage = msg.usage ?? msg.message?.usage;
+    if (usage) {
+      events.push({
+        type: 'usage',
+        input_tokens: usage.input_tokens ?? 0,
+        output_tokens: usage.output_tokens ?? 0,
+        cache_creation_input_tokens: usage.cache_creation_input_tokens ?? 0,
+        cache_read_input_tokens: usage.cache_read_input_tokens ?? 0,
+        // model is injected by the run() loop via _modelForUsage tag on the event
+        _from_result: true,
+      });
+    }
+    return events;
+  }
+
+  if (msg.type === 'tool_use') {
+    return [{ type: 'tool_use', tool: msg.name ?? msg.tool, input: msg.input ?? {} }];
+  }
+  if (msg.type === 'tool_use_summary') {
+    const output = (msg.result ?? msg.output ?? '');
+    return [{ type: 'tool_use_summary', summary: msg.summary, output: output ? output.slice(0, 2048) : undefined }];
+  }
+  if (msg.type === 'tool_progress') {
+    return [{ type: 'tool_progress', tool: msg.tool_name, elapsed: msg.elapsed_time_seconds }];
+  }
+  // Delta or text content
+  if (msg.delta?.text) return [{ type: 'assistant', content: msg.delta.text }];
+  if (msg.content && typeof msg.content === 'string') return [{ type: 'assistant', content: msg.content }];
+  // Pass through unknown message types as-is
+  return [msg];
+}