chore: enforce type annotations on all functions via ruff ANN rules

Enable the `ANN` (flake8-annotations) rule set to require return type
and argument annotations on all function definitions. Pyright strict
already enforces argument types but infers return types silently; this
closes the gap so every function has an explicit return annotation.

Configuration choices:
- `ANN401` (any-type) is ignored: `Any` is sometimes the right answer
  and pyright strict already catches genuine misuse.
- `allow-star-arg-any = true`: `*args: Any, **kwargs: Any` is a common
  valid pattern for pass-through wrappers.
- Per-file ignores for `test_func_metadata.py` and `test_server.py` where
  untyped parameters are intentional (testing schema inference on
  unannotated signatures).
- README code snippets (via pytest-examples) exempt — short doc
  examples shouldn't need full annotations.

Auto-fix added `-> None` or inferred return types to ~910 functions.
The remaining ~100 were annotated manually — mostly
`@asynccontextmanager` generators, pytest fixtures, and ASGI handlers
that Ruff couldn't infer.

Author: maxisbey

examples/mcpserver/memory.py

@@ -50,11 +50,17 @@ def cosine_similarity(a: list[float], b: list[float]) -> float:
     return np.dot(a_array, b_array) / (np.linalg.norm(a_array) * np.linalg.norm(b_array))
 
 
+@dataclass
+class Deps:
+    openai: AsyncOpenAI
+    pool: asyncpg.Pool
+
+
 async def do_ai(
     user_prompt: str,
     system_prompt: str,
     result_type: type[T] | Annotated,
-    deps=None,
+    deps: Deps | None = None,
 ) -> T:
     agent = Agent(
         DEFAULT_LLM_MODEL,
@@ -65,14 +71,8 @@ async def do_ai(
     return result.data
 
 
-@dataclass
-class Deps:
-    openai: AsyncOpenAI
-    pool: asyncpg.Pool
-
-
 async def get_db_pool() -> asyncpg.Pool:
-    async def init(conn):
+    async def init(conn: asyncpg.Connection) -> None:
         await conn.execute("CREATE EXTENSION IF NOT EXISTS vector;")
         await register_vector(conn)
 
@@ -90,11 +90,11 @@ class MemoryNode(BaseModel):
     embedding: list[float]
 
     @classmethod
-    async def from_content(cls, content: str, deps: Deps):
+    async def from_content(cls, content: str, deps: Deps) -> Self:
         embedding = await get_embedding(content, deps)
         return cls(content=content, embedding=embedding)
 
-    async def save(self, deps: Deps):
+    async def save(self, deps: Deps) -> None:
         async with deps.pool.acquire() as conn:
             if self.id is None:
                 result = await conn.fetchrow(
@@ -129,7 +129,7 @@ async def save(self, deps: Deps):
                     self.id,
                 )
 
-    async def merge_with(self, other: Self, deps: Deps):
+    async def merge_with(self, other: Self, deps: Deps) -> None:
         self.content = await do_ai(
             f"{self.content}\n\n{other.content}",
             "Combine the following two texts into a single, coherent text.",
@@ -145,7 +145,7 @@ async def merge_with(self, other: Self, deps: Deps):
         if other.id is not None:
             await delete_memory(other.id, deps)
 
-    def get_effective_importance(self):
+    def get_effective_importance(self) -> float:
         return self.importance * (1 + math.log(self.access_count + 1))
 
 
@@ -157,12 +157,12 @@ async def get_embedding(text: str, deps: Deps) -> list[float]:
     return embedding_response.data[0].embedding
 
 
-async def delete_memory(memory_id: int, deps: Deps):
+async def delete_memory(memory_id: int, deps: Deps) -> None:
     async with deps.pool.acquire() as conn:
         await conn.execute("DELETE FROM memories WHERE id = $1", memory_id)
 
 
-async def add_memory(content: str, deps: Deps):
+async def add_memory(content: str, deps: Deps) -> str:
     new_memory = await MemoryNode.from_content(content, deps)
     await new_memory.save(deps)
 
@@ -204,7 +204,7 @@ async def find_similar_memories(embedding: list[float], deps: Deps) -> list[Memo
     return memories
 
 
-async def update_importance(user_embedding: list[float], deps: Deps):
+async def update_importance(user_embedding: list[float], deps: Deps) -> None:
     async with deps.pool.acquire() as conn:
         rows = await conn.fetch("SELECT id, importance, access_count, embedding FROM memories")
         for row in rows:
@@ -228,7 +228,7 @@ async def update_importance(user_embedding: list[float], deps: Deps):
             )
 
 
-async def prune_memories(deps: Deps):
+async def prune_memories(deps: Deps) -> None:
     async with deps.pool.acquire() as conn:
         rows = await conn.fetch(
             """
@@ -265,7 +265,7 @@ async def display_memory_tree(deps: Deps) -> str:
 @mcp.tool()
 async def remember(
     contents: list[str] = Field(description="List of observations or memories to store"),
-):
+) -> str:
     deps = Deps(openai=AsyncOpenAI(), pool=await get_db_pool())
     try:
         return "\n".join(await asyncio.gather(*[add_memory(content, deps) for content in contents]))
@@ -281,7 +281,7 @@ async def read_profile() -> str:
     return profile
 
 
-async def initialize_database():
+async def initialize_database() -> None:
     pool = await asyncpg.create_pool("postgresql://postgres:postgres@localhost:54320/postgres")
     try:
         async with pool.acquire() as conn:

examples/servers/simple-auth/mcp_simple_auth/auth_server.py

@@ -47,7 +47,7 @@ class SimpleAuthProvider(SimpleOAuthProvider):
     2. Stores token state for introspection by Resource Servers
     """
 
-    def __init__(self, auth_settings: SimpleAuthSettings, auth_callback_path: str, server_url: str):
+    def __init__(self, auth_settings: SimpleAuthSettings, auth_callback_path: str, server_url: str) -> None:
         super().__init__(auth_settings, auth_callback_path, server_url)
 
 
@@ -134,7 +134,7 @@ async def introspect_handler(request: Request) -> Response:
     return Starlette(routes=routes)
 
 
-async def run_server(server_settings: AuthServerSettings, auth_settings: SimpleAuthSettings):
+async def run_server(server_settings: AuthServerSettings, auth_settings: SimpleAuthSettings) -> None:
     """Run the Authorization Server."""
     auth_server = create_authorization_server(server_settings, auth_settings)
 

examples/servers/simple-auth/mcp_simple_auth/legacy_as_server.py

@@ -39,7 +39,7 @@ class ServerSettings(BaseModel):
 class LegacySimpleOAuthProvider(SimpleOAuthProvider):
     """Simple OAuth provider for legacy MCP server."""
 
-    def __init__(self, auth_settings: SimpleAuthSettings, auth_callback_path: str, server_url: str):
+    def __init__(self, auth_settings: SimpleAuthSettings, auth_callback_path: str, server_url: str) -> None:
         super().__init__(auth_settings, auth_callback_path, server_url)
 
 

examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py

@@ -51,7 +51,7 @@ class SimpleOAuthProvider(OAuthAuthorizationServerProvider[AuthorizationCode, Re
     3. Maintaining token state for introspection
     """
 
-    def __init__(self, settings: SimpleAuthSettings, auth_callback_url: str, server_url: str):
+    def __init__(self, settings: SimpleAuthSettings, auth_callback_url: str, server_url: str) -> None:
         self.settings = settings
         self.auth_callback_url = auth_callback_url
         self.server_url = server_url
@@ -66,7 +66,7 @@ async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
         """Get OAuth client information."""
         return self.clients.get(client_id)
 
-    async def register_client(self, client_info: OAuthClientInformationFull):
+    async def register_client(self, client_info: OAuthClientInformationFull) -> None:
         """Register a new OAuth client."""
         if not client_info.client_id:
             raise ValueError("No client_id provided")

examples/servers/simple-auth/mcp_simple_auth/token_verifier.py

@@ -25,7 +25,7 @@ def __init__(
         introspection_endpoint: str,
         server_url: str,
         validate_resource: bool = False,
-    ):
+    ) -> None:
         self.introspection_endpoint = introspection_endpoint
         self.server_url = server_url
         self.validate_resource = validate_resource

examples/servers/structured-output-lowlevel/mcp_structured_output_lowlevel/__main__.py

@@ -75,7 +75,7 @@ async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequ
 )
 
 
-async def run():
+async def run() -> None:
     """Run the low-level server using stdio transport."""
     async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
         await server.run(

examples/snippets/clients/completion_client.py

@@ -17,7 +17,7 @@
 )
 
 
-async def run():
+async def run() -> None:
     """Run the completion client example."""
     async with stdio_client(server_params) as (read, write):
         async with ClientSession(read, write) as session:
@@ -68,7 +68,7 @@ async def run():
                 print(f"Completions for 'style' argument: {result.completion.values}")
 
 
-def main():
+def main() -> None:
     """Entry point for the completion client."""
     asyncio.run(run())
 

examples/snippets/clients/display_utilities.py

@@ -17,7 +17,7 @@
 )
 
 
-async def display_tools(session: ClientSession):
+async def display_tools(session: ClientSession) -> None:
     """Display available tools with human-readable names"""
     tools_response = await session.list_tools()
 
@@ -29,7 +29,7 @@ async def display_tools(session: ClientSession):
             print(f"   {tool.description}")
 
 
-async def display_resources(session: ClientSession):
+async def display_resources(session: ClientSession) -> None:
     """Display available resources with human-readable names"""
     resources_response = await session.list_resources()
 
@@ -43,7 +43,7 @@ async def display_resources(session: ClientSession):
         print(f"Resource Template: {display_name}")
 
 
-async def run():
+async def run() -> None:
     """Run the display utilities example."""
     async with stdio_client(server_params) as (read, write):
         async with ClientSession(read, write) as session:
@@ -57,7 +57,7 @@ async def run():
             await display_resources(session)
 
 
-def main():
+def main() -> None:
     """Entry point for the display utilities client."""
     asyncio.run(run())
 

examples/snippets/clients/oauth_client.py

@@ -21,7 +21,7 @@
 class InMemoryTokenStorage(TokenStorage):
     """Demo In-memory token storage implementation."""
 
-    def __init__(self):
+    def __init__(self) -> None:
         self.tokens: OAuthToken | None = None
         self.client_info: OAuthClientInformationFull | None = None
 
@@ -52,7 +52,7 @@ async def handle_callback() -> tuple[str, str | None]:
     return params["code"][0], params.get("state", [None])[0]
 
 
-async def main():
+async def main() -> None:
     """Run the OAuth client example."""
     oauth_auth = OAuthClientProvider(
         server_url="http://localhost:8001",
@@ -80,7 +80,7 @@ async def main():
                 print(f"Available resources: {[r.uri for r in resources.resources]}")
 
 
-def run():
+def run() -> None:
     asyncio.run(main())
 
 

examples/snippets/clients/parsing_tool_results.py

@@ -6,7 +6,7 @@
 from mcp.client.stdio import stdio_client
 
 
-async def parse_tool_results():
+async def parse_tool_results() -> None:
     """Demonstrates how to parse different types of content in CallToolResult."""
     server_params = StdioServerParameters(command="python", args=["path/to/mcp_server.py"])
 
@@ -52,7 +52,7 @@ async def parse_tool_results():
                         print(f"Error: {content.text}")
 
 
-async def main():
+async def main() -> None:
     await parse_tool_results()