list_sessions

Instructions

Implementation Reference

• src/tools/handlers.ts:182-239 (handler)

  The core handler function that implements list_sessions tool logic by fetching session stats and details from SessionManager and returning formatted results.

  async handleListSessions(): Promise<
    ToolResult<{
      active_sessions: number;
      max_sessions: number;
      session_timeout: number;
      oldest_session_seconds: number;
      total_messages: number;
      sessions: Array<{
        id: string;
        created_at: number;
        last_activity: number;
        age_seconds: number;
        inactive_seconds: number;
        message_count: number;
        notebook_url: string;
      }>;
    }> 
  > {
    log.info(`🔧 [TOOL] list_sessions called`);
  
    try {
      const stats = this.sessionManager.getStats();
      const sessions = this.sessionManager.getAllSessionsInfo();
  
      const result = {
        active_sessions: stats.active_sessions,
        max_sessions: stats.max_sessions,
        session_timeout: stats.session_timeout,
        oldest_session_seconds: stats.oldest_session_seconds,
        total_messages: stats.total_messages,
        sessions: sessions.map((info) => ({
          id: info.id,
          created_at: info.created_at,
          last_activity: info.last_activity,
          age_seconds: info.age_seconds,
          inactive_seconds: info.inactive_seconds,
          message_count: info.message_count,
          notebook_url: info.notebook_url,
        })),
      };
  
      log.success(
        `✅ [TOOL] list_sessions completed (${result.active_sessions} sessions)`
      );
      return {
        success: true,
        data: result,
      };
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      log.error(`❌ [TOOL] list_sessions failed: ${errorMessage}`);
      return {
        success: false,
        error: errorMessage,
      };
    }
  }

• src/tools/definitions/session-management.ts:4-13 (schema)

  Tool schema defining the list_sessions tool with description and empty input schema (no parameters required).

  {
    name: "list_sessions",
    description:
      "List all active sessions with stats (age, message count, last activity). " +
      "Use to continue the most relevant session instead of starting from scratch.",
    inputSchema: {
      type: "object",
      properties: {},
    },
  },

• src/tools/definitions.ts:27-32 (registration)

  Registration of sessionManagementTools (containing list_sessions schema) into the complete list of tool definitions via buildToolDefinitions.

  return [
    dynamicAskQuestionTool,
    ...notebookManagementTools,
    ...sessionManagementTools,
    ...systemTools,
  ];

• src/index.ts:232-234 (registration)

  Dispatch registration in the MCP server CallToolRequestSchema handler that routes list_sessions calls to the handler method.

  case "list_sessions":
    result = await this.toolHandlers.handleListSessions();
    break;