feat: Add LLM provider adapter documentation and examp

[dgenio]

Summary

This PR addresses #235 by providing comprehensive documentation and examples for creating adapters that convert MCP tool schemas to various LLM provider formats (Gemini, OpenAI, Claude).

Changes

• New documentation page (docs/llm-adapters.md): Comprehensive guide covering:

  • Basic adapter patterns
  • Complete implementations for Gemini, OpenAI, and Anthropic Claude
  • Advanced schema transformations (nested objects, arrays, enums)
  • Error handling patterns
  • Best practices

• Runnable example (examples/snippets/clients/llm_adapter_example.py): Demonstrates:

  • Connecting to MCP servers
  • Listing and converting tools
  • Batch conversion with error handling
  • Validation utilities

• Documentation updates: Added references in:

  • docs/index.md - Getting Started section
  • README.md - Advanced Usage and Documentation sections
  • mkdocs.yml - Navigation menu

Design Decision

Following maintainer feedback, this PR provides documentation and examples rather than official adapter utilities. This approach:

• Makes it easy for developers to create adapters
• Avoids maintenance burden of third-party SDK dependencies
• Provides clear patterns and best practices
• Includes working examples for all three major providers

Testing

• ✅ All files pass linting (ruff, pyright)
• ✅ Documentation follows mkdocs format
• ✅ Example script is registered and runnable
• ✅ No breaking changes (documentation only)

Related

Closes #235

[dgenio]

Hi — I'm the author of this PR. After reviewing the current state of main, here's what I found:

Merge status: The PR will have merge conflicts in README.md and possibly examples/snippets/pyproject.toml due to upstream line shifts, but the core new files (docs/llm-adapters.md and the example) are unaffected.

Issues I plan to fix in a rebase:

1. Too much code in README.md — The full ~500-line adapter example is embedded via snippet-source. I'll trim this to a brief section with a link to the docs page instead.
2. Duplicate link — The "See the LLM Provider Adapters guide" link appears twice in quick succession.
3. Stale naming — The example references fastmcp_quickstart which should be updated to reflect the FastMCP → MCPServer rename.
4. import json inside function body — This appears 3 times in the example; will move to top-level imports per project guidelines.

The core content (docs/llm-adapters.md guide and the example file) is solid and directly matches @felixweinberger's guidance on issue #235 ("maybe with an example in documentation"). I'll rebase and clean up shortly.

[maxisbey]

Thanks for the PR. The v2 rework changed the code this targets, so it no longer applies as-is. Closing as part of a general backlog cleanup following the v2 release. If this is still relevant against v2, feel free to reopen.

_{AI Disclaimer}