feat: usage-aware tool ranking for LLM agent discovery - #43

Summary

Implements the feature described in #31: track tool invocations locally and use that data to rank --list output, reducing token costs for LLM agents working with large MCP servers.

• --sort usage|recent|alpha|default -- control list ordering by call frequency, recency, alphabetical, or insertion order
• --top N -- show only the top N tools (the key feature for agents: --list --top 10 --compact yields ~20 tokens instead of ~1,400)
• --compact -- space-separated tool names only, no descriptions

Usage data is stored in ~/.cache/mcp2cli/usage.json with the format from the issue. Last-write-wins for file locking per maintainer approval. When usage data exists for a source, the default sort is usage; otherwise insertion order is preserved.

Design decisions (per discussion in #31)

1. Single module -- all code stays in __init__.py as approved
2. Last-write-wins -- no fcntl or sqlite, simple JSON read/write
3. Default to usage sort when usage data exists for the source

Hooks

Usage is recorded after successful execution in:

• handle_mcp() -- MCP HTTP and stdio modes
• _handle_openapi_mode() -- OpenAPI mode
• handle_graphql() -- GraphQL mode

LLM agent workflow

# Before: ~1,400 tokens for 96 tools
mcp2cli @myapi --list

# After: ~20 tokens for the 10 most-used tools
mcp2cli @myapi --list --top 10 --compact

Test plan

• 24 new tests in tests/test_usage.py covering:
  • Usage file load/save/corruption handling
  • Recording usage (increment, multiple tools, multiple sources)
  • Source hash determinism
  • All four sort modes (default, alpha, usage, recent)
  • --compact output for MCP, OpenAPI, and GraphQL listing
  • --top N truncation
  • Combined --sort + --top + --compact
• All 112 existing tests pass (2 pre-existing failures in test_helpers.py::TestCaching unrelated to this PR)

Closes #31