feat: Add upload_entries MCP tool and push CLI command

[evansenter]

Summary

Adds remote ingestion support for multi-machine setups (issue #93).

New MCP tool: upload_entries

• Accepts raw JSONL entries from client machines
• Parses server-side (so future parser improvements apply to all data)
• Deduplicates via existing UUID logic

New CLI command: push

• Reads local JSONL files
• Uploads to remote server via MCP HTTP
• Supports batching for large uploads

Usage

# Set remote URL
export AGENT_SESSION_ANALYTICS_URL=https://speck-vm.tailnet.ts.net/mcp

# Push last 7 days of session data
agent-session-analytics-cli push --days 7

# Or specify URL directly
agent-session-analytics-cli push --url https://server/mcp --days 30

Test plan

• make check passes (384 tests)
• Manual test: push from laptop to speck-vm once server is set up

Part of #93

🤖 Generated with Claude Code

[claude]

Prompt: evansenter/dotfiles/.../claude-review.md

Code Review

Summary

This PR adds remote ingestion support for multi-machine setups via a new upload_entries MCP tool and push CLI command. The implementation allows clients to read local JSONL files and upload them to a remote server over MCP HTTP.

Issues Found

Critical

None

Important

• tests/test_server.py - Missing test for upload_entries MCP tool. Per CLAUDE.md guidelines, new MCP tools should have corresponding tests (the file already imports and tests all other MCP tools).
• src/agent_session_analytics/guide.md - Missing documentation for upload_entries tool. Per CLAUDE.md: "Documentation in guide.md" is part of the endpoint checklist.
• src/agent_session_analytics/cli.py:1427-1470 - Missing upload_entries in benchmark. Per CLAUDE.md: "Add to benchmark: Update cmd_benchmark() in cli.py to include the new tool".

Suggestions

• src/agent_session_analytics/cli.py:1503 - Consider adding --json flag to cmd_push subparser for consistency with other CLI commands. Currently, format_output is called with args.json, but the subparser does not define this argument. This will cause an AttributeError when the function runs since args.json will not exist.
• src/agent_session_analytics/cli.py:1528-1530 - Silently skipping json.JSONDecodeError without any logging may make debugging difficult. Consider adding a logger.debug or incrementing an error counter that is reported in the output.

Verdict

REQUEST_CHANGES - Missing tests, documentation, and benchmark entry per CLAUDE.md guidelines. Also has a bug where args.json is used but not defined in the subparser.

---

Automated review by Claude Code

[claude]

Prompt: evansenter/dotfiles/.../claude-review.md

Code Review

Summary

This PR adds remote ingestion support for multi-machine setups via two new MCP tools (upload_entries and get_sync_status) and a push CLI command. The implementation allows clients to read local JSONL files and upload them to a remote server with incremental sync based on timestamps.

Issues Found

Critical

None

Important

• tests/test_server.py - Missing tests for upload_entries and get_sync_status MCP tools. Per CLAUDE.md: new MCP tools should have corresponding tests.
• src/agent_session_analytics/guide.md - Missing documentation for both new tools. Per CLAUDE.md: "Documentation in guide.md" is part of the endpoint checklist.
• src/agent_session_analytics/cli.py:1427-1470 - Missing get_sync_status and upload_entries in benchmark. Per CLAUDE.md: "Add to benchmark: Update cmd_benchmark() in cli.py to include the new tool". Note: These may be intentionally skipped since they modify data, but that should be documented in the "Skipped tools" comment at line 1472.

Suggestions

• src/agent_session_analytics/cli.py:1580-1583 - Silently skipping json.JSONDecodeError without incrementing a counter may make debugging difficult. Consider tracking these parse errors and including them in the output (similar to how parse_errors is tracked for the upload response).

Previously Addressed (Filtered)

• src/agent_session_analytics/cli.py:1503 - The previous review incorrectly flagged args.json as undefined. The --json flag is correctly defined on the parent parser (line 1698) and is inherited by all subcommands via parser.parse_args().

1 item from prior feedback rounds was not re-raised (was incorrect).

Verdict

REQUEST_CHANGES - Missing tests, documentation, and benchmark entry per CLAUDE.md guidelines.

---

Automated review by Claude Code

[claude]

Prompt: evansenter/dotfiles/.../claude-review.md

Code Review

Summary

This PR adds remote ingestion support for multi-machine setups via two new MCP tools (upload_entries and get_sync_status) and a push CLI command. The implementation allows clients to read local JSONL files and upload them to a remote server with incremental sync based on timestamps.

Issues Found

Critical

None

Important

None

Suggestions

None

Previously Addressed (Filtered)

• tests/test_server.py - Missing tests for MCP tools (Implemented: 4 tests added)
• src/agent_session_analytics/guide.md - Missing documentation for tools (Implemented: Remote Sync section added)
• src/agent_session_analytics/cli.py:1476 - Missing benchmark entry (Implemented: documented in skipped tools comment)
• src/agent_session_analytics/cli.py:1580 - Silent JSON parse errors (Implemented: local_parse_errors counter added)
• src/agent_session_analytics/cli.py:1503 - args.json undefined (Invalid: --json is on parent parser)

5 items from prior feedback rounds were not re-raised.

Verdict

APPROVE - All previous feedback has been addressed. The implementation is clean, secure (uses parameterized queries), well-tested, and properly documented. The PR correctly marks itself as "Part of #93" since hook integration and TAILSCALE_SETUP.md documentation are separate tasks.

---

Automated review by Claude Code

[evansenter]

Feedback Addressed

Implemented

• [Important] Missing tests for new MCP tools - Added test_get_sync_status and test_upload_entries in test_server.py
• [Important] Missing guide.md documentation - Added "Remote Sync (Multi-Machine)" section with usage examples
• [Suggestion] Missing benchmark entry - Added comment noting sync tools are skipped (they require remote server)
• [Suggestion] Silent JSON decode errors not counted - Added local_parse_errors counter to push command output

[claude]

Prompt: evansenter/dotfiles/.../claude-review.md

Code Review

Summary

This PR adds remote ingestion support for multi-machine setups via two new MCP tools (upload_entries and get_sync_status) and a push CLI command. Clients can read local JSONL files and upload them to a remote server with incremental sync based on timestamps.

Issues Found

Critical

None

Important

None

Suggestions

None

Previously Addressed (Filtered)

• tests/test_server.py - Missing tests for MCP tools (Implemented: 4 tests added)
• src/agent_session_analytics/guide.md - Missing documentation for tools (Implemented: Remote Sync section added)
• src/agent_session_analytics/cli.py:1476 - Missing benchmark entry (Implemented: documented in skipped tools comment)
• src/agent_session_analytics/cli.py - Silent JSON parse errors (Implemented: local_parse_errors counter added)

4 items from prior feedback rounds were not re-raised.

Verdict

APPROVE - All previous feedback has been addressed. The implementation is clean: uses parameterized SQL queries, has proper error handling with logging, includes 4 tests for the new functionality, and is well documented in guide.md.

---

Automated review by Claude Code