ai-compass

Implementation Reference

• apps/mcp-server/src/index.ts:49-111 (handler)

  Tool registration and handler definition for 'recommend_models'. Validates input, fetches model data, and calls the core recommendation function.

  server.tool(
    "recommend_models",
    {
      use_case: z
        .string()
        .describe(
          "Natural language description of what you want to build or do with an AI model",
        ),
    },
    async ({ use_case }) => {
      const apiKey = process.env.ANTHROPIC_API_KEY;
      if (!apiKey) {
        return {
          content: [
            {
              type: "text" as const,
              text: "Error: ANTHROPIC_API_KEY environment variable is required.",
            },
          ],
        };
      }
  
      try {
        const validation = await validateQuery(use_case, apiKey);
        if (!validation.valid) {
          return {
            content: [
              {
                type: "text" as const,
                text:
                  validation.message ??
                  "Please describe an AI use case you want to build.",
              },
            ],
          };
        }
  
        const { models, ageHours } = await getModels();
        const recs = await recommend(use_case, models, apiKey);
  
        const result = recs.map((r) => ({
          model_id: r.model_id,
          rank: r.rank,
          rank_label: r.rank_label,
          reasoning: r.reasoning,
          cost_estimate: r.estimated_cost_example,
          tradeoffs: r.tradeoffs,
          dataset_age_hours: ageHours,
        }));
  
        return {
          content: [
            { type: "text" as const, text: JSON.stringify(result, null, 2) },
          ],
        };
      } catch (err) {
        const msg = err instanceof Error ? err.message : "Unknown error";
        return {
          content: [{ type: "text" as const, text: `Error: ${msg}` }],
        };
      }
    },
  );

• packages/core/src/recommend.ts:90-100 (handler)

  The core recommendation logic that orchestrates calling Claude and parsing the response.

  export async function recommend(
    userQuery: string,
    models: Model[],
    apiKey?: string,
  ): Promise<Recommendation[]> {
    if (!userQuery.trim()) throw new Error("Query cannot be empty");
    if (!models.length) throw new Error("Models array cannot be empty");
  
    const raw = await callClaude(userQuery, models, apiKey);
    return parseRecommendations(raw);
  }