Testing MCP Tools

PROJECT CONTEXT:
My MCP server works until it does not - host updates, schema drift, and edge inputs break it silently. The best MCP codebases treat tools as testable functions with protocol-level and contract-level suites on top.

GOAL:
Build a three-layer test suite for my MCP server: handler unit tests, protocol surface tests, and host contract tests wired into CI.

REQUIREMENTS:
- Unit tests for every tool handler: happy paths, validation rejections, error conversion
- Protocol tests: initialization, tool listing, invocation, and error responses over the transport
- Contract tests pinning the tool surface (names, schemas, descriptions) against golden files
- Regression cases for every bug found in host integration
- The suite running in CI on every change

CONSTRAINTS:
- Handlers must be testable without the transport - separate logic from protocol glue
- Golden-file changes require an explicit, reviewed update - surface drift is a decision

DEFINITION OF DONE:
- Every handler has happy, invalid-input, and internal-error tests
- Protocol tests pass against the running server, not mocks alone
- A deliberate schema change fails the contract test until goldens are updated
- CI blocks merges on any suite failure

COMMON FAILURES TO AVOID:
- Testing handlers only, missing serialization and protocol bugs entirely
- No contract pinning, so tool renames silently break every downstream host
- Bugs fixed without regression tests, returning two releases later
- A suite that exists but does not run automatically