Get Item References

Instructions

Implementation Reference

• src/tools/item-details.ts:59-79 (registration)

  The tool 'get_item_references' is registered via server.registerTool() with input schema (itemId: number) and a handler that calls client.getItemRelations then formatReferences.

  server.registerTool(
    "get_item_references",
    {
      title: "Get Item References",
      description:
        "Get upstream and downstream traceability references for a Codebeamer item. " +
        "Upstream references point to items this one is derived from (e.g. requirements). " +
        "Downstream references point to items derived from this one (e.g. test cases).",
      inputSchema: {
        itemId: z
          .number()
          .int()
          .positive()
          .describe("Numeric item ID"),
      },
    },
    async ({ itemId }) => {
      const page = await client.getItemRelations(itemId);
      return { content: [{ type: "text", text: formatReferences(page) }] };
    },
  );

• src/tools/item-details.ts:75-78 (handler)

  The handler function for 'get_item_references' - calls client.getItemRelations(itemId) to fetch the relations page, then passes it to formatReferences() for display.

  async ({ itemId }) => {
    const page = await client.getItemRelations(itemId);
    return { content: [{ type: "text", text: formatReferences(page) }] };
  },

• src/tools/item-details.ts:61-73 (schema)

  Input schema for 'get_item_references' - expects a single 'itemId' parameter: a positive integer (Zod schema).

  {
    title: "Get Item References",
    description:
      "Get upstream and downstream traceability references for a Codebeamer item. " +
      "Upstream references point to items this one is derived from (e.g. requirements). " +
      "Downstream references point to items derived from this one (e.g. test cases).",
    inputSchema: {
      itemId: z
        .number()
        .int()
        .positive()
        .describe("Numeric item ID"),
    },

• src/formatters/item-formatter.ts:245-262 (helper)

  formatReferences() helper function - formats upstream and downstream references into a Markdown table using the shared relationsTable() utility.

  export function formatReferences(page: CbItemRelationsPage): string {
    const upstream = page.upstreamReferences ?? [];
    const downstream = page.downstreamReferences ?? [];
    const total = upstream.length + downstream.length;
  
    if (total === 0) return "_No references found._";
  
    const lines: string[] = [`## References (${total})`];
  
    if (upstream.length > 0) {
      lines.push("", `### Upstream (${upstream.length})`, "", ...relationsTable(upstream));
    }
    if (downstream.length > 0) {
      lines.push("", `### Downstream (${downstream.length})`, "", ...relationsTable(downstream));
    }
  
    return lines.join("\n");
  }

• src/formatters/item-formatter.ts:215-223 (helper)

  relationsTable() helper - shared utility used by formatReferences to render relations as a Markdown table with columns: Relation ID, Type, Target ID, Target Name.

  function relationsTable(relations: { id: number; type?: { name?: string }; itemRevision?: { id: number; name: string } }[]): string[] {
    const rows = relations.map(
      (r) => `| ${r.id} | ${r.type?.name ?? "?"} | ${r.itemRevision?.id ?? "?"} | ${r.itemRevision?.name ?? "?"} |`,
    );
    return [
      "| Relation ID | Type | Target ID | Target Name |",
      "|-------------|------|-----------|-------------|",
      ...rows,
    ];