claude-sessions-mcp

Instructions

Implementation Reference

• src/mcp/index.ts:138-151 (registration)

  Registers the 'get_session_files' MCP tool, including input schema (project_name, session_id) and thin handler that delegates to session.getSessionFiles

  server.tool(
    'get_session_files',
    'Get list of all files changed in a session (from file-history-snapshot and tool_use)',
    {
      project_name: z.string().describe('Project folder name'),
      session_id: z.string().describe('Session ID'),
    },
    async ({ project_name, session_id }) => {
      const result = await Effect.runPromise(session.getSessionFiles(project_name, session_id))
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
      }
    }
  )

• src/lib/session.ts:260-325 (handler)

  Core implementation of getSessionFiles: parses session messages, extracts unique file changes from 'file-history-snapshot' and 'tool_use' (Write/Edit) blocks

  export const getSessionFiles = (projectName: string, sessionId: string) =>
    Effect.gen(function* () {
      const messages = yield* readSession(projectName, sessionId)
      const fileChanges: FileChange[] = []
      const seenFiles = new Set<string>()
  
      for (const msg of messages) {
        // Check for file-history-snapshot type
        if (msg.type === 'file-history-snapshot') {
          const snapshot = msg as unknown as {
            type: string
            messageId?: string
            snapshot?: {
              trackedFileBackups?: Record<string, unknown>
              timestamp?: string
            }
          }
  
          const backups = snapshot.snapshot?.trackedFileBackups
          if (backups && typeof backups === 'object') {
            for (const filePath of Object.keys(backups)) {
              if (!seenFiles.has(filePath)) {
                seenFiles.add(filePath)
                fileChanges.push({
                  path: filePath,
                  action: 'modified',
                  timestamp: snapshot.snapshot?.timestamp,
                  messageUuid: snapshot.messageId ?? msg.uuid,
                })
              }
            }
          }
        }
  
        // Also check tool_use for Write/Edit operations
        if (msg.type === 'assistant' && msg.message) {
          const assistantMsg = msg.message as {
            content?: Array<{ type: string; name?: string; input?: { file_path?: string } }>
          }
          const content = assistantMsg.content
          if (Array.isArray(content)) {
            for (const block of content) {
              if (block.type === 'tool_use' && (block.name === 'Write' || block.name === 'Edit')) {
                const filePath = block.input?.file_path
                if (filePath && !seenFiles.has(filePath)) {
                  seenFiles.add(filePath)
                  fileChanges.push({
                    path: filePath,
                    action: block.name === 'Write' ? 'created' : 'modified',
                    timestamp: msg.timestamp,
                    messageUuid: msg.uuid,
                  })
                }
              }
            }
          }
        }
      }
  
      return {
        sessionId,
        projectName,
        files: fileChanges,
        totalChanges: fileChanges.length,
      } satisfies SessionFilesSummary
    })

• src/lib/session.ts:252-257 (schema)

  TypeScript interface defining the output structure of getSessionFiles

  export interface SessionFilesSummary {
    sessionId: string
    projectName: string
    files: FileChange[]
    totalChanges: number
  }

• src/lib/session.ts:104-110 (helper)

  Helper function readSession loads and parses session messages from .jsonl file, used by getSessionFiles

  export const readSession = (projectName: string, sessionId: string) =>
    Effect.gen(function* () {
      const filePath = path.join(getSessionsDir(), projectName, `${sessionId}.jsonl`)
      const content = yield* Effect.tryPromise(() => fs.readFile(filePath, 'utf-8'))
      const lines = content.trim().split('\n').filter(Boolean)
      return lines.map((line) => JSON.parse(line) as Message)
    })

• src/mcp/index.ts:142-144 (schema)

  Zod input schema for the MCP tool parameters

    project_name: z.string().describe('Project folder name'),
    session_id: z.string().describe('Session ID'),
  },