get_session_summary

Instructions

Implementation Reference

• server/src/mcp/tools.js:368-426 (handler)

  The handler function for the get_session_summary tool. It resolves the project, finds the session by UUID, retrieves metadata and parses the session, then returns a JSON summary with title, message counts, dates, tags, favorites, and token stats.

  // ─── get_session_summary ─────────────────────────────────────────
  server.tool(
    'get_session_summary',
    'Get a quick summary of a session — title, message count, dates, tags, favorites, and token stats. Defaults to the current project. Cheaper than get_session when you only need metadata, not full messages.',
    {
      sessionId: z.string().describe('The session UUID'),
      projectId: z.string().optional().describe('Project ID (defaults to current project)'),
    },
    async ({ sessionId, projectId }) => {
      try {
        const { fileScanner, sessionParser, metadataService, currentProjectId } = await getServices()
        const { project, projectId: resolvedId } = await resolveProject(fileScanner, projectId, currentProjectId)
  
        const sessions = await fileScanner.scanSessions(project.path)
        const session = sessions.find(s => s.sessionId === sessionId)
  
        if (!session) {
          return {
            content: [{ type: 'text', text: `Session not found: ${sessionId} in project "${project.name}"` }],
            isError: true,
          }
        }
  
        const meta = await metadataService.getMetadata(resolvedId, sessionId)
        const parsed = await sessionParser.parseSession(session.filePath)
  
        const userMessages = parsed.messages.filter(m => m.role === 'user').length
        const assistantMessages = parsed.messages.filter(m => m.role === 'assistant').length
  
        const summary = {
          sessionId,
          projectId: resolvedId,
          projectName: project.name,
          title: meta?.customTitle || session.title || sessionId,
          messageCount: parsed.messages.length,
          userMessages,
          assistantMessages,
          template: parsed.template,
          createdAt: session.createdAt,
          lastUpdated: session.lastUpdatedAt,
          isFavorited: meta?.isFavorited || false,
          isHidden: meta?.isHidden || false,
          tags: meta?.tags || [],
          notes: meta?.notes || null,
          tokens: parsed.stats?.tokens || null,
        }
  
        return {
          content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }],
        }
      } catch (error) {
        return {
          content: [{ type: 'text', text: `Error getting summary: ${error.message}` }],
          isError: true,
        }
      }
    }
  )

• server/src/mcp/tools.js:373-376 (schema)

  Input schema for get_session_summary: sessionId (required string) and projectId (optional string, defaults to current project).

  {
    sessionId: z.string().describe('The session UUID'),
    projectId: z.string().optional().describe('Project ID (defaults to current project)'),
  },

• server/src/mcp/index.js:106-108 (registration)

  Registration call: registerTools(server, getServices) which registers the get_session_summary tool on the MCP server.

  registerTools(server, getServices)
  registerResources(server, getServices)
  registerPrompts(server)

• server/src/mcp/tools.js:7-25 (helper)

  The resolveProject helper function used by get_session_summary to find the project by ID (with partial match fallback).

  async function resolveProject(fileScanner, projectId, currentProjectId) {
    const targetId = projectId || currentProjectId
    const projects = await fileScanner.scanProjects()
    const project = projects.find(p => p.id === targetId)
  
    if (!project) {
      // Try partial match (user might pass just the short name)
      const partial = projects.find(p =>
        p.name === targetId || p.id.endsWith(`-${targetId}`)
      )
      if (partial) return { project: partial, projectId: partial.id }
  
      const available = projects.slice(0, 10).map(p => `  ${p.id} (${p.name})`).join('\n')
      throw new Error(
        `Project not found: "${targetId}"\n\nAvailable projects:\n${available}${projects.length > 10 ? `\n  ... and ${projects.length - 10} more` : ''}`
      )
    }
  
    return { project, projectId: targetId }

• server/src/mcp/index.js:44-71 (helper)

  The getServices helper that lazy-initializes and provides all services (fileScanner, sessionParser, metadataService, currentProjectId) used by the handler.

  async function getServices() {
    if (services) return services
  
    const projectRoot = getProjectRoot()
  
    // Resolve DB path: same location as the web server uses
    const serverDir = path.resolve(__dirname, '../..')
    const dbPath = path.join(serverDir, 'data', 'search.db')
  
    const searchDb = new SearchDatabase(dbPath)
    await searchDb.init()
  
    // Allow concurrent reads with web server (WAL mode + busy timeout)
    await searchDb.db.run('PRAGMA busy_timeout = 5000')
  
    const metadataService = new SessionMetadataService(searchDb)
    await metadataService.init()
  
    const memoryService = new MemoryService(searchDb)
    await memoryService.init()
  
    const fileScanner = new FileScanner(projectRoot)
    const sessionParser = new SessionParser()
  
    services = { searchDb, metadataService, memoryService, fileScanner, sessionParser, currentProjectId }
    console.error(`[claudex-mcp] Services initialized (project: ${currentProjectId}, projects: ${projectRoot})`)
    return services
  }