feat: initial fastmcp-extensions library implementation

[Aaron ("AJ") Steers (aaronsteers)]

Summary

Initial implementation of fastmcp-extensions, an unofficial extension library for FastMCP 2.0 that consolidates common patterns from Airbyte MCP servers.

Key features:

• MCP annotation constants (READ_ONLY_HINT, DESTRUCTIVE_HINT, IDEMPOTENT_HINT, OPEN_WORLD_HINT)
• Deferred registration decorators (@mcp_tool, @mcp_prompt, @mcp_resource) with automatic domain detection from module filename
• Registration utilities to register tools/prompts/resources with a FastMCP app, optionally filtered by domain
• Tool testing utilities for stdio and HTTP transports (in fastmcp_extensions.utils.testing)
• Tool list measurement utilities for tracking context size (in fastmcp_extensions.utils.measurement)
• Generic get_prompt_text helper for agents that can't access prompts directly

Dependencies: Only fastmcp>=2.2.7,<3.0 (near-zero dependency as requested)

Updates since last revision

• Testing module converted to package for -m syntax support - fastmcp_extensions.utils.testing is now a package with __main__.py, enabling direct CLI invocation via python -m fastmcp_extensions.utils.testing --app module:app <tool_name> '<json_args>'
• Added TK-TODO CI check workflow - New workflow that fails if any TK-TODO markers are found in the codebase, preventing accidental merges of unresolved TODOs (supports IGNORE:TK escape hatch)
• Moved testing/measurement utilities to utils/ submodule - Import paths changed from fastmcp_extensions.testing to fastmcp_extensions.utils.testing
• Deleted bin scripts - Template scripts removed; usage guidance is now in module docstrings
• Domain parameter removed from decorators - Domain is now ALWAYS auto-inferred from the calling module's filename (no override option)

Review & Testing Checklist for Human

• Review _get_caller_file_stem() in decorators.py - This walks the call stack to auto-detect domain from filename. Verify the stack frame logic handles edge cases (e.g., decorators applied in unusual contexts)
• Review CLI argument parsing in testing/__main__.py - Verify --app and --http --cmd flags work correctly for both stdio and HTTP transports
• Verify TK-TODO workflow correctly ignores its own references - The workflow file uses IGNORE:TK comments to suppress self-references
• Test with an actual MCP server - Verify the library works when integrated with a real FastMCP app (e.g., airbyte-ops-mcp)

Recommended test plan:

# Run unit tests
uv sync --extra dev
poe test

# Verify lint passes
poe lint

# Test CLI invocation (after installing in a project with an MCP server)
python -m fastmcp_extensions.utils.testing --help

# Integration test: Install in airbyte-ops-mcp and verify tools still work
cd ../airbyte-ops-mcp
uv add git+https://github.com/airbytehq/fastmcp-extensions@devin/1768613848-initial-library-implementation
poe mcp-tool-test list_connectors_in_repo '{}'

Notes

• This library extracts patterns that were duplicated across airbyte-ops-mcp and connector-builder-mcp
• The ToolDomain enum was intentionally NOT included - domain is now auto-inferred from module filename
• Usage guidance for testing/measurement utilities is in the module docstrings (see fastmcp_extensions/utils/testing/__init__.py and fastmcp_extensions/utils/measurement.py)

Link to Devin run: https://app.devin.ai/sessions/1fb5bdafcca747329006c5d526701a8c
Requested by: Aaron ("AJ") Steers (@aaronsteers)

[devin-ai-integration]

Original prompt from AJ Steers

Received message in Slack channel #ask-devin-ai:

@Devin - We've developed a library of patterns, practices, and utilities for fastmcp. I think we want to start to consolidate those into a (near-)zero-dependency helper library for fastmcp. I think we can call it `fastmcp-extensions` as an unofficial extension library for fastmcp 2.0.
Thread URL: https://airbytehq-team.slack.com/archives/C08BHPUMEPJ/p1768613362416599

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

🎉 Thanks for opening this pull request!

Your contribution is appreciated. Here are some helpful commands you can use:

Quick Commands

• /autofix - Auto-format and fix linting issues (ruff format + ruff check --fix)
• /lock - Update the uv.lock file with latest dependencies

Available Poe Tasks

You can run any of these tasks using the slash command: /poe <task-name>

Core Tasks

• /poe test - Run all tests
• /poe test-fast - Run tests with fast exit on first failure
• /poe lint - Check code style and quality
• /poe format - Format code with ruff
• /poe deps - Check for unused and missing dependencies
• /poe check - Run format check, linting, dependency check, and tests

Quick Fixes

• /poe fix - Auto-format and fix linting issues
• /poe clean - Clean up build artifacts and cache

Build & Install

• /poe build - Build the package
• /poe install - Install with development dependencies

Other Commands

• /poe version - Show package version
• /poe pre-commit - Run pre-commit style checks

The CI will automatically run tests when you push commits. Happy coding! 🚀

[Aaron ("AJ") Steers (aaronsteers)]

Can this comment be deleted now?

[devin-ai-integration]

Done - removed the comment.

[Aaron ("AJ") Steers (aaronsteers)]

Ditto. Delete this comment and delete the test pypi url reference at the bottom of this file. Our next PR will test the publish - and all code is correct as-is. No need for these remnants that are only necessary within the template repo itself.