create_reference

Add downstream references between Codebeamer items to establish derivation and traceability links, such as connecting requirements to their source items.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fromItemId`	Yes	Item ID that will have the downstream reference added
`toItemId`	Yes	Item ID to reference as downstream

Implementation Reference

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

The handler function for 'create_reference', which invokes the client's createDownstreamReference method.

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-79 (schema)

The schema definition for the 'create_reference' tool inputs.

{
  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/tools/associations-write.ts:59-89 (registration)

The registration of the 'create_reference' tool in the MCP server.

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 }] };
  },
);

codebeamer-mcp