Add examples/ to the ty static-analysis gate (#4466)

* Add examples/ to ty static-analysis gate

* Fix example type errors and stale SDK idioms for ty

* Use typing_extensions.TypedDict for the quiz tool-param type

Question is a take_quiz parameter, so FastMCP builds a Pydantic schema
for it; typing.TypedDict raises PydanticUserError on Python 3.10/3.11
(only 3.12+ accepts it). ty and 3.12 runs miss this, so it slipped in.

* Guard get_access_token() None case in huggingface_oauth example

Caught by the ty gate this PR adds: the example, merged separately,
had never been type-checked against examples/. Matches the existing
aws_oauth/keycloak_oauth pattern.

* Print actual YAML text in custom serializer example

examples/apps/qr_server/qr_server.py

@@ -23,7 +23,7 @@ import base64
 import io
 
 import qrcode  # type: ignore[import-untyped]
-from mcp import types
+from mcp_types import ImageContent
 
 from fastmcp import FastMCP
 from fastmcp.apps import AppConfig, ResourceCSP
@@ -153,7 +153,7 @@ def generate_qr(
     img.save(buffer, format="PNG")
     b64 = base64.b64encode(buffer.getvalue()).decode()
     return ToolResult(
-        content=[types.ImageContent(type="image", data=b64, mimeType="image/png")]
+        content=[ImageContent(type="image", data=b64, mime_type="image/png")]
     )
 
 

examples/apps/quiz/quiz_server.py

@@ -28,12 +28,20 @@ from prefab_ui.components import (
     Text,
 )
 from prefab_ui.rx import ERROR, RESULT, Rx
+from typing_extensions import TypedDict
 
 from fastmcp import FastMCP, FastMCPApp
 
 app = FastMCPApp("Quiz")
 
-DEFAULT_QUESTIONS = [
+
+class Question(TypedDict):
+    question: str
+    options: list[str]
+    correct: int
+
+
+DEFAULT_QUESTIONS: list[Question] = [
     {
         "question": "What is the capital of Australia?",
         "options": ["Sydney", "Melbourne", "Canberra", "Perth"],
@@ -102,7 +110,7 @@ def submit_answer(
 @app.ui()
 def take_quiz(
     topic: str = "General Knowledge",
-    questions: list[dict] | None = None,
+    questions: list[Question] | None = None,
 ) -> PrefabApp:
     """Launch a quiz UI.
 

examples/apps/sales_dashboard/sales_dashboard_server.py

@@ -1,3 +1,5 @@
+from typing import TypedDict
+
 from prefab_ui.components import (
     Card,
     CardContent,
@@ -17,7 +19,15 @@ from fastmcp import FastMCP
 
 mcp = FastMCP("Sales Dashboard")
 
-MONTHLY_REVENUE = [
+
+class MonthlyRevenue(TypedDict):
+    month: str
+    new_business: int
+    expansion: int
+    renewal: int
+
+
+MONTHLY_REVENUE: list[MonthlyRevenue] = [
     {"month": "Jul", "new_business": 182_000, "expansion": 74_000, "renewal": 210_000},
     {"month": "Aug", "new_business": 195_000, "expansion": 81_000, "renewal": 215_000},
     {"month": "Sep", "new_business": 224_000, "expansion": 93_000, "renewal": 208_000},

examples/auth/aws_oauth/server.py

@@ -48,6 +48,8 @@ def echo(message: str) -> str:
 async def get_access_token_claims() -> dict:
     """Get the authenticated user's access token claims."""
     token = get_access_token()
+    if token is None:
+        return {"error": "Not authenticated"}
     return {
         "sub": token.claims.get("sub"),
         "username": token.claims.get("username"),

examples/auth/huggingface_oauth/server.py

@@ -2,6 +2,7 @@ import os
 
 from fastmcp import FastMCP
 from fastmcp.server.auth.providers.huggingface import HuggingFaceProvider
+from fastmcp.server.dependencies import get_access_token
 
 auth_provider = HuggingFaceProvider(
     # Your Hugging Face OAuth app client ID
@@ -21,9 +22,9 @@ mcp = FastMCP(name="Hugging Face Secured App", auth=auth_provider)
 @mcp.tool
 async def get_user_info() -> dict:
     """Returns information about the authenticated Hugging Face user."""
-    from fastmcp.server.dependencies import get_access_token
-
     token = get_access_token()
+    if token is None:
+        return {"error": "Not authenticated"}
     return {
         "subject": token.claims.get("sub"),
         "username": token.claims.get("preferred_username"),

examples/auth/keycloak_oauth/server.py

@@ -33,6 +33,8 @@ def echo(message: str) -> str:
 async def get_access_token_claims() -> dict:
     """Get the authenticated user's access token claims."""
     token = get_access_token()
+    if token is None:
+        return {"error": "Not authenticated"}
     return {
         "sub": token.claims.get("sub"),
         "scope": token.claims.get("scope"),

examples/custom_tool_serializer_decorator.py

@@ -12,8 +12,9 @@ from typing import Any
 
 import yaml
 
-from fastmcp import FastMCP
-from fastmcp.tools.tool import ToolResult
+from fastmcp import Client, FastMCP
+from fastmcp.tools import ToolResult
+from fastmcp.types import TextContent
 
 
 def with_serializer(serializer: Callable[[Any], str]):
@@ -55,18 +56,19 @@ def get_json_data() -> dict:
 
 
 async def example_usage():
+    async with Client(server) as client:
         # YAML serialized tool
-    yaml_result = await server._call_tool_mcp("get_example_data", {})
+        yaml_result = await client.call_tool("get_example_data", {})
         print("YAML Tool Result:")
-    print(yaml_result)
+        if yaml_result.content and isinstance(yaml_result.content[0], TextContent):
+            print(yaml_result.content[0].text)
         print()
 
         # Default JSON serialized tool
-    json_result = await server._call_tool_mcp("get_json_data", {})
+        json_result = await client.call_tool("get_json_data", {})
         print("JSON Tool Result:")
-    print(json_result)
+        print(json_result.data)
 
 
 if __name__ == "__main__":
     asyncio.run(example_usage())
-    server.run()

examples/providers/sqlite/server.py

@@ -23,7 +23,7 @@ from rich import print
 
 from fastmcp import Client, FastMCP
 from fastmcp.server.providers import Provider
-from fastmcp.tools.tool import Tool, ToolResult
+from fastmcp.tools import Tool, ToolResult
 
 DB_PATH = Path(__file__).parent / "tools.db"
 

examples/skills/client.py

@@ -41,7 +41,7 @@ async def main():
         print("=== Resource Templates ===")
         templates = await client.list_resource_templates()
         for t in templates:
-            print(f"  {t.uriTemplate}")
+            print(f"  {t.uri_template}")
         print()
 
         # Read a skill's main file

examples/task_elicitation.py

@@ -51,6 +51,7 @@ async def plan_dinner(ctx: Context) -> str:
         return "Dinner cancelled!"
 
     prefs = result.data
+    assert isinstance(prefs, DinnerPrefs)
     await ctx.report_progress(1, 2, "Planning your menu...")
     await asyncio.sleep(1)
     await ctx.report_progress(2, 2, "Done!")

examples/text_me.py

@@ -28,9 +28,7 @@ from fastmcp import FastMCP
 
 
 class SurgeSettings(BaseSettings):
-    model_config: SettingsConfigDict = SettingsConfigDict(
-        env_prefix="SURGE_", env_file=".env"
-    )
+    model_config = SettingsConfigDict(env_prefix="SURGE_", env_file=".env")
 
     api_key: str
     account_id: str

examples/tool_result_echo.py

@@ -10,7 +10,7 @@ import time
 from dataclasses import dataclass
 
 from fastmcp import FastMCP
-from fastmcp.tools.tool import ToolResult
+from fastmcp.tools import ToolResult
 
 mcp = FastMCP("Echo Server")
 

pyproject.toml

@@ -136,14 +136,32 @@ python_functions = ["test_*"]
 addopts = ["--inline-snapshot=disable"]
 
 [tool.ty.src]
-include = ["fastmcp_slim", "fastmcp_remote", "tests"]
-exclude = ["**/node_modules", "**/__pycache__", ".venv", ".git", "dist"]
+include = ["fastmcp_slim", "fastmcp_remote", "tests", "examples"]
+exclude = [
+    "**/node_modules",
+    "**/__pycache__",
+    ".venv",
+    ".git",
+    "dist",
+    # Example subtrees excluded from the ty gate. Each either pins its own
+    # fastmcp (resolved against a different install) or requires a third-party
+    # dependency not installed in this tree.
+    "examples/testing_demo",             # own uv.lock, targets fastmcp v1 on purpose
+    "examples/atproto_mcp",              # needs atproto (+ its own package)
+    "examples/smart_home",              # needs phue
+    "examples/apps/qr_server",          # needs qrcode
+    "examples/providers/sqlite",        # needs aiosqlite
+    "examples/memory.py",               # needs asyncpg, numpy, pydantic_ai, pgvector
+    "examples/get_file.py",             # needs aiohttp
+]
 
 [tool.ty.environment]
 python-version = "3.10"
 
 [tool.ty.analysis]
-replace-imports-with-any = ["prefab_ui.**"]
+# prefab_ui is the apps SDK; pyautogui/PIL are optional runtime deps used only
+# inside example tool bodies (screenshot demos) and are not installed here.
+replace-imports-with-any = ["prefab_ui.**", "pyautogui", "PIL", "PIL.**"]
 
 [tool.ty.rules]
 division-by-zero = "warn"