ツール出力が大きすぎてコンテキストを溶かす問題 — カーソルで小分けに返すページング設計

def list_articles_cursor(after_published_at=None, after_id=None, limit=20):
    if after_published_at is None:
        rows = db.query(
            "SELECT id, slug, title, category, published_at "
            "FROM articles WHERE status = 'published' "
            "ORDER BY published_at DESC, id DESC LIMIT ?",
            (limit + 1,),
        )
    else:
        rows = db.query(
            "SELECT id, slug, title, category, published_at "
            "FROM articles WHERE status = 'published' "
            "AND (published_at, id) < (?, ?) "
            "ORDER BY published_at DESC, id DESC LIMIT ?",
            (after_published_at, after_id, limit + 1),
        )
    return rows

import base64
import hmac
import hashlib
import json
 
CURSOR_SECRET = b"replace-with-env-secret"  # 実際は環境変数から読み込む
 
def encode_cursor(published_at: str, item_id: int) -> str:
    payload = json.dumps(
        {"p": published_at, "i": item_id, "k": "published_at_id_v1"},
        separators=(",", ":"),
    ).encode()
    sig = hmac.new(CURSOR_SECRET, payload, hashlib.sha256).digest()[:8]
    return base64.urlsafe_b64encode(payload + sig).decode()
 
def decode_cursor(cursor: str):
    raw = base64.urlsafe_b64decode(cursor.encode())
    payload, sig = raw[:-8], raw[-8:]
    expected = hmac.new(CURSOR_SECRET, payload, hashlib.sha256).digest()[:8]
    if not hmac.compare_digest(sig, expected):
        raise ValueError("cursor signature mismatch")
    data = json.loads(payload)
    if data.get("k") != "published_at_id_v1":
        raise ValueError("cursor scheme mismatch — 古いカーソルです")
    return data["p"], data["i"]

def list_articles_tool(cursor: str | None = None, limit: int = 20):
    after_p, after_i = (decode_cursor(cursor) if cursor else (None, None))
    rows = list_articles_cursor(after_p, after_i, limit)
 
    has_more = len(rows) > limit
    page = rows[:limit]
    next_cursor = (
        encode_cursor(page[-1]["published_at"], page[-1]["id"])
        if has_more and page else None
    )
 
    total = db.scalar(
        "SELECT COUNT(*) FROM articles WHERE status = 'published'"
    )
    return {
        "items": [
            {"slug": r["slug"], "title": r["title"],
             "category": r["category"], "published_at": r["published_at"]}
            for r in page
        ],
        "page_size": len(page),
        "has_more": has_more,
        "next_cursor": next_cursor,
        "total_published": total,
        "hint": (
            f"全{total}件中の最新{len(page)}件です。"
            "さらに古い記事が必要な場合のみ next_cursor を渡して再呼び出ししてください。"
        ),
    }

const listArticlesTool = {
  name: "list_articles",
  description:
    "公開済み記事を新しい順に返します。1回の呼び出しは最大50件です。" +
    "続きが必要なときだけ、前回の応答の next_cursor を cursor に渡してください。",
  input_schema: {
    type: "object",
    properties: {
      cursor: {
        type: "string",
        description: "前回応答の next_cursor。最初の呼び出しでは省略します。",
      },
      limit: {
        type: "integer",
        minimum: 1,
        maximum: 50,
        default: 20,
      },
    },
  },
} as const;
 
function clampLimit(requested?: number): number {
  if (!requested || requested < 1) return 20;
  return Math.min(requested, 50);
}