From aa75d47ead317c76e7cd9745ff76dd296b4de883 Mon Sep 17 00:00:00 2001
From: silverwind <me@silverwind.io>
Date: Thu, 26 Mar 2026 08:06:32 +0100
Subject: [PATCH] Document server-side pagination limit in README

The maximum effective page size for paginated tools is determined by
the Gitea server's [api].MAX_RESPONSE_ITEMS setting (default: 50).
Requesting a perPage value higher than this limit will be silently
capped by the server.

Fixes: https://gitea.com/gitea/gitea-mcp/issues/165
Co-Authored-By: Claude (claude-opus-4-6) <noreply@anthropic.com>
---
 README.md       | 3 +++
 README.zh-cn.md | 5 ++++-
 README.zh-tw.md | 5 ++++-
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index fa3ccdd..ae7a1c5 100644
--- a/README.md
+++ b/README.md
@@ -166,6 +166,9 @@ To configure the MCP server for Gitea, add the following to your MCP configurati
 > You can provide your Gitea host and access token either as command-line arguments or environment variables.
 > Command-line arguments have the highest priority
 
+> [!NOTE]
+> Many tools support `page` and `perPage` parameters for pagination. The maximum effective page size is determined by the Gitea server's `[api].MAX_RESPONSE_ITEMS` setting (default: **50**). Requesting a `perPage` value higher than this limit will be silently capped by the server.
+
 Once everything is set up, try typing the following in your MCP-compatible chatbox:
 
 ```text
diff --git a/README.zh-cn.md b/README.zh-cn.md
index 86485ae..f9266ec 100644
--- a/README.zh-cn.md
+++ b/README.zh-cn.md
@@ -163,9 +163,12 @@ cp gitea-mcp /usr/local/bin/
 **默认日志路径**: `$HOME/.gitea-mcp/gitea-mcp.log`
 
 > [!注意]
-> 可通过命令行参数或环境变量提供 Gitea 主机和访问令牌。  
+> 可通过命令行参数或环境变量提供 Gitea 主机和访问令牌。
 > 命令行参数优先。
 
+> [!注意]
+> 许多工具支持 `page` 和 `perPage` 分页参数。最大有效页面大小由 Gitea 服务器的 `[api].MAX_RESPONSE_ITEMS` 设置决定（默认值：**50**）。请求超过此限制的 `perPage` 值将被服务器静默截断。
+
 一切设置完成后，可在 MCP 聊天框输入：
 
 ```text
diff --git a/README.zh-tw.md b/README.zh-tw.md
index 2dac558..6566353 100644
--- a/README.zh-tw.md
+++ b/README.zh-tw.md
@@ -163,9 +163,12 @@ cp gitea-mcp /usr/local/bin/
 **預設日誌路徑**: `$HOME/.gitea-mcp/gitea-mcp.log`
 
 > [!注意]
-> 可用命令列參數或環境變數提供 Gitea 主機與存取令牌。  
+> 可用命令列參數或環境變數提供 Gitea 主機與存取令牌。
 > 命令列參數優先。
 
+> [!注意]
+> 許多工具支援 `page` 和 `perPage` 分頁參數。最大有效頁面大小由 Gitea 伺服器的 `[api].MAX_RESPONSE_ITEMS` 設定決定（預設值：**50**）。請求超過此限制的 `perPage` 值將被伺服器靜默截斷。
+
 一切設定完成後，可在 MCP 聊天框輸入：
 
 ```text