show_concentration

Instructions

Implementation Reference

• apps/mcp/src/tools/portfolio.ts:212-281 (handler)

  MCP tool handler for 'show_concentration' - computes HHI concentration by ticker, currency, sector, and country dimensions. Gets transactions from DB, aggregates holdings, maps with prices, and returns grouped slices with HHI scores and top contributors.

  server.tool(
    'show_concentration',
    'Portfolio concentration measured by Herfindahl-Hirschman Index (HHI) across ticker, currency, sector, and country dimensions. HHI ranges 0–10000; >2500 is high, >5000 very high. Returns top contributors per dimension.',
    {},
    async () => {
      const db = getDb();
      const txns = db.select().from(transactions).all();
      const holdings = aggregateHoldings(txns);
      if (holdings.size === 0) return ok({});
  
      const priceMap = new Map(
        db
          .select()
          .from(prices)
          .all()
          .map((p) => [p.ticker, p]),
      );
  
      const positions = [...holdings.entries()]
        .map(([ticker, h]) => {
          const p = priceMap.get(ticker);
          const marketValue = p ? p.current_price * h.shares : 0;
          return {
            ticker,
            marketValue,
            currency: p?.currency ?? 'USD',
            sector: p?.sector ?? 'Unknown',
            country: p?.country ?? 'Unknown',
          };
        })
        .filter((p) => p.marketValue > 0);
  
      const hhi = (slices: { value: number }[]) => {
        const total = slices.reduce((s, x) => s + x.value, 0);
        if (total <= 0) return 0;
        return Math.round(
          slices.reduce((s, { value }) => {
            const p = value / total;
            return s + p * p * 10000;
          }, 0),
        );
      };
  
      const groupBy = (keyOf: (p: (typeof positions)[number]) => string) => {
        const map = positions.reduce(
          (m, p) => m.set(keyOf(p), (m.get(keyOf(p)) ?? 0) + p.marketValue),
          new Map<string, number>(),
        );
        const slices = [...map.entries()]
          .map(([label, value]) => ({ label, value }))
          .sort((a, b) => b.value - a.value);
        const total = slices.reduce((s, x) => s + x.value, 0);
        return {
          hhi: hhi(slices),
          slices: slices.map((s) => ({
            label: s.label,
            value: s.value,
            pct: total > 0 ? (s.value / total) * 100 : 0,
          })),
        };
      };
  
      return ok({
        by_ticker: groupBy((p) => p.ticker),
        by_currency: groupBy((p) => p.currency),
        by_sector: groupBy((p) => p.sector),
        by_country: groupBy((p) => p.country),
      });
    },
  );

• apps/mcp/src/index.ts:19-23 (registration)

  Registration of the portfolio tools (including show_concentration) via registerPortfolioTools(server) at MCP server startup.

  registerPortfolioTools(server);
  registerReportTools(server);
  registerMutateTools(server);
  registerSnapshotTools(server);
  registerStockTools(server);

• apps/mcp/src/tools/portfolio.ts:22-23 (registration)

  Export function registerPortfolioTools that registers show_concentration and other portfolio tools on the MCP server instance.

  export function registerPortfolioTools(server: McpServer): void {

• packages/db/src/aggregate.ts:3-30 (helper)

  Helper function aggregateHoldings - aggregates transaction records into a Map of ticker to Holding (shares, cost basis). Used by the show_concentration handler.

  export const aggregateHoldings = (txns: Transaction[]): Map<string, Holding> => {
    const sorted = [...txns].sort((a, b) => a.date.localeCompare(b.date));
  
    const map = sorted.reduce((acc, t) => {
      const h = acc.get(t.ticker) ?? { ticker: t.ticker, shares: 0, costShares: 0, totalCost: 0 };
  
      if (t.type === 'buy') {
        h.shares += t.shares;
        h.costShares += t.shares;
        h.totalCost += t.shares * t.price;
      } else if (t.type === 'sell') {
        const ratio = h.shares > 0 ? (h.shares - t.shares) / h.shares : 0;
        h.shares -= t.shares;
        h.costShares = h.costShares * ratio;
        h.totalCost = h.totalCost * ratio;
      } else if (t.type === 'deposit') {
        h.shares += t.shares;
        if (t.price > 0) {
          h.costShares += t.shares;
          h.totalCost += t.shares * t.price;
        }
      }
  
      return acc.set(t.ticker, h);
    }, new Map<string, Holding>());
  
    return new Map([...map.entries()].filter(([, h]) => h.shares > 0));
  };

• apps/mcp/src/helpers.ts:22-23 (helper)

  Server instructions mentioning show_concentration as part of the risk/concentration/rebalance investigation protocol.

  - Risk / concentration / rebalance → get_brief + show_concentration.
  - Macro / market environment → get_brief (signals and macro are already inside).