Loom Recap MCP Server

[acreeger]

Summary

Build an MCP server that allows Claude to capture context that scrolls away during a session - the goal, decisions, insights, risks, and assumptions. This powers the Loom Context Panel in the VS Code extension.

Motivation

During a Claude session, important context scrolls out of view:

• Why am I here? - The original goal/problem being solved
• What did we decide and why? - Key choices made, with reasoning
• What did we learn? - Key findings, constraints, gotchas discovered
• What are we assuming / what could go wrong? - Risks and assumptions

The sticky TODO list shows progress, but these four categories of context are lost. The Recap MCP captures them so the VS Code extension can display them.

Recap File Schema

Stored in ~/.config/iloom-ai/recaps/ using same path-encoding as looms:

{
  "goal": "The original problem statement",
  "entries": [
    {
      "id": "uuid",
      "timestamp": "2025-12-15T10:23:45Z",
      "type": "decision",
      "content": "Using soft reset instead of hard reset to preserve uncommitted changes"
    },
    {
      "id": "uuid",
      "timestamp": "2025-12-15T10:25:12Z",
      "type": "insight",
      "content": "The finish command already has WIP commit handling that we can reuse"
    }
  ]
}

Entry types: decision, insight, risk, assumption, other

MCP Tools

set_goal

Set the initial goal (called once at session start)

• Input: { goal: string }
• Output: { success: true }

add_entry

Append an entry to the recap

• Input: { type: "decision" | "insight" | "risk" | "assumption" | "other", content: string }
• Output: { id: string, timestamp: string }

get_recap

Read current recap (for catching up or review)

• Input: (none)
• Output: { goal: string, entries: Array<{ id, timestamp, type, content }> }

CLI Command: il recap --json

Fast read-only command for the VS Code extension:

• Skips config validation, loom validation, etc.
• Reads ~/.config/iloom-ai/recaps/{current-loom}.json and outputs it
• Fast startup - extension calls this to get current recap state
• Extension doesn't need to know path-encoding logic

MCP Integration

Follow existing pattern from issue-management-server.ts:

• New file: src/mcp/recap-server.ts
• Uses @modelcontextprotocol/sdk
• Receives LOOM_PATH env var to derive recap filename
• Injected via CLI same as issue_management MCP

Acceptance Criteria

• Recap MCP server implemented with three tools
• Recap files stored in ~/.config/iloom-ai/recaps/ with correct naming
• il recap --json command works and is fast
• MCP config generation updated to include recap server
• Server starts with Claude session (alongside issue_management)

Related

• iloom-vscode#43 - POC Loom Context Panel (consumes this data)
• Prompt updates (separate issue) - tells Claude when to use this MCP

[acreeger]

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 9 (6 new files, 3 modified files)
• Estimated lines of code: ~1200-1500 LOC (implementation + tests combined)
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good (follows existing MCP server patterns from issue-management-server.ts)
• Overall risk level: Low

Reasoning: This is a self-contained feature that follows proven patterns already in the codebase. The MCP server implementation closely mirrors the existing issue-management-server.ts (~323 LOC), and the il recap --json CLI command is straightforward. No cross-cutting changes, breaking changes, or architectural complexity—purely additive with isolated scope. The file count is under 10, and the implementation cleanly separates concerns (MCP server, business logic, CLI command). Risk is low because it's an opt-in feature that doesn't affect existing workflows.

[acreeger]

Analysis Phase

• Fetch and understand issue requirements
• Research existing MCP server patterns in codebase
• Research recap file storage and path-encoding patterns
• Research CLI command patterns for the il recap command
• Research MCP config generation for injection
• Document technical findings and affected files

---

Executive Summary

This issue adds a Loom Recap MCP Server to capture session context (goal, decisions, insights, risks, assumptions) that scrolls away during Claude sessions. The implementation follows established patterns: the MCP server mirrors issue-management-server.ts, file storage uses MetadataManager.ts path-encoding conventions, and CLI integration follows summary.ts patterns.

Impact Summary

• 6 new files: MCP server, types, CLI command, and tests
• 3 modified files: tsup.config.ts (build), src/utils/mcp.ts (config generator), src/commands/ignite.ts (MCP injection)
• Key decision: Path-encoding approach (using MetadataManager.slugifyPath() vs custom implementation)

---

Complete Technical Reference (click to expand for implementation details)

Problem Space Research

Problem Understanding

During Claude sessions, important context scrolls out of view - the original goal, key decisions made and their reasoning, discoveries/constraints, and risks/assumptions. The TODO list tracks progress but not these contextual categories. This MCP server captures them for the VS Code extension's Loom Context Panel.

Architectural Context

• Storage: ~/.config/iloom-ai/recaps/ (parallel to existing ~/.config/iloom-ai/looms/)
• Path-encoding: Same convention as MetadataManager.slugifyPath() at /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/lib/MetadataManager.ts:113-125
• MCP pattern: Follows issue-management-server.ts at /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/issue-management-server.ts
• CLI pattern: Follows summary.ts at /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/summary.ts (fast read-only command)

Edge Cases Identified

• Empty recap file (no entries yet): Return { goal: null, entries: [] }
• Non-existent recap file: Return empty recap or error gracefully
• Invalid JSON in recap file: Log warning, return empty recap
• LOOM_PATH env var missing in MCP server: Exit with error (matches issue-management-server.ts:22-32)

Codebase Research Findings

Affected Area: MCP Server Infrastructure

Entry Point: /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/issue-management-server.ts:1-323
Dependencies:

• Uses: @modelcontextprotocol/sdk, zod, IssueManagementProviderFactory
• Used By: src/utils/mcp.ts generates config, src/commands/ignite.ts injects MCP

MCP Server Pattern (issue-management-server.ts)

• Line 9-11: Imports McpServer, StdioServerTransport from SDK
• Line 22-56: validateEnvironment() validates required env vars and exits on error
• Line 58-62: Server initialization with McpServer({ name, version })
• Line 71-146: Tool registration with server.registerTool() - includes inputSchema, outputSchema, handler
• Line 298-323: main() function with transport connection via StdioServerTransport

MCP Config Generation (src/utils/mcp.ts)

• Line 15-89: generateIssueManagementMcpConfig() generates server config object
• Line 78-87: Config structure: { mcpServers: { server_name: { transport, command, args, env } } }
• Line 83: Args point to built server JS file: dist/mcp/issue-management-server.js

MCP Injection Point (src/commands/ignite.ts)

• Line 159-183: Generates MCP config for issue/PR workflows
• Line 166: Calls generateIssueManagementMcpConfig()
• Line 218-225: Passes mcpConfig to launchClaude() options

Path Encoding Pattern (MetadataManager.ts)

• Line 97: loomsDir = path.join(os.homedir(), '.config', 'iloom-ai', 'looms')
• Line 113-125: slugifyPath() algorithm:
  1. Trim trailing slashes
  2. Replace path separators (/ or \) with ___ (triple underscore)
  3. Replace non-alphanumeric (except _ and -) with hyphens
  4. Append .json

CLI Command Pattern (summary.ts)

• Line 43-48: Constructor with dependency injection (managers as optional params)
• Line 56-104: execute() with --json mode for machine output
• Line 73-85: JSON mode returns structured result
• Line 87-89: Non-JSON mode prints to stdout via console.log()

Build Configuration (tsup.config.ts)

• Line 24-41: MCP server build config - separate entry in defineConfig array
• Line 26: Entry: src/mcp/issue-management-server.ts
• Line 29: Output: dist/mcp/
• Line 30: clean: false - doesn't clean other builds

Affected Files

New Files to Create

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/recap-server.ts - MCP server implementation (~200 LOC based on issue-management-server.ts pattern)
2. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/recap-types.ts - TypeScript types for recap schema
3. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/recap.ts - CLI command for il recap --json
4. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/recap-server.test.ts - Unit tests
5. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/recap.test.ts - CLI command tests
6. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/utils/recap-mcp.ts - Config generator function (or extend mcp.ts)

Files to Modify

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/tsup.config.ts:24-41 - Add recap-server.ts build entry
2. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/utils/mcp.ts - Add generateRecapMcpConfig() or extend existing function
3. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/ignite.ts:159-183 - Inject recap MCP alongside issue_management MCP
4. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/cli.ts - Register recap command

Integration Points

• recap-server.ts receives LOOM_PATH env var from ignite.ts via MCP config
• recap-server.ts derives recap filename using same algorithm as MetadataManager.slugifyPath()
• recap.ts CLI command reads from ~/.config/iloom-ai/recaps/{slugified-path}.json
• ignite.ts generates MCP config that includes recap server alongside issue_management server

Similar Patterns Found

• /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/issue-management-server.ts - Direct template for MCP server
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/types.ts - Pattern for types file
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/summary.ts - Pattern for fast read-only CLI command
• /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/lib/MetadataManager.ts - Path encoding and file storage pattern

[acreeger]

Update: il recap --json should include the file path in the response so the VS Code extension can watch it:

{
  "filePath": "/Users/adam/.config/iloom-ai/recaps/___Users___adam___...",
  "goal": "...",
  "entries": [...]
}

Extension flow:

1. Call il recap --json once at startup
2. Get filePath from response
3. Set up file watcher on that path
4. On file change, read file directly

This avoids polling - extension gets immediate updates via file watching, but doesn't need to know the path-encoding logic.

[acreeger]

Implementation Plan for Issue #346

Summary

Implement a Loom Recap MCP Server that captures session context (goal, decisions, insights, risks, assumptions) during Claude sessions. This includes the MCP server with 3 tools (set_goal, add_entry, get_recap), a fast il recap --json CLI command for the VS Code extension, and integration with the existing MCP injection pipeline.

Questions and Key Decisions

Question	Answer	Rationale
How does MCP server know where to store recap?	Pass RECAP_FILE_PATH env var from ignite.ts (complete file path)	Simplifies MCP server - it just reads/writes to wherever it's told. Path derivation logic stays centralized in ignite.ts
How does MCP server access loom context?	Pass LOOM_METADATA_JSON env var (stringified JSON of the loom metadata)	Server imports LoomMetadata type from codebase and parses the JSON. This decouples on-disk format from MCP contract - the JSON file format can drift without needing MCP updates
Where to store recaps?	~/.config/iloom-ai/recaps/	Parallel structure to looms/ directory, follows existing pattern
How to derive recap filename?	ignite.ts uses MetadataManager.slugifyPath() algorithm	Maintains consistency with existing ~/.config/iloom-ai/looms/ naming convention
Should recap command validate config?	No - skip all validation for speed	Issue specifies fast startup for VS Code extension

High-Level Execution Phases

1. Phase 1: Create recap types (src/mcp/recap-types.ts) with file schema and tool input/output interfaces
2. Phase 2: Implement recap MCP server (src/mcp/recap-server.ts) with 3 tools - receives RECAP_FILE_PATH and LOOM_METADATA_JSON env vars
3. Phase 3: Create il recap CLI command (src/commands/recap.ts) with fast --json mode
4. Phase 4: Add recap server to build config (tsup.config.ts)
5. Phase 5: Create MCP config generator (src/utils/mcp.ts) that computes file path and stringifies metadata
6. Phase 6: Integrate recap MCP into ignite command (src/commands/ignite.ts)
7. Phase 7: Register recap command in CLI (src/cli.ts)
8. Phase 8: Implement unit tests for all new code

Quick Stats

• 0 files for deletion
• 4 files to modify (tsup.config.ts, src/utils/mcp.ts, src/commands/ignite.ts, src/cli.ts)
• 4 new files to create (recap-types.ts, recap-server.ts, recap.ts, tests)
• Dependencies: None (uses existing @modelcontextprotocol/sdk, zod, fs-extra)
• Estimated complexity: Simple (follows existing patterns exactly)

---

Complete Implementation Guide (click to expand for step-by-step details)

Automated Test Cases to Create

Test File: /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/recap-server.test.ts (NEW)

Purpose: Unit tests for MCP server tool handlers and file operations

Click to expand complete test structure (50 lines)

// Test structure using vitest describe/it format
import { describe, it, expect, vi, beforeEach } from 'vitest'

vi.mock('fs-extra')

describe('RecapServer', () => {
  describe('validateEnvironment', () => {
    it('should exit with error when RECAP_FILE_PATH missing')
    it('should exit with error when LOOM_METADATA_JSON missing')
    it('should return parsed metadata when both env vars are valid')
  }

  describe('parseLoomMetadata', () => {
    it('should parse valid JSON into LoomMetadata type')
    it('should throw on invalid JSON')
    it('should handle missing optional fields gracefully')
  }

  describe('set_goal tool', () => {
    it('should create new recap file with goal')
    it('should update existing recap file with new goal')
    it('should ensure parent directory exists')
  }

  describe('add_entry tool', () => {
    it('should append entry to existing recap file')
    it('should create new recap file if none exists')
    it('should generate UUID and timestamp for entry')
    it('should validate entry type is valid enum value')
  }

  describe('get_recap tool', () => {
    it('should return recap with filePath, goal and entries')
    it('should return empty recap when file does not exist')
    it('should handle invalid JSON gracefully')
  }

  describe('loom metadata access', () => {
    it('should provide loom metadata from parsed LOOM_METADATA_JSON')
    it('should expose issue_numbers from metadata')
    it('should expose branchName from metadata')
  }
})

Test File: /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/recap.test.ts (NEW)

Purpose: Unit tests for CLI command

Click to expand complete test structure (30 lines)

import { describe, it, expect, vi, beforeEach } from 'vitest'

vi.mock('fs-extra')

describe('RecapCommand', () => {
  describe('execute', () => {
    it('should output JSON with filePath when --json flag provided')
    it('should auto-detect loom from current directory')
    it('should return empty recap when file does not exist')
    it('should handle invalid JSON in recap file')
  }

  describe('getRecapFilePath', () => {
    it('should derive path from cwd using slugifyPath algorithm')
    it('should use recaps directory under ~/.config/iloom-ai/')
  }

  describe('JSON output format', () => {
    it('should include filePath in response')
    it('should include goal field (null if not set)')
    it('should include entries array')
  }
})

Files to Modify

1. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/tsup.config.ts:24-41

Change: Add recap-server.ts as additional MCP server build entry

Add new build config object after the existing issue-management-server config (line 41):

// Recap MCP Server build configuration (after line 41)
{
  entry: ['src/mcp/recap-server.ts'],
  format: ['esm'],
  target: 'node16',
  outDir: 'dist/mcp',
  clean: false,
  sourcemap: true,
  dts: false,
  banner: { js: '#!/usr/bin/env node' },
  outExtension() { return { js: '.js' } },
},

2. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/utils/mcp.ts:89

Change: Add new function generateRecapMcpConfig() that computes the recap file path and receives loom metadata as the LoomMetadata type, then stringifies it for the env var

Click to expand function pseudocode (35 lines)

import type { LoomMetadata } from '../lib/MetadataManager.js'

/**
 * Generate MCP configuration for recap server
 * @param loomPath - Absolute path to the loom workspace (used to derive recap file path)
 * @param loomMetadata - The loom metadata object (will be stringified for MCP server)
 */
export function generateRecapMcpConfig(loomPath: string, loomMetadata: LoomMetadata): Record<string, unknown>[] {
  // Compute recap file path using slugifyPath algorithm (same as MetadataManager)
  const recapsDir = path.join(os.homedir(), '.config', 'iloom-ai', 'recaps')
  let slug = loomPath.replace(/[/\\]+$/, '')
  slug = slug.replace(/[/\\]/g, '___')
  slug = slug.replace(/[^a-zA-Z0-9_-]/g, '-')
  const recapFilePath = path.join(recapsDir, `${slug}.json`)
  
  // Pass both env vars:
  // - RECAP_FILE_PATH: where to read/write recap data
  // - LOOM_METADATA_JSON: stringified JSON of loom metadata (parsed using LoomMetadata type)
  const envVars = { 
    RECAP_FILE_PATH: recapFilePath,
    LOOM_METADATA_JSON: JSON.stringify(loomMetadata),
  }
  
  return [{
    mcpServers: {
      recap: {
        transport: 'stdio',
        command: 'node',
        args: [path.join(path.dirname(new URL(import.meta.url).pathname), '../dist/mcp/recap-server.js')],
        env: envVars,
      },
    },
  }]
}

3. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/ignite.ts:159-225

Change: Generate and inject recap MCP config alongside issue_management MCP, reading loom metadata and passing it to the config generator

At line ~166, after generateIssueManagementMcpConfig() call:

// Also generate recap MCP config
// Read loom metadata using MetadataManager
const loomMetadata = await metadataManager.readMetadata(context.workspacePath)
if (loomMetadata) {
  const recapMcpConfig = generateRecapMcpConfig(context.workspacePath, loomMetadata)
  // Merge recap config into mcpConfig array
  if (mcpConfig) {
    mcpConfig.push(...recapMcpConfig)
  } else {
    mcpConfig = recapMcpConfig
  }
}

Add import at top of file:

import { generateRecapMcpConfig } from '../utils/mcp.js'

4. /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/cli.ts:1127-1167

Change: Register new recap command after summary command (around line 1127)

Click to expand command registration (25 lines)

program
  .command('recap')
  .description('Get or display recap for current loom')
  .option('--json', 'Output as JSON with filePath for file watching')
  .action(async (options: { json?: boolean }) => {
    const executeAction = async (): Promise<void> => {
      try {
        const { RecapCommand } = await import('./commands/recap.js')
        const command = new RecapCommand()
        const result = await command.execute({ json: options.json })
        if (options.json && result) {
          console.log(JSON.stringify(result, null, 2))
        }
        process.exit(0)
      } catch (error) {
        if (options.json) {
          console.log(JSON.stringify({ error: error instanceof Error ? error.message : 'Unknown error' }, null, 2))
        } else {
          logger.error(`Recap failed: ${error instanceof Error ? error.message : 'Unknown error'}`)
        }
        process.exit(1)
      }
    }
    if (options.json) {
      const jsonLogger = createStderrLogger()
      await withLogger(jsonLogger, executeAction)
    } else {
      await executeAction()
    }
  })

New Files to Create

/Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/recap-types.ts (NEW)

Purpose: TypeScript types for recap file schema and MCP tool interfaces

Click to expand complete structure (50 lines)

/**
 * Type definitions for Loom Recap MCP Server
 */

/** Entry types for recap entries */
export type RecapEntryType = 'decision' | 'insight' | 'risk' | 'assumption' | 'other'

/** Single recap entry */
export interface RecapEntry {
  id: string
  timestamp: string
  type: RecapEntryType
  content: string
}

/** Recap file schema stored in ~/.config/iloom-ai/recaps/ */
export interface RecapFile {
  goal: string | null
  entries: RecapEntry[]
}

/** Output for get_recap tool and CLI --json (includes filePath per comment 3657912639) */
export interface RecapOutput {
  filePath: string
  goal: string | null
  entries: RecapEntry[]
}

/** Input for set_goal tool */
export interface SetGoalInput {
  goal: string
}

/** Input for add_entry tool */
export interface AddEntryInput {
  type: RecapEntryType
  content: string
}

/** Output for add_entry tool */
export interface AddEntryOutput {
  id: string
  timestamp: string
}

/** Output for set_goal tool */
export interface SetGoalOutput {
  success: true
}

/Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/recap-server.ts (NEW)

Purpose: MCP server implementation with 3 tools - receives RECAP_FILE_PATH and LOOM_METADATA_JSON env vars

Click to expand complete structure (175 lines)

/**
 * Loom Recap MCP Server
 * Captures session context (goal, decisions, insights, risks, assumptions)
 * for the VS Code Loom Context Panel
 * 
 * Environment variables:
 * - RECAP_FILE_PATH: Complete path to the recap.json file (read/write)
 * - LOOM_METADATA_JSON: Stringified JSON of the loom metadata (parsed using LoomMetadata type)
 */
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'
import path from 'path'
import fs from 'fs-extra'
import { randomUUID } from 'crypto'
import type { RecapFile, RecapEntry, RecapOutput } from './recap-types.js'
import type { LoomMetadata } from '../lib/MetadataManager.js'

interface EnvConfig {
  recapFilePath: string
  loomMetadata: LoomMetadata
}

// Parse and validate required env vars
function validateEnvironment(): EnvConfig {
  const recapFilePath = process.env.RECAP_FILE_PATH
  const loomMetadataJson = process.env.LOOM_METADATA_JSON
  
  if (!recapFilePath) {
    console.error('Missing required environment variable: RECAP_FILE_PATH')
    process.exit(1)
  }
  if (!loomMetadataJson) {
    console.error('Missing required environment variable: LOOM_METADATA_JSON')
    process.exit(1)
  }
  
  // Parse the stringified JSON into LoomMetadata type
  // This allows the on-disk format to drift without MCP changes
  let loomMetadata: LoomMetadata
  try {
    loomMetadata = JSON.parse(loomMetadataJson) as LoomMetadata
  } catch (error) {
    console.error(`Failed to parse LOOM_METADATA_JSON: ${error}`)
    process.exit(1)
  }
  
  return { recapFilePath, loomMetadata }
}

// Read recap file (returns empty recap if not found)
async function readRecapFile(filePath: string): Promise<RecapFile> {
  try {
    if (await fs.pathExists(filePath)) {
      const content = await fs.readFile(filePath, 'utf8')
      return JSON.parse(content) as RecapFile
    }
  } catch (error) {
    console.error(`Warning: Could not read recap file: ${error}`)
  }
  return { goal: null, entries: [] }
}

// Write recap file (ensures parent directory exists)
async function writeRecapFile(filePath: string, recap: RecapFile): Promise<void> {
  await fs.ensureDir(path.dirname(filePath), { mode: 0o755 })
  await fs.writeFile(filePath, JSON.stringify(recap, null, 2), { mode: 0o644 })
}

// Store parsed config globally for tool handlers
let envConfig: EnvConfig

// Initialize MCP server
const server = new McpServer({
  name: 'loom-recap',
  version: '0.1.0',
})

// Register set_goal tool
server.registerTool(
  'set_goal',
  {
    title: 'Set Goal',
    description: 'Set the initial goal (called once at session start)',
    inputSchema: {
      goal: z.string().describe('The original problem statement'),
    },
    outputSchema: {
      success: z.literal(true),
    },
  },
  async ({ goal }) => {
    const recap = await readRecapFile(envConfig.recapFilePath)
    recap.goal = goal
    await writeRecapFile(envConfig.recapFilePath, recap)
    return { content: [{ type: 'text', text: JSON.stringify({ success: true }) }], structuredContent: { success: true } }
  }
)

// Register add_entry tool
server.registerTool(
  'add_entry',
  {
    title: 'Add Entry',
    description: 'Append an entry to the recap',
    inputSchema: {
      type: z.enum(['decision', 'insight', 'risk', 'assumption', 'other']).describe('Entry type'),
      content: z.string().describe('Entry content'),
    },
    outputSchema: {
      id: z.string(),
      timestamp: z.string(),
    },
  },
  async ({ type, content }) => {
    const recap = await readRecapFile(envConfig.recapFilePath)
    const entry: RecapEntry = {
      id: randomUUID(),
      timestamp: new Date().toISOString(),
      type,
      content,
    }
    recap.entries.push(entry)
    await writeRecapFile(envConfig.recapFilePath, recap)
    const result = { id: entry.id, timestamp: entry.timestamp }
    return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result }
  }
)

// Register get_recap tool
server.registerTool(
  'get_recap',
  {
    title: 'Get Recap',
    description: 'Read current recap (for catching up or review)',
    inputSchema: {},
    outputSchema: {
      filePath: z.string(),
      goal: z.string().nullable(),
      entries: z.array(z.object({
        id: z.string(),
        timestamp: z.string(),
        type: z.enum(['decision', 'insight', 'risk', 'assumption', 'other']),
        content: z.string(),
      })),
    },
  },
  async () => {
    const recap = await readRecapFile(envConfig.recapFilePath)
    const result: RecapOutput = { filePath: envConfig.recapFilePath, goal: recap.goal, entries: recap.entries }
    return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result }
  }
)

// Main server startup
async function main(): Promise<void> {
  console.error('Starting Loom Recap MCP Server...')
  envConfig = validateEnvironment()
  console.error(`Recap file path: ${envConfig.recapFilePath}`)
  console.error(`Loom metadata: issue_numbers=${envConfig.loomMetadata.issue_numbers?.join(',') || 'none'}, branch=${envConfig.loomMetadata.branchName || 'unknown'}`)
  const transport = new StdioServerTransport()
  await server.connect(transport)
  console.error('Loom Recap MCP Server running on stdio transport')
}

main().catch((error) => {
  console.error('Fatal error starting MCP server:', error)
  process.exit(1)
})

/Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/recap.ts (NEW)

Purpose: Fast CLI command for VS Code extension to get recap with file path

Click to expand complete structure (70 lines)

/**
 * RecapCommand - Fast read-only command for VS Code extension
 * 
 * Reads ~/.config/iloom-ai/recaps/{current-loom}.json and outputs it
 * Skips config validation for fast startup
 * Includes filePath in output so extension can set up file watcher
 */
import path from 'path'
import os from 'os'
import fs from 'fs-extra'
import type { RecapFile, RecapOutput } from '../mcp/recap-types.js'

const RECAPS_DIR = path.join(os.homedir(), '.config', 'iloom-ai', 'recaps')

// Reuse MetadataManager.slugifyPath() algorithm
function slugifyPath(loomPath: string): string {
  let slug = loomPath.replace(/[/\\]+$/, '')
  slug = slug.replace(/[/\\]/g, '___')
  slug = slug.replace(/[^a-zA-Z0-9_-]/g, '-')
  return `${slug}.json`
}

export interface RecapCommandInput {
  json?: boolean
}

export class RecapCommand {
  /**
   * Execute the recap command
   * Returns RecapOutput in JSON mode, void otherwise
   */
  async execute(input: RecapCommandInput): Promise<RecapOutput | void> {
    // Derive recap file path from current working directory
    const loomPath = process.cwd()
    const filePath = path.join(RECAPS_DIR, slugifyPath(loomPath))
    
    // Read recap file (return empty if not found)
    let recap: RecapFile = { goal: null, entries: [] }
    try {
      if (await fs.pathExists(filePath)) {
        const content = await fs.readFile(filePath, 'utf8')
        recap = JSON.parse(content) as RecapFile
      }
    } catch (error) {
      // Graceful degradation - return empty recap on read error
      // This is intentional for fast startup
    }
    
    // Build output with filePath for file watching
    const result: RecapOutput = {
      filePath,
      goal: recap.goal,
      entries: recap.entries,
    }
    
    if (input.json) {
      return result
    }
    
    // Non-JSON mode: print human-readable format
    console.log(`Recap file: ${filePath}`)
    console.log(`Goal: ${recap.goal ?? '(not set)'}`)
    console.log(`Entries: ${recap.entries.length}`)
    for (const entry of recap.entries) {
      console.log(`  [${entry.type}] ${entry.content}`)
    }
  }
}

Detailed Execution Order

Phase 1: Create Types

1. Create /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/recap-types.ts -> Verify: TypeScript compiles without errors

Phase 2: Implement MCP Server

1. Create /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/recap-server.ts -> Verify: File compiles, uses both RECAP_FILE_PATH and LOOM_METADATA_JSON env vars, imports LoomMetadata type
2. Create /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/mcp/recap-server.test.ts -> Verify: Tests pass

Phase 3: Create CLI Command

1. Create /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/recap.ts -> Verify: File compiles
2. Create /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/recap.test.ts -> Verify: Tests pass

Phase 4: Update Build Config

1. Modify /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/tsup.config.ts:41 -> Verify: pnpm build succeeds, dist/mcp/recap-server.js exists

Phase 5: Add MCP Config Generator

1. Modify /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/utils/mcp.ts:89 -> Verify: generateRecapMcpConfig() exported, accepts loomPath and loomMetadata (LoomMetadata type) params, stringifies metadata to JSON

Phase 6: Integrate into Ignite

1. Modify /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/commands/ignite.ts:159-225 -> Verify: il spin includes recap MCP in config with both RECAP_FILE_PATH and LOOM_METADATA_JSON

Phase 7: Register CLI Command

1. Modify /Users/adam/Documents/Projects/iloom-cli/feat-issue-346__loom-recap-mcp/src/cli.ts:1127 -> Verify: il recap --json works

Phase 8: Final Verification

1. Run pnpm build -> Verify: Build succeeds
2. Run pnpm test -> Verify: All tests pass
3. Manual test: il recap --json -> Verify: Output includes filePath, goal, entries

Dependencies and Configuration

• None - uses existing dependencies (@modelcontextprotocol/sdk, zod, fs-extra, crypto)

[acreeger]

Implementation Phase

Implementing Loom Recap MCP Server with 3 tools (set_goal, add_entry, get_recap), CLI command, and integration.

• Create src/mcp/recap-types.ts - TypeScript types for recap schema
• Create src/mcp/recap-server.ts - MCP server with 3 tools
• Create src/commands/recap.ts - Fast CLI command for VS Code extension
• Update tsup.config.ts - Add recap-server build entry
• Update src/utils/mcp.ts - Add generateRecapMcpConfig() function
• Update src/commands/ignite.ts - Inject recap MCP alongside issue_management
• Update src/cli.ts - Register recap command
• Create tests for new functionality
• Build and validate

ETA: ~8 minutes

[acreeger]

iloom Session Summary

Key Themes:

• MCP server receives stringified metadata JSON instead of file path to decouple from on-disk format changes
• Loom description used as default goal for new recap files, avoiding empty state issues
• Combined identical MCP build configurations in tsup.config for cleaner architecture
• Optional fields in RecapFile schema allow {} return for missing files instead of providing defaults

---

Session Details (click to expand)

Key Insights

• Passing stringified LOOM_METADATA_JSON instead of file path decouples the MCP server from on-disk format evolution - the MCP imports the LoomMetadata type and deserializes, so format changes don't require MCP updates
• Using goal?: string | null and entries?: RecapEntry[] in RecapFile allows readRecapFile to return {} for missing files, with consumers providing defaults - cleaner separation of concerns
• The loom metadata already contains the issue/PR description, which makes a perfect default goal for new recap files - eliminates cold-start UX issues
• TSup allows multiple entry points in a single build config when they share identical settings - reduced config duplication

Decisions Made

• RECAP_FILE_PATH env var: Pass complete path to recap.json directly so MCP doesn't need path encoding logic
• LOOM_METADATA_JSON env var: Pass stringified metadata JSON for type-safe deserialization vs. file path that couples to storage format
• Default goal from metadata: Use getLoomMetadata().description as fallback when recap.goal is undefined - provides context-aware defaults
• Optional RecapFile fields: Made goal and entries optional so missing files return {} instead of hardcoded defaults
• Combined MCP builds: Merged issue-management-server and recap-server into single tsup entry since configurations were identical

Challenges Resolved

• Test failures with MetadataManager mock: Initial mock implementation wasn't matching the pattern from other tests - resolved by using vi.fn(() => ({ ... })) syntax instead of vi.fn().mockImplementation
• TypeScript compilation error: readMetadata returns nullable type but generateRecapMcpConfig expected non-null - added null check with clear error message
• Unused variable warning: validatedLoomMetadata was stored but never accessed - exported getLoomMetadata() getter for consistency with getRecapFilePath()

Lessons Learned

• When mocking in Vitest, check existing test files for the established pattern - saves debugging time on mock implementation details
• Making fields optional in storage schemas provides flexibility - consumers can decide appropriate defaults based on context
• Leveraging existing metadata (like loom description) for smart defaults improves UX without adding complexity
• Environment variables that pass data structures as JSON enable type-safe deserialization while decoupling from file formats

---

Generated with 🤖❤️ by iloom.ai

[acreeger]

Schema update: goal is nullable

The goal field should be nullable - only set for branch mode looms.

For issue/PR looms, the title is already displayed in the panel header, so goal is redundant.

For branch mode (no issue), Claude sets the goal from the user's problem statement.

{
  "filePath": "...",
  "goal": null,  // or "User's problem statement" for branch mode
  "entries": [...]
}

The set_goal MCP tool becomes optional - only called in branch mode prompts.