Rhumb

Instructions

Implementation Reference

• packages/mcp/src/tools/alternatives.ts:19-60 (handler)

  The primary logic handler for the get_alternatives tool. It fetches service scores, retrieves peers by tags, filters, and sorts them.

  export async function handleGetAlternatives(
    input: GetAlternativesInput,
    client: RhumbApiClient
  ): Promise<GetAlternativesOutput> {
    try {
      const score = await client.getServiceScore(input.slug);
      if (!score) return { alternatives: [] };
  
      const tags = score.tags;
      if (tags.length === 0) return { alternatives: [] };
  
      // Search for peer services using each failure tag
      const searchPromises = tags.map((tag) => client.searchServices(tag));
      const results = await Promise.all(searchPromises);
      const allPeers = results.flat();
  
      // Deduplicate, exclude current service, filter to higher scores
      const currentScore = score.aggregateScore ?? 0;
      const seen = new Set<string>();
      const sharedTags = tags.join(", ");
  
      const alternatives = allPeers
        .filter((peer) => {
          if (peer.slug === input.slug) return false;
          if (seen.has(peer.slug)) return false;
          seen.add(peer.slug);
          return (peer.aggregateScore ?? 0) > currentScore;
        })
        .sort((a, b) => (b.aggregateScore ?? 0) - (a.aggregateScore ?? 0))
        .map((peer) => ({
          name: peer.name,
          slug: peer.slug,
          aggregateScore: peer.aggregateScore,
          reason: `Higher AN Score alternative (shared failure patterns: ${sharedTags})`
        }));
  
      return { alternatives };
    } catch {
      // Resilient fallback: return empty array on any error
      return { alternatives: [] };
    }
  }

• packages/mcp/src/types.ts:68-74 (schema)

  Schema definition for the get_alternatives tool input.

  export const GetAlternativesInputSchema = {
    type: "object" as const,
    properties: {
      slug: { type: "string" as const, description: "Service slug from find_services results (e.g. 'stripe'). Returns other Services in the same category, ranked by AN Score." }
    },
    required: ["slug"] as const
  };

• packages/mcp/src/server.ts:88-102 (registration)

  Registration of the get_alternatives tool with the MCP server.

  // -- get_alternatives --------------------------------------------------
  server.tool(
    "get_alternatives",
    "Find alternative Services, ranked by AN Score. Use when a Service doesn't meet your needs or you want to compare options in the same category.",
    {
      slug: z.string().describe(GetAlternativesInputSchema.properties.slug.description)
    },
    async ({ slug }) => {
      const result = await handleGetAlternatives({ slug }, client);
      return {
        content: [{ type: "text" as const, text: JSON.stringify(result) }]
      };
    }
  );