Add session documentation system (migration + MCP tools)

Phase 1-2 complete: Database schema + 9 MCP tools for session docs Database Changes (migration 016): - session_notes table (accomplishments, decisions, gotchas, etc.) - session_plans table (plan mode plans with lifecycle tracking) - project_documentation table (persistent project docs) - sessions.documentation column (auto-generated markdown) - HNSW indexes for semantic search across all doc types MCP Tools Added (session-docs.ts): 1. session_note_add - Add structured notes to session 2. session_notes_list - List notes by type 3. session_plan_save - Save plan with embedding 4. session_plan_update_status - Track plan lifecycle 5. session_plan_list - List session plans 6. project_doc_upsert - Create/update project docs 7. project_doc_get - Get specific doc by type 8. project_doc_list - List all project docs 9. session_documentation_generate - Auto-generate markdown Replaces: CLAUDE.md files, ~/.claude/plans/ directory Next: Update session-start/end scripts for temp file management Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-19 10:13:57 +02:00
parent afce0bd3e5
commit 3745a13eaf
5 changed files with 926 additions and 0 deletions
--- a/src/index.ts
+++ b/src/index.ts
@@ -49,6 +49,17 @@ import {
  buildRecord,
  sessionCommitLink,
 } from './tools/sessions.js';
+import {
+  sessionNoteAdd,
+  sessionNotesList,
+  sessionPlanSave,
+  sessionPlanUpdateStatus,
+  sessionPlanList,
+  projectDocUpsert,
+  projectDocGet,
+  projectDocList,
+  sessionDocumentationGenerate,
+} from './tools/session-docs.js';

 // Create MCP server
 const server = new Server(
@@ -476,6 +487,82 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
        );
        break;

+      // Session Documentation
+      case 'session_note_add':
+        result = await sessionNoteAdd({
+          session_id: a.session_id,
+          note_type: a.note_type,
+          content: a.content,
+        });
+        break;
+      case 'session_notes_list':
+        result = JSON.stringify(
+          await sessionNotesList({
+            session_id: a.session_id,
+            note_type: a.note_type,
+          }),
+          null,
+          2
+        );
+        break;
+      case 'session_plan_save':
+        result = await sessionPlanSave({
+          session_id: a.session_id,
+          plan_content: a.plan_content,
+          plan_file_name: a.plan_file_name,
+          status: a.status,
+        });
+        break;
+      case 'session_plan_update_status':
+        result = await sessionPlanUpdateStatus({
+          plan_id: a.plan_id,
+          status: a.status,
+        });
+        break;
+      case 'session_plan_list':
+        result = JSON.stringify(
+          await sessionPlanList({
+            session_id: a.session_id,
+            status: a.status,
+          }),
+          null,
+          2
+        );
+        break;
+      case 'project_doc_upsert':
+        result = await projectDocUpsert({
+          project: a.project,
+          doc_type: a.doc_type,
+          title: a.title,
+          content: a.content,
+          session_id: a.session_id,
+        });
+        break;
+      case 'project_doc_get':
+        result = JSON.stringify(
+          await projectDocGet({
+            project: a.project,
+            doc_type: a.doc_type,
+          }),
+          null,
+          2
+        );
+        break;
+      case 'project_doc_list':
+        result = JSON.stringify(
+          await projectDocList({
+            project: a.project,
+          }),
+          null,
+          2
+        );
+        break;
+      case 'session_documentation_generate':
+        result = await sessionDocumentationGenerate({
+          session_id: a.session_id,
+        });
+        break;
+
      default:
        throw new Error(`Unknown tool: ${name}`);
    }
--- a/src/tools/index.ts
+++ b/src/tools/index.ts
@@ -825,4 +825,118 @@ export const toolDefinitions = [
      required: ['session_id', 'commit_sha', 'repo'],
    },
  },
+
+  // Session Documentation Tools
+  {
+    name: 'session_note_add',
+    description: 'Add a note to current session with auto-generated embedding',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session ID' },
+        note_type: { type: 'string', enum: ['accomplishment', 'decision', 'gotcha', 'next_steps', 'context'], description: 'Category of note' },
+        content: { type: 'string', description: 'Note content' },
+      },
+      required: ['session_id', 'note_type', 'content'],
+    },
+  },
+  {
+    name: 'session_notes_list',
+    description: 'List all notes for a session, optionally filtered by type',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session ID' },
+        note_type: { type: 'string', enum: ['accomplishment', 'decision', 'gotcha', 'next_steps', 'context'], description: 'Filter by note type (optional)' },
+      },
+      required: ['session_id'],
+    },
+  },
+  {
+    name: 'session_plan_save',
+    description: 'Save a plan to database with semantic embedding',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session ID' },
+        plan_content: { type: 'string', description: 'Plan content in markdown' },
+        plan_file_name: { type: 'string', description: 'Original filename (e.g., eloquent-yellow-cat.md) - optional' },
+        status: { type: 'string', enum: ['draft', 'approved', 'executed', 'abandoned'], description: 'Plan status (default: draft)' },
+      },
+      required: ['session_id', 'plan_content'],
+    },
+  },
+  {
+    name: 'session_plan_update_status',
+    description: 'Update plan status (draft → approved → executed)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        plan_id: { type: 'number', description: 'Plan ID to update' },
+        status: { type: 'string', enum: ['draft', 'approved', 'executed', 'abandoned'], description: 'New status' },
+      },
+      required: ['plan_id', 'status'],
+    },
+  },
+  {
+    name: 'session_plan_list',
+    description: 'List plans for a session',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session ID' },
+        status: { type: 'string', enum: ['draft', 'approved', 'executed', 'abandoned'], description: 'Filter by status (optional)' },
+      },
+      required: ['session_id'],
+    },
+  },
+  {
+    name: 'project_doc_upsert',
+    description: 'Create or update project documentation (replaces CLAUDE.md sections)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project key (e.g., CF, VPN)' },
+        doc_type: { type: 'string', enum: ['overview', 'architecture', 'guidelines', 'history'], description: 'Documentation type' },
+        title: { type: 'string', description: 'Document title' },
+        content: { type: 'string', description: 'Document content in markdown' },
+        session_id: { type: 'string', description: 'Session ID (optional)' },
+      },
+      required: ['project', 'doc_type', 'title', 'content'],
+    },
+  },
+  {
+    name: 'project_doc_get',
+    description: 'Get specific project documentation by type',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project key' },
+        doc_type: { type: 'string', enum: ['overview', 'architecture', 'guidelines', 'history'], description: 'Documentation type' },
+      },
+      required: ['project', 'doc_type'],
+    },
+  },
+  {
+    name: 'project_doc_list',
+    description: 'List all documentation for a project',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project key' },
+      },
+      required: ['project'],
+    },
+  },
+  {
+    name: 'session_documentation_generate',
+    description: 'Auto-generate full markdown documentation for a session (tasks, commits, notes, plans)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session ID' },
+      },
+      required: ['session_id'],
+    },
+  },
 ];
--- a/src/tools/session-docs.ts
+++ b/src/tools/session-docs.ts
@@ -0,0 +1,424 @@
+// Session documentation operations - notes, plans, and project documentation
+// Replaces file-based CLAUDE.md and plan files with database storage
+
+import { query, queryOne, execute } from '../db.js';
+import { getEmbedding, formatEmbedding } from '../embeddings.js';
+
+// ============================================================================
+// SESSION NOTES
+// ============================================================================
+
+interface SessionNoteAddArgs {
+  session_id: string;
+  note_type: 'accomplishment' | 'decision' | 'gotcha' | 'next_steps' | 'context';
+  content: string;
+}
+
+interface SessionNotesListArgs {
+  session_id: string;
+  note_type?: 'accomplishment' | 'decision' | 'gotcha' | 'next_steps' | 'context';
+}
+
+interface SessionNote {
+  id: number;
+  session_id: string;
+  note_type: string;
+  content: string;
+  created_at: string;
+}
+
+/**
+ * Add a note to current session
+ * Auto-generates embedding for semantic search
+ */
+export async function sessionNoteAdd(args: SessionNoteAddArgs): Promise<string> {
+  const { session_id, note_type, content } = args;
+
+  // Generate embedding for semantic search
+  const embedding = await getEmbedding(content);
+  const embeddingFormatted = embedding ? formatEmbedding(embedding) : null;
+
+  await execute(
+    `INSERT INTO session_notes (session_id, note_type, content, embedding)
+     VALUES ($1, $2, $3, $4)`,
+    [session_id, note_type, content, embeddingFormatted]
+  );
+
+  return `Note added to session ${session_id} (type: ${note_type})`;
+}
+
+/**
+ * List all notes for a session, optionally filtered by type
+ */
+export async function sessionNotesList(args: SessionNotesListArgs): Promise<SessionNote[]> {
+  const { session_id, note_type } = args;
+
+  let sql = `
+    SELECT id, session_id, note_type, content, created_at
+    FROM session_notes
+    WHERE session_id = $1
+  `;
+
+  const params: unknown[] = [session_id];
+
+  if (note_type) {
+    sql += ` AND note_type = $2`;
+    params.push(note_type);
+  }
+
+  sql += ` ORDER BY created_at ASC`;
+
+  const notes = await query<SessionNote>(sql, params);
+  return notes;
+}
+
+// ============================================================================
+// SESSION PLANS
+// ============================================================================
+
+interface SessionPlanSaveArgs {
+  session_id: string;
+  plan_content: string;
+  plan_file_name?: string;
+  status?: 'draft' | 'approved' | 'executed' | 'abandoned';
+}
+
+interface SessionPlanUpdateStatusArgs {
+  plan_id: number;
+  status: 'draft' | 'approved' | 'executed' | 'abandoned';
+}
+
+interface SessionPlanListArgs {
+  session_id: string;
+  status?: 'draft' | 'approved' | 'executed' | 'abandoned';
+}
+
+interface SessionPlan {
+  id: number;
+  session_id: string;
+  plan_file_name: string | null;
+  plan_content: string;
+  status: string;
+  created_at: string;
+  approved_at: string | null;
+  completed_at: string | null;
+}
+
+/**
+ * Save a plan to database
+ * Extracts embedding from plan content for semantic search
+ */
+export async function sessionPlanSave(args: SessionPlanSaveArgs): Promise<string> {
+  const { session_id, plan_content, plan_file_name, status = 'draft' } = args;
+
+  // Generate embedding for semantic search
+  const embedding = await getEmbedding(plan_content);
+  const embeddingFormatted = embedding ? formatEmbedding(embedding) : null;
+
+  const result = await queryOne<{ id: number }>(
+    `INSERT INTO session_plans (session_id, plan_file_name, plan_content, status, embedding)
+     VALUES ($1, $2, $3, $4, $5)
+     RETURNING id`,
+    [session_id, plan_file_name || null, plan_content, status, embeddingFormatted]
+  );
+
+  const planId = result?.id || 0;
+
+  return `Plan saved to session ${session_id} (plan_id: ${planId}, status: ${status})`;
+}
+
+/**
+ * Update plan status (draft → approved → executed)
+ */
+export async function sessionPlanUpdateStatus(args: SessionPlanUpdateStatusArgs): Promise<string> {
+  const { plan_id, status } = args;
+
+  // Set timestamps based on status
+  let sql = 'UPDATE session_plans SET status = $1';
+  const params: unknown[] = [status, plan_id];
+
+  if (status === 'approved') {
+    sql += ', approved_at = NOW()';
+  } else if (status === 'executed' || status === 'abandoned') {
+    sql += ', completed_at = NOW()';
+  }
+
+  sql += ' WHERE id = $2';
+
+  await execute(sql, params);
+
+  return `Plan ${plan_id} status updated to: ${status}`;
+}
+
+/**
+ * List plans for a session
+ */
+export async function sessionPlanList(args: SessionPlanListArgs): Promise<SessionPlan[]> {
+  const { session_id, status } = args;
+
+  let sql = `
+    SELECT id, session_id, plan_file_name, plan_content, status,
+           created_at, approved_at, completed_at
+    FROM session_plans
+    WHERE session_id = $1
+  `;
+
+  const params: unknown[] = [session_id];
+
+  if (status) {
+    sql += ` AND status = $2`;
+    params.push(status);
+  }
+
+  sql += ` ORDER BY created_at DESC`;
+
+  const plans = await query<SessionPlan>(sql, params);
+  return plans;
+}
+
+// ============================================================================
+// PROJECT DOCUMENTATION
+// ============================================================================
+
+interface ProjectDocUpsertArgs {
+  project: string;
+  doc_type: 'overview' | 'architecture' | 'guidelines' | 'history';
+  title: string;
+  content: string;
+  session_id?: string;
+}
+
+interface ProjectDocGetArgs {
+  project: string;
+  doc_type: 'overview' | 'architecture' | 'guidelines' | 'history';
+}
+
+interface ProjectDocListArgs {
+  project: string;
+}
+
+interface ProjectDoc {
+  id: number;
+  project: string;
+  doc_type: string;
+  title: string;
+  content: string;
+  last_updated_session: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/**
+ * Create or update project documentation
+ * Links to current session
+ */
+export async function projectDocUpsert(args: ProjectDocUpsertArgs): Promise<string> {
+  const { project, doc_type, title, content, session_id } = args;
+
+  await execute(
+    `INSERT INTO project_documentation (project, doc_type, title, content, last_updated_session, updated_at)
+     VALUES ($1, $2, $3, $4, $5, NOW())
+     ON CONFLICT (project, doc_type)
+     DO UPDATE SET
+       title = EXCLUDED.title,
+       content = EXCLUDED.content,
+       last_updated_session = EXCLUDED.last_updated_session,
+       updated_at = NOW()`,
+    [project, doc_type, title, content, session_id || null]
+  );
+
+  return `Project documentation updated: ${project} (${doc_type})`;
+}
+
+/**
+ * Get specific project documentation by type
+ */
+export async function projectDocGet(args: ProjectDocGetArgs): Promise<ProjectDoc | null> {
+  const { project, doc_type } = args;
+
+  const doc = await queryOne<ProjectDoc>(
+    `SELECT id, project, doc_type, title, content, last_updated_session, created_at, updated_at
+     FROM project_documentation
+     WHERE project = $1 AND doc_type = $2`,
+    [project, doc_type]
+  );
+
+  return doc;
+}
+
+/**
+ * List all documentation for a project
+ */
+export async function projectDocList(args: ProjectDocListArgs): Promise<ProjectDoc[]> {
+  const { project } = args;
+
+  const docs = await query<ProjectDoc>(
+    `SELECT id, project, doc_type, title, content, last_updated_session, created_at, updated_at
+     FROM project_documentation
+     WHERE project = $1
+     ORDER BY doc_type`,
+    [project]
+  );
+
+  return docs;
+}
+
+// ============================================================================
+// SESSION DOCUMENTATION GENERATION
+// ============================================================================
+
+interface SessionDocumentationGenerateArgs {
+  session_id: string;
+}
+
+/**
+ * Auto-generate full markdown documentation for a session
+ * Aggregates: tasks, commits, notes, decisions, plans
+ * Stores in sessions.documentation field
+ */
+export async function sessionDocumentationGenerate(args: SessionDocumentationGenerateArgs): Promise<string> {
+  const { session_id } = args;
+
+  // Fetch session details
+  const session = await queryOne<{
+    id: string;
+    project: string;
+    session_number: number;
+    started_at: string;
+    ended_at: string;
+    duration_minutes: number;
+    summary: string;
+    git_branch: string;
+  }>(
+    `SELECT id, project, session_number, started_at, ended_at, duration_minutes, summary, git_branch
+     FROM sessions
+     WHERE id = $1`,
+    [session_id]
+  );
+
+  if (!session) {
+    throw new Error(`Session not found: ${session_id}`);
+  }
+
+  // Fetch tasks worked on
+  const tasks = await query<{ task_id: string; title: string; status: string }>(
+    `SELECT DISTINCT t.id as task_id, t.title, t.status
+     FROM task_activity ta
+     JOIN tasks t ON ta.task_id = t.id
+     WHERE ta.session_id = $1
+     ORDER BY t.id`,
+    [session_id]
+  );
+
+  // Fetch commits made
+  const commits = await query<{ commit_sha: string; commit_message: string }>(
+    `SELECT commit_sha, commit_message
+     FROM session_commits
+     WHERE session_id = $1
+     ORDER BY committed_at`,
+    [session_id]
+  );
+
+  // Fetch notes
+  const notes = await query<{ note_type: string; content: string }>(
+    `SELECT note_type, content
+     FROM session_notes
+     WHERE session_id = $1
+     ORDER BY created_at`,
+    [session_id]
+  );
+
+  // Fetch plans
+  const plans = await query<{ plan_content: string; status: string }>(
+    `SELECT plan_content, status
+     FROM session_plans
+     WHERE session_id = $1
+     ORDER BY created_at DESC
+     LIMIT 1`,
+    [session_id]
+  );
+
+  // Build markdown documentation
+  let doc = `# Session ${session.session_number} - ${session.project}\n\n`;
+  doc += `**Date:** ${new Date(session.started_at).toLocaleDateString()}\n`;
+  doc += `**Duration:** ${session.duration_minutes || 0} minutes\n`;
+  doc += `**Status:** ${session.summary ? '✅ Complete' : '⚠️ In Progress'}\n`;
+  if (session.git_branch) {
+    doc += `**Branch:** ${session.git_branch}\n`;
+  }
+  doc += `\n---\n\n`;
+
+  // Summary
+  if (session.summary) {
+    doc += `## Summary\n\n${session.summary}\n\n`;
+  }
+
+  // Tasks
+  if (tasks.length > 0) {
+    doc += `## Tasks Completed\n\n`;
+    tasks.forEach(task => {
+      doc += `- **${task.task_id}**: ${task.title} (${task.status})\n`;
+    });
+    doc += `\n`;
+  }
+
+  // Commits
+  if (commits.length > 0) {
+    doc += `## Commits\n\n`;
+    commits.forEach(commit => {
+      const shortSha = commit.commit_sha.substring(0, 7);
+      doc += `- \`${shortSha}\` - ${commit.commit_message || 'No message'}\n`;
+    });
+    doc += `\n`;
+  }
+
+  // Notes by type
+  const notesByType: Record<string, string[]> = {};
+  notes.forEach(note => {
+    if (!notesByType[note.note_type]) {
+      notesByType[note.note_type] = [];
+    }
+    notesByType[note.note_type].push(note.content);
+  });
+
+  if (notesByType.accomplishment && notesByType.accomplishment.length > 0) {
+    doc += `## Accomplishments\n\n`;
+    notesByType.accomplishment.forEach(content => {
+      doc += `${content}\n\n`;
+    });
+  }
+
+  if (notesByType.decision && notesByType.decision.length > 0) {
+    doc += `## Key Decisions\n\n`;
+    notesByType.decision.forEach(content => {
+      doc += `${content}\n\n`;
+    });
+  }
+
+  if (notesByType.gotcha && notesByType.gotcha.length > 0) {
+    doc += `## Gotchas & Learnings\n\n`;
+    notesByType.gotcha.forEach(content => {
+      doc += `${content}\n\n`;
+    });
+  }
+
+  if (notesByType.next_steps && notesByType.next_steps.length > 0) {
+    doc += `## Next Steps\n\n`;
+    notesByType.next_steps.forEach(content => {
+      doc += `${content}\n\n`;
+    });
+  }
+
+  // Plan (if exists)
+  if (plans.length > 0 && plans[0].status === 'executed') {
+    doc += `## Plan\n\n${plans[0].plan_content}\n\n`;
+  }
+
+  // Store documentation in sessions table
+  await execute(
+    `UPDATE sessions SET documentation = $1 WHERE id = $2`,
+    [doc, session_id]
+  );
+
+  return `Documentation generated for session ${session_id} (${doc.length} characters)`;
+}