refero_similar

Instructions

Implementation Reference

• src/tools/similar.ts:44-69 (handler)

  Main handler for refero_similar: resolves an identifier via resolveStyle, fetches full detail via getById, extracts the .similar array, maps results through toShorthand, and returns a SimilarResult.

  export async function handleSimilar(args: SimilarArgs): Promise<SimilarResult> {
    const identifier = asIdentifier(args.identifier);
    const limit = asLimit(args.limit);
  
    const catalog = await ensureCatalog();
    const match = resolveStyle(identifier, catalog);
    if (!match) {
      throw new IdentifierNotFoundError(
        `No style matched identifier ${JSON.stringify(identifier)} for refero_similar. ` +
          `Try refero_search first to find a valid id or site name.`,
      );
    }
  
    // Always fetch fresh detail — the .similar bucket is computed server-side
    // and isn't stored alongside the cached FullStyle. Refresh is cheap (one
    // request, fully cached afterwards via ensureStyle if needed).
    const detail = await getById(match.id);
    const similar = (detail.similar ?? []).slice(0, limit);
  
    return {
      identifier,
      styleId: match.id,
      count: similar.length,
      results: similar.map((s) => toShorthand(s)),
    };
  }

• src/tools/similar.ts:12-22 (schema)

  Input (SimilarArgs) and output (SimilarResult) type definitions for the refero_similar tool.

  export interface SimilarArgs {
    identifier?: unknown;
    limit?: unknown;
  }
  
  export interface SimilarResult {
    identifier: string;
    styleId: string;
    count: number;
    results: StyleShorthand[];
  }

• src/server.ts:95-114 (registration)

  Registration of refero_similar tool in the TOOLS array with name, description, inputSchema (identifier + limit).

  {
    name: "refero_similar",
    description:
      "Refero's own \"similar styles\" recommendation list for a given style. Useful for follow-up exploration once you've found a candidate via refero_search.",
    inputSchema: {
      type: "object",
      properties: {
        identifier: {
          type: "string",
          description: "uuid, hostname/URL, or site name.",
        },
        limit: {
          type: "number",
          description: "How many similar styles to return (default 10, max 20).",
        },
      },
      required: ["identifier"],
      additionalProperties: false,
    },
  },

• src/server.ts:168-169 (registration)

  Dispatch routing: maps 'refero_similar' tool name to handleSimilar handler.

  case "refero_similar":
    return handleSimilar(a);

• src/tools/shared.ts:62-76 (helper)

  toShorthand helper used to project style items in the refero_similar results.

  export function toShorthand(
    item: StyleListItem,
    opts: { score?: number; tags?: string[] } = {},
  ): StyleShorthand {
    return {
      id: item.id,
      siteName: item.siteName,
      url: item.url,
      northStar: item.northStar,
      theme: item.colorScheme,
      tags: opts.tags ?? [],
      thumbnailUrl: item.thumbnailUrl,
      ...(opts.score !== undefined ? { score: opts.score } : {}),
    };
  }