Merge pull request #231 from jlowin/contrib

Ensure contrib is importable

docs/docs.json

@@ -61,7 +61,8 @@
                     "patterns/composition",
                     "patterns/decorating-methods",
                     "patterns/openapi",
-                    "patterns/fastapi"
+                    "patterns/fastapi",
+                    "patterns/contrib"
                 ]
             },
             {

docs/patterns/contrib.mdx

@@ -0,0 +1,42 @@
+---
+title: "Contrib Modules"
+description: "Community-contributed modules extending FastMCP"
+icon: "cubes"
+---
+
+
+FastMCP includes a `contrib` package that holds community-contributed modules. These modules extend FastMCP's functionality but aren't officially maintained by the core team.
+
+Contrib modules provide additional features, integrations, or patterns that complement the core FastMCP library. They offer a way for the community to share useful extensions while keeping the core library focused and maintainable.
+
+The available modules can be viewed in the [contrib directory](https://github.com/jlowin/fastmcp/tree/main/src/contrib).
+
+## Usage
+
+To use a contrib module, import it from the `fastmcp.contrib` package:
+
+```python
+from fastmcp.contrib import my_module
+```
+
+## Important Considerations
+
+- **Stability**: Modules in `contrib` may have different testing requirements or stability guarantees compared to the core library.
+- **Compatibility**: Changes to core FastMCP might break modules in `contrib` without explicit warnings in the main changelog.
+- **Dependencies**: Contrib modules may have additional dependencies not required by the core library. These dependencies are typically documented in the module's README or separate requirements files.
+
+## Contributing
+
+We welcome contributions to the `contrib` package! If you have a module that extends FastMCP in a useful way, consider contributing it:
+
+1. Create a new directory in `src/fastmcp/contrib/` for your module
+3. Add proper tests for your module in `tests/contrib/`
+2. Include comprehensive documentation in a README.md file, including usage and examples, as well as any additional dependencies or installation instructions
+5. Submit a pull request
+
+The ideal contrib module:
+- Solves a specific use case or integration need
+- Follows FastMCP coding standards
+- Includes thorough documentation and examples
+- Has comprehensive tests
+- Specifies any additional dependencies

src/fastmcp/contrib/README.md

@@ -6,4 +6,14 @@ This directory holds community-contributed modules for FastMCP. These modules ex
 *   Modules in `contrib` may have different testing requirements or stability guarantees compared to the core library.
 *   Changes to the core FastMCP library might break modules in `contrib` without explicit warnings in the main changelog.
 
-Use these modules at your own discretion. Contributions are welcome, but please include tests and documentation.
+Use these modules at your own discretion. Contributions are welcome, but please include tests and documentation.
+
+## Usage
+
+To use a contrib module, import it from the `fastmcp.contrib` package.
+
+```python
+from fastmcp.contrib import my_module
+```
+
+Note that the contrib modules may have different dependencies than the core library, which can be noted in their respective README's or even separate requirements / dependency files.

src/fastmcp/contrib/bulk_tool_caller/bulk_tool_caller.py

@@ -3,10 +3,14 @@ from typing import Any
 from mcp.types import CallToolResult
 from pydantic import BaseModel, Field
 
-from contrib.mcp_mixin.mcp_mixin import _DEFAULT_SEPARATOR_TOOL, MCPMixin, mcp_tool
 from fastmcp import FastMCP
 from fastmcp.client import Client
 from fastmcp.client.transports import FastMCPTransport
+from fastmcp.contrib.mcp_mixin.mcp_mixin import (
+    _DEFAULT_SEPARATOR_TOOL,
+    MCPMixin,
+    mcp_tool,
+)
 
 
 class CallToolRequest(BaseModel):

src/fastmcp/contrib/bulk_tool_caller/example.py

@@ -1,7 +1,7 @@
 """Sample code for FastMCP using MCPMixin."""
 
-from contrib.bulk_tool_caller import BulkToolCaller
 from fastmcp import FastMCP
+from fastmcp.contrib.bulk_tool_caller import BulkToolCaller
 
 mcp = FastMCP()
 

src/fastmcp/contrib/mcp_mixin/README.md

@@ -10,7 +10,7 @@ Inherit from `MCPMixin` and use the decorators on the methods you want to regist
 
 ```python
 from fastmcp import FastMCP
-from contrib.mcp_mixin import MCPMixin, mcp_tool, mcp_resource
+from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool, mcp_resource
 
 class MyComponent(MCPMixin):
     @mcp_tool(name="my_tool", description="Does something cool.")

src/fastmcp/contrib/mcp_mixin/example.py

@@ -2,13 +2,13 @@
 
 import asyncio
 
-from contrib.mcp_mixin import (
+from fastmcp import FastMCP
+from fastmcp.contrib.mcp_mixin import (
     MCPMixin,
     mcp_prompt,
     mcp_resource,
     mcp_tool,
 )
-from fastmcp import FastMCP
 
 mcp = FastMCP()
 

tests/contrib/test_bulk_tool_caller.py

@@ -3,12 +3,12 @@ from typing import Any
 import pytest
 from mcp.types import EmbeddedResource, ImageContent, TextContent
 
-from contrib.bulk_tool_caller.bulk_tool_caller import (
+from fastmcp import FastMCP
+from fastmcp.contrib.bulk_tool_caller.bulk_tool_caller import (
     BulkToolCaller,
     CallToolRequest,
     CallToolRequestResult,
 )
-from fastmcp import FastMCP
 
 ContentType = TextContent | ImageContent | EmbeddedResource
 

tests/contrib/test_mcp_mixin.py

@@ -2,18 +2,18 @@
 
 import pytest
 
-from contrib.mcp_mixin import (
+from fastmcp import FastMCP
+from fastmcp.contrib.mcp_mixin import (
     MCPMixin,
     mcp_prompt,
     mcp_resource,
     mcp_tool,
 )
-from contrib.mcp_mixin.mcp_mixin import (
+from fastmcp.contrib.mcp_mixin.mcp_mixin import (
     _DEFAULT_SEPARATOR_PROMPT,
     _DEFAULT_SEPARATOR_RESOURCE,
     _DEFAULT_SEPARATOR_TOOL,
 )
-from fastmcp import FastMCP
 
 
 class TestMCPMixin: