link_source_record

Instructions

Implementation Reference

• src/tools.ts:258-268 (handler)

  Handler function for the link_source_record tool. Destructures entity_id from the params and POSTs the remaining body (source_record_id, confidence, linked_by) to /entities/{entity_id}/links.

  async ({ entity_id, ...body }) => {
    try {
      const data = await api.post(
        `/entities/${entity_id}/links`,
        body as Record<string, unknown>,
      );
      return jsonContent(data);
    } catch (e) {
      return errorContent(e);
    }
  },

• src/tools.ts:244-257 (schema)

  Input schema for link_source_record: entity_id (string), source_record_id (string), confidence (optional number 0-1), linked_by (optional string).

  {
    entity_id: z.string().describe("UUID of the AnchorID to link to"),
    source_record_id: z.string().describe("UUID of the source record to link"),
    confidence: z
      .number()
      .min(0)
      .max(1)
      .optional()
      .describe("Confidence score for this link (0-1)"),
    linked_by: z
      .string()
      .optional()
      .describe('Who/what created this link (default: "api")'),
  },

• src/tools.ts:239-269 (registration)

  Registration of the 'link_source_record' tool via server.tool(), including description and schema.

  // ─── 6. link_source_record ───────────────────────────────────────
  server.tool(
    "link_source_record",
    "Create or reactivate a link between an AnchorID and a source record. " +
      "Idempotent — calling twice returns the existing link.",
    {
      entity_id: z.string().describe("UUID of the AnchorID to link to"),
      source_record_id: z.string().describe("UUID of the source record to link"),
      confidence: z
        .number()
        .min(0)
        .max(1)
        .optional()
        .describe("Confidence score for this link (0-1)"),
      linked_by: z
        .string()
        .optional()
        .describe('Who/what created this link (default: "api")'),
    },
    async ({ entity_id, ...body }) => {
      try {
        const data = await api.post(
          `/entities/${entity_id}/links`,
          body as Record<string, unknown>,
        );
        return jsonContent(data);
      } catch (e) {
        return errorContent(e);
      }
    },
  );

• src/tools.ts:18-22 (helper)

  Helper function jsonContent() used to format API response data as MCP tool content.

  function jsonContent(data: unknown) {
    return {
      content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
    };
  }

• src/tools.ts:25-42 (helper)

  Helper function errorContent() used to format errors (including ApiError) as MCP tool content with isError flag.

  function errorContent(err: unknown) {
    if (err instanceof ApiError) {
      const payload = {
        error: err.message,
        status_code: err.status_code,
        request_id: err.request_id,
        details: err.details,
      };
      return {
        content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
        isError: true,
      };
    }
    return {
      content: [{ type: "text" as const, text: (err as Error).message ?? String(err) }],
      isError: true,
    };
  }