list-projects

Instructions

Implementation Reference

• src/tools/projects/list_projects.ts:9-19 (handler)

  The core handler that executes the list-projects tool logic. If projectId is provided, fetches a single project by ID; otherwise fetches all projects.

  export async function listProjects(args: ListProjectsArgs): Promise<QTestProject | QTestProject[]> {
    const { projectId } = args
  
    if (projectId !== undefined) {
      const raw = await qtestFetchGlobal(config, `/projects/${projectId}`, 'GET')
      return raw as QTestProject
    }
  
    const raw = await qtestFetchGlobal(config, '/projects', 'GET')
    return extractArray<QTestProject>(raw)
  }

• src/tools/projects/list_projects.ts:5-7 (schema)

  Input argument interface for listProjects, accepting an optional projectId number.

  export interface ListProjectsArgs {
    projectId?: number
  }

• src/server.ts:120-133 (registration)

  Tool registration on the MCP server: registers 'list-projects' with description and Zod schema, linking to the handler via the imported listProjects function.

  server.registerTool(
    'list-projects',
    {
      description:
        'Projects — list all qTest projects, or fetch a single project by ID',
      inputSchema: {
        projectId: z.number().int().optional().describe('Project ID; omit to list all projects'),
      },
    },
    async ({ projectId }) => {
      const result = await listProjects({ projectId })
      return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] }
    }
  )

• src/client.ts:58-67 (helper)

  Helper function used by the handler to extract an array from API responses that may wrap data in 'items', 'data', or 'object' keys.

  export function extractArray<T>(raw: unknown): T[] {
    if (Array.isArray(raw)) return raw as T[]
    if (raw && typeof raw === 'object') {
      for (const key of ['items', 'data', 'object'] as const) {
        const val = (raw as Record<string, unknown>)[key]
        if (Array.isArray(val)) return val as T[]
      }
    }
    return []
  }

• src/client.ts:5-29 (helper)

  Helper function that performs the actual HTTP GET request to the qTest API (global endpoint). Used by the handler to call /projects and /projects/{id}.

  export async function qtestFetchGlobal(
    config: QTestConfig,
    endpoint: string,
    method: 'GET' | 'POST' | 'DELETE',
    body?: unknown
  ): Promise<unknown> {
    const url = `${config.baseUrl}/api/v3${endpoint}`
    const response = await fetch(url, {
      method,
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${config.token}`,
      },
      body: body !== undefined ? JSON.stringify(body) : undefined,
    })
    if (!response.ok) {
      const text = await response.text()
      throw new Error(`HTTP ${response.status}: ${text}`)
    }
    if (response.status === 204 || response.headers.get('content-length') === '0') {
      return null
    }
    const text = await response.text()
    return text ? JSON.parse(text) : null
  }