premium_routing

Instructions

Implementation Reference

• mcp-server/src/index.ts:322-350 (handler)

  The async handler function that executes the premium_routing tool logic. It builds URL params from the input schema, calls the API endpoint /premium/routing, and formats the response into a human-readable text block.

    async ({ task, budget, min_quality, top_n }) => {
      const params = new URLSearchParams();
      if (task) params.set('task', task);
      if (typeof budget === 'number') params.set('budget', String(budget));
      if (typeof min_quality === 'number') params.set('min_quality', String(min_quality));
      if (typeof top_n === 'number') params.set('top_n', String(top_n));
      const data = (await fetchJSON(`/premium/routing?${params}`, { auth: true })) as {
        task: string;
        recommendations: {
          rank: number;
          model: { name: string; provider: string };
          pricing: { input: number; output: number };
          composite_score: number;
          components: { quality: number; availability: number; cost: number; latency: number };
        }[];
        billing?: { credits_charged: number; credits_remaining?: number };
      };
      const list = data.recommendations
        .map(r => {
          const c = r.components;
          return `  #${r.rank} ${r.model.name} (${r.model.provider}) score=${r.composite_score.toFixed(3)}\n     in $${r.pricing.input}/1M, out $${r.pricing.output}/1M\n     quality=${c.quality.toFixed(2)} avail=${c.availability.toFixed(2)} cost=${c.cost.toFixed(2)} latency=${c.latency.toFixed(2)}`;
        })
        .join('\n\n');
      const billing = data.billing
        ? `\n\nCharged ${data.billing.credits_charged} credit. Remaining: ${data.billing.credits_remaining}.`
        : '';
      return { content: [{ type: 'text' as const, text: `Routing for "${data.task}":\n\n${list}${billing}` }] };
    },
  );

• mcp-server/src/index.ts:316-321 (schema)

  Input schema for the premium_routing tool using Zod: optional task (enum: code/reasoning/creative/general), budget (number), min_quality (0-1), and top_n (1-10).

  {
    task: z.enum(['code', 'reasoning', 'creative', 'general']).optional().describe('Task type the model needs to be good at (default: general)'),
    budget: z.number().optional().describe('Max blended USD per 1M tokens'),
    min_quality: z.number().min(0).max(1).optional().describe('Minimum quality score in [0, 1]'),
    top_n: z.number().min(1).max(10).optional().describe('How many models to return (default 5)'),
  },

• mcp-server/src/index.ts:313-350 (registration)

  Registration of the tool using server.tool() with name 'premium_routing', description about ranked recommended AI models, Zod input schema, and the async handler.

  server.tool(
    'premium_routing',
    'Get a ranked list of recommended AI models for a task with full score breakdown (quality, availability, cost, latency). Costs 1 credit.',
    {
      task: z.enum(['code', 'reasoning', 'creative', 'general']).optional().describe('Task type the model needs to be good at (default: general)'),
      budget: z.number().optional().describe('Max blended USD per 1M tokens'),
      min_quality: z.number().min(0).max(1).optional().describe('Minimum quality score in [0, 1]'),
      top_n: z.number().min(1).max(10).optional().describe('How many models to return (default 5)'),
    },
    async ({ task, budget, min_quality, top_n }) => {
      const params = new URLSearchParams();
      if (task) params.set('task', task);
      if (typeof budget === 'number') params.set('budget', String(budget));
      if (typeof min_quality === 'number') params.set('min_quality', String(min_quality));
      if (typeof top_n === 'number') params.set('top_n', String(top_n));
      const data = (await fetchJSON(`/premium/routing?${params}`, { auth: true })) as {
        task: string;
        recommendations: {
          rank: number;
          model: { name: string; provider: string };
          pricing: { input: number; output: number };
          composite_score: number;
          components: { quality: number; availability: number; cost: number; latency: number };
        }[];
        billing?: { credits_charged: number; credits_remaining?: number };
      };
      const list = data.recommendations
        .map(r => {
          const c = r.components;
          return `  #${r.rank} ${r.model.name} (${r.model.provider}) score=${r.composite_score.toFixed(3)}\n     in $${r.pricing.input}/1M, out $${r.pricing.output}/1M\n     quality=${c.quality.toFixed(2)} avail=${c.availability.toFixed(2)} cost=${c.cost.toFixed(2)} latency=${c.latency.toFixed(2)}`;
        })
        .join('\n\n');
      const billing = data.billing
        ? `\n\nCharged ${data.billing.credits_charged} credit. Remaining: ${data.billing.credits_remaining}.`
        : '';
      return { content: [{ type: 'text' as const, text: `Routing for "${data.task}":\n\n${list}${billing}` }] };
    },
  );

• mcp-server/src/index.ts:19-59 (helper)

  The fetchJSON helper function used by the handler to make authenticated HTTP requests to the TensorFeed API.

  async function fetchJSON(path: string, opts: FetchOptions = {}): Promise<unknown> {
    const headers: Record<string, string> = {
      'User-Agent': `TensorFeed-MCP/${SDK_VERSION}`,
    };
    if (opts.body !== undefined) headers['Content-Type'] = 'application/json';
    if (opts.auth) {
      const token = process.env.TENSORFEED_TOKEN;
      if (!token) {
        throw new Error(
          'TENSORFEED_TOKEN env var is not set. Premium MCP tools require a bearer token. ' +
            'Buy credits at https://tensorfeed.ai/developers/agent-payments and pass the returned tf_live_... token via the TENSORFEED_TOKEN env var in your MCP client config.',
        );
      }
      headers['Authorization'] = `Bearer ${token}`;
    }
    const res = await fetch(`${API_BASE}${path}`, {
      method: opts.method ?? 'GET',
      headers,
      ...(opts.body !== undefined ? { body: JSON.stringify(opts.body) } : {}),
    });
    if (!res.ok) {
      let errPayload: unknown;
      try {
        errPayload = await res.json();
      } catch {
        errPayload = await res.text().catch(() => '');
      }
      if (res.status === 402) {
        throw new Error(
          `Payment required (402). Your token may be out of credits. Top up at https://tensorfeed.ai/developers/agent-payments. Detail: ${JSON.stringify(errPayload)}`,
        );
      }
      if (res.status === 401) {
        throw new Error(
          `Token rejected (401). Check that TENSORFEED_TOKEN is set to a valid tf_live_... token. Detail: ${JSON.stringify(errPayload)}`,
        );
      }
      throw new Error(`API error ${res.status}: ${JSON.stringify(errPayload)}`);
    }
    return res.json();
  }