Create Downstream Reference

Instructions

Implementation Reference

• src/tools/associations-write.ts:59-89 (registration)

  Registration of the 'create_reference' tool on the MCP server with inputSchema (fromItemId, toItemId) and handler callback.

  server.registerTool(
    "create_reference",
    {
      title: "Create Downstream Reference",
      description:
        "Add a downstream reference from one Codebeamer item to another. " +
        "Downstream references represent derivation/traceability links (e.g. a requirement derived from another). " +
        "The 'from' item gets the downstream reference pointing to the 'to' item.",
      inputSchema: {
        fromItemId: z
          .number()
          .int()
          .positive()
          .describe("Item ID that will have the downstream reference added"),
        toItemId: z
          .number()
          .int()
          .positive()
          .describe("Item ID to reference as downstream"),
      },
    },
    async ({ fromItemId, toItemId }) => {
      await client.createDownstreamReference(fromItemId, toItemId);
      const text =
        `**Downstream reference created**\n\n` +
        `| Field | Value |\n|---|---|\n` +
        `| Upstream (from) | #${fromItemId} |\n` +
        `| Downstream (to) | #${toItemId} |`;
      return { content: [{ type: "text", text }] };
    },
  );

• src/tools/associations-write.ts:80-88 (handler)

  Handler function for 'create_reference' that calls client.createDownstreamReference(fromItemId, toItemId) and returns a formatted success message.

  async ({ fromItemId, toItemId }) => {
    await client.createDownstreamReference(fromItemId, toItemId);
    const text =
      `**Downstream reference created**\n\n` +
      `| Field | Value |\n|---|---|\n` +
      `| Upstream (from) | #${fromItemId} |\n` +
      `| Downstream (to) | #${toItemId} |`;
    return { content: [{ type: "text", text }] };
  },

• src/tools/associations-write.ts:61-78 (schema)

  Input schema definition for 'create_reference': requires fromItemId and toItemId (positive integers), with title and description metadata.

  {
    title: "Create Downstream Reference",
    description:
      "Add a downstream reference from one Codebeamer item to another. " +
      "Downstream references represent derivation/traceability links (e.g. a requirement derived from another). " +
      "The 'from' item gets the downstream reference pointing to the 'to' item.",
    inputSchema: {
      fromItemId: z
        .number()
        .int()
        .positive()
        .describe("Item ID that will have the downstream reference added"),
      toItemId: z
        .number()
        .int()
        .positive()
        .describe("Item ID to reference as downstream"),
    },

• src/client/codebeamer-client.ts:372-408 (helper)

  createDownstreamReference method on CodebeamerClient - fetches the target item, finds the superordinateRequirement field in the tracker schema, and sets it via a PUT request to /items/{toItemId}/fields.

  async createDownstreamReference(fromItemId: number, toItemId: number): Promise<void> {
    // Downstream reference is created by setting the "superordinateRequirement" field
    // on the downstream (to) item to point to the upstream (from) item.
    const toItem = await this.getItem(toItemId);
    const trackerId = toItem.tracker?.id;
    if (!trackerId) throw new Error(`Cannot determine tracker for item ${toItemId}`);
  
    const schema = await this.getTrackerSchema(trackerId);
    const superordinateField = schema.find(
      (f) => f.legacyRestName === "superordinateRequirement",
    );
    if (!superordinateField) {
      throw new Error(
        `Tracker ${trackerId} has no superordinateRequirement field. Cannot create downstream reference.`,
      );
    }
  
    const fields = await this.getItemEditableFields(toItemId);
    const currentField = fields.find((f) => f.fieldId === superordinateField.id);
    const existingValues = currentField?.values ?? [];
    if (existingValues.some((v) => v.id === fromItemId)) return; // already linked
  
    const newValues = [...existingValues, { id: fromItemId, type: "TrackerItemReference" }];
  
    await this.http.put(`/items/${toItemId}/fields`, {
      body: {
        fieldValues: [
          {
            fieldId: superordinateField.id,
            type: "ChoiceFieldValue",
            values: newValues,
          },
        ],
      },
      resource: `add downstream reference from ${fromItemId} to ${toItemId}`,
    });
  }