Skip to content

docs(mcp): document execute_query max_rows default and result semantics - #129

Merged
codeasier merged 1 commit into
mainfrom
docs/issue-123-mcp-max-rows
Sep 17, 2026
Merged

codeasier merged 1 commit into
mainfrom
docs/issue-123-mcp-max-rows

Conversation

@codeasier

Copy link
Copy Markdown
Owner

📝 Description

The MCP execute_query tool is declared as execute_query(template, params=None, device_id=None, max_rows: int = 100), so it returns at most 100 rows by default, while pt-snap query prints every row unless -n is given. Neither docs/en/mcp.md nor docs/zh/mcp.md mentioned max_rows, and neither explained the total / returned / device_id / rows fields. An agent following the guide could read 100 rows and treat them as the complete result (for example when summing leaked bytes), unless it happened to notice total > returned.

The default difference is intentional (it keeps a large result from flooding an agent's context); it just needed to be written down. Same class of drift as #91 / #94.

Changes:

  • docs/en/mcp.md, docs/zh/mcp.md: new Query Results and Row Limits / 查询结果与行数限制 section with a field table, the CLI vs. MCP default difference, that total stays exact when the cap is hit (the service runs a COUNT(*)), the returned < total pattern with a paging example, and the min(limit, max_rows) interaction for templates that expose limit. The tools table row now states the default, and the example return shape includes device_id (which the tool actually returns).
  • docs/en/querying.md, docs/zh/querying.md: one-sentence cross-reference from the -n / output-format section back to the MCP behavior.
  • tests/test_mcp_server.py: test_execute_query_default_max_rows_caps_rows_but_keeps_exact_total inserts 150 leak candidates and asserts returned == 100, total == 150, and that max_rows=0 returns all 150 — so the documented behavior is pinned and future drift shows up in CI.

No production code changes.

🔗 Related Issue

Fixes #123

🧪 Testing

  • Tests added/updated
  • Manual testing completed

pytest tests/test_mcp_server.py tests/test_contract_cli_mcp.py: 24 passed. pytest tests/test_governance.py: 26 passed. Full suite (macOS, Python 3.13.11): 770 passed, 1 xfailed. Section anchors used by the cross-references exist in both languages. ruff check . / black --check . clean.

✅ Checklist

  • Code follows project guidelines
  • Documentation updated (if applicable)
  • No new warnings introduced
  • Changes tested locally

Snapshot Runtime Provenance

  • Snapshot provenance evaluation completed when snapshot runtime files change
    Snapshot provenance decision: no-update
    Snapshot provenance no-update reason: This PR changes only user documentation under docs/ and one MCP test; no files under src/pt_snap_cli/snapshot/ are touched.

📋 Additional Notes

docs/en/ and docs/zh/ were updated together to keep the behavioral descriptions aligned, per AGENTS.md Documentation Boundaries.

The MCP execute_query tool defaults to max_rows=100 while the CLI shows
every row unless -n is given, and the MCP guides never mentioned max_rows
or explained the total/returned/device_id/rows fields. An agent following
the guide could read 100 rows and treat them as the complete result.

Add a "Query Results and Row Limits" section to docs/en/mcp.md and
docs/zh/mcp.md covering the field meanings, the deliberate CLI/MCP default
difference, that total stays exact when the cap is hit, and how to lift or
page past the cap; note the default in the tools table and fix the example
return shape to include device_id. Cross-reference from the querying
guides' output-format sections. Pin the behavior with an MCP test that
inserts 150 leak candidates and checks returned == 100, total == 150, and
max_rows=0 returning everything.

Fixes #123
@codeasier
codeasier merged commit 4fe1faf into main Sep 17, 2026
6 checks passed
@codeasier
codeasier deleted the docs/issue-123-mcp-max-rows branch October 3, 2026 19:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCS] MCP 指南未说明 execute_query 的 max_rows 默认值为 100(CLI 默认无限制)及 total/returned 语义

1 participant