llmkit-mcp-server

Instructions

Implementation Reference

• packages/mcp-server/src/local-handlers.ts:170-224 (handler)

  The `handleLocalAgents` function implements the core logic for the "llmkit_local_agents" tool, calculating costs for Claude Code subagents.

  export async function handleLocalAgents() {
    // Agent attribution is Claude Code specific (subagent JSONL files).
    // Other tools don't have subagent concepts (yet).
    const agentData = await getAgentCosts();
    if (!agentData) return fail('No agent data found. Agent attribution requires Claude Code with subagents.');
  
    const { session, agents, mainConversationCost } = agentData;
    const agentTotal = agents.reduce((s, a) => s + a.totalCost, 0);
  
    const byType: { type: string; count: number; costUsd: number; tokens: number }[] = [];
    if (agents.length > 0) {
      const typeMap = new Map<string, { count: number; cost: number; tokens: number }>();
      for (const a of agents) {
        const e = typeMap.get(a.agentType) ?? { count: 0, cost: 0, tokens: 0 };
        e.count++;
        e.cost += a.totalCost;
        e.tokens += a.totalInput + a.totalOutput;
        typeMap.set(a.agentType, e);
      }
      for (const [type, d] of typeMap) {
        byType.push({ type, count: d.count, costUsd: d.cost, tokens: d.tokens });
      }
    }
  
    const topAgents = agents.slice(0, 5).map(a => ({
      type: a.agentType, id: a.agentId, costUsd: a.totalCost, messages: a.messages, models: a.models,
    }));
  
    const lines = [
      'Agent Cost Attribution',
      '\u2500'.repeat(25),
      `Session: ${session.sessionId.slice(0, 12)}...`,
      `Total: $${session.totalCost.toFixed(4)}`,
      '',
      `Main conversation: $${mainConversationCost.toFixed(4)}`,
      `Subagents: $${agentTotal.toFixed(4)} (${agents.length} agents)`,
    ];
  
    if (byType.length > 0) {
      lines.push('', 'By type:');
      for (const t of byType) lines.push(`  ${t.type}: ${t.count}x, $${t.costUsd.toFixed(4)}, ${t.tokens.toLocaleString()} tokens`);
      lines.push('', 'Top agents:');
      for (const a of topAgents) lines.push(`  ${a.type} (${a.id}): $${a.costUsd.toFixed(4)}, ${a.messages} msgs`);
    }
  
    return ok(lines.join('\n'), {
      sessionId: session.sessionId,
      totalCostUsd: session.totalCost,
      mainConversationCostUsd: mainConversationCost,
      subagentsTotalCostUsd: agentTotal,
      agentCount: agents.length,
      byType,
      topAgents,
    });
  }

• packages/mcp-server/src/tools.ts:197-213 (schema)

  The input and output schema for "llmkit_local_agents" defined within `LOCAL_TOOLS`.

    name: 'llmkit_local_agents',
    description: 'Subagent cost attribution for the current Claude Code session. Shows which agents cost the most.',
    inputSchema: { type: 'object' as const, properties: {} },
    outputSchema: {
      type: 'object' as const,
      properties: {
        sessionId: { type: 'string' },
        totalCostUsd: { type: 'number' },
        mainConversationCostUsd: { type: 'number' },
        subagentsTotalCostUsd: { type: 'number' },
        agentCount: { type: 'number' },
        byType: { type: 'array', items: { type: 'object', properties: { type: { type: 'string' }, count: { type: 'number' }, costUsd: { type: 'number' }, tokens: { type: 'number' } } } },
      },
      required: ['sessionId', 'totalCostUsd', 'agentCount'],
    },
    annotations: { title: 'Agent Costs', ...HINTS },
  },

• packages/mcp-server/src/tools.ts:291-306 (registration)

  Registration of the "llmkit_local_agents" tool in the HANDLER_MAP in `packages/mcp-server/src/tools.ts`.

  const HANDLER_MAP: Record<string, Handler> = {
    llmkit_usage_stats: handleUsageStats,
    llmkit_cost_query: handleCostQuery,
    llmkit_list_keys: () => handleListKeys(),
    llmkit_budget_status: handleBudgetStatus,
    llmkit_health: () => handleHealth(),
    llmkit_session_summary: handleSessionSummary,
    llmkit_local_session: () => handleLocalSession(),
    llmkit_local_projects: () => handleLocalProjects(),
    llmkit_local_cache: () => handleLocalCache(),
    llmkit_local_forecast: () => handleLocalForecast(),
    llmkit_local_agents: () => handleLocalAgents(),
    llmkit_notion_cost_snapshot: handleNotionCostSnapshot,
    llmkit_notion_budget_check: handleNotionBudgetCheck,
    llmkit_notion_session_report: handleNotionSessionReport,
  };