Skip to content

Rename Enabled transform to Visibility #2950

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jlowin merged 3 commits into from
Jan 20, 2026
Merged

Rename Enabled transform to Visibility #2950

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e861613
Rename Enabled transform class to Visibility
jlowin Jan 20, 2026
3ea9289
Update v3-features doc to use Visibility terminology
jlowin Jan 20, 2026
081223f
Fix missed reset_components reference in docs
jlowin Jan 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/development/v3-notes/v3-features.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ class Provider:

Providers support:
- **Lifecycle management**: `async def lifespan()` for setup/teardown
- **Enabled control**: `enable()` / `disable()` with name, version, tags, components, and allowlist mode
- **Visibility control**: `enable()` / `disable()` with name, version, tags, components, and allowlist mode
- **Transform stacking**: `provider.add_transform(Namespace(...))`, `provider.add_transform(ToolTransform(...))`

### LocalProvider
Expand Down Expand Up @@ -106,7 +106,7 @@ Transforms modify components (tools, resources, prompts) as they flow from provi

- `Namespace` - adds prefixes to names (`tool` → `api_tool`) and path segments to URIs (`data://x` → `data://api/x`)
- `ToolTransform` - modifies tool schemas (rename, description, tags, argument transforms)
- `Enabled` - sets enabled state on components by key or tag (backs `enable()`/`disable()` API)
- `Visibility` - sets visibility state on components by key or tag (backs `enable()`/`disable()` API)
- `VersionFilter` - filters components by version range (`version_gte`, `version_lt`)
- `ResourcesAsTools` - exposes resources as tools for tool-only clients
- `PromptsAsTools` - exposes prompts as tools for tool-only clients
Expand Down Expand Up @@ -149,7 +149,7 @@ Transforms apply at two levels:
- **Provider-level**: `provider.add_transform()` - affects only that provider's components
- **Server-level**: `server.add_transform()` - affects all components from all providers

Documentation: `docs/servers/providers/transforms.mdx`, `docs/servers/enabled.mdx`
Documentation: `docs/servers/providers/transforms.mdx`, `docs/servers/visibility.mdx`

### ResourcesAsTools and PromptsAsTools

Expand Down Expand Up @@ -232,9 +232,9 @@ Documentation: `docs/servers/context.mdx`

---

## Enabled System
## Visibility System

Components can be enabled/disabled using the enabled system. Each `enable()` or `disable()` call adds a stateless Enabled transform that marks components via internal metadata. Later transforms override earlier ones.
Components can be enabled/disabled using the visibility system. Each `enable()` or `disable()` call adds a stateless Visibility transform that marks components via internal metadata. Later transforms override earlier ones.

```python
mcp = FastMCP("Server")
Expand All @@ -261,7 +261,7 @@ Works at both server and provider level. Supports:
- **Allowlist mode** (`only=True`): Only explicitly enabled components visible
- **Tag-based filtering**: Enable/disable groups of components by tag
- **Override semantics**: Later transforms override earlier marks (enable after disable = enabled)
- **Transform ordering**: Enabled transforms are injected at the point you call them, so component state is known
- **Transform ordering**: Visibility transforms are injected at the point you call them, so component state is known

### Per-Session Visibility

Expand All @@ -286,7 +286,7 @@ async def unlock_premium(ctx: Context) -> str:
@mcp.tool
async def reset_features(ctx: Context) -> str:
"""Reset to default feature set."""
await ctx.reset_components()
await ctx.reset_visibility()
return "Features reset to defaults"

# Globally disabled - sessions unlock individually
Expand All @@ -296,11 +296,11 @@ mcp.disable(tags={"premium"})
Session visibility methods:
- `await ctx.enable_components(...)`: Enable components for this session
- `await ctx.disable_components(...)`: Disable components for this session
- `await ctx.reset_components()`: Clear session rules, return to global defaults
- `await ctx.reset_visibility()`: Clear session rules, return to global defaults

Session rules override global transforms. FastMCP automatically sends `ToolListChangedNotification` (and resource/prompt equivalents) to affected sessions when visibility changes.

Documentation: `docs/servers/enabled.mdx`
Documentation: `docs/servers/visibility.mdx`

---

Expand Down
4 changes: 2 additions & 2 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@
"servers/tasks",
"servers/telemetry",
"servers/versioning",
"servers/enabled"
"servers/visibility"
]
},
{
Expand Down Expand Up @@ -563,7 +563,7 @@
"group": "transforms",
"pages": [
"python-sdk/fastmcp-server-transforms-__init__",
"python-sdk/fastmcp-server-transforms-enabled",
"python-sdk/fastmcp-server-transforms-visibility",
"python-sdk/fastmcp-server-transforms-namespace",
"python-sdk/fastmcp-server-transforms-prompts_as_tools",
"python-sdk/fastmcp-server-transforms-resources_as_tools",
Expand Down
8 changes: 4 additions & 4 deletions docs/python-sdk/fastmcp-server-context.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -591,7 +591,7 @@ Enable components matching criteria for this session only.

Session rules override global transforms. Rules accumulate - each call
adds a new rule to the session. Later marks override earlier ones
(Enabled transform semantics).
(Visibility transform semantics).

Sends notifications to this session only: ToolListChangedNotification,
ResourceListChangedNotification, and PromptListChangedNotification.
Expand All @@ -615,7 +615,7 @@ Disable components matching criteria for this session only.

Session rules override global transforms. Rules accumulate - each call
adds a new rule to the session. Later marks override earlier ones
(Enabled transform semantics).
(Visibility transform semantics).

Sends notifications to this session only: ToolListChangedNotification,
ResourceListChangedNotification, and PromptListChangedNotification.
Expand All @@ -629,10 +629,10 @@ ResourceListChangedNotification, and PromptListChangedNotification.
- `match_all`: If True, matches all components regardless of other criteria.


#### `reset_components` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1073" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
#### `reset_visibility` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/context.py#L1073" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
reset_components(self) -> None
reset_visibility(self) -> None
```

Clear all session visibility rules.
Expand Down
10 changes: 5 additions & 5 deletions docs/python-sdk/fastmcp-server-providers-base.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None
Get tool by transformed name with all transforms applied.

Note: This method does NOT filter disabled components. The Server
(FastMCP) performs enabled filtering after all transforms complete,
(FastMCP) performs visibility filtering after all transforms complete,
allowing session-level transforms to override provider-level disables.

**Args:**
Expand Down Expand Up @@ -152,7 +152,7 @@ get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | N
Get resource by transformed URI with all transforms applied.

Note: This method does NOT filter disabled components. The Server
(FastMCP) performs enabled filtering after all transforms complete.
(FastMCP) performs visibility filtering after all transforms complete.

**Args:**
- `uri`: The transformed resource URI to look up.
Expand Down Expand Up @@ -182,7 +182,7 @@ get_resource_template(self, uri: str, version: VersionSpec | None = None) -> Res
Get resource template by transformed URI with all transforms applied.

Note: This method does NOT filter disabled components. The Server
(FastMCP) performs enabled filtering after all transforms complete.
(FastMCP) performs visibility filtering after all transforms complete.

**Args:**
- `uri`: The transformed template URI to look up.
Expand Down Expand Up @@ -212,7 +212,7 @@ get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None
Get prompt by transformed name with all transforms applied.

Note: This method does NOT filter disabled components. The Server
(FastMCP) performs enabled filtering after all transforms complete.
(FastMCP) performs visibility filtering after all transforms complete.

**Args:**
- `name`: The transformed prompt name to look up.
Expand Down Expand Up @@ -289,7 +289,7 @@ disable(self) -> Self

Disable components matching all specified criteria.

Adds an enabled transform that marks matching components as disabled.
Adds a visibility transform that marks matching components as disabled.
Components can be re-enabled by calling enable() with matching criteria
(the later transform wins).
Comment on lines +292 to 294
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

find . -name "base.py" -type f | grep -E "(fastmcp|server.*provider)" | head -20

Repository: jlowin/fastmcp

Length of output: 263

🏁 Script executed:

git ls-files | grep -E "fastmcp.*base\.py|server.*providers.*base\.py"

Repository: jlowin/fastmcp

Length of output: 346

🏁 Script executed:

fd "base.py" --type f

Repository: jlowin/fastmcp

Length of output: 346

🏁 Script executed:

cat -n src/fastmcp/server/providers/base.py | head -350

Repository: jlowin/fastmcp

Length of output: 15488

🏁 Script executed:

wc -l src/fastmcp/server/providers/base.py

Repository: jlowin/fastmcp

Length of output: 98

🏁 Script executed:

rg -n -B2 -A5 'def enable\(' src/fastmcp/server/providers/base.py

Repository: jlowin/fastmcp

Length of output: 332

🏁 Script executed:

rg -n -B2 -A5 'def disable\(' src/fastmcp/server/providers/base.py

Repository: jlowin/fastmcp

Length of output: 273

🏁 Script executed:

sed -n '492,538p' src/fastmcp/server/providers/base.py

Repository: jlowin/fastmcp

Length of output: 1897

🏁 Script executed:

sed -n '541,578p' src/fastmcp/server/providers/base.py

Repository: jlowin/fastmcp

Length of output: 1471

🏁 Script executed:

cat -n docs/python-sdk/fastmcp-server-providers-base.mdx | sed -n '260,300p'

Repository: jlowin/fastmcp

Length of output: 1891

Update enable() documentation to match disable() and source code

The disable() change is correct, but the documentation for enable() at line 264 needs updating. The source code docstring for enable() says "Adds a visibility transform" (matching disable()), but the documentation still shows "Adds an enabled transform". Change line 264 from "Adds an enabled transform" to "Adds a visibility transform" for consistency with both the source and the disable() method.


Expand Down
16 changes: 8 additions & 8 deletions docs/python-sdk/fastmcp-server-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,7 +191,7 @@ list_tools(self) -> Sequence[Tool]

List all enabled tools from providers.

Overrides Provider.list_tools() to add enabled filtering, auth filtering,
Overrides Provider.list_tools() to add visibility filtering, auth filtering,
and middleware execution. Returns all versions (no deduplication).
Protocol handlers deduplicate for MCP wire format.

Expand All @@ -204,7 +204,7 @@ get_tool(self, name: str, version: VersionSpec | None = None) -> Tool | None

Get a tool by name, filtering disabled tools.

Overrides Provider.get_tool() to add enabled filtering after all
Overrides Provider.get_tool() to add visibility filtering after all
transforms (including session-level) have been applied. This ensures
session transforms can override provider-level disables.

Expand All @@ -224,7 +224,7 @@ list_resources(self) -> Sequence[Resource]

List all enabled resources from providers.

Overrides Provider.list_resources() to add enabled filtering, auth filtering,
Overrides Provider.list_resources() to add visibility filtering, auth filtering,
and middleware execution. Returns all versions (no deduplication).
Protocol handlers deduplicate for MCP wire format.

Expand All @@ -237,7 +237,7 @@ get_resource(self, uri: str, version: VersionSpec | None = None) -> Resource | N

Get a resource by URI, filtering disabled resources.

Overrides Provider.get_resource() to add enabled filtering after all
Overrides Provider.get_resource() to add visibility filtering after all
transforms (including session-level) have been applied.

**Args:**
Expand All @@ -256,7 +256,7 @@ list_resource_templates(self) -> Sequence[ResourceTemplate]

List all enabled resource templates from providers.

Overrides Provider.list_resource_templates() to add enabled filtering,
Overrides Provider.list_resource_templates() to add visibility filtering,
auth filtering, and middleware execution. Returns all versions (no deduplication).
Protocol handlers deduplicate for MCP wire format.

Expand All @@ -269,7 +269,7 @@ get_resource_template(self, uri: str, version: VersionSpec | None = None) -> Res

Get a resource template by URI, filtering disabled templates.

Overrides Provider.get_resource_template() to add enabled filtering after
Overrides Provider.get_resource_template() to add visibility filtering after
all transforms (including session-level) have been applied.

**Args:**
Expand All @@ -288,7 +288,7 @@ list_prompts(self) -> Sequence[Prompt]

List all enabled prompts from providers.

Overrides Provider.list_prompts() to add enabled filtering, auth filtering,
Overrides Provider.list_prompts() to add visibility filtering, auth filtering,
and middleware execution. Returns all versions (no deduplication).
Protocol handlers deduplicate for MCP wire format.

Expand All @@ -301,7 +301,7 @@ get_prompt(self, name: str, version: VersionSpec | None = None) -> Prompt | None

Get a prompt by name, filtering disabled prompts.

Overrides Provider.get_prompt() to add enabled filtering after all
Overrides Provider.get_prompt() to add visibility filtering after all
transforms (including session-level) have been applied.

**Args:**
Expand Down
Loading