feat(adapters): FastMCP Catalog bridge — auto-ingest tools from FastMCP servers (#114)

[dgenio]

Summary

Closes #114

Adds adapters/fastmcp.py — a bridge between FastMCP servers and contextweaver Catalog objects. Converts FastMCP tool definitions into SelectableItems with namespace inference, tag mapping, and schema preservation, and provides live server discovery via the FastMCP Client.

What changed

• src/contextweaver/adapters/fastmcp.py (new) — core module with:
  • infer_fastmcp_namespace() — 2-segment namespace inference matching FastMCP's {namespace}_{name} composition convention (vs 3+ in the generic MCP adapter)
  • fastmcp_tool_to_selectable() — convert tool definition dicts to SelectableItem, delegating annotation/schema parsing to the existing mcp_tool_to_selectable(), then adjusting id, namespace, name, and tags
  • fastmcp_tools_to_catalog() — batch-convert to a populated Catalog
  • load_fastmcp_catalog() — async live discovery from any FastMCP source (server instance, URL, file path, config dict, existing Client) via tools/list
• src/contextweaver/adapters/__init__.py — re-exports new public names
• pyproject.toml — adds contextweaver[fastmcp] optional extra (fastmcp>=2.0)
• tests/test_adapters.py — 22 new tests: namespace inference, tag mapping, schema preservation, annotations, catalog building, import guard
• examples/fastmcp_adapter_demo.py (new) — standalone example showing namespace inference, tool conversion, catalog building, filtering, and hydration
• CHANGELOG.md — entry under [Unreleased] / Added

Why

FastMCP powers ~70% of MCP servers. Without a direct bridge, users must manually convert each tool definition—this friction blocks adoption. The adapter reuses mcp_tool_to_selectable() internally and adds FastMCP-specific namespace inference and tag mapping on top.

How verified

ruff format src/ tests/ examples/   → 84 files left unchanged
ruff check src/ tests/ examples/    → All checks passed!
mypy src/                           → Success: no issues found in 42 source files
pytest -q tests/test_adapters.py    → 90 passed in 0.27s
pytest -q                           → 563 passed in 6.13s
python examples/fastmcp_adapter_demo.py → runs successfully
python -m contextweaver demo         → runs successfully
All 10 example scripts               → run successfully

Tradeoffs / risks

• infer_fastmcp_namespace accepts 2-segment underscore names (e.g. github_search → ns=github), which is more aggressive than the generic MCP heuristic. This matches FastMCP composition conventions but may over-infer for non-FastMCP tools — users can pass namespace= to override.
• load_fastmcp_catalog is async (matching the context/ async-first convention). Callers in sync contexts need asyncio.run().
• Module is 271 lines (under the 300-line limit).

Checklist

• Tests added/updated for every new/changed public function
• make ci targets pass locally (fmt, lint, type, test, example, demo)
• CHANGELOG.md updated under [Unreleased]
• Google-style docstrings for all new public APIs
• Module ≤ 300 lines (271 lines)
• Related issue linked ([adapters] FastMCP Catalog bridge — auto-ingest tools from FastMCP servers #114)
• No print() in library code
• No business logic in __init__.py

[Copilot]

Pull request overview

Adds a FastMCP-to-Catalog adapter so FastMCP servers (and their tools/list outputs) can be converted into contextweaver SelectableItems and loaded into a Catalog, with an optional extra for live discovery via fastmcp.Client.

Changes:

• Introduces src/contextweaver/adapters/fastmcp.py with namespace inference, tool conversion, catalog building, and async live discovery.
• Exposes the new adapter functions via src/contextweaver/adapters/__init__.py and adds a fastmcp optional extra in pyproject.toml.
• Adds FastMCP-focused tests and an example demo script, plus a CHANGELOG entry.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/contextweaver/adapters/fastmcp.py	New FastMCP adapter (namespace inference, conversion, catalog creation, async discovery).
src/contextweaver/adapters/__init__.py	Re-exports FastMCP adapter public API.
pyproject.toml	Adds contextweaver[fastmcp] optional dependency group.
tests/test_adapters.py	Adds tests for FastMCP namespace inference, conversion, catalog building, and import guard.
examples/fastmcp_adapter_demo.py	Adds a standalone demo for dict-based conversion and catalog usage.
CHANGELOG.md	Documents the new adapter under [Unreleased].