Phase 4: Query tools implementation

[evansenter]

Summary

Implements all query MCP tools for session analytics:

• query_tool_frequency - Tool usage counts with project filter
• query_timeline - Events in time window with filtering by tool/project
• query_commands - Bash command breakdown with prefix filter
• query_sessions - Session metadata with token totals
• query_tokens - Token usage grouped by day/session/model

Also adds:

• ensure_fresh_data() - Auto-refresh mechanism that checks data staleness (>5 min old) and refreshes transparently before queries
• Comprehensive tests for all queries (18 new tests, 53 total)

Test plan

• Run make check - all 53 tests pass
• Verify query_tool_frequency returns tool counts
• Verify query_timeline respects time ranges and filters
• Verify query_commands with prefix filter
• Verify query_sessions returns session metadata
• Verify query_tokens supports all grouping modes (day/session/model)

Closes #4

🤖 Generated with Claude Code

[claude]

Pull Request Review: Phase 4 Query Tools Implementation

Overview

This PR implements comprehensive query tools for the session analytics MCP server with good architecture and solid test coverage. The implementation is well-structured and follows Python best practices.

---

✅ Code Quality & Best Practices

Strengths

1. Well-structured architecture: Clear separation of concerns across storage.py, queries.py, ingest.py, and server.py
2. Good use of dataclasses: Event, Session, IngestionState, and Pattern models are clean and type-safe
3. Proper SQL parameterization: All queries use parameterized statements, avoiding SQL injection vulnerabilities
4. Comprehensive test coverage: 18 new tests covering all query functions with good edge case handling
5. Incremental ingestion: Smart file-based state tracking prevents redundant processing
6. Auto-refresh mechanism: ensure_fresh_data() provides good UX for stale data detection

Security Review

✅ No SQL Injection Vulnerabilities

All queries properly use parameterized SQL. User-supplied values (project, prefix, tool, etc.) are passed via params list, never interpolated into SQL strings.

✅ Path Traversal Protection

Database path uses Path.home() with hardcoded subdirectories. Log file discovery is constrained to ~/.claude/projects/ by default.

---

🐛 Potential Issues & Edge Cases

1. Race Condition in ensure_fresh_data() (Low severity)

Location: src/session_analytics/queries.py:33-40

If multiple queries run concurrently on stale data, they'll all trigger ingestion simultaneously. This could cause duplicate work and SQLite lock contention. For an MCP server handling sequential requests, this is low priority.

2. Timezone Handling (Low severity)

Location: src/session_analytics/ingest.py:133-135

Converting to naive datetime assumes local timezone. Document that all timestamps are stored in local timezone.

3. Empty UUID Handling (Low severity)

Location: src/session_analytics/ingest.py:270

For summary entries with missing uuid and leafUuid, creates "summary:unknown" which could collide. Recommend adding timestamp suffix for uniqueness.

4. F-string Query Construction (Documentation needed)

While SAFE in current implementation (where_clause is built from hardcoded strings only), add comments explaining this to prevent future bugs.

---

🚀 Performance Considerations

Good Practices

1. Batch inserts with executemany()
2. Proper indexing on filter columns
3. Query limits with sensible defaults
4. Incremental ingestion

Potential Optimizations

1. Session stats update (ingest.py:358-399) - Currently full table scan. For large DBs, consider updating only affected sessions.

2. LIKE queries (queries.py:65-66) - Leading % prevents index usage. Consider prefix matching if acceptable.

---

📋 Test Coverage

✅ Excellent Coverage

• 18 new tests for all query functions
• Good use of fixtures
• Covers basic functionality, filters, and edge cases

Suggestions for additional tests:

• Empty database edge cases
• Malformed JSONL handling
• Concurrent ingestion (if addressing race condition)

---

📝 Documentation

✅ Good Documentation

• guide.md with clear examples
• Comprehensive docstrings
• Clear README

Minor suggestions:

• Add example outputs to MCP tool docstrings
• Document error handling expectations

---

🎯 Summary & Recommendations

Critical Issues

None - Code is production-ready.

High Priority

1. Add comments explaining f-string SQL safety
2. Fix empty UUID handling for summary entries

Medium Priority

1. Document timezone handling
2. Optimize session stats for large DBs
3. Consider concurrent ingestion protection

Low Priority

1. Add example outputs to docstrings
2. Optimize LIKE queries
3. Add edge case tests

---

✅ Approval

Excellent work! Implementation is clean, secure, well-tested, and follows best practices. Issues identified are minor and don't block merging.

Recommendation: ✅ Approve and merge

The codebase demonstrates:

• Strong SQL security understanding
• Good architectural design
• Comprehensive testing (53 total tests)
• Production-ready error handling

Great job! 🚀

[evansenter]

Superseded by #19 which contains all Phase 1-7 work plus RFC #18 refactoring.