TestCollab MCP Server

Instructions

Implementation Reference

• src/tools/test-cases/get.ts:248-384 (handler)

  The handler function for the get_test_case tool, which validates inputs, fetches test case data via the API client, normalizes the response, and formats the result as a text message containing the test case details and any missing steps.

  export async function handleGetTestCase(
    args: unknown
  ): Promise<{ content: Array<{ type: "text"; text: string }> }> {
    // Validate input
    const parsed = getTestCaseSchema.safeParse(args);
    if (!parsed.success) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: {
                code: "VALIDATION_ERROR",
                message: "Invalid input parameters",
                details: parsed.error.errors,
              },
            }),
          },
        ],
      };
    }
  
    const { id, project_id, parse_reusable_steps } = parsed.data;
  
    // Resolve project ID: check request context first (HTTP), then env config (stdio)
    const requestContext = getRequestContext();
    const envConfig = requestContext ? null : getConfig();
    const resolvedProjectId = project_id ?? requestContext?.defaultProjectId ?? envConfig?.defaultProjectId;
  
    if (!resolvedProjectId) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: {
                code: "MISSING_PROJECT_ID",
                message:
                  "project_id is required. Either provide it in the request or set TC_DEFAULT_PROJECT.",
              },
            }),
          },
        ],
      };
    }
  
    try {
      const client = getApiClient();
      const existingRaw = await client.getTestCaseRaw(id, resolvedProjectId, {
        parseRs: parse_reusable_steps ?? true,
      });
      const existing = unwrapApiEntity(existingRaw);
  
      if (!existing) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                error: {
                  code: "INVALID_TEST_CASE",
                  message: `Unable to load test case ${id}.`,
                },
              }),
            },
          ],
        };
      }
  
      const stepsSource = getExistingStepsSource(existing);
      const steps = stepsSource?.map((s, index) => ({
        step_number: getStepNumber(s, index),
        step: getStepText(s) ?? "",
        expected_result: getStepExpectedResult(s) ?? null,
        reusable_step_id: getStepReusableId(s) ?? null,
      }));
  
      const stepsMissingExpectedResults = (steps ?? [])
        .filter((step) => !normalizeString(step.expected_result))
        .map((step) => step.step_number);
  
      const suiteValue = getField<unknown>(existing, "suite");
      const projectValue = getField<unknown>(existing, "project");
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                success: true,
                testCase: {
                  id: extractId(existing) ?? id,
                  title: getField<string>(existing, "title"),
                  description: getField<string | null>(existing, "description"),
                  priority: toNumberId(getField<unknown>(existing, "priority")),
                  suite: typeof suiteValue === "object" ? extractId(suiteValue) : suiteValue,
                  suiteTitle:
                    getField<string>(existing, "suite_title") ??
                    (suiteValue && typeof suiteValue === "object"
                      ? getField<string>(suiteValue, "title")
                      : undefined),
                  project:
                    typeof projectValue === "object"
                      ? extractId(projectValue)
                      : projectValue,
                  projectTitle:
                    projectValue && typeof projectValue === "object"
                      ? getField<string>(projectValue, "title")
                      : undefined,
                  steps,
                },
                stepsMissingExpectedResults,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      const message = error instanceof Error ? error.message : "Unknown error";
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: {
                code: "API_ERROR",
                message: message,
              },
            }),
          },
        ],
      };
    }
  }

• src/tools/test-cases/get.ts:16-26 (schema)

  Zod schema definition for the inputs required by the get_test_case tool.

  export const getTestCaseSchema = z.object({
    id: z.number().describe("Test case ID to retrieve (required)"),
    project_id: z
      .number()
      .optional()
      .describe("Project ID (uses default if not specified)"),
    parse_reusable_steps: z
      .boolean()
      .optional()
      .describe("Parse reusable steps into full steps (default: true)"),
  });

• src/tools/test-cases/get.ts:34-65 (registration)

  Registration definition for the get_test_case tool, including its name, description, and input schema.

  export const getTestCaseTool = {
    name: "get_test_case",
    description: `Fetch a single test case with full details, including steps and expected results.
  
  Required: id (test case ID)
  Optional: project_id, parse_reusable_steps (default: true)
  
  Example:
  {
    "id": 1835,
    "parse_reusable_steps": true
  }`,
  
    inputSchema: {
      type: "object" as const,
      properties: {
        id: {
          type: "number",
          description: "Test case ID to retrieve (required)",
        },
        project_id: {
          type: "number",
          description: "Project ID (optional if default is set)",
        },
        parse_reusable_steps: {
          type: "boolean",
          description: "Parse reusable steps into full steps (default: true)",
        },
      },
      required: ["id"],
    },
  };