René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Decorator type signatures lose parameter types (use ParamSpec)","articleBody":"# Issue: Decorator type signatures lose parameter types\n\n## Summary\n\nThe MCP server decorators (`@server.call_tool()`, `@server.list_tools()`, etc.) use `Callable[..., Awaitable[...]]` which discards parameter type information, preventing static type checkers from validating decorated functions.\n\n## Current Behavior\n\n```python\n# In mcp/server/lowlevel/server.py\ndef call_tool(self, *, validate_input: bool = True):\n    def decorator(\n        func: Callable[\n            ...,  # \u003c-- Ellipsis loses parameter types!\n            Awaitable[UnstructuredContent | StructuredContent | ...],\n        ],\n    ):\n        # ...\n```\n\nWhen decorating a function:\n```python\n@server.call_tool()  # type: ignore  # \u003c-- Required!\nasync def call_tool(name: str, arguments: dict[str, object]) -\u003e list[TextContent]:\n    ...\n```\n\nMypy cannot verify:\n- Parameter names/types are correct\n- Arguments are passed correctly to decorated function\n- Return type matches decorator constraints\n\n## Expected Behavior\n\nDecorators should preserve parameter types using `ParamSpec`:\n\n```python\nfrom typing import ParamSpec, TypeVar, Callable, Awaitable\n\nP = ParamSpec('P')\nR = TypeVar('R')\n\ndef call_tool(self, *, validate_input: bool = True):\n    def decorator(\n        func: Callable[P, Awaitable[R]]\n    ) -\u003e Callable[P, Awaitable[R]]:\n        # ... wrapper implementation\n        return func  # Type signature preserved\n```\n\nThis would:\n- ✅ Preserve parameter types through decoration\n- ✅ Enable static type checking\n- ✅ Eliminate need for `# type: ignore`\n- ✅ Improve IDE autocomplete/hints\n\n## Environment\n\n- **mcp version**: 1.24.0\n- **Python version**: 3.14 (but affects 3.10+)\n- **Type checker**: mypy (strict mode)\n\n## Impact\n\nThe package includes `py.typed` marker claiming type support, but decorators break type checking. Projects using strict mypy must either:\n1. Disable type checking for entire MCP server modules\n2. Add `# type: ignore` to every decorated function\n3. Create local type stubs to work around the issue\n\n## Workaround\n\nCurrently using broad mypy overrides:\n```toml\n[[tool.mypy.overrides]]\nmodule = \"myproject.mcp_server\"\ndisable_error_code = [\"misc\", \"no-untyped-call\", \"explicit-any\"]\n```\n\nThis defeats the purpose of having `py.typed`.\n\n## Related\n\n- Python typing docs: https://docs.python.org/3/library/typing.html#typing.ParamSpec\n- Similar issue in other libraries: https://github.com/python/mypy/issues/1927","author":{"url":"https://github.com/Morriz","@type":"Person","name":"Morriz"},"datePublished":"2026-01-01T21:03:52.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":2},"url":"https://github.com/1822/python-sdk/issues/1822"}