Visibility transform crashes when tags passed as list instead of set

[strawgate]

Summary

Visibility(False, tags=['internal']) crashes with TypeError when applied to components. The constructor accepts any iterable for tags (type hint is set[str] | None), but _matches() performs set intersection (&) which fails on lists.

Reproduction

from fastmcp import FastMCP
from fastmcp.server.transforms.visibility import Visibility

mcp = FastMCP('test')

@mcp.tool(tags={'internal'})
def my_tool() -> str:
    """A test tool"""
    return 'hello'

vis = Visibility(False, tags=['internal'])
mcp.add_transform(vis)

# Crashes:
tools = await mcp.list_tools()
# TypeError: unsupported operand type(s) for &: 'set' and 'list'

Root Cause

visibility.py:88 stores tags without coercion:

self.tags = tags  # stored as-is (could be list)

visibility.py:171 uses set intersection:

return self.tags is None or bool(component.tags & self.tags)

component.tags is always a set (enforced by Pydantic BeforeValidator), but self.tags can be a list, and set & list raises TypeError.

Note

The safe API paths (provider.disable(), ctx.disable_components()) already coerce to set. Only direct Visibility() construction is affected.

Fix

Coerce tags to set in the constructor: self.tags = set(tags) if tags is not None else None

[marvin-context-protocol]

Claude finished @strawgate's task in 1m 3s —— View job

---

Triage

• Read issue and reproduction
• Locate Visibility class and _matches in src/fastmcp/server/transforms/visibility.py
• Verify root cause (set & list → TypeError)
• Check related paths (create_visibility_transforms, enable/disable_components) for consistency

Recommendation

The report is accurate and the proposed fix is correct. Apply a minimal, defensive coercion in Visibility.__init__ so any iterable (list, tuple, generator) is normalized to the canonical set[str] the rest of the class expects.

For consistency, coerce all four iterable args (names, keys, tags, components) — not just tags. Today only tags crashes because it's the only one using set intersection (&). The others use in and happen to work with lists, but the type hints say set[str] | None and downstream code (e.g. __repr__ at visibility.py:97-106) already calls set(...) on them. Normalizing once at construction removes the footgun for future maintainers and matches the coercion create_visibility_transforms already does at visibility.py:347-352.

Findings

• Bug site: src/fastmcp/server/transforms/visibility.py:171 — bool(component.tags & self.tags) requires both operands to be sets. component.tags is guaranteed to be a set via FastMCPComponent's Pydantic BeforeValidator, but self.tags is stored as-is at line 88.
• Verified locally: set({'a','b'}) & ['a','c'] → TypeError: unsupported operand type(s) for &: 'set' and 'list'.
• Safe paths already coerce: create_visibility_transforms (visibility.py:332-357), enable_components/disable_components (visibility.py:372-477) all accept set or wrap inputs in set(...) before building a Visibility. Only direct user construction of Visibility(...) is exposed.
• No existing test in tests/server/transforms/test_visibility.py covers passing a non-set iterable to Visibility.

Detailed Action Plan

1. Edit src/fastmcp/server/transforms/visibility.py, Visibility.__init__ (lines 84-90). Replace the four direct assignments with a small coercion helper so any iterable becomes set:

   def _to_set(value):
       return set(value) if value is not None else None
   
   self._enabled = enabled
   self.names = _to_set(names)
   self.keys = _to_set(keys)
   self.version = version
   self.tags = _to_set(tags)
   self.components = _to_set(components)
   self.match_all = match_all

   (Inline set(x) if x is not None else None is equally fine — pick whichever reads cleaner.) Keep the type hints as set[str] | None; the docstrings don't need to change.

2. Add regression tests in tests/server/transforms/test_visibility.py:

   • Visibility(False, tags=['internal']) applied to a component tagged {'internal'} should mark it disabled, not raise.
   • Parametrize the same test over list, tuple, and frozenset inputs for tags, names, keys, and components to lock in the coercion contract.
   • Assert isinstance(vis.tags, set) (and the same for the other three) after construction.

3. Run the suite per CLAUDE.md:

   uv sync
   uv run pytest tests/server/transforms/test_visibility.py -n auto
   uv run prek run --all-files

4. PR per CLAUDE.md conventions: 1–2 paragraphs describing the problem (type hint says set but constructor accepts any iterable, and _matches uses set intersection) and the solution (normalize at construction). Label as a bug. No need to touch enable_components/disable_components/create_visibility_transforms — they already coerce.

Related Files

File	Relevance	Lines
src/fastmcp/server/transforms/visibility.py	Visibility.__init__ stores tags without coercion; _matches does component.tags & self.tags.	60-90, 171
src/fastmcp/server/transforms/visibility.py	create_visibility_transforms already wraps inputs in set(...) — confirms coercion is the expected contract.	332-357
tests/server/transforms/test_visibility.py	Visibility transform test suite — add regression tests here.	—

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[strawgate]

this would be a type checking violation so not sure how important this is to fix though ideally we'd take a more generic type than sets in general for these -- I think ideally we'd accept a sequence and convert it to a set if we need a set

[strawgate]

Closing — this is a type checking issue, not a bug. The constructor signature is tags: set[str] | None. Passing a list is a type error that any type checker (mypy, pyright, ty) would catch. All internal callers already pass set(tags) correctly.