list_sessions

Instructions

Implementation Reference

• src/tools/sessions/list-sessions.ts:61-87 (handler)

  The main handler function that executes the 'list_sessions' tool logic. It takes args (projectId, filters), builds the API URL via endpoints.listSessions, makes an authenticated GET request, and returns the response as text content.

  export async function handleListSessions(args?: ListSessionsArgs) {
    const token = getApiKey(args);
    if (!token) {
      throw new Error(
        "Missing TESTDINO_PAT environment variable. Configure it in your .cursor/mcp.json under 'env'."
      );
    }
    if (!args?.projectId) throw new Error("projectId is required");
  
    try {
      const { releaseId, assigneeUserId, ...rest } = args;
      const url = endpoints.listSessions({
        ...rest,
        ...(releaseId ? { milestone: releaseId } : {}),
        ...(assigneeUserId ? { assignee: assigneeUserId } : {}),
      });
      const response = await apiRequestJson<unknown>(url, {
        headers: { Authorization: `Bearer ${token}` },
      });
      return {
        content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
      };
    } catch (error) {
      const msg = error instanceof Error ? error.message : String(error);
      throw new Error(`Failed to list sessions: ${msg}`);
    }
  }

• src/tools/sessions/list-sessions.ts:25-59 (schema)

  Tool registration object including the name 'list_sessions', description, and inputSchema (JSON Schema) defining all parameters: projectId (required), search, status, state, sessionType, assigneeUserId, releaseId, tags, isClosed, sortBy, sortOrder, page, limit.

  export const listSessionsTool = {
    name: "list_sessions",
    description:
      "Browse exploratory sessions for a project. Filter by status (active|closed), state, sessionType, assigneeUserId, release (releaseId), tags, or free-text search on name. Pass releaseId='none' for sessions not attached to a release. Default page size 25 (max 200).",
    inputSchema: {
      type: "object",
      properties: {
        projectId: { type: "string", description: "Project ID (required)." },
        search: { type: "string", description: "Match by session name." },
        status: { type: "string", enum: ["active", "closed"] },
        state: {
          type: "string",
          description:
            "Workflow state. Either canonical ('under_review', 'done') or display ('Under review', 'Done') form — the server normalizes lowercase+underscored.",
        },
        sessionType: { type: "string" },
        assigneeUserId: {
          type: "string",
          description:
            "User _id OR email — both accepted (server resolves email to user _id).",
        },
        releaseId: {
          type: "string",
          description: "'none' for unlinked sessions.",
        },
        tags: { type: "string", description: "Single tag or comma-separated." },
        isClosed: { type: "boolean" },
        sortBy: { type: "string", enum: ["createdAt", "updatedAt", "name"] },
        sortOrder: { type: "string", enum: ["asc", "desc"] },
        page: { type: "number" },
        limit: { type: "number", description: "Default 25 (max 200)." },
      },
      required: ["projectId"],
    },
  };

• src/index.ts:327-332 (registration)

  Route in the main server's CallToolRequestSchema handler that matches the name 'list_sessions' and dispatches to the handleListSessions function.

  // Sessions
  if (name === "list_sessions") {
    return await handleListSessions(
      args as Parameters<typeof handleListSessions>[0]
    );
  }

• src/index.ts:125-130 (registration)

  Tool definition registration: listSessionsTool is included in the tools array passed to ListToolsRequestSchema, making it visible as an available MCP tool.

    // Sessions
    listSessionsTool,
    getSessionTool,
    createSessionTool,
    updateSessionTool,
  ];

• src/lib/endpoints.ts:469-492 (helper)

  Endpoint helper: constructs the URL for the list sessions API call (GET /api/mcp/sessions/:projectId) with query parameters.

  /**
   * List exploratory sessions
   * GET /api/mcp/sessions/:projectId
   */
  listSessions: (params: {
    projectId: string;
    search?: string;
    status?: string;
    state?: string;
    sessionType?: string;
    assignee?: string;
    milestone?: string;
    tags?: string;
    isClosed?: boolean;
    sortBy?: string;
    sortOrder?: string;
    page?: number;
    limit?: number;
  }): string => {
    const baseUrl = getBaseUrl();
    const { projectId, ...queryParams } = params;
    const queryString = buildQueryString(queryParams);
    return `${baseUrl}/api/mcp/sessions/${projectId}${queryString}`;
  },