Add configurable NFT page size and slice responses #126

akolotov · 2025-07-04T22:30:57Z

Summary

add nft_page_size to configuration and environment files
slice results of nft_tokens_by_address using the new config
update pagination logic and unit tests
document new pagination pattern

Closes #124

https://chatgpt.com/codex/tasks/task_b_6868533fa4688323b3b5260a94066d97

Summary by CodeRabbit

New Features
- Introduced a unified, context-aware pagination strategy using opaque cursors and configurable page sizes for NFT tokens, logs, transactions, and advanced filters.
- Added environment variables and configuration options to control page sizes per tool.
- Implemented multi-page fetching for filtered transaction queries to ensure sufficient data is returned despite filtering.
Bug Fixes
- Improved pagination accuracy by slicing returned data and generating cursors from the last returned item to avoid skipping or duplicating items.
Documentation
- Enhanced pagination documentation with detailed guidance on context conservation, cursor usage, and multi-page fetching strategies.
Tests
- Expanded test coverage for pagination logic, including default and custom page sizes, multi-page fetching, and cursor encoding consistency.
- Updated integration tests to enforce page size limits and verify pagination metadata presence.

coderabbitai · 2025-07-04T22:31:02Z

Walkthrough

The codebase introduces a configurable page size for the nft_tokens_by_address tool, limiting the number of items returned per page and generating pagination cursors based on the last item in the returned slice. Configuration, documentation, and tests are updated to support and verify the new pagination mechanism.

Changes

File(s)	Change Summary
blockscout_mcp_server/config.py, .env.example, Dockerfile	Added `nft_page_size` config variable with default 10; updated env var docs and Dockerfile ENV accordingly.
blockscout_mcp_server/tools/address_tools.py	Refactored `nft_tokens_by_address` to slice API results to `nft_page_size` and generate cursor from last slice item.
tests/tools/test_address_tools_2.py	Enhanced and added tests for pagination slicing, cursor generation, and custom page size handling.
tests/integration/test_address_tools_integration.py	Updated integration test to assert response size is ≤ 10.
SPEC.md, .cursor/rules/110-new-mcp-tool.mdc	Revised documentation to clarify new pagination slicing and cursor derivation behavior.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant MCP_Server
    participant Blockscout_API

    Client->>MCP_Server: Request NFT tokens (with/without cursor)
    MCP_Server->>Blockscout_API: Fetch full page (e.g., 50 items)
    Blockscout_API-->>MCP_Server: Return items (up to 50)
    MCP_Server->>MCP_Server: Slice items to page size (e.g., 10)
    MCP_Server->>MCP_Server: Generate cursor from last item in slice
    MCP_Server-->>Client: Return sliced items + pagination cursor

Assessment against linked issues

Objective	Addressed	Explanation
Add `nft_page_size` config variable to `config.py` with default 10 (#124)	✅
Update Dockerfile and `.env.example` with `BLOCKSCOUT_NFT_PAGE_SIZE` env variable (#124)	✅
Refactor `nft_tokens_by_address` to slice response and generate cursor from last item in slice (#124)	✅
Update/expand unit and integration tests for slicing, cursor, and custom page size (#124)	✅
Update documentation in `SPEC.md` and `.cursor/rules/110-new-mcp-tool.mdc` for new pagination pattern (#124)	✅

Poem

In the garden of code, a page size was set,
Ten tokens per nibble, no more to beget.
The cursor now follows the last in the row,
So clients stay happy, and paginated flows grow.
🐇✨
"Hop, hop! Sliced neat, pagination's a treat!"

✨ Finishing Touches

📝 Generate Docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Explain this complex logic.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai explain this code block.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and explain its main purpose.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (2)

SPEC.md (2)
235-235: Markdown-lint warning: missing fenced-code language

markdownlint flags this fence (MD040). Although the block starts earlier with json, the closing fence is indented and the linter treats it as a new fence without a language. Out-dent the closing or add a dummy language to silence the warning.

Example:
-      ```
+```
237-244: New slicing section is clear but missing env-var cross-reference

Good explanation of the slicing logic. Consider explicitly linking the config key (nft_page_size) to its environment variable (BLOCKSCOUT_NFT_PAGE_SIZE) in this paragraph for quicker discoverability.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8bc668d and 638ecd9.

📒 Files selected for processing (2)

.cursor/rules/110-new-mcp-tool.mdc (1 hunks)
SPEC.md (4 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

.cursor/rules/110-new-mcp-tool.mdc

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/110-new-mcp-tool.mdc:0-0
Timestamp: 2025-07-04T20:22:01.652Z
Learning: Applies to blockscout_mcp_server/tools/*.py : Truncate large data fields in API responses and flag the truncation, providing guidance on how to retrieve the full data.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/110-new-mcp-tool.mdc:0-0
Timestamp: 2025-07-04T20:22:01.652Z
Learning: Applies to blockscout_mcp_server/tools/*.py : For paginated tools, do not expose individual pagination parameters; use a single, opaque cursor string and handle it with apply_cursor_to_params.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/110-new-mcp-tool.mdc:0-0
Timestamp: 2025-07-04T20:22:01.652Z
Learning: Applies to blockscout_mcp_server/tools/*.py : For paginated tools, include the exact notice '**SUPPORTS PAGINATION**: If response includes 'pagination' field, use the provided next_call to get additional pages.' in the docstring.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/220-integration-testing-guidelines.mdc:0-0
Timestamp: 2025-07-04T20:31:56.449Z
Learning: Applies to tests/integration/test_*_integration.py : Integration tests for cursor-based pagination must perform a two-step test: (1) call the tool without a cursor and extract the cursor from the response, (2) call the tool again with the cursor and assert that the second page's data is different from the first.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/220-integration-testing-guidelines.mdc:0-0
Timestamp: 2025-07-04T20:31:56.449Z
Learning: Applies to tests/integration/test_*_integration.py : Integration tests for paginated tools must use a loop with a max_pages_to_check limit to search across pages, and skip the test with a clear message if the target data is not found within the limit.

SPEC.md (13)

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/110-new-mcp-tool.mdc:0-0
Timestamp: 2025-07-04T20:22:01.652Z
Learning: Applies to blockscout_mcp_server/tools/*.py : For paginated tools, do not expose individual pagination parameters; use a single, opaque cursor string and handle it with apply_cursor_to_params.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/110-new-mcp-tool.mdc:0-0
Timestamp: 2025-07-04T20:22:01.652Z
Learning: Applies to blockscout_mcp_server/tools/*.py : For paginated tools, include the exact notice '**SUPPORTS PAGINATION**: If response includes 'pagination' field, use the provided next_call to get additional pages.' in the docstring.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/110-new-mcp-tool.mdc:0-0
Timestamp: 2025-07-04T20:22:01.652Z
Learning: Applies to blockscout_mcp_server/tools/*.py : Truncate large data fields in API responses and flag the truncation, providing guidance on how to retrieve the full data.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/900-rules-maintenance.mdc:0-0
Timestamp: 2025-07-04T20:35:06.699Z
Learning: Applies to .cursor/AGENTS.md : Update the corresponding guidance in the 'Rule Application Guidelines' section of `.cursor/AGENTS.md` to reflect the changes made to the rule file.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/130-version-management.mdc:0-0
Timestamp: 2025-07-04T20:25:11.247Z
Learning: Applies to blockscout_mcp_server/__init__.py : When updating the version of the MCP server, update the `__version__` variable in `blockscout_mcp_server/__init__.py`.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/110-new-mcp-tool.mdc:0-0
Timestamp: 2025-07-04T20:22:01.652Z
Learning: Applies to blockscout_mcp_server/tools/*.py : Simplify address objects in API responses to a single address string to save LLM context.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/110-new-mcp-tool.mdc:0-0
Timestamp: 2025-07-04T20:22:01.652Z
Learning: Applies to blockscout_mcp_server/tools/*.py : Recursively truncate nested data structures in API responses, replacing long strings with a structured object to signal truncation.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/000-role-and-task.mdc:0-0
Timestamp: 2025-07-04T20:18:25.785Z
Learning: Applies to **/*.py : The MCP server must wrap Blockscout APIs and expose blockchain data (balances, tokens, NFTs, contract metadata) via the Model Context Protocol (MCP)

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/130-version-management.mdc:0-0
Timestamp: 2025-07-04T20:25:11.247Z
Learning: Update both `pyproject.toml` and `blockscout_mcp_server/__init__.py` simultaneously to maintain consistency across the codebase.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-04T20:16:41.158Z
Learning: Read the project technical description in `SPEC.md` to clearly understand how the MCP server communicates with counterparties and important aspects of the server implementation before responding to a user request

Learnt from: CR
PR: blockscout/mcp-server#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-04T20:16:41.158Z
Learning: Read `.cursor/rules/010-implementation-rules.mdc` for general coding instructions before responding to a user request

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/220-integration-testing-guidelines.mdc:0-0
Timestamp: 2025-07-04T20:31:56.449Z
Learning: Applies to tests/integration/test_*_integration.py : Integration tests for cursor-based pagination must perform a two-step test: (1) call the tool without a cursor and extract the cursor from the response, (2) call the tool again with the cursor and assert that the second page's data is different from the first.

Learnt from: CR
PR: blockscout/mcp-server#0
File: .cursor/rules/110-new-mcp-tool.mdc:0-0
Timestamp: 2025-07-04T20:22:01.652Z
Learning: Applies to blockscout_mcp_server/tools/*.py : For tools that query Blockscout API, use dynamic chain resolution via get_blockscout_base_url and make_blockscout_request.

🪛 markdownlint-cli2 (0.17.2)

SPEC.md

235-235: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

⏰ Context from checks skipped due to timeout of 90000ms (1)

GitHub Check: Docker build and docker push

🔇 Additional comments (2)

SPEC.md (2)

205-206: Mechanism paragraph – looks good

Clear, technically accurate text that matches the implementation (apply_cursor_to_params). No action needed.

179-180: Invalid JSON example – extra brace breaks tooling copy-paste

The sample JSON now has one closing brace too many. Anyone copying it into a linter / example request will get a parse error.
-      }
-      ```
+    }
+    ```
Removing the superfluous brace keeps the example syntactically valid.

Likely an incorrect or invalid review comment.

Copilot

Pull Request Overview

This PR introduces a configurable page size for the nft_tokens_by_address tool, slices API responses accordingly, and updates all related tests, docs, and environment settings.

Adds nft_page_size to configuration, .env, and Dockerfile
Implements response slicing and custom cursor generation in address_tools.py
Updates unit/integration tests and SPEC.md to reflect the new pagination pattern

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/tools/test_address_tools_2.py	Adjusted unit tests to cover default slicing and custom page sizes
tests/integration/test_address_tools_integration.py	Tightened integration test to assert slice length ≤ page size
blockscout_mcp_server/tools/address_tools.py	Added slicing logic based on `config.nft_page_size` and new cursor logic
blockscout_mcp_server/config.py	Introduced `nft_page_size` setting
SPEC.md	Documented the response slicing and context-aware pagination pattern
Dockerfile	Exposed `BLOCKSCOUT_NFT_PAGE_SIZE` environment variable
.env.example	Added example entry for `BLOCKSCOUT_NFT_PAGE_SIZE`
.cursor/rules/110-new-mcp-tool.mdc	Updated example code snippet to illustrate per-tool pagination

Comments suppressed due to low confidence (2)

tests/tools/test_address_tools_2.py:346

Add an assertion on len(result.data) (e.g., assert len(result.data) == config.nft_page_size) to verify that the slicing behavior returns the expected number of items.

        result = await nft_tokens_by_address(chain_id=chain_id, address=address, ctx=mock_ctx)

.cursor/rules/110-new-mcp-tool.mdc:400

The example snippet still uses a hard-coded PAGE_SIZE. Consider showing how to read a per-tool page size from your configuration (e.g., config.nft_page_size) to align with project conventions.

    PAGE_SIZE = 10 # This should be a configurable value per-tool

blockscout_mcp_server/tools/address_tools.py

coderabbitai

Actionable comments posted: 0

🔭 Outside diff range comments (2)

tests/tools/test_transaction_tools_3.py (2)
319-319: Fix inconsistent variable naming.

The variable should be renamed from hash to tx_hash to maintain consistency with the rest of the file and avoid shadowing the built-in hash() function.

Apply this diff to fix the inconsistency:
-    hash = "0xabc123"
+    tx_hash = "0xabc123"
327-327: Update the function call to use the renamed variable.

Since the variable should be renamed to tx_hash, update the function call accordingly.

Apply this diff:
-            await get_transaction_logs(chain_id=chain_id, transaction_hash=hash, cursor=invalid_cursor, ctx=mock_ctx)
+            await get_transaction_logs(chain_id=chain_id, transaction_hash=tx_hash, cursor=invalid_cursor, ctx=mock_ctx)

♻️ Duplicate comments (1)

blockscout_mcp_server/tools/address_tools.py (1)

205-220: NFT pagination correctly implements configurable page size.

The implementation properly slices items based on the configured nft_page_size and constructs pagination parameters from the last item in the sliced list.

Note: The hard-coded value 50 on line 218 has been previously flagged and will be addressed in a future update.

🧹 Nitpick comments (3)

.cursor/rules/110-new-mcp-tool.mdc (1)

356-397: Well-designed pagination pattern that balances API efficiency with LLM context constraints.

The new context conservation strategy and page size configuration approach is excellent. The separation between API fetch size and LLM response size addresses a real problem.

Consider adding guidance on choosing appropriate page sizes based on typical item complexity (e.g., "For simple items like addresses, 20-30 is reasonable; for complex items with nested data, 5-10 may be better").
blockscout_mcp_server/tools/transaction_tools.py (2)
122-208: Excellent implementation of smart pagination for sparse filtered data.

The function elegantly handles the challenge of accumulating enough filtered items across multiple API pages. The progress reporting integration and the logic for determining has_more_pages are well-thought-out.

Consider making max_pages_to_fetch configurable via config to allow tuning for different deployment scenarios:
+    max_pages_to_fetch: int = config.smart_pagination_max_pages,  # Default could be 10 in config
-    max_pages_to_fetch: int = 10,  # Prevent infinite loops
585-602: Consider simplifying the address extraction logic for better readability.

While the current logic is correct, it could be more readable.
-        address_value = (
-            item.get("address", {}).get("hash") if isinstance(item.get("address"), dict) else item.get("address")
-        )
+        address_obj = item.get("address")
+        address_value = address_obj.get("hash") if isinstance(address_obj, dict) else address_obj

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 638ecd9 and 157ef08.

📒 Files selected for processing (19)

.cursor/rules/110-new-mcp-tool.mdc (3 hunks)
.cursor/rules/210-unit-testing-guidelines.mdc (3 hunks)
.env.example (1 hunks)
AGENTS.md (3 hunks)
Dockerfile (1 hunks)
SPEC.md (4 hunks)
blockscout_mcp_server/config.py (1 hunks)
blockscout_mcp_server/tools/address_tools.py (7 hunks)
blockscout_mcp_server/tools/common.py (2 hunks)
blockscout_mcp_server/tools/transaction_tools.py (9 hunks)
tests/integration/test_address_tools_integration.py (2 hunks)
tests/integration/test_transaction_tools_integration.py (4 hunks)
tests/tools/test_address_logs.py (3 hunks)
tests/tools/test_common.py (2 hunks)
tests/tools/test_transaction_tools.py (15 hunks)
tests/tools/test_transaction_tools_2.py (4 hunks)
tests/tools/test_transaction_tools_3.py (19 hunks)
tests/tools/test_transaction_tools_helpers.py (1 hunks)
tests/tools/test_transaction_tools_pagination.py (1 hunks)

✅ Files skipped from review due to trivial changes (1)

tests/tools/test_transaction_tools_2.py

🚧 Files skipped from review as they are similar to previous changes (3)

Dockerfile
blockscout_mcp_server/config.py
tests/integration/test_address_tools_integration.py

🧰 Additional context used

📓 Path-based instructions (13)

`.env.example`: Add new API environment variables to .env.example when introducing a new endpoint.

.env.example: Add new API environment variables to .env.example when introducing a new endpoint.

📄 Source: CodeRabbit Inference Engine (.cursor/rules/110-new-mcp-tool.mdc)