自作 MCP サーバの巨大なツール結果でエージェントのコンテキストを溢れさせない設計

const FIELDS = ["slug", "title", "updatedAt", "premium"] as const;
 
server.registerTool(
  "list_articles",
  {
    description: "記事の要約一覧を返す。fields で取得する列を絞れる",
    inputSchema: {
      site: z.string(),
      fields: z.array(z.enum(FIELDS)).default(["slug", "title"]),
    },
  },
  async ({ site, fields }) => {
    const rows = await db.allArticles(site);
    const projected = rows.map((r) =>
      Object.fromEntries(fields.map((f) => [f, r[f]]))
    );
    return { content: [{ type: "text", text: JSON.stringify(projected) }] };
  }
);

const PAGE_LIMIT = 20;
 
server.registerTool(
  "list_articles",
  {
    description: "記事一覧をページ単位で返す。続きは cursor を渡す",
    inputSchema: {
      site: z.string(),
      cursor: z.string().optional(),
      limit: z.number().min(1).max(50).default(PAGE_LIMIT),
    },
  },
  async ({ site, cursor, limit }) => {
    const offset = cursor ? decodeCursor(cursor) : 0;
    const rows = await db.allArticles(site);
    const page = rows.slice(offset, offset + limit);
    const next = offset + limit < rows.length
      ? encodeCursor(offset + limit)
      : null;
 
    const summary = page.map((r) => ({ slug: r.slug, title: r.title }));
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          items: summary,
          nextCursor: next,
          total: rows.length,
        }),
      }],
    };
  }
);
 
// cursor は中身を推測されないよう base64 で包むだけでも実用上は十分です
const encodeCursor = (n: number) => Buffer.from(String(n)).toString("base64");
const decodeCursor = (c: string) => Number(Buffer.from(c, "base64").toString());

async ({ site, cursor, limit }) => {
  const { page, next, total } = await fetchPage(site, cursor, limit);
 
  const links = page.map((r) => ({
    type: "resource_link" as const,
    uri: `article://${site}/${r.slug}`,
    name: r.title,
    description: `${r.updatedAt} ${r.premium ? "[premium]" : ""}`.trim(),
    mimeType: "text/markdown",
  }));
 
  return {
    content: [
      { type: "text", text: JSON.stringify({ nextCursor: next, total }) },
      ...links,
    ],
  };
}

const OUTPUT_BUDGET = 2000; // トークン上限（ツール共通の契約）
 
function enforceBudget(payload: string, toolName: string): string {
  const tokens = enc.encode(payload).length;
  if (tokens <= OUTPUT_BUDGET) return payload;
  // 予算超過は「黙って切る」のではなく、超過を明示して縮小を促す
  return JSON.stringify({
    error: "OUTPUT_BUDGET_EXCEEDED",
    tool: toolName,
    tokens,
    budget: OUTPUT_BUDGET,
    hint: "limit を下げるか fields を絞って再呼び出ししてください",
  });
}

// 安定キー（updatedAt + slug）でカーソルを作る
const decodeKey = (c?: string) =>
  c ? JSON.parse(Buffer.from(c, "base64").toString()) : null;
 
async function fetchPageStable(site: string, cursor: string | undefined, limit: number) {
  const after = decodeKey(cursor); // { updatedAt, slug } or null
  const rows = await db.articlesAfter(site, after, limit + 1); // 1件多めに取る
  const hasMore = rows.length > limit;
  const page = rows.slice(0, limit);
  const last = page.at(-1);
  const next = hasMore && last
    ? Buffer.from(JSON.stringify({ updatedAt: last.updatedAt, slug: last.slug })).toString("base64")
    : null;
  return { page, next };
}