feat(mcp): selective tool registration via --tools / --exclude-tools

[codemug]

Summary

177 MCP tools across 22 categories is a lot of surface area for an AI agent to reason about. This PR adds a small spec grammar that lets users restrict which tools the MCP server exposes, with both category-level and per-tool granularity.

• --tools / --exclude-tools CLI flags (env equivalents: AIOFMP_MCP_TOOLS / AIOFMP_MCP_EXCLUDE_TOOLS). When both are set, --tools defines the universe and --exclude-tools prunes from it.
• --list-tools prints the inventory and exits — no FMP_API_KEY required.
• Spec grammar mixes category and per-tool selection in one comma-separated list:
  • chart or chart(*) — whole category
  • chart(get_intraday_1hour) — single tool
  • chart(t1,t2),quote(*),search — mix freely
  • * — every tool (default)

Design

• aiofmp/mcp_selection.py discovers the inventory by AST-scanning *_tools.py modules. No imports during validation, so --list-tools and CLI errors don't side-effect the global mcp instance.
• register_tools() imports only the categories present in the effective selection, then calls mcp.remove_tool() for tools outside each category's allow-set.
• CLI validates the spec via click.UsageError so bad inputs fail fast with the valid category/tool list.
• Default behavior (no flags) is unchanged: all 177 tools register.

Files

• aiofmp/mcp_selection.py (new) — inventory + spec parser + selection compute
• aiofmp/mcp_server.py — register_tools() refactor, env-var resolution
• aiofmp/cli.py — new flags + --list-tools short-circuit
• tests/test_mcp_selection.py (new) — 34 tests for inventory, parser, selection compute, formatter
• tests/test_cli_mcp_server.py (new) — 6 tests for CLI surface + validation
• tests/test_mcp_server.py — 6 new tests for env-var resolution + register_tools() mocking
• README.md — new "Selective Tool Registration" section + flags in CLI Reference + env vars in the table
• CHANGELOG.md — backfilled from history (1.0.0 → 1.1.0 → 1.2.0) + Unreleased entry

Test plan

• pytest — 928 passed (40 new)
• ruff check — clean
• ruff format --check — clean
• Manual smoke: aiofmp-mcp-server --list-tools prints inventory, --tools bogus exits non-zero with the valid category list

🤖 Generated with Claude Code