Mcp Pager — Zero Config Response Paging For Mcp Servers (typescript + Python)

mcp-pager

MCP サーバー向けの、トークンを考慮したレスポンス管理です。

ツールが数千件のレコードを返す一方で、LLM にはトークン数の上限があります。mcp-pager はその間に入ります — サイズの大きすぎるツールのレスポンスをインターセプトし、トークン数に応じて分割して、エージェントが読み取れるメタデータとともに各ページを返すため、LLM は次に何を取得すればよいかを正確に把握できます。コードは1行。既存のサーバーを変更する必要はありません。

---

言語を選択

	TypeScript / JavaScript	Python
インストール	npm install mcp-pager	pip install mcp-pager
ドキュメント	TypeScript ガイド →	Python ガイド →
レジストリ	npmjs.com/package/mcp-pager	pypi.org/project/mcp-pager
MCP SDK	@modelcontextprotocol/sdk	mcp (FastMCP)

---

機能

Tool call  →  mcp-pager  →  Your MCP server
                 │
           token count ≤ limit?
           ├─ yes → return as-is
           └─ no  → chunk → store → return page 1 + metadata

get_next_page(cursor) → read from store → return next chunk + metadata

レスポンスが大きすぎる場合、LLM はそのまま実行できる構造化メタデータを受け取ります。

{
  "hasMore": true,
  "pageIndex": 0,
  "totalPages": 22,
  "remainingPages": 21,
  "nextCursor": "eyJpZCI6Ijkx...",
  "instruction": "Call `get_next_page` with nextCursor to get the next page. Repeat until hasMore is false."
}

---

主な機能

機能	説明
設定不要	サーバー全体を1行でラップします
バックエンド呼び出しは1回	LLM が何ページ取得しても、API の呼び出しは1回です
スライディング TTL	ページを取得するたびにカーソルの有効期限がリセットされるため、長時間のセッションが途中でタイムアウトしません
Redis バックエンド	マルチプロセス／サーバーレスのデプロイに対応した、本番環境向けの共有ストレージです
HMAC 署名	マルチテナント環境向けに、オプションでカーソルに署名できます
オブザーバビリティ	型付きのライフサイクルイベントを受け取る onPaginate / on_paginate コールバックです
エージェントが読み取れるメタデータ	構造化 JSON により、LLM は次に何をすればよいかを正確に把握できます

---

ドキュメント

ドキュメント	説明
TypeScript ガイド	API、バックエンド、署名、オブザーバビリティの全容
Python ガイド	API、FastMCP との統合、バックエンドの全容
LLM プロンプトガイド	Claude、GPT-4o、Cursor 向けにテスト済みのシステムプロンプト
移行ガイド	手動ページネーションから mcp-pager への移行
トークン削減量	実例による導入前／導入後の数値
ロードマップ	v1.x で予定されている内容（スマートレスポンス処理）

ソース

mcp-pager/
├── src/              TypeScript source
├── docs/             Guides and documentation
├── python/
│   ├── mcp_pager/    Python source
│   └── README.md     Full Python documentation
└── examples/         Demo servers (TS + Python)

---

ライセンス

MIT — Satish Kakollu