feat: add Reports API tools (person assignments, assignable people, overdue)

[schmunk42]

What

Adds three read-only MCP tools wrapping the Basecamp Reports API:

Tool	Endpoint
get_assignable_people	GET /reports/todos/assigned.json
get_person_assignments	GET /reports/todos/assigned/{person_id}.json (optional group_by: bucket|date)
get_overdue_todos	GET /reports/todos/overdue.json

Why

get_person_assignments is the API counterpart of the web report at /reports/todos/assigned/{person_id} and returns one person's active, pending to-dos across all projects in a single call. Without it, answering "what is assigned to person X?" requires iterating every project and todolist — slow, and projects missed by the iteration silently read as "no assignments" (false negatives in downstream reporting).

get_assignable_people provides the person IDs to feed into the report; get_overdue_todos is the third report endpoint of the same API section.

Implementation notes

• All three tools are read-only (get_* naming, consistent with the existing toolset).
• get_assignable_people uses the shared get_all_pages pagination helper.
• The per-person report returns a single JSON object (person, grouped_by, todos); the embedded todos list follows Link-header pagination defensively and merges pages into one report, guarded by MAX_PAGES.
• Error handling mirrors the existing tools (auth check, 401-expired hint).

Tests

tests/test_assignment_reports.py — endpoint/params wiring, group_by pass-through, multi-page merge, non-200 errors, MAX_PAGES cap. Full suite: 75 passed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added Reports API–backed tools for assignable people, person assignment to-dos across projects, and overdue to-dos.
  • Person assignment reports support optional grouping by bucket or due date.
  • Reports aggregate paginated results into a single response with consistent summary fields and counts.
• Documentation
  • Updated the changelog and README tool listings to document the new Reports tools and usage details.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0eb3b9cd-2a89-4df5-92b7-341d772568f1

📥 Commits

Reviewing files that changed from the base of the PR and between 5a70e18 and f98312f.

📒 Files selected for processing (2)

• basecamp_client.py
• basecamp_fastmcp.py

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

• basecamp_client.py
• basecamp_fastmcp.py

---

📝 Walkthrough

Walkthrough

Adds three Reports API-backed Basecamp MCP tools for assignable people, person assignments, and overdue todos, with pagination aggregation, grouping support, authentication/error handling, documentation, and unit tests.

Changes

Reports API integration

Layer / File(s)	Summary
Reports API client methods basecamp_client.py	Adds client methods for assignable people, per-person assignments with optional grouping and pagination merging, overdue todos, and explicit request timeouts.
FastMCP report tools basecamp_fastmcp.py, README.md, CHANGELOG.md	Exposes the three reports through authenticated asynchronous MCP tools, constrains grouping values, and documents the expanded tool set.
Report behavior validation tests/test_assignment_reports.py	Tests endpoints, query parameters, pagination limits and merging, returned report data, and error handling.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant FastMCPServer
  participant BasecampClient
  participant ReportsAPI
  FastMCPServer->>BasecampClient: request report data
  BasecampClient->>ReportsAPI: GET Reports API endpoint
  ReportsAPI-->>BasecampClient: JSON payload and Link header
  BasecampClient->>ReportsAPI: follow rel="next" pages
  BasecampClient-->>FastMCPServer: return aggregated report

Loading

Possibly related PRs

• georgeantonopoulos/Basecamp-MCP-Server#35: Both changes use Link-header pagination and a MAX_PAGES safeguard.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change by naming the new Reports API tools and the three added report types.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

basecamp_fastmcp.py (1)

303-303: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider constraining group_by to the two valid values.

The API only accepts 'bucket' or 'date' (per the docstring); typing this as Optional[Literal["bucket", "date"]] would let the MCP tool schema expose the valid enum to calling agents instead of an unconstrained string.

♻️ Proposed refactor

-async def get_person_assignments(person_id: str, group_by: Optional[str] = None) -> Dict[str, Any]:
+async def get_person_assignments(person_id: str, group_by: Optional[Literal["bucket", "date"]] = None) -> Dict[str, Any]:

(requires adding Literal to the typing import if not already present)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@basecamp_fastmcp.py` at line 303, Update the get_person_assignments signature
to type group_by as Optional[Literal["bucket", "date"]], adding Literal to the
typing imports if necessary, so the MCP schema exposes only the API-supported
values while preserving its optional behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@basecamp_client.py`:
- Around line 607-654: Update the shared get() HTTP helper to pass an explicit
requests timeout, using the established timeout pattern from download_upload or
download_attachment, so get_person_assignments and the other report methods
cannot block indefinitely. Preserve existing request behavior and error handling
while applying the timeout to every underlying GET call.

---

Nitpick comments:
In `@basecamp_fastmcp.py`:
- Line 303: Update the get_person_assignments signature to type group_by as
Optional[Literal["bucket", "date"]], adding Literal to the typing imports if
necessary, so the MCP schema exposes only the API-supported values while
preserving its optional behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 85f1cfb6-8bd4-48ea-bf4a-0ad85541fe4d

📥 Commits

Reviewing files that changed from the base of the PR and between 0084785 and 5a70e18.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• basecamp_client.py
• basecamp_fastmcp.py
• tests/test_assignment_reports.py

[georgeantonopoulos]

Thanks — the Reports API work is useful, and I confirmed CodeRabbit’s timeout and group_by concerns are resolved. One compatibility pass is required before merge:

• Add get_assignable_people, get_person_assignments, and get_overdue_todos to mcp_server_cli.py in both _get_available_tools() and _execute_tool(), matching the FastMCP schemas and response shapes (including group_by: bucket|date).
• Add focused CLI tests proving the tools appear in tools/list and dispatch correctly.
• Update the branch onto current main and resolve the CHANGELOG.md conflict, then let the Actions matrix run.

The CLI is legacy, but this repo explicitly keeps it for compatibility and tests, and recent public-tool changes update both entry points. The current head passes its 75 tests; this request is about maintaining that contract.