feat: Add pagination and reduce token usage in responses

[alexlmiller]

Summary

This PR addresses a significant issue with token consumption when using the TrueNAS MCP server with LLM clients. Initial list operations were consuming 40k+ tokens due to:

1. No pagination - list operations returned all items regardless of count
2. Raw API responses included by default - duplicating data in get operations
3. Recursive child datasets always included - creating large nested payloads

Changes

Pagination Support (all list operations):

• Added limit parameter (default: 100, max: 500)
• Added offset parameter for pagination
• Returns pagination metadata: {total, limit, offset, returned, has_more}

Affected tools:

• list_pools, list_datasets
• list_snapshots, list_snapshot_tasks
• list_apps, list_instances, list_legacy_vms
• list_smb_shares, list_nfs_exports, list_iscsi_targets
• list_users

Opt-in Raw Response:

• get_app, get_instance, get_legacy_vm now exclude raw field by default
• Added include_raw parameter (default: false) to restore if needed for debugging

Dataset Control:

• Added include_children parameter to list_datasets and get_dataset (default: true)
• Can be set to false to reduce payload for large dataset hierarchies

⚠️ Breaking Changes

This PR introduces intentional breaking changes to reduce token usage:

1. get_app, get_instance, get_legacy_vm: No longer include raw field by default

   • Migration: Use include_raw=true to restore previous behavior

2. All list operations: Now paginated by default (limit=100)

   • Migration: Use limit=500 for larger result sets, or implement pagination

Rationale

When using this MCP server with Claude or other LLM clients, excessive response sizes directly impact:

• Context window consumption
• Response latency
• Cost per interaction

With environments containing hundreds of snapshots, datasets, or users, the previous behavior was impractical for LLM use cases. These changes make the server significantly more efficient while maintaining full functionality through opt-in parameters.

Documentation

Updated README.md with a new "Pagination and Response Control" section documenting:

• Pagination parameters and response format
• include_raw usage guidelines
• include_children for datasets

Test plan

• Verify list operations return paginated results with metadata
• Test limit and offset parameters work correctly
• Confirm include_raw=true returns full API response
• Test include_children=false excludes child datasets
• Verify backwards compatibility for callers not using new parameters