Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Pre-4.2 polish: stale docs, examples and docstrings (#6452)

nate nowack9abb58e349d0
diff --git a/.agents/skills/fix-issue/SKILL.md b/.agents/skills/fix-issue/SKILL.md
index ba33d334d..b7bef935d 100644
--- a/.agents/skills/fix-issue/SKILL.md
+++ b/.agents/skills/fix-issue/SKILL.md
@@ -17,7 +17,7 @@ Use [python-tests](../python-tests/SKILL.md). Reproduce the failure on unchanged
Self-review the full change with [review-pr](../review-pr/SKILL.md), including docs and dependency bounds. Separate necessary compatibility changes from accidental regressions and say whether a breaking change remains. Do not infer compatibility from passing tests.
-Run the repository's required dependency sync, full tests, and static checks before committing. Honor branch and attribution conventions. If a required check fails, investigate and report evidence rather than hiding the failure.
+Run the repository's required dependency sync, the relevant tests, and applicable static checks before committing, per AGENTS.md. Honor branch and attribution conventions. If a required check fails, investigate and report evidence rather than hiding the failure.
## Publish and follow through
diff --git a/.agents/skills/triage/SKILL.md b/.agents/skills/triage/SKILL.md
index 300a45e97..cdd1ea671 100644
--- a/.agents/skills/triage/SKILL.md
+++ b/.agents/skills/triage/SKILL.md
@@ -34,4 +34,4 @@ Lead with the strongest pick as soon as evidence supports it: link, what breaks,
When the user chooses implementation, use [fix-issue](../fix-issue/SKILL.md). For an assignment decision on an external contribution, use [review-issue](../review-issue/SKILL.md). Triage alone does not authorize public mutations or implementation.
-For a batch of maintainer decisions, save a self-contained proposal naming each target, exact action or patch, pinned revisions, evidence and executed checks, remaining questions, and dependencies between items. Include contributor ownership and the canonical issue or PR for proposed closures. Use [upstream EGM in the maintainer session](../../../.github/agentic/README.md#maintainer-review-with-egm) when independent batch review is requested. A Cloud node returns its assigned stage's declared output; the maintainer-facing session assembles the proposal and obtains sign-off.
+For a batch of maintainer decisions, save a self-contained proposal naming each target, exact action or patch, pinned revisions, evidence and executed checks, remaining questions, and dependencies between items. Include contributor ownership and the canonical issue or PR for proposed closures. Use upstream EGM in the maintainer session when independent batch review is requested. A Cloud node returns its assigned stage's declared output; the maintainer-facing session assembles the proposal and obtains sign-off.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 7c4bef52e..0b4846aae 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -5,4 +5,4 @@ contact_links:
about: Please review the documentation before opening an issue.
- name: MCP Python SDK
url: https://github.com/modelcontextprotocol/python-sdk/issues
- about: Issues related to the low-level MCP Python SDK, including the FastMCP 1.0 module that is included in the `mcp` package, should be filed on the official MCP repository.
+ about: Issues related to the low-level MCP Python SDK, including its built-in high-level servers (`MCPServer` in SDK v2, FastMCP 1.0 in SDK v1), should be filed on the official MCP repository.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 08d3a9921..0c8a2c37f 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -14,12 +14,12 @@ it in the final merged commit. See the contributor-credit policy in the guide. -
- [ ] Bug fix (simple, well-scoped fix for a clearly broken behavior)
- [ ] Documentation improvement
-- [ ] Enhancement (maintainers typically implement enhancements β€” see [CONTRIBUTING.md](../CONTRIBUTING.md))
+- [ ] Enhancement (maintainers typically implement enhancements β€” see [CONTRIBUTING.md](https://github.com/PrefectHQ/fastmcp/blob/main/CONTRIBUTING.md))
## Checklist
- [ ] This PR addresses an existing issue (or fixes a self-evident bug)
-- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [ ] I have read [CONTRIBUTING.md](https://github.com/PrefectHQ/fastmcp/blob/main/CONTRIBUTING.md)
- [ ] I have added tests that cover my changes
- [ ] I have run `uv run prek run --all-files` and all checks pass
- [ ] I have self-reviewed my changes
diff --git a/dev-docs/v4-notes/index.md b/dev-docs/v4-notes/index.md
index 478eb79fe..01aaf0c11 100644
--- a/dev-docs/v4-notes/index.md
+++ b/dev-docs/v4-notes/index.md
@@ -22,8 +22,8 @@ FastMCP v4.0 is an engine swap. Three forces drive the major version:
The migration lives on `main`, which now depends on the stable MCP Python SDK 2.0 line. FastMCP continues cutting prereleases while the v4 APIs soak, then ships 4.0.0 from the same branch.
-- **`main` owns FastMCP 4.** It carries stable `mcp>=2.0.0` and `mcp-types>=2.0.0` dependencies. Beta 4 is the current prerelease target; the [Known Gaps](known-gaps.md) page tracks the remaining decisions before 4.0.0.
-- **`release/3.x` is the maintenance line.** A `release/3.x` branch is cut from pre-merge `main`. It stays on the SDK v1 line, receives upstream security patches, and serves users who cannot move to the SDK v2 beta yet.
+- **`main` owns FastMCP 4.** It carries stable `mcp>=2.0.0` and `mcp-types>=2.0.0` dependencies. 4.0.0 shipped on 2026-08-31; these notes record the pre-GA plan.
+- **`release/3.x` is the maintenance line.** A `release/3.x` branch is cut from pre-merge `main`. It stays on the SDK v1 line, receives upstream security patches, and serves users who cannot move to SDK v2 yet.
### Release codenames
@@ -37,7 +37,8 @@ Following the pun-title convention (`v<version>: <pun>`), the v4 line runs a sin
| `4.0.0b2` (beta) | **Four the Better** | _for the better_ β€” a hardening release focused on correctness, compatibility, and security |
| `4.0.0b3` (beta) | **Fast Fourward** | _fast forward_ β€” the accumulated v4 work enters its GA soak |
| `4.0.0b4` (beta) | **Calm Befour the Storm** | _calm before the storm_ β€” one last hardening pass before the stable release |
-| `4.0.0` (stable) | **Fourmidable** | _formidable_ β€” the stable release of the new protocol foundation |
+| `4.0.0b5` (beta) | **Group Effourt** | _group effort_ β€” the final prerelease before 4.0.0 |
+| `4.0.0` (stable) | **Four Real** | _for real_ β€” the stable release of the new protocol foundation |
## How to read the register
diff --git a/docs/apps/images/app-chart.png b/docs/apps/images/app-chart.png
deleted file mode 100644
index cfc816d0e..000000000
Binary files a/docs/apps/images/app-chart.png and /dev/null differ
diff --git a/docs/apps/images/app-contacts.png b/docs/apps/images/app-contacts.png
deleted file mode 100644
index 5d74f7cb9..000000000
Binary files a/docs/apps/images/app-contacts.png and /dev/null differ
diff --git a/docs/apps/images/app-datatable.png b/docs/apps/images/app-datatable.png
deleted file mode 100644
index e69de29bb..000000000
diff --git a/docs/apps/images/app-greet.png b/docs/apps/images/app-greet.png
deleted file mode 100644
index 70a0e4412..000000000
Binary files a/docs/apps/images/app-greet.png and /dev/null differ
diff --git a/docs/apps/images/app-overview.png b/docs/apps/images/app-overview.png
deleted file mode 100644
index 35f68fd58..000000000
Binary files a/docs/apps/images/app-overview.png and /dev/null differ
diff --git a/docs/apps/images/app-quickstart-dev.png b/docs/apps/images/app-quickstart-dev.png
deleted file mode 100644
index d043f0ed3..000000000
Binary files a/docs/apps/images/app-quickstart-dev.png and /dev/null differ
diff --git a/docs/apps/images/app-quickstart.png b/docs/apps/images/app-quickstart.png
deleted file mode 100644
index ddca745cf..000000000
Binary files a/docs/apps/images/app-quickstart.png and /dev/null differ
diff --git a/docs/cli/auth.mdx b/docs/cli/auth.mdx
index 2345df2de..20bf50921 100644
--- a/docs/cli/auth.mdx
+++ b/docs/cli/auth.mdx
@@ -45,7 +45,7 @@ By default, the generated document includes a placeholder `client_id`. Update it
| Logo URI | `--logo-uri` | Client's logo URL |
| Scope | `--scope` | Space-separated list of scopes |
| Output | `--output`, `-o` | Save to file (default: stdout) |
-| Pretty | `--pretty` | Pretty-print JSON (default: true) |
+| Pretty | `--pretty` | Pretty-print JSON (default: true; pass `--pretty=false` for compact output) |
### Example
diff --git a/docs/cli/overview.mdx b/docs/cli/overview.mdx
index fca609c85..12d97e285 100644
--- a/docs/cli/overview.mdx
+++ b/docs/cli/overview.mdx
@@ -5,8 +5,6 @@ description: The fastmcp command-line interface
icon: terminal
---
-import { VersionBadge } from '/snippets/version-badge.mdx'
-
The `fastmcp` CLI is installed automatically with FastMCP. It's the primary way to run, test, install, and interact with MCP servers from your terminal.
```bash
diff --git a/docs/clients/client.mdx b/docs/clients/client.mdx
index 9a32fc3f1..300b6d926 100644
--- a/docs/clients/client.mdx
+++ b/docs/clients/client.mdx
@@ -60,7 +60,7 @@ Pass your server instance to `Client(server)` in a test to exercise tool discove
### Discovering and Downloading Skills
-An agent can also use the client to retrieve a server's skills. `list_skills()` discovers them, `read_skill()` fetches and verifies every file of one, and `skill.to_directory()` [installs it into a local agent](/servers/skills#install-skills-into-a-local-agent).
+An agent can also use the client to retrieve a server's skills. With `SkillsClientExtension` (see [Skills extension](#skills-extension)), `list_skills()` discovers them; for servers that publish skills only as resources, use `list_skill_resources()`. `read_skill()` fetches and verifies every file of one, and `skill.to_directory()` [installs it into a local agent](/servers/skills#install-skills-into-a-local-agent).
## Choosing a Transport
diff --git a/docs/clients/logging.mdx b/docs/clients/logging.mdx
index 12631fa86..21c546c51 100644
--- a/docs/clients/logging.mdx
+++ b/docs/clients/logging.mdx
@@ -19,6 +19,8 @@ Provide a `log_handler` function when creating the client:
```python
import logging
+from pathlib import Path
+
from fastmcp import Client
from fastmcp.client.logging import LogMessage
@@ -59,7 +61,7 @@ async def log_handler(message: LogMessage):
logger.log(level, msg, extra=extra)
client = Client(
- "my_mcp_server.py",
+ Path("my_mcp_server.py"),
log_handler=log_handler,
)
```
diff --git a/docs/clients/roots.mdx b/docs/clients/roots.mdx
index 08f5c9786..2679e10d3 100644
--- a/docs/clients/roots.mdx
+++ b/docs/clients/roots.mdx
@@ -20,10 +20,12 @@ Register them once with `roots=`, and the client answers however the server asks
When the paths are known up front, pass them as a list. The client holds them for the life of the connection and hands back the same set every time a server asks.
```python
+from pathlib import Path
+
from fastmcp import Client
client = Client(
- "my_mcp_server.py",
+ Path("my_mcp_server.py"),
roots=["file:///path/to/root1", "file:///path/to/root2"]
)
```
@@ -33,6 +35,8 @@ client = Client(
Pass a callback instead when the roots depend on something the client learns at runtime, such as the workspace the user has open. It runs at the moment a server asks, on either route, and receives the request context so you can see which request it is answering:
```python
+from pathlib import Path
+
from fastmcp import Client
from fastmcp.client.roots import RequestContext
@@ -41,7 +45,7 @@ async def roots_callback(context: RequestContext) -> list[str]:
return ["file:///path/to/root1", "file:///path/to/root2"]
client = Client(
- "my_mcp_server.py",
+ Path("my_mcp_server.py"),
roots=roots_callback
)
```
diff --git a/docs/integrations/gemini.mdx b/docs/integrations/gemini.mdx
index e47d06d61..d72eb9705 100644
--- a/docs/integrations/gemini.mdx
+++ b/docs/integrations/gemini.mdx
@@ -5,8 +5,6 @@ description: Connect FastMCP servers to the Google Gemini SDK
icon: message-code
---
-import { VersionBadge } from "/snippets/version-badge.mdx"
-
Google's Gemini API includes built-in support for MCP servers in their Python and JavaScript SDKs, allowing you to connect directly to MCP servers and use their tools seamlessly with Gemini models.
## Gemini Python SDK
diff --git a/docs/integrations/permit.mdx b/docs/integrations/permit.mdx
index 8d3cee50e..aececdc6a 100644
--- a/docs/integrations/permit.mdx
+++ b/docs/integrations/permit.mdx
@@ -366,8 +366,6 @@ if __name__ == "__main__":
</Tip>
-[permit.io]: https://www.permit.io
[permit-github]: https://github.com/permitio
[permit-fastmcp-github]: https://github.com/permitio/permit-fastmcp
-[Agent.Security]: https://agent.security
[fastmcp-middleware]: /servers/middleware
diff --git a/docs/servers/dependency-injection.mdx b/docs/servers/dependency-injection.mdx
index e6cde446b..1bd18caed 100644
--- a/docs/servers/dependency-injection.mdx
+++ b/docs/servers/dependency-injection.mdx
@@ -285,7 +285,7 @@ Common claims vary by identity provider:
### Background Task Dependencies
-<VersionBadge version="2.3.0" />
+<VersionBadge version="2.14.0" />
For background task execution, FastMCP provides dependencies that integrate with [Docket](https://github.com/chrisguidry/docket). `CurrentDocket()` and `CurrentWorker()` require installing `fastmcp[tasks]`; `Progress()` also works during immediate foreground execution with an in-memory tracker, and delegates to Docket progress when a Docket worker context is active.
diff --git a/docs/servers/middleware.mdx b/docs/servers/middleware.mdx
index c9c34300c..ced1cd931 100644
--- a/docs/servers/middleware.mdx
+++ b/docs/servers/middleware.mdx
@@ -460,7 +460,7 @@ mcp.add_middleware(ResponseCachingMiddleware(
Each settings class accepts:
- `enabled` β€” Enable/disable caching for this operation
- `ttl` β€” Time-to-live in seconds
-- `included_*` / `excluded_*` β€” Whitelist or blacklist specific items
+- `included_tools` / `excluded_tools` (`CallToolSettings` only) β€” Allowlist or blocklist specific tools by name
For persistence or distributed deployments, configure a different storage backend:
diff --git a/docs/servers/telemetry.mdx b/docs/servers/telemetry.mdx
index 102da5307..f03fbfa08 100644
--- a/docs/servers/telemetry.mdx
+++ b/docs/servers/telemetry.mdx
@@ -217,7 +217,7 @@ The name check must happen before `ParentBased` delegates. If the name-based sam
FastMCP assumes it owns the MCP span hierarchy. When something else already owns it β€” an MCP-aware OpenTelemetry instrumentation library, or a service mesh that understands the protocol β€” FastMCP's spans duplicate what that layer already emits, and the same request shows up twice in your traces.
-Setting `propagation_only` resolves the duplication in FastMCP's favor of the other layer:
+Setting `propagation_only` resolves the duplication in favor of the other layer:
```bash
export FASTMCP_TELEMETRY_MODE=propagation_only
diff --git a/docs/servers/transforms/tool-search.mdx b/docs/servers/transforms/tool-search.mdx
index 0bb41b389..8595f1a96 100644
--- a/docs/servers/transforms/tool-search.mdx
+++ b/docs/servers/transforms/tool-search.mdx
@@ -229,7 +229,7 @@ Tools discovered through search can also be called directly via `client.call_too
Search results respect the full authorization pipeline. Tools filtered by middleware, visibility transforms, or component-level auth checks won't appear in search results.
-App-only tools are excluded too. A [MCP app](/apps/overview) can declare backend tools intended for its UI, and hosts use that declaration to omit them from the model's tool list. A search result is tool output rather than an advertised listing, so the search transform applies that filtering itself. Its `call_tool` proxy also excludes app-only tools. [App visibility is not a security boundary](/apps/low-level#tool-visibility): clients can still call these tools directly through MCP, subject to the server's authentication and authorization checks.
+App-only tools are excluded too. An [MCP app](/apps/overview) can declare backend tools intended for its UI, and hosts use that declaration to omit them from the model's tool list. A search result is tool output rather than an advertised listing, so the search transform applies that filtering itself. Its `call_tool` proxy also excludes app-only tools. [App visibility is not a security boundary](/apps/low-level#tool-visibility): clients can still call these tools directly through MCP, subject to the server's authentication and authorization checks.
The search tool queries `list_tools()` through the complete pipeline at search time, so the same filtering that controls what a client sees in the listing also controls what they can discover through search.
diff --git a/docs/servers/transforms/tool-transformation.mdx b/docs/servers/transforms/tool-transformation.mdx
index 7cbeaf036..44b8bf5eb 100644
--- a/docs/servers/transforms/tool-transformation.mdx
+++ b/docs/servers/transforms/tool-transformation.mdx
@@ -53,7 +53,7 @@ from fastmcp import FastMCP
from fastmcp.tools import Tool, tool
from fastmcp.tools.tool_transform import ArgTransform
-# Create a tool without registering it
+# Define a tool without registering it
@tool
def search(q: str, limit: int = 10) -> list[str]:
"""Search for items."""
@@ -76,7 +76,7 @@ mcp = FastMCP("Server")
mcp.add_tool(better_search)
```
-The standalone `@tool` decorator (from `fastmcp.tools`) creates a Tool object without registering it to any server. This separates creation from registration, letting you transform tools before deciding where they go.
+The standalone `@tool` decorator (from `fastmcp.tools`) attaches tool metadata to a function without registering it to any server; `Tool.from_tool()` accepts the decorated function directly. This separates creation from registration, letting you transform tools before deciding where they go.
## Modification Options
diff --git a/docs/updates.mdx b/docs/updates.mdx
index 621203f84..377a8575f 100644
--- a/docs/updates.mdx
+++ b/docs/updates.mdx
@@ -6,6 +6,16 @@ icon: "sparkles"
tag: NEW
---
+<Update label="FastMCP 4.1.8" description="November 10, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v4.1.8: Backporch Light"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v4.1.8"
+cta="Read the release notes"
+>
+FastMCP 4.1.8 backports 28 fixes from the 4.2 line, led by OAuth proxy token revocation, which now works for the client that owns the token. It also fixes recursive and untyped schema hydration, GitHub sessions across transient verification failures, proxied sampling and prompt arguments, and a set of OpenAPI, client timeout, task and CLI edge cases. Thanks to our 21 contributors, including 9 first-time contributors.
+</Card>
+</Update>
+
<Update label="FastMCP 4.2.0a4" description="November 9, 2026" tags={["Releases"]}>
<Card
title="FastMCP v4.2.0a4: Skills to Pay the Bills"
@@ -16,6 +26,16 @@ FastMCP 4.2.0a4 requires Python 3.11 or newer and adds `Annotated` dependencies.
</Card>
</Update>
+<Update label="FastMCP 4.1.7" description="November 9, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v4.1.7: Dumpster Dive"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v4.1.7"
+cta="Read the release notes"
+>
+FastMCP 4.1.7 backports 42 fixes from the 4.2 line, covering OpenAPI schema and parameter handling, OAuth redirect and consent edge cases, proxy and response caching, and lost-connection errors in the client. It also requires patched joserfc and Authlib releases and closes a redirect URI validation gap for callers that pass raw strings. Thanks to our 41 contributors, including 28 first-time contributors.
+</Card>
+</Update>
+
<Update label="FastMCP 4.2.0a3" description="November 3, 2026" tags={["Releases"]}>
<Card
title="FastMCP v4.2.0a3: A Particular Set of Skills"
@@ -36,6 +56,16 @@ The second 4.2 alpha carries every fix from 4.1.5 plus the ones that only land o
</Card>
</Update>
+<Update label="FastMCP 4.1.5" description="November 1, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v4.1.5: Back to the Fourture"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v4.1.5"
+cta="Read the release notes"
+>
+Twelve fixes backported from main onto the new `release/4.1` line: mounted resource templates keep their list-style query parameters, `FastMCPStdioTransport` forwards script arguments, OpenAPI tools report timeouts and concise upstream errors (and reject undeclared arguments under strict validation), a missing prompt argument returns invalid params, and JSON Schema `const`/`enum` compare by JSON equality, so `true` no longer passes for `1`. Thanks to our 12 contributors, including 7 first-time contributors.
+</Card>
+</Update>
+
<Update label="FastMCP 4.2.0a1" description="October 27, 2026" tags={["Releases"]}>
<Card
title="FastMCP v4.2.0a1: Skill Issue"
@@ -76,6 +106,26 @@ Component authorization now applies after transforms, denied resources cannot fa
</Card>
</Update>
+<Update label="FastMCP 3.4.11" description="October 20, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.4.11: Trust Issues"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.11"
+cta="Read the release notes"
+>
+This release requires certifi 2026.10.19 or later for FastMCP's HTTP stack and certifi-backed integrations following the eMudhra CA compromise. Follow the [security notice](https://github.com/PrefectHQ/fastmcp/blob/main/SECURITY.md#certificate-authority-incident-october-2026) to update custom, system, and installer trust stores too; upgrading FastMCP alone is insufficient. Thanks to our 1 contributor, with no first-time contributors in this release.
+</Card>
+</Update>
+
+<Update label="FastMCP 3.4.10" description="October 20, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.4.10: Back in Check"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.10"
+cta="Read the release notes"
+>
+This release backports component authorization checks after transforms and prevents denied concrete resources from being served by matching templates. All 3.x users are encouraged to upgrade. Thanks to our 2 contributors, including 1 first-time contributor.
+</Card>
+</Update>
+
<Update label="FastMCP 4.1.1" description="October 17, 2026" tags={["Releases"]}>
<Card
title="FastMCP v4.1.1: Regex Marks the Spot"
@@ -86,6 +136,16 @@ Regex tool search now rejects patterns over 1,000 characters and stops after abo
</Card>
</Update>
+<Update label="FastMCP 3.4.9" description="October 16, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.4.9: Contain Yourself"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.9"
+cta="Read the release notes"
+>
+This release backports security fixes from 4.1: OpenAPI path parameters reject `.` and `..` segments, a skill's `SKILL.md` must stay inside its skill folder, regex tool search is bounded in time and pattern length, and JWT verifiers share JWKS refreshes instead of fetching on every unknown key ID. All 3.x users are encouraged to upgrade. Thanks to our 6 contributors, including 3 first-time contributors.
+</Card>
+</Update>
+
<Update label="FastMCP 4.1.0" description="October 8, 2026" tags={["Releases"]}>
<Card
title="FastMCP v4.1.0: Fourth and One"
@@ -108,6 +168,16 @@ This release contains important security and bug fixes. All users are encouraged
</Card>
</Update>
+<Update label="FastMCP 3.4.8" description="October 4, 2026" tags={["Releases"]}>
+<Card
+title="FastMCP v3.4.8: Long Arm of the Patch"
+href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.4.8"
+cta="Read the release notes"
+>
+This release contains important security and bug fixes. All users are encouraged to upgrade. Thanks to our 2 contributors.
+</Card>
+</Update>
+
<Update label="FastMCP 4.0.10" description="September 25, 2026" tags={["Releases"]}>
<Card
title="FastMCP v4.0.10: Inside Job"
@@ -545,7 +615,6 @@ First patch after 3.0 β€” mostly smoothing out rough edges discovered in the wil
title="FastMCP v3.0.0: Three at Last"
href="https://github.com/PrefectHQ/fastmcp/releases/tag/v3.0.0"
cta="Read the release notes"
-img="assets/updates/release-3-0.png"
>
FastMCP 3.0 is stable. Two betas, two release candidates, 21 new contributors, and more than 100,000 pre-release installs later β€” the architecture held up, the upgrade path was smooth, and we're shipping it.
diff --git a/examples/code_mode/README.md b/examples/code_mode/README.md
index 28834f350..b98bc40d2 100644
--- a/examples/code_mode/README.md
+++ b/examples/code_mode/README.md
@@ -1,6 +1,6 @@
# Code Mode
-CodeMode collapses an entire tool catalog into two meta-tools: `search` (keyword-based discovery) and `execute` (run Python scripts that chain tool calls in a sandbox). Instead of burning context tokens on every intermediate result, the LLM writes a script that runs server-side and returns only the final answer.
+CodeMode collapses an entire tool catalog into three meta-tools: `search` (keyword-based discovery), `get_schema` (parameter details), and `execute` (run Python scripts that chain tool calls in a sandbox). Instead of burning context tokens on every intermediate result, the LLM writes a script that runs server-side and returns only the final answer.
## Run
@@ -15,10 +15,11 @@ uv run python client.py # in another
══════════════════ CodeMode Transform ══════════════════
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ list_tools() ──────────────┐
-β”‚ Tool Description β”‚
-β”‚ search Search for available tools ... β”‚
-β”‚ execute Chain `await call_tool(...)` ... β”‚
-└── 8 backend tools collapsed into 2 β”€β”€β”€β”€β”€β”€β”˜
+β”‚ Tool Description β”‚
+β”‚ search Search for available tools β”‚
+β”‚ get_schema Get parameter schemas β”‚
+β”‚ execute Chain `await call_tool(...)` β”‚
+└── 8 backend tools collapsed into 3 β”€β”€β”€β”€β”€β”€β”˜
β”Œβ”€β”€β”€β”€ search(query="math arithmetic") ─────┐
β”‚ # Tool Description β”‚
diff --git a/examples/code_mode/client.py b/examples/code_mode/client.py
index ccc5ab6db..e3f35f28a 100644
--- a/examples/code_mode/client.py
+++ b/examples/code_mode/client.py
@@ -1,9 +1,9 @@
"""Example: Client using CodeMode to discover and chain tools.
-CodeMode exposes just two tools: `search` (keyword query) and `execute`
-(run Python code with `call_tool` available). This client demonstrates
-both: searching for tools, then chaining multiple calls in a single
-execute block β€” one round-trip instead of many.
+CodeMode exposes just three tools: `search` (keyword query), `get_schema`
+(parameter details), and `execute` (run Python code with `call_tool`
+available). This client demonstrates searching for tools, then chaining
+multiple calls in a single execute block β€” one round-trip instead of many.
Run with:
uv run python examples/code_mode/client.py
@@ -74,10 +74,11 @@ async def main():
console.rule("[bold]CodeMode[/bold]")
console.print()
- # Step 1: list_tools only returns two synthetic meta-tools
+ # Step 1: list_tools only returns three synthetic meta-tools
console.print(
"The server has 8 tools. CodeMode replaces them with "
- "two synthetic tools β€” [bold]search[/bold] and [bold]execute[/bold]:"
+ "three synthetic tools β€” [bold]search[/bold], [bold]get_schema[/bold] "
+ "and [bold]execute[/bold]:"
)
console.print()
tools = await client.list_tools()
diff --git a/examples/code_mode/server.py b/examples/code_mode/server.py
index 70aca8bfa..4a8c95647 100644
--- a/examples/code_mode/server.py
+++ b/examples/code_mode/server.py
@@ -1,8 +1,8 @@
"""Example: CodeMode transform β€” search and execute tools via code.
-CodeMode replaces the entire tool catalog with two meta-tools: `search`
-(keyword-based tool discovery) and `execute` (run Python code that chains
-tool calls in a sandbox). This dramatically reduces round-trips and
+CodeMode replaces the entire tool catalog with three meta-tools: `search`
+(keyword-based tool discovery), `get_schema` (parameter details), and
+`execute` (run Python code that chains tool calls in a sandbox). This dramatically reduces round-trips and
context window usage when an LLM needs to orchestrate many tools.
Requires pydantic-monty for the sandbox:
@@ -74,7 +74,7 @@ def read_file(path: str) -> str:
return f.read()
-# CodeMode collapses all 8 tools into just `search` + `execute`.
+# CodeMode collapses all 8 tools into `search`, `get_schema` and `execute`.
# The LLM discovers tools via keyword search, then writes Python
# scripts that chain multiple tool calls in a single round-trip.
mcp.add_transform(CodeMode())
diff --git a/examples/fastmcp_config/env_interpolation_example.json b/examples/fastmcp_config/env_interpolation_example.json
index 0eb4af048..138a9be84 100644
--- a/examples/fastmcp_config/env_interpolation_example.json
+++ b/examples/fastmcp_config/env_interpolation_example.json
@@ -1,6 +1,6 @@
{
"$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
- "entrypoint": "src/server.py:app",
+ "source": { "path": "src/server.py", "entrypoint": "app" },
"environment": {
"python": "3.12",
"dependencies": ["fastmcp", "httpx", "pandas"]
diff --git a/examples/fastmcp_config/fastmcp.json b/examples/fastmcp_config/fastmcp.json
index 3511d1153..9cdde79d3 100644
--- a/examples/fastmcp_config/fastmcp.json
+++ b/examples/fastmcp_config/fastmcp.json
@@ -1,5 +1,5 @@
{
- "$schema": "https://gofastmcp.com/schemas/fastmcp/v1.json",
+ "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
"source": {
"path": "server.py"
},
diff --git a/examples/fastmcp_config/simple.fastmcp.json b/examples/fastmcp_config/simple.fastmcp.json
index 40541fefc..c1271df4a 100644
--- a/examples/fastmcp_config/simple.fastmcp.json
+++ b/examples/fastmcp_config/simple.fastmcp.json
@@ -1,6 +1,6 @@
{
- "$schema": "https://gofastmcp.com/schemas/fastmcp/v1.json",
- "entrypoint": "server.py",
+ "$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+ "source": { "path": "server.py" },
"deployment": {
"transport": "stdio"
}
diff --git a/examples/fastmcp_config_demo/README.md b/examples/fastmcp_config_demo/README.md
index 7abf11c3d..665e9e966 100644
--- a/examples/fastmcp_config_demo/README.md
+++ b/examples/fastmcp_config_demo/README.md
@@ -26,14 +26,14 @@ With the configuration file in place, you can run the server in several ways:
```bash
# Auto-detect fastmcp.json in current directory
-cd examples/mcp_server_config_demo
+cd examples/fastmcp_config_demo
fastmcp run
# Or specify the config file explicitly
-fastmcp run examples/mcp_server_config_demo/fastmcp.json
+fastmcp run examples/fastmcp_config_demo/fastmcp.json
# Or use development mode with the Inspector UI
-fastmcp dev examples/mcp_server_config_demo/fastmcp.json
+fastmcp dev inspector examples/fastmcp_config_demo/fastmcp.json
```
## Benefits
@@ -48,7 +48,7 @@ fastmcp dev examples/mcp_server_config_demo/fastmcp.json
The `fastmcp.json` file supports three main sections:
-1. **entrypoint** (required): The Python file containing your server
+1. **source** (required): Where the server lives (`path`, optional `entrypoint`)
2. **environment** (optional): Python version and dependencies
3. **deployment** (optional): Runtime settings like transport and logging
diff --git a/examples/memory.fastmcp.json b/examples/memory.fastmcp.json
index 5ee1aea97..39b6807f2 100644
--- a/examples/memory.fastmcp.json
+++ b/examples/memory.fastmcp.json
@@ -1,6 +1,6 @@
{
"$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
- "entrypoint": "memory.py",
+ "source": { "path": "memory.py" },
"environment": {
"dependencies": ["pydantic-ai-slim[openai]", "asyncpg", "numpy", "pgvector"]
}
diff --git a/examples/mount_example.fastmcp.json b/examples/mount_example.fastmcp.json
index d30d2e3e9..131562397 100644
--- a/examples/mount_example.fastmcp.json
+++ b/examples/mount_example.fastmcp.json
@@ -1,4 +1,4 @@
{
"$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
- "entrypoint": "mount_example.py"
+ "source": { "path": "mount_example.py" }
}
diff --git a/examples/providers/sqlite/README.md b/examples/providers/sqlite/README.md
index 9175a5e43..a8a9edbf4 100644
--- a/examples/providers/sqlite/README.md
+++ b/examples/providers/sqlite/README.md
@@ -4,14 +4,14 @@ This example demonstrates serving MCP tools from a database. Tools can be added,
## Structure
-- `tools.db` - SQLite database with tool configurations (committed for convenience)
+- `tools.db` - SQLite database with tool configurations (created by `setup_db.py`; gitignored)
- `setup_db.py` - Script to create/reset the database
- `server.py` - MCP server that loads tools from the database
## Usage
```bash
-# Reset the database (optional - tools.db is pre-seeded)
+# Create or reset the database (required before the first run)
uv run examples/providers/sqlite/setup_db.py
# Run the server
@@ -23,12 +23,14 @@ uv run fastmcp run examples/providers/sqlite/server.py
The `SQLiteToolProvider` queries the database on every `list_tools` and `call_tool` request:
```python
-class SQLiteToolProvider(BaseToolProvider):
- async def list_tools(self) -> list[Tool]:
+class SQLiteToolProvider(Provider):
+ async def _list_tools(self) -> Sequence[Tool]:
# Query database for enabled tools
...
- async def get_tool(self, name: str) -> Tool | None:
+ async def _get_tool(
+ self, name: str, version: VersionSpec | None = None
+ ) -> Tool | None:
# Efficient single-tool lookup
...
```
diff --git a/examples/providers/sqlite/server.py b/examples/providers/sqlite/server.py
index 694a2906e..c2f8ff564 100644
--- a/examples/providers/sqlite/server.py
+++ b/examples/providers/sqlite/server.py
@@ -24,6 +24,7 @@ from rich import print
from fastmcp import Client, FastMCP
from fastmcp.server.providers import Provider
from fastmcp.tools import Tool, ToolResult
+from fastmcp.utilities.versions import VersionSpec
DB_PATH = Path(__file__).parent / "tools.db"
@@ -75,14 +76,16 @@ class SQLiteToolProvider(Provider):
super().__init__()
self.db_path = db_path
- async def list_tools(self) -> Sequence[Tool]:
+ async def _list_tools(self) -> Sequence[Tool]:
async with aiosqlite.connect(self.db_path) as db:
db.row_factory = aiosqlite.Row
async with db.execute("SELECT * FROM tools WHERE enabled = 1") as cursor:
rows = await cursor.fetchall()
return [self._make_tool(row) for row in rows]
- async def get_tool(self, name: str) -> Tool | None:
+ async def _get_tool(
+ self, name: str, version: VersionSpec | None = None
+ ) -> Tool | None:
async with aiosqlite.connect(self.db_path) as db:
db.row_factory = aiosqlite.Row
async with db.execute(
diff --git a/examples/screenshot.fastmcp.json b/examples/screenshot.fastmcp.json
index 9ff06d797..781dee5d1 100644
--- a/examples/screenshot.fastmcp.json
+++ b/examples/screenshot.fastmcp.json
@@ -1,6 +1,6 @@
{
"$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
- "entrypoint": "screenshot.py",
+ "source": { "path": "screenshot.py" },
"environment": {
"dependencies": ["pyautogui", "Pillow"]
}
diff --git a/examples/smart_home/hub.fastmcp.json b/examples/smart_home/hub.fastmcp.json
index 25daabbbd..4e5d39ff5 100644
--- a/examples/smart_home/hub.fastmcp.json
+++ b/examples/smart_home/hub.fastmcp.json
@@ -1,6 +1,6 @@
{
"$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
- "entrypoint": "src/smart_home/hub.py",
+ "source": { "path": "src/smart_home/hub.py" },
"environment": {
"dependencies": [
"smart_home@git+https://github.com/PrefectHQ/fastmcp.git#subdirectory=examples/smart_home"
diff --git a/examples/smart_home/lights.fastmcp.json b/examples/smart_home/lights.fastmcp.json
index 534cab55c..ed89109b7 100644
--- a/examples/smart_home/lights.fastmcp.json
+++ b/examples/smart_home/lights.fastmcp.json
@@ -1,6 +1,6 @@
{
"$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
- "entrypoint": "src/smart_home/lights/server.py",
+ "source": { "path": "src/smart_home/lights/server.py" },
"environment": {
"dependencies": [
"smart_home@git+https://github.com/PrefectHQ/fastmcp.git#subdirectory=examples/smart_home"
diff --git a/examples/task_elicitation.py b/examples/task_elicitation.py
index 18d56f2e7..f813a07be 100644
--- a/examples/task_elicitation.py
+++ b/examples/task_elicitation.py
@@ -20,11 +20,11 @@ Works with both in-memory and Redis backends:
# Redis (distributed, needs a worker running separately)
# Terminal 1: docker compose -f examples/tasks/docker-compose.yml up -d
# Terminal 2: FASTMCP_DOCKET_URL=redis://localhost:24242/0 \
- # uv run fastmcp tasks worker examples/task_elicitation.py
+ # uv run python -m fastmcp_tasks.worker_cli worker examples/task_elicitation.py
# Terminal 3: FASTMCP_DOCKET_URL=redis://localhost:24242/0 \
# uv run python examples/task_elicitation.py
-Requires the `docket` extra (included in dev dependencies).
+Requires the `tasks` extra (included in dev dependencies).
"""
import asyncio
diff --git a/examples/tasks/.envrc b/examples/tasks/.envrc
index 7c90adf43..5069c49e5 100644
--- a/examples/tasks/.envrc
+++ b/examples/tasks/.envrc
@@ -6,6 +6,7 @@
# This is the default the example runs on.
export FASTMCP_DOCKET_URL=memory://
-# For distributed workers across separate processes (the `fastmcp tasks worker`
-# CLI), point at Redis instead and run `docker compose up -d` first:
+# For distributed workers across separate processes
+# (`python -m fastmcp_tasks.worker_cli worker`), point at Redis instead and run
+# `docker compose up -d` first:
# export FASTMCP_DOCKET_URL=redis://localhost:24242/0
diff --git a/fastmcp_remote/README.md b/fastmcp_remote/README.md
index 7f576eb70..28471f558 100644
--- a/fastmcp_remote/README.md
+++ b/fastmcp_remote/README.md
@@ -101,5 +101,9 @@ SSL_CERT_FILE=/path/to/ca-bundle.pem uvx fastmcp-remote https://internal.example
- `--ignore-tool`: Hide tools whose names match a glob pattern.
- `--auth`: Choose `oauth` or `none`. The default uses OAuth unless an `Authorization` header is provided.
- `--verify`: Control TLS certificate verification. Pass a path to a CA bundle to trust a self-signed certificate, or `false` to disable verification (insecure). Defaults to verification enabled.
+- `--debug`: Enable debug logging.
+- `--silent`: Suppress non-critical logs. Cannot be combined with `--debug`.
+
+Pass a port after the URL (`uvx fastmcp-remote <url> 3334`) to fix the OAuth callback port; by default an available local port is used.
OAuth tokens are stored under `~/.fastmcp/remote` by default. Set `FASTMCP_REMOTE_CONFIG_DIR` to use another directory.
diff --git a/fastmcp_slim/fastmcp/apps/file_upload.py b/fastmcp_slim/fastmcp/apps/file_upload.py
index a72ced285..681661101 100644
--- a/fastmcp_slim/fastmcp/apps/file_upload.py
+++ b/fastmcp_slim/fastmcp/apps/file_upload.py
@@ -9,7 +9,7 @@ Requires ``fastmcp[apps]`` (prefab-ui).
Usage::
from fastmcp import FastMCP
- from fastmcp.apps import FileUpload
+ from fastmcp.apps.file_upload import FileUpload
mcp = FastMCP("My Server")
mcp.add_provider(FileUpload())
diff --git a/fastmcp_slim/fastmcp/cli/run.py b/fastmcp_slim/fastmcp/cli/run.py
index 03344a769..be35caa67 100644
--- a/fastmcp_slim/fastmcp/cli/run.py
+++ b/fastmcp_slim/fastmcp/cli/run.py
@@ -330,10 +330,10 @@ async def run_v1_server_async(
stateless: bool = False,
log_level: LogLevelType | None = None,
) -> None:
- """Run a FastMCP 1.x server using async methods.
+ """Run the MCP SDK's high-level `MCPServer` using async methods.
Args:
- server: FastMCP 1.x server instance
+ server: SDK `MCPServer` instance
host: Host to bind to
port: Port to bind to
transport: Transport protocol to use
diff --git a/fastmcp_slim/fastmcp/client/_sdk_context_shim.py b/fastmcp_slim/fastmcp/client/_sdk_context_shim.py
index 958bec383..6e523b294 100644
--- a/fastmcp_slim/fastmcp/client/_sdk_context_shim.py
+++ b/fastmcp_slim/fastmcp/client/_sdk_context_shim.py
@@ -22,11 +22,10 @@ _SessionT = TypeVar("_SessionT")
class RequestContext(Generic[_SessionT, LifespanContextT]):
- """Placeholder for the removed SDK ``RequestContext`` generic.
+ """Subscriptable stand-in for the SDK's removed `RequestContext` generic.
- Subscriptable with two type parameters to match existing client handler
- annotations. Not instantiated anywhere; exists only so module imports and
- annotation evaluation succeed until the Phase C client port lands.
+ Takes two type parameters so client handler type aliases keep their
+ signature; never instantiated.
"""
def __class_getitem__(cls, item: Any) -> Any: # pragma: no cover - typing only
diff --git a/fastmcp_slim/fastmcp/client/client.py b/fastmcp_slim/fastmcp/client/client.py
index 7472aa64f..99cfd750f 100644
--- a/fastmcp_slim/fastmcp/client/client.py
+++ b/fastmcp_slim/fastmcp/client/client.py
@@ -306,7 +306,7 @@ class Client(
- ClientTransport: Direct transport instance
- FastMCP: In-process FastMCP server
- AnyUrl or str: URL to connect to
- - Path: File path for local socket
+ - Path: Python (.py) or Node (.js) script to run over stdio
- MCPConfig: MCP server configuration
- dict: Transport configuration
diff --git a/fastmcp_slim/fastmcp/client/sampling/handlers/google_genai.py b/fastmcp_slim/fastmcp/client/sampling/handlers/google_genai.py
index d55283d45..6f473a04c 100644
--- a/fastmcp_slim/fastmcp/client/sampling/handlers/google_genai.py
+++ b/fastmcp_slim/fastmcp/client/sampling/handlers/google_genai.py
@@ -1,4 +1,4 @@
-"""Google GenAI sampling handler with tool support for FastMCP 3.0."""
+"""Google GenAI sampling handler for FastMCP."""
import base64
from collections.abc import Mapping, Sequence
diff --git a/fastmcp_slim/fastmcp/client/transports/inference.py b/fastmcp_slim/fastmcp/client/transports/inference.py
index 288737da8..88826fc64 100644
--- a/fastmcp_slim/fastmcp/client/transports/inference.py
+++ b/fastmcp_slim/fastmcp/client/transports/inference.py
@@ -142,7 +142,7 @@ def infer_transport(
if isinstance(transport, ClientTransport):
return transport
- # the transport is a FastMCP server (2.x or 1.0)
+ # the transport is a FastMCP server or the SDK's MCPServer
elif _is_fastmcp_server(transport):
inferred_transport = FastMCPTransport(
mcp=cast("FastMCP[Any] | SDKServer", transport)
diff --git a/fastmcp_slim/fastmcp/client/transports/memory.py b/fastmcp_slim/fastmcp/client/transports/memory.py
index 0c516aed7..0fba7104c 100644
--- a/fastmcp_slim/fastmcp/client/transports/memory.py
+++ b/fastmcp_slim/fastmcp/client/transports/memory.py
@@ -47,7 +47,7 @@ class FastMCPTransport(ClientTransport):
def __init__(self, mcp: "FastMCP[Any] | SDKServer", raise_exceptions: bool = False):
"""Initialize a FastMCPTransport from a FastMCP server instance."""
- # Accept both FastMCP 2.x and FastMCP 1.0 servers. Their underlying
+ # Accept both fastmcp FastMCP servers and the SDK's MCPServer. Their underlying
# lowlevel MCP ``Server`` lives on different attributes
# (``_mcp_server`` vs ``_lowlevel_server``); ``_lowlevel_of`` resolves
# it uniformly so we can drive the async ``Server.run`` for both.
diff --git a/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md b/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md
index 39c3a2352..2dfd4506e 100644
--- a/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md
+++ b/fastmcp_slim/fastmcp/contrib/mcp_mixin/README.md
@@ -1,5 +1,3 @@
-from mcp.types import ToolAnnotations
-
# MCP Mixin
This module provides the `MCPMixin` base class and associated decorators (`@mcp_tool`, `@mcp_resource`, `@mcp_prompt`).
@@ -8,17 +6,16 @@ It allows developers to easily define classes whose methods can be registered as
Includes support for
Tools:
-* [enable/disable](https://gofastmcp.com/servers/tools#disabling-tools)
-* [annotations](https://gofastmcp.com/servers/tools#annotations-2)
-* [excluded arguments](https://gofastmcp.com/servers/tools#excluding-arguments)
+* [enable/disable](https://gofastmcp.com/servers/tools#component-visibility)
+* [annotations](https://gofastmcp.com/servers/tools#mcp-annotations)
* [meta](https://gofastmcp.com/servers/tools#param-meta)
Prompts:
-* [enable/disable](https://gofastmcp.com/servers/prompts#disabling-prompts)
+* [enable/disable](https://gofastmcp.com/servers/prompts#component-visibility)
* [meta](https://gofastmcp.com/servers/prompts#param-meta)
Resources:
-* [enable/disable](https://gofastmcp.com/servers/resources#disabling-resources)
+* [enable/disable](https://gofastmcp.com/servers/resources#component-visibility)
* [meta](https://gofastmcp.com/servers/resources#param-meta)
## Usage
@@ -41,17 +38,6 @@ class MyComponent(MCPMixin):
# This function can't be called by client because it's disabled
return "You'll never get here!"
- # example of excluded parameter tool
- @mcp_tool(
- name="my_tool", description="Does something cool.",
- enabled=False, exclude_args=['delete_everything'],
- )
- def excluded_param_tool_method(self, delete_everything=False):
- # MCP tool calls can't pass the "delete_everything" argument
- if delete_everything:
- return "Nothing to delete, I bet you're not a tool :)"
- return "You might be a tool if..."
-
# example tool w/annotations
@mcp_tool(
name="my_tool", description="Does something cool.",
@@ -69,7 +55,6 @@ class MyComponent(MCPMixin):
@mcp_tool(
name="my_tool", description="Does something cool.",
enabled=True,
- exclude_args=['delete_all'],
annotations=ToolAnnotations(
title="Attn LLM, use this tool first!",
readOnlyHint=False,
@@ -103,7 +88,7 @@ class MyComponent(MCPMixin):
# example resource w/meta and title
@mcp_resource(
uri="component://config",
- title="Data resource Title,
+ title="Data resource Title",
meta={"internal": True, "cache_ttl": 3600, "priority": "high"}
)
def config_resource_method(self):
@@ -144,4 +129,4 @@ component.register_all(mcp_server, prefix="my_comp")
# Or 'my_tool' and 'component://data' are registered (if no prefix used)
```
-The `prefix` argument in registration methods is optional. If omitted, methods are registered with their original decorated names/URIs. Individual separators (`tools_separator`, `resources_separator`, `prompts_separator`) can also be provided to `register_all` to change the separator for specific types.
+The `prefix` argument in registration methods is optional. If omitted, methods are registered with their original decorated names/URIs. Individual separators (`tool_separator`, `resource_separator`, `prompt_separator`) can also be provided to `register_all` to change the separator for specific types.
diff --git a/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py
index 5ba0a9243..fdd1bd792 100644
--- a/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py
+++ b/fastmcp_slim/fastmcp/server/auth/oauth_proxy/proxy.py
@@ -248,7 +248,7 @@ class OAuthProxy(OAuthProvider, ConsentMixin):
5. Token Management:
- Clients may expect different token formats/claims than upstream provides
- Need to track tokens for revocation and refresh
- - Solution: Store token relationships, forward upstream tokens transparently
+ - Solution: Issue FastMCP-signed JWTs and map their JTIs to the stored upstream tokens
OAuth Flow Implementation
------------------------
@@ -268,7 +268,7 @@ class OAuthProxy(OAuthProvider, ConsentMixin):
4. Token Exchange:
- Validate client's code and PKCE verifier
- - Return previously obtained upstream tokens
+ - Issue FastMCP access/refresh tokens backed by the stored upstream tokens
- Clean up one-time use authorization code
5. Token Refresh:
@@ -279,8 +279,9 @@ class OAuthProxy(OAuthProvider, ConsentMixin):
State Management
---------------
The proxy maintains minimal but crucial state via pluggable storage (client_storage):
- - _oauth_transactions: Active authorization flows with client context
- - _client_codes: Authorization codes with PKCE challenges and upstream tokens
+ - _transaction_store: Active authorization flows with client context
+ - _code_store: Authorization codes with PKCE challenges and upstream tokens
+ - _upstream_token_store: Upstream token sets
- _jti_mapping_store: Maps FastMCP token JTIs to upstream token IDs
- _refresh_token_store: Refresh token metadata (keyed by token hash)
@@ -589,7 +590,7 @@ class OAuthProxy(OAuthProvider, ConsentMixin):
if isinstance(jwt_signing_key, str):
if len(jwt_signing_key) < 12:
logger.warning(
- "jwt_signing_key is less than 12 characters; it is recommended to use a longer. "
+ "jwt_signing_key is less than 12 characters; it is recommended to use a longer "
"string for the key derivation."
)
jwt_signing_key = derive_jwt_key(
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/aws.py b/fastmcp_slim/fastmcp/server/auth/providers/aws.py
index d715c9f6f..39d1700bc 100644
--- a/fastmcp_slim/fastmcp/server/auth/providers/aws.py
+++ b/fastmcp_slim/fastmcp/server/auth/providers/aws.py
@@ -7,14 +7,15 @@ the complexity of AWS Cognito's OAuth flow, token validation, and user managemen
Example:
```python
from fastmcp import FastMCP
- from fastmcp.server.auth.providers.aws_cognito import AWSCognitoProvider
+ from fastmcp.server.auth.providers.aws import AWSCognitoProvider
# Simple AWS Cognito OAuth protection
auth = AWSCognitoProvider(
user_pool_id="your-user-pool-id",
aws_region="eu-central-1",
client_id="your-cognito-client-id",
- client_secret="your-cognito-client-secret"
+ client_secret="your-cognito-client-secret",
+ base_url="https://my-server.com",
)
mcp = FastMCP("My Protected Server", auth=auth)
@@ -108,7 +109,7 @@ class AWSCognitoProvider(OIDCProxy):
Example:
```python
from fastmcp import FastMCP
- from fastmcp.server.auth.providers.aws_cognito import AWSCognitoProvider
+ from fastmcp.server.auth.providers.aws import AWSCognitoProvider
auth = AWSCognitoProvider(
user_pool_id="eu-central-1_XXXXXXXXX",
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/discord.py b/fastmcp_slim/fastmcp/server/auth/providers/discord.py
index a00591e91..b14f05e36 100644
--- a/fastmcp_slim/fastmcp/server/auth/providers/discord.py
+++ b/fastmcp_slim/fastmcp/server/auth/providers/discord.py
@@ -1,7 +1,7 @@
"""Discord OAuth provider for FastMCP.
This module provides a complete Discord OAuth integration that's ready to use
-with just a client ID and client secret. It handles all the complexity of
+with a client ID, client secret, and base URL. It handles all the complexity of
Discord's OAuth flow, token validation, and user management.
Example:
@@ -12,7 +12,8 @@ Example:
# Simple Discord OAuth protection
auth = DiscordProvider(
client_id="your-discord-client-id",
- client_secret="your-discord-client-secret"
+ client_secret="your-discord-client-secret",
+ base_url="https://my-server.com",
)
mcp = FastMCP("My Protected Server", auth=auth)
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/github.py b/fastmcp_slim/fastmcp/server/auth/providers/github.py
index fa2cb169c..271ff09dd 100644
--- a/fastmcp_slim/fastmcp/server/auth/providers/github.py
+++ b/fastmcp_slim/fastmcp/server/auth/providers/github.py
@@ -1,7 +1,7 @@
"""GitHub OAuth provider for FastMCP.
This module provides a complete GitHub OAuth integration that's ready to use
-with just a client ID and client secret. It handles all the complexity of
+with a client ID, client secret, and base URL. It handles all the complexity of
GitHub's OAuth flow, token validation, and user management.
Example:
@@ -12,7 +12,8 @@ Example:
# Simple GitHub OAuth protection
auth = GitHubProvider(
client_id="your-github-client-id",
- client_secret="your-github-client-secret"
+ client_secret="your-github-client-secret",
+ base_url="https://my-server.com",
)
mcp = FastMCP("My Protected Server", auth=auth)
diff --git a/fastmcp_slim/fastmcp/server/auth/providers/google.py b/fastmcp_slim/fastmcp/server/auth/providers/google.py
index 1237258cc..64d91a99b 100644
--- a/fastmcp_slim/fastmcp/server/auth/providers/google.py
+++ b/fastmcp_slim/fastmcp/server/auth/providers/google.py
@@ -1,7 +1,7 @@
"""Google OAuth provider for FastMCP.
This module provides a complete Google OAuth integration that's ready to use
-with just a client ID and client secret. It handles all the complexity of
+with a client ID, client secret, and base URL. It handles all the complexity of
Google's OAuth flow, token validation, and user management.
Example:
@@ -12,7 +12,8 @@ Example:
# Simple Google OAuth protection
auth = GoogleProvider(
client_id="your-google-client-id.apps.googleusercontent.com",
- client_secret="your-google-client-secret"
+ client_secret="your-google-client-secret",
+ base_url="https://my-server.com",
)
mcp = FastMCP("My Protected Server", auth=auth)
diff --git a/fastmcp_slim/fastmcp/server/context.py b/fastmcp_slim/fastmcp/server/context.py
index caa2e4078..68a7fe0af 100644
--- a/fastmcp_slim/fastmcp/server/context.py
+++ b/fastmcp_slim/fastmcp/server/context.py
@@ -229,16 +229,16 @@ class Context:
def is_background_task(self) -> bool:
"""True when this context is running in a background task (Docket worker).
- When True, certain operations like elicit() will use task-aware
- implementations that can pause the task and wait for client input.
+ When True, imperative `ctx.elicit()` is unavailable; gather input by
+ returning an `InputRequiredResult` and reading `ctx.input_responses` /
+ `ctx.request_state` when the task re-runs.
Example:
```python
@server.tool(task=True)
async def my_task(ctx: Context) -> str:
- # Works transparently in both foreground and background task modes
- result = await ctx.elicit("Need input", str)
- return str(result)
+ await ctx.report_progress(1, 2)
+ return "done"
```
"""
return self._task_id is not None
diff --git a/fastmcp_slim/fastmcp/server/middleware/caching.py b/fastmcp_slim/fastmcp/server/middleware/caching.py
index 5e9851951..124657203 100644
--- a/fastmcp_slim/fastmcp/server/middleware/caching.py
+++ b/fastmcp_slim/fastmcp/server/middleware/caching.py
@@ -260,8 +260,7 @@ class ResponseCachingStatistics(FastMCPBaseModel):
class ResponseCachingMiddleware(Middleware):
- """The response caching middleware offers a simple way to cache responses to mcp methods. The Middleware
- supports cache invalidation via notifications from the server. The Middleware implements TTL-based caching
+ """The response caching middleware offers a simple way to cache responses to mcp methods. The Middleware implements TTL-based caching
but cache implementations may offer additional features like LRU eviction, size limits, and more.
When items are retrieved from the cache they will no longer be the original objects, but rather no-op objects
@@ -376,7 +375,7 @@ class ResponseCachingMiddleware(Middleware):
call_next: CallNext[mcp_types.ListToolsRequest, Sequence[Tool]],
) -> Sequence[Tool]:
"""List tools from the cache, if caching is enabled, and the result is in the cache. Otherwise,
- otherwise call the next middleware and store the result in the cache if caching is enabled."""
+ call the next middleware and store the result in the cache if caching is enabled."""
if self._list_tools_settings.get("enabled") is False:
return await call_next(context)
@@ -409,7 +408,7 @@ class ResponseCachingMiddleware(Middleware):
call_next: CallNext[mcp_types.ListResourcesRequest, Sequence[Resource]],
) -> Sequence[Resource]:
"""List resources from the cache, if caching is enabled, and the result is in the cache. Otherwise,
- otherwise call the next middleware and store the result in the cache if caching is enabled."""
+ call the next middleware and store the result in the cache if caching is enabled."""
if self._list_resources_settings.get("enabled") is False:
return await call_next(context)
@@ -442,7 +441,7 @@ class ResponseCachingMiddleware(Middleware):
call_next: CallNext[mcp_types.ListPromptsRequest, Sequence[Prompt]],
) -> Sequence[Prompt]:
"""List prompts from the cache, if caching is enabled, and the result is in the cache. Otherwise,
- otherwise call the next middleware and store the result in the cache if caching is enabled."""
+ call the next middleware and store the result in the cache if caching is enabled."""
if self._list_prompts_settings.get("enabled") is False:
return await call_next(context)
@@ -473,7 +472,7 @@ class ResponseCachingMiddleware(Middleware):
call_next: CallNext[mcp_types.CallToolRequestParams, ToolResult],
) -> ToolResult:
"""Call a tool from the cache, if caching is enabled, and the result is in the cache. Otherwise,
- otherwise call the next middleware and store the result in the cache if caching is enabled."""
+ call the next middleware and store the result in the cache if caching is enabled."""
tool_name = context.message.name
if self._call_tool_settings.get(
@@ -542,7 +541,7 @@ class ResponseCachingMiddleware(Middleware):
call_next: CallNext[mcp_types.ReadResourceRequestParams, ResourceResult],
) -> ResourceResult:
"""Read a resource from the cache, if caching is enabled, and the result is in the cache. Otherwise,
- otherwise call the next middleware and store the result in the cache if caching is enabled."""
+ call the next middleware and store the result in the cache if caching is enabled."""
if self._read_resource_settings.get("enabled") is False:
return await call_next(context)
@@ -591,7 +590,7 @@ class ResponseCachingMiddleware(Middleware):
call_next: CallNext[mcp_types.GetPromptRequestParams, PromptResult],
) -> PromptResult:
"""Get a prompt from the cache, if caching is enabled, and the result is in the cache. Otherwise,
- otherwise call the next middleware and store the result in the cache if caching is enabled."""
+ call the next middleware and store the result in the cache if caching is enabled."""
if self._get_prompt_settings.get("enabled") is False:
return await call_next(context)
diff --git a/fastmcp_slim/fastmcp/server/middleware/error_handling.py b/fastmcp_slim/fastmcp/server/middleware/error_handling.py
index 29f8bc0f1..9b50b6c3c 100644
--- a/fastmcp_slim/fastmcp/server/middleware/error_handling.py
+++ b/fastmcp_slim/fastmcp/server/middleware/error_handling.py
@@ -1,6 +1,5 @@
"""Error handling middleware for consistent error responses and tracking."""
-import asyncio
import logging
import traceback
from collections.abc import Callable
@@ -113,8 +112,7 @@ class ErrorHandlingMiddleware(Middleware):
return MCPError(code=-32001, message=f"Not found: {error!s}")
elif issubclass(error_type, PermissionError):
return MCPError(code=-32000, message=f"Permission denied: {error!s}")
- # asyncio.TimeoutError is a subclass of TimeoutError in Python 3.10, alias in 3.11+
- elif issubclass(error_type, (TimeoutError, asyncio.TimeoutError)):
+ elif issubclass(error_type, TimeoutError):
return MCPError(code=-32000, message=f"Request timeout: {error!s}")
else:
return MCPError(code=-32603, message=f"Internal error: {error!s}")
diff --git a/fastmcp_slim/fastmcp/server/middleware/logging.py b/fastmcp_slim/fastmcp/server/middleware/logging.py
index fe77a4d03..052023acb 100644
--- a/fastmcp_slim/fastmcp/server/middleware/logging.py
+++ b/fastmcp_slim/fastmcp/server/middleware/logging.py
@@ -179,15 +179,15 @@ class LoggingMiddleware(BaseLoggingMiddleware):
"""Initialize logging middleware.
Args:
- logger: Logger instance to use. If None, creates a logger named 'fastmcp.requests'
+ logger: Logger instance to use. If None, creates a logger named 'fastmcp.middleware.logging'
log_level: Log level for messages (default: INFO)
include_payloads: Whether to include message payloads in logs
- include_payload_length: Whether to include response size in logs
- estimate_payload_tokens: Whether to estimate response tokens
+ include_payload_length: Whether to include payload size in logs
+ estimate_payload_tokens: Whether to estimate payload tokens using length // 4
max_payload_length: Maximum length of payload to log (prevents huge logs)
methods: List of methods to log. If None, logs all methods.
payload_serializer: Callable that converts objects to a JSON string for the
- payload. If not provided, uses FastMCP's default tool serializer.
+ payload. If not provided, uses `default_serializer` (pydantic_core JSON with a `str` fallback).
"""
self.logger: Logger = logger or logging.getLogger("fastmcp.middleware.logging")
self.log_level = log_level
@@ -230,14 +230,14 @@ class StructuredLoggingMiddleware(BaseLoggingMiddleware):
"""Initialize structured logging middleware.
Args:
- logger: Logger instance to use. If None, creates a logger named 'fastmcp.structured'
+ logger: Logger instance to use. If None, creates a logger named 'fastmcp.middleware.structured_logging'
log_level: Log level for messages (default: INFO)
include_payloads: Whether to include message payloads in logs
include_payload_length: Whether to include payload size in logs
estimate_payload_tokens: Whether to estimate token count using length // 4
methods: List of methods to log. If None, logs all methods.
payload_serializer: Callable that converts objects to a JSON string for the
- payload. If not provided, uses FastMCP's default tool serializer.
+ payload. If not provided, uses `default_serializer` (pydantic_core JSON with a `str` fallback).
"""
self.logger: Logger = logger or logging.getLogger(
"fastmcp.middleware.structured_logging"
diff --git a/fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py b/fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py
index 158158db7..c87cc31cc 100644
--- a/fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py
+++ b/fastmcp_slim/fastmcp/server/providers/fastmcp_provider.py
@@ -39,7 +39,7 @@ class FastMCPProviderTool(Tool):
"""Tool that delegates execution to a wrapped server's middleware.
When `run()` is called, this tool invokes the wrapped server's
- `_call_tool_middleware()` method, ensuring the server's middleware
+ `call_tool()` method, ensuring the server's middleware
chain is executed.
"""
diff --git a/fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py b/fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py
index ebb662571..9a1c1de76 100644
--- a/fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py
+++ b/fastmcp_slim/fastmcp/server/providers/local_provider/local_provider.py
@@ -61,7 +61,7 @@ class LocalProvider(
When used standalone, LocalProvider uses default settings. When attached
to a FastMCP server via the server's decorators, server-level settings
- like `_tool_serializer` and `_support_tasks_by_default` are injected.
+ like `_support_tasks_by_default` are injected.
Example:
```python
diff --git a/fastmcp_slim/fastmcp/server/providers/openapi/README.md b/fastmcp_slim/fastmcp/server/providers/openapi/README.md
deleted file mode 100644
index 8b55d8753..000000000
--- a/fastmcp_slim/fastmcp/server/providers/openapi/README.md
+++ /dev/null
@@ -1,266 +0,0 @@
-# OpenAPI Server Implementation (New)
-
-This directory contains the next-generation FastMCP server implementation for OpenAPI integration, designed to replace the legacy implementation in `/server/openapi.py`.
-
-## Architecture Overview
-
-The new implementation uses a **stateless request building approach** with `openapi-core` and `RequestDirector`, providing zero-latency startup and robust OpenAPI support optimized for serverless environments.
-
-### Core Components
-
-1. **`server.py`** - `FastMCPOpenAPI` main server class with RequestDirector integration
-2. **`components.py`** - Simplified component implementations using RequestDirector
-3. **`routing.py`** - Route mapping and component selection logic
-
-### Key Architecture Principles
-
-#### 1. Stateless Performance
-- **Zero Startup Latency**: No code generation or heavy initialization
-- **RequestDirector**: Stateless HTTP request building using openapi-core
-- **Pre-calculated Schemas**: All complex processing done during parsing
-
-#### 2. Unified Implementation
-- **Single Code Path**: All components use RequestDirector consistently
-- **No Fallbacks**: Simplified architecture without hybrid complexity
-- **Performance First**: Optimized for cold starts and serverless deployments
-
-#### 3. OpenAPI Compliance
-- **openapi-core Integration**: Leverages proven library for parameter serialization
-- **Full Feature Support**: Complete OpenAPI 3.0/3.1 support including deepObject
-- **Error Handling**: Comprehensive HTTP error mapping to MCP errors
-
-## Component Classes
-
-### RequestDirector-Based Components
-
-#### `OpenAPITool`
-- Executes operations using RequestDirector for HTTP request building
-- Automatic parameter validation and OpenAPI-compliant serialization
-- Built-in error handling and structured response processing
-- **Advantages**: Zero latency, robust, comprehensive OpenAPI support
-
-#### `OpenAPIResource` / `OpenAPIResourceTemplate`
-- Provides resource access using RequestDirector
-- Consistent parameter handling across all resource types
-- Support for complex parameter patterns and collision resolution
-- **Advantages**: High performance, simplified architecture, reliable error handling
-
-## Server Implementation
-
-### `FastMCPOpenAPI` Class
-
-The main server class orchestrates the stateless request building approach:
-
-```python
-class FastMCPOpenAPI(FastMCP):
- def __init__(self, openapi_spec: dict, client: httpx2.AsyncClient, **kwargs):
- # 1. Parse OpenAPI spec to HTTP routes with pre-calculated schemas
- self._routes = parse_openapi_to_http_routes(openapi_spec)
-
- # 2. Initialize RequestDirector with openapi-core Spec
- self._spec = Spec.from_dict(openapi_spec)
- self._director = RequestDirector(self._spec)
-
- # 3. Create components using RequestDirector
- self._create_components()
-```
-
-### Component Creation Logic
-
-```python
-def _create_tool(self, route: HTTPRoute) -> Tool:
- # All tools use RequestDirector for consistent, high-performance request building
- return OpenAPITool(
- client=self._client,
- route=route,
- director=self._director,
- name=tool_name,
- description=description,
- parameters=flat_param_schema
- )
-```
-
-## Data Flow
-
-### Stateless Request Building
-
-```
-OpenAPI Spec β†’ HTTPRoute with Pre-calculated Fields β†’ RequestDirector β†’ HTTP Request β†’ Structured Response
-```
-
-1. **Spec Parsing**: OpenAPI spec parsed to `HTTPRoute` models with pre-calculated schemas
-2. **RequestDirector Setup**: openapi-core Spec initialized for request building
-3. **Component Creation**: Create components with RequestDirector reference
-4. **Request Building**: RequestDirector builds HTTP request from flat parameters
-5. **Request Execution**: Execute request with httpx2 client
-6. **Response Processing**: Return structured MCP response
-
-## Key Features
-
-### 1. Enhanced Parameter Handling
-
-#### Parameter Collision Resolution
-- **Automatic Suffixing**: Colliding parameters get location-based suffixes
-- **Example**: `id` in path and body becomes `id__path` and `id`
-- **Transparent**: LLMs see suffixed parameters, implementation routes correctly
-
-#### DeepObject Style Support
-- **Native Support**: Generated client handles all deepObject variations
-- **Explode Handling**: Proper support for explode=true/false
-- **Complex Objects**: Nested object serialization works correctly
-
-### 2. Robust Error Handling
-
-#### HTTP Error Mapping
-- **Status Code Mapping**: HTTP errors mapped to appropriate MCP errors
-- **Structured Responses**: Error details preserved in tool results
-- **Timeout Handling**: Network timeouts handled gracefully
-
-#### Request Building Error Handling
-- **Parameter Validation**: Invalid parameters caught during request building
-- **Schema Validation**: openapi-core validates all OpenAPI constraints
-- **Graceful Degradation**: Missing optional parameters handled smoothly
-
-### 3. Performance Optimizations
-
-#### Efficient Client Reuse
-- **Connection Pooling**: HTTP connections reused across requests
-- **Client Caching**: Generated clients cached for performance
-- **Async Support**: Full async/await throughout
-
-#### Request Optimization
-- **Pre-calculated Schemas**: All complex processing done during initialization
-- **Parameter Mapping**: Collision resolution handled upfront
-- **Zero Latency**: No runtime code generation or complex schema processing
-
-## Configuration
-
-### Server Options
-
-```python
-server = FastMCPOpenAPI(
- openapi_spec=spec, # Required: OpenAPI specification
- client=httpx_client, # Required: HTTP client instance
- name="API Server", # Optional: Server name
- route_map=custom_routes, # Optional: Custom route mappings
- enable_caching=True, # Optional: Enable response caching
-)
-```
-
-### Route Mapping Customization
-
-```python
-from fastmcp.server.openapi_new.routing import RouteMap
-
-custom_routes = RouteMap({
- "GET:/users": "tool", # Force specific operations to be tools
- "GET:/status": "resource", # Force specific operations to be resources
-})
-```
-
-## Testing Strategy
-
-### Test Structure
-
-Tests are organized by functionality:
-- `test_server.py` - Server integration and RequestDirector behavior
-- `test_parameter_collisions.py` - Parameter collision handling
-- `test_deepobject_style.py` - DeepObject parameter style support
-- `test_openapi_features.py` - General OpenAPI feature compliance
-
-### Testing Philosophy
-
-1. **Real Integration**: Test with real OpenAPI specs and HTTP clients
-2. **Minimal Mocking**: Only mock external API endpoints
-3. **Behavioral Focus**: Test behavior, not implementation details
-4. **Performance Focus**: Test that initialization is fast and stateless
-
-### Example Test Pattern
-
-```python
-async def test_stateless_request_building():
- """Test that server works with stateless RequestDirector approach."""
-
- # Test server initialization is fast
- start_time = time.time()
- server = FastMCPOpenAPI(spec=valid_spec, client=client)
- init_time = time.time() - start_time
- assert init_time < 0.01 # Should be very fast
-
- # Verify RequestDirector functionality
- assert hasattr(server, '_director')
- assert hasattr(server, '_spec')
-```
-
-## Migration Benefits
-
-### From Legacy Implementation
-
-1. **Eliminated Startup Latency**: Zero code generation overhead (100-200ms improvement)
-2. **Better OpenAPI Compliance**: openapi-core handles all OpenAPI features correctly
-3. **Serverless Friendly**: Perfect for cold-start environments
-4. **Simplified Architecture**: Single RequestDirector approach eliminates complexity
-5. **Enhanced Reliability**: No dynamic code generation failures
-
-### Backward Compatibility
-
-- **Same Interface**: Public API unchanged from legacy implementation
-- **Performance Improvement**: Significantly faster initialization
-- **No Breaking Changes**: Existing code works without modification
-
-## Monitoring and Debugging
-
-### Logging
-
-```python
-# Enable debug logging to see implementation choices
-import logging
-logging.getLogger("fastmcp.server.openapi_new").setLevel(logging.DEBUG)
-```
-
-### Key Log Messages
-- **RequestDirector Initialization**: Success/failure of RequestDirector setup
-- **Schema Pre-calculation**: Pre-calculated schema and parameter map status
-- **Request Building**: Parameter mapping and URL construction details
-- **Performance Metrics**: Request timing and error rates
-
-### Debugging Common Issues
-
-1. **RequestDirector Initialization Fails**
- - Check OpenAPI spec validity with `openapi-core`
- - Verify spec format is correct JSON/YAML
- - Ensure all required OpenAPI fields are present
-
-2. **Parameter Issues**
- - Enable debug logging for parameter processing
- - Check for parameter collision warnings
- - Verify OpenAPI spec parameter definitions
-
-3. **Performance Issues**
- - Monitor RequestDirector request building timing
- - Check HTTP client configuration
- - Review response processing timing
-
-## Future Enhancements
-
-### Planned Features
-
-1. **Advanced Caching**: Intelligent response caching with TTL
-2. **Streaming Support**: Handle streaming API responses
-3. **Batch Operations**: Optimize multiple operation calls
-4. **Enhanced Monitoring**: Detailed metrics and health checks
-5. **Configuration Management**: Dynamic configuration updates
-
-### Performance Improvements
-
-1. **Enhanced Schema Caching**: More aggressive schema pre-calculation
-2. **Parallel Processing**: Concurrent operation execution
-3. **Memory Optimization**: Further reduce memory footprint
-4. **Request Optimization**: Smart request batching and deduplication
-
-## Related Documentation
-
-- `/utilities/openapi_new/README.md` - Utility implementation details
-- `/server/openapi/README.md` - Legacy implementation reference
-- `/tests/server/openapi_new/` - Comprehensive test suite
-- Project documentation on OpenAPI integration patterns
diff --git a/fastmcp_slim/fastmcp/server/server.py b/fastmcp_slim/fastmcp/server/server.py
index cda46c54e..eb00b1872 100644
--- a/fastmcp_slim/fastmcp/server/server.py
+++ b/fastmcp_slim/fastmcp/server/server.py
@@ -2037,7 +2037,7 @@ class FastMCP(
This decorator supports multiple calling patterns:
- @server.tool (without parentheses)
- - @server.tool (with empty parentheses)
+ - @server.tool() (with empty parentheses)
- @server.tool("custom_name") (with name as first argument)
- @server.tool(name="custom_name") (with name as keyword argument)
- server.tool(function, name="custom_name") (direct function call)
@@ -2052,17 +2052,12 @@ class FastMCP(
meta: Optional meta information about the tool
Examples:
- Register a tool with a custom name:
+ Register a tool:
```python
@server.tool
def my_tool(x: int) -> str:
return str(x)
- # Register a tool with a custom name
- @server.tool
- def my_tool(x: int) -> str:
- return str(x)
-
@server.tool("custom_name")
def my_tool(x: int) -> str:
return str(x)
@@ -2176,7 +2171,7 @@ class FastMCP(
return "Hello, world!"
@server.resource("resource://my-resource")
- async get_data() -> str:
+ async def get_data() -> str:
data = await fetch_data()
return f"Hello, world! {data}"
diff --git a/fastmcp_slim/fastmcp/utilities/types.py b/fastmcp_slim/fastmcp/utilities/types.py
index 56d77e59c..058da1bcd 100644
--- a/fastmcp_slim/fastmcp/utilities/types.py
+++ b/fastmcp_slim/fastmcp/utilities/types.py
@@ -27,9 +27,7 @@ from typing_extensions import TypeVar
T = TypeVar("T", default=Any)
-# TODO(sdkv2): the SDK's `mcp.types.AnyFunction` alias was removed with the
-# mcp.types module. FastMCP owns it now; keep the same `Callable[..., Any]`
-# meaning used by tool/prompt/resource decorators.
+# MCP SDK v2 dropped the `AnyFunction` alias; FastMCP owns it now with the same `Callable[..., Any]` meaning.
AnyFunction: TypeAlias = Callable[..., Any]
# sentinel values for optional arguments
diff --git a/fastmcp_tasks/fastmcp_tasks/settings.py b/fastmcp_tasks/fastmcp_tasks/settings.py
index a179c1e88..e830d5638 100644
--- a/fastmcp_tasks/fastmcp_tasks/settings.py
+++ b/fastmcp_tasks/fastmcp_tasks/settings.py
@@ -56,7 +56,7 @@ class DocketSettings(BaseSettings):
Default is memory:// for single-process scenarios. Use Redis or Valkey
when coordinating tasks across multiple processes (e.g., additional
- workers via the fastmcp tasks CLI).
+ workers via `python -m fastmcp_tasks.worker_cli`).
"""
),
),
diff --git a/fastmcp_tasks/fastmcp_tasks/worker_cli.py b/fastmcp_tasks/fastmcp_tasks/worker_cli.py
index 80d68d0e3..ca2babcd3 100644
--- a/fastmcp_tasks/fastmcp_tasks/worker_cli.py
+++ b/fastmcp_tasks/fastmcp_tasks/worker_cli.py
@@ -105,7 +105,7 @@ def check_distributed_backend(settings: DocketSettings) -> None:
"[bold red]βœ— In-memory backend not supported by CLI[/bold red]\n\n"
"Your Docket configuration uses an in-memory backend (memory://) which\n"
"only works within a single process.\n\n"
- "To use [cyan]fastmcp tasks[/cyan] CLI commands (which run in separate\n"
+ "To run [cyan]fastmcp_tasks.worker_cli[/cyan] workers (which run in separate\n"
"processes), you need a distributed backend:\n\n"
"[bold]1. Install Redis or Valkey:[/bold]\n"
" [dim]macOS:[/dim] brew install redis\n"
@@ -119,7 +119,7 @@ def check_distributed_backend(settings: DocketSettings) -> None:
"[bold]4. Try again[/bold]\n\n"
"The memory backend works great for single-process servers, but the CLI\n"
"commands need a distributed backend to coordinate across processes.\n\n"
- "Need help? See: [cyan]https://gofastmcp.com/docs/tasks[/cyan]"
+ "Need help? See: [cyan]https://gofastmcp.com/servers/tasks[/cyan]"
)
sys.exit(1)
@@ -140,8 +140,8 @@ def worker(
(FASTMCP_DOCKET_*).
Example:
- fastmcp tasks worker server.py
- fastmcp tasks worker examples/tasks/server.py
+ python -m fastmcp_tasks.worker_cli worker server.py
+ python -m fastmcp_tasks.worker_cli worker examples/tasks/server.py
"""
# Load server to get task functions
try:
diff --git a/justfile b/justfile
index eb11e2df2..b57e59b8d 100644
--- a/justfile
+++ b/justfile
@@ -23,7 +23,7 @@ docs-broken-links:
# Generate API reference documentation for all modules
api-ref-all:
uvx --with-editable "{{api_ref_package}}" --refresh-package mdxify mdxify@latest --all --root-module fastmcp --nav-output docs/python-sdk-pages.json --exclude fastmcp.contrib
-# Generate API reference for specific modules (e.g., just api-ref prefect.flows prefect.tasks)
+# Generate API reference for specific modules (e.g., just api-ref fastmcp.server.server fastmcp.client.client)
api-ref *MODULES:
uvx --with-editable "{{api_ref_package}}" --refresh-package mdxify mdxify@latest {{MODULES}} --root-module fastmcp --nav-output docs/python-sdk-pages.json
diff --git a/loq.toml b/loq.toml
index ab7259a11..dcc432035 100644
--- a/loq.toml
+++ b/loq.toml
@@ -6,10 +6,6 @@ respect_gitignore = true
exclude = ["**/uv.lock", ".git/**", "docs/**"]
-[[rules]]
-path = "tests/**"
-max_lines = 1000
-
[[rules]]
path = "fastmcp_slim/fastmcp/server/context.py"
max_lines = 1404
@@ -50,10 +46,6 @@ max_lines = 1016
path = "tests/server/providers/openapi/test_openapi_features.py"
max_lines = 1029
-[[rules]]
-path = "tests/server/tasks/test_task_mount.py"
-max_lines = 1088
-
[[rules]]
path = "tests/server/test_dependencies.py"
max_lines = 1194