refactor: move standard tool filters to dedicated tool_filters module

- Create tool_filters.py with all constants, config args, and public filter functions
- Define constants for config names, env vars, HTTP headers, and annotation keys
- Move STANDARD_CONFIG_ARGS and STANDARD_TOOL_FILTERS to tool_filters.py
- Rename middleware.py to _middleware.py to hide from public API
- Update __init__.py exports to include new public symbols
- Remove ToolFilterMiddleware from public exports (implementation detail)
- Update tests to import from correct modules

Co-Authored-By: AJ Steers <aj@airbyte.io>

Author: devin-ai-integration[bot]

src/fastmcp_extensions/__init__.py

@@ -11,6 +11,7 @@
 - Prompt text retrieval helpers
 """
 
+from fastmcp_extensions._middleware import ToolFilterFn
 from fastmcp_extensions.annotations import (
     DESTRUCTIVE_HINT,
     IDEMPOTENT_HINT,
@@ -22,10 +23,6 @@
     mcp_resource,
     mcp_tool,
 )
-from fastmcp_extensions.middleware import (
-    ToolFilterFn,
-    ToolFilterMiddleware,
-)
 from fastmcp_extensions.registration import (
     PromptDef,
     ResourceDef,
@@ -34,23 +31,71 @@
     register_mcp_tools,
 )
 from fastmcp_extensions.server import (
+    MCPServerConfig,
+    MCPServerConfigArg,
+    get_mcp_config,
+    mcp_server,
+)
+from fastmcp_extensions.tool_filters import (
+    # Constants - Annotation Keys
+    ANNOTATION_DESTRUCTIVE_HINT,
+    ANNOTATION_MCP_MODULE,
+    ANNOTATION_READ_ONLY_HINT,
+    # Constants - Config Names
+    CONFIG_EXCLUDE_MODULES,
+    CONFIG_EXCLUDE_TOOLS,
+    CONFIG_INCLUDE_MODULES,
+    CONFIG_NO_DESTRUCTIVE_TOOLS,
+    CONFIG_READONLY_MODE,
+    # Constants - Environment Variables
+    ENV_EXCLUDE_MODULES,
+    ENV_EXCLUDE_TOOLS,
+    ENV_INCLUDE_MODULES,
+    ENV_NO_DESTRUCTIVE_TOOLS,
+    ENV_READONLY_MODE,
+    # Config Args
     EXCLUDE_MODULES_CONFIG_ARG,
     EXCLUDE_TOOLS_CONFIG_ARG,
+    # Constants - HTTP Headers
+    HEADER_EXCLUDE_MODULES,
+    HEADER_EXCLUDE_TOOLS,
+    HEADER_INCLUDE_MODULES,
+    HEADER_NO_DESTRUCTIVE_TOOLS,
+    HEADER_READONLY_MODE,
     INCLUDE_MODULES_CONFIG_ARG,
     NO_DESTRUCTIVE_TOOLS_CONFIG_ARG,
     READONLY_MODE_CONFIG_ARG,
     STANDARD_CONFIG_ARGS,
     STANDARD_TOOL_FILTERS,
-    MCPServerConfig,
-    MCPServerConfigArg,
-    get_mcp_config,
-    mcp_server,
+    # Filter Functions
+    module_filter,
+    no_destructive_tools_filter,
+    readonly_mode_filter,
+    tool_exclusion_filter,
 )
 
 __all__ = [
+    "ANNOTATION_DESTRUCTIVE_HINT",
+    "ANNOTATION_MCP_MODULE",
+    "ANNOTATION_READ_ONLY_HINT",
+    "CONFIG_EXCLUDE_MODULES",
+    "CONFIG_EXCLUDE_TOOLS",
+    "CONFIG_INCLUDE_MODULES",
+    "CONFIG_NO_DESTRUCTIVE_TOOLS",
+    "CONFIG_READONLY_MODE",
     "DESTRUCTIVE_HINT",
+    "ENV_EXCLUDE_MODULES",
+    "ENV_EXCLUDE_TOOLS",
+    "ENV_INCLUDE_MODULES",
+    "ENV_NO_DESTRUCTIVE_TOOLS",
+    "ENV_READONLY_MODE",
     "EXCLUDE_MODULES_CONFIG_ARG",
     "EXCLUDE_TOOLS_CONFIG_ARG",
+    "HEADER_EXCLUDE_MODULES",
+    "HEADER_EXCLUDE_TOOLS",
+    "HEADER_INCLUDE_MODULES",
+    "HEADER_NO_DESTRUCTIVE_TOOLS",
+    "HEADER_READONLY_MODE",
     "IDEMPOTENT_HINT",
     "INCLUDE_MODULES_CONFIG_ARG",
     "NO_DESTRUCTIVE_TOOLS_CONFIG_ARG",
@@ -64,13 +109,16 @@
     "PromptDef",
     "ResourceDef",
     "ToolFilterFn",
-    "ToolFilterMiddleware",
     "get_mcp_config",
     "mcp_prompt",
     "mcp_resource",
     "mcp_server",
     "mcp_tool",
+    "module_filter",
+    "no_destructive_tools_filter",
+    "readonly_mode_filter",
     "register_mcp_prompts",
     "register_mcp_resources",
     "register_mcp_tools",
+    "tool_exclusion_filter",
 ]

src/fastmcp_extensions/middleware.py src/fastmcp_extensions/_middleware.pysrc/fastmcp_extensions/middleware.py renamed to src/fastmcp_extensions/_middleware.py

@@ -1,62 +1,14 @@
 # Copyright (c) 2025 Airbyte, Inc., all rights reserved.
-"""MCP Middleware for dynamic tool filtering.
+"""Internal module for tool filtering implementation.
 
-This module provides middleware for filtering MCP tools on a per-request basis,
-allowing different clients to see different tools based on their HTTP headers
-or other request-specific context.
+This is a private module that provides the internal implementation for
+per-request tool filtering. Users should not import from this module directly.
 
-## Key Components
+For tool filtering, use the `mcp_server()` function with `tool_filters` or
+`include_standard_tool_filters` parameters instead.
 
-- `ToolFilterMiddleware`: Middleware that filters tools based on a callable
-- `ToolFilterFn`: Type alias for tool filter functions
-
-## Basic Usage
-
-The simplest way to use tool filtering is with the standard filters:
-
-```py
-from fastmcp_extensions import mcp_server
-
-app = mcp_server(
-    name="my-server",
-    include_standard_tool_filters=True,
-)
-```
-
-This automatically adds:
-- `readonly_mode`: When MCP_READONLY_MODE=1 or X-MCP-Readonly-Mode: true,
-  only tools with readOnlyHint=True are visible
-- `no_destructive_tools`: When MCP_NO_DESTRUCTIVE_TOOLS=1 or X-No-Destructive-Tools: true,
-  tools with destructiveHint=True are hidden
-
-## Custom Filters
-
-For custom filtering logic, create your own filter functions:
-
-```py
-from fastmcp_extensions import mcp_server, get_mcp_config, MCPServerConfigArg
-
-
-def my_custom_filter(tool, app):
-    if get_mcp_config(app, "my_config") == "1":
-        # Custom filtering logic
-        return tool.name.startswith("allowed_")
-    return True
-
-
-app = mcp_server(
-    name="my-server",
-    server_config_args=[
-        MCPServerConfigArg(
-            name="my_config",
-            http_header_key="X-My-Config",
-            env_var="MY_CONFIG",
-            default="0",
-        ),
-    ],
-    tool_filters=[my_custom_filter],
-)
-```
+See Also:
+    - FastMCP middleware documentation: https://gofastmcp.com/servers/middleware
 """
 
 from __future__ import annotations