claude-session-manager

Instructions

Implementation Reference

• src/claude_session_manager_mcp/server.py:544-558 (registration)

  Registration of the list_sessions tool with MCP Server, defining its name, description, and input schema requiring project_name.

  Tool(
      name="list_sessions",
      description="List all sessions in a project",
      inputSchema={
          "type": "object",
          "properties": {
              "project_name": {
                  "type": "string",
                  "description": "Project folder name (e.g., '-Users-young-works-myproject')"
              }
          },
          "required": ["project_name"]
      }
  ),
  Tool(

• src/claude_session_manager_mcp/server.py:694-696 (handler)

  Handler dispatch in the main call_tool function that handles the list_sessions tool call by extracting the project_name parameter and invoking the get_sessions function.

  elif name == "list_sessions":
      project_name = arguments.get("project_name", "")
      result = get_sessions(project_name)

• src/claude_session_manager_mcp/server.py:65-82 (handler)

  Primary handler function that lists sessions for the specified project by scanning .jsonl files (excluding agent-), parsing summaries, and sorting by updated_at.

  def get_sessions(project_name: str) -> list[dict]:
      """Get all sessions for a project."""
      base_path = get_base_path()
      project_path = base_path / project_name
      sessions = []
  
      if not project_path.exists():
          return sessions
  
      for jsonl_file in project_path.glob("*.jsonl"):
          if jsonl_file.name.startswith("agent-"):
              continue
  
          session_info = parse_session_summary(jsonl_file)
          if session_info:
              sessions.append(session_info)
  
      return sorted(sessions, key=lambda s: s.get("updated_at", ""), reverse=True)

• src/claude_session_manager_mcp/server.py:85-140 (helper)

  Supporting helper that parses a session's .jsonl file to extract metadata: session_id, title (derived from first user message), message_count, created_at, updated_at timestamps.

  def parse_session_summary(file_path: Path) -> dict | None:
      """Parse session file for summary info."""
      session_id = file_path.stem
      info = {
          "session_id": session_id,
          "title": f"Session {session_id[:8]}",
          "message_count": 0,
          "created_at": None,
          "updated_at": None,
      }
  
      try:
          with open(file_path, 'r', encoding='utf-8') as f:
              first_user_content = None
              for line in f:
                  line = line.strip()
                  if not line:
                      continue
                  try:
                      entry = json.loads(line)
                      entry_type = entry.get('type')
  
                      if entry_type in ('user', 'assistant'):
                          info["message_count"] += 1
                          timestamp = entry.get('timestamp', '')
                          if timestamp:
                              if not info["created_at"] or timestamp < info["created_at"]:
                                  info["created_at"] = timestamp
                              if not info["updated_at"] or timestamp > info["updated_at"]:
                                  info["updated_at"] = timestamp
  
                          if entry_type == 'user' and first_user_content is None:
                              message = entry.get('message', {})
                              content_list = message.get('content', [])
                              for item in content_list:
                                  if isinstance(item, dict) and item.get('type') == 'text':
                                      text = item.get('text', '').strip()
                                      text = re.sub(r'<ide_[^>]*>.*?</ide_[^>]*>', '', text, flags=re.DOTALL).strip()
                                      if text:
                                          first_user_content = text
                                          break
                  except json.JSONDecodeError:
                      continue
  
              if first_user_content:
                  if '\n\n' in first_user_content:
                      info["title"] = first_user_content.split('\n\n')[0][:100]
                  elif '\n' in first_user_content:
                      info["title"] = first_user_content.split('\n')[0][:100]
                  else:
                      info["title"] = first_user_content[:100]
  
      except Exception:
          return None
  
      return info if info["message_count"] > 0 else None