Make fastapi.cli a runnable package

[paulo-raca]

Description

python -m fastmcp.cli didn't work before, despite there being an if __main__ block.

This PR fixes the structure, adding a __main__.py file to make the package runnable

• My change closes #(issue number)
• I have followed the repository's development workflow
• I have tested my changes manually and by adding relevant tests
• I have performed all required documentation updates

Review Checklist

• I have self-reviewed my changes
• My Pull Request is ready for review

---

[coderabbitai]

Walkthrough

The CLI entry-point behavior has been refactored by removing the runtime execution guard from src/fastmcp/cli/__init__.py and adding a new src/fastmcp/cli/__main__.py file. The __init__.py module no longer automatically invokes the CLI app when executed as a script, though the app remains importable. The new __main__.py module serves as the package entry point, importing the app and calling it to launch the CLI when the package is run as a script.

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description explains the problem and solution clearly, but is incomplete: the contributor checklist items are mostly unchecked, and the issue number is not specified.	Complete the checklist items by checking relevant boxes (especially issue reference) and confirm testing and documentation updates were performed, or clarify why they weren't needed.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: making the fastmcp.cli package runnable as a module via python -m by adding a main.py entry point.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 54692c3 and 16348c6.

📒 Files selected for processing (2)

• src/fastmcp/cli/__init__.py (0 hunks)
• src/fastmcp/cli/__main__.py (1 hunks)

💤 Files with no reviewable changes (1)

• src/fastmcp/cli/init.py

🧰 Additional context used

📓 Path-based instructions (1)

src/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

src/**/*.py: Python source code must be version ≥3.10 with full type annotations
Prioritize readable, understandable code - clarity over cleverness; avoid obfuscated or confusing patterns even if they're shorter
Never use bare except in code - be specific with exception types

Files:

• src/fastmcp/cli/__main__.py

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Run tests: Python 3.10 on windows-latest
• GitHub Check: label-issue-or-pr

🔇 Additional comments (3)

src/fastmcp/cli/__main__.py (3)

1-2: LGTM!

The docstring clearly describes the module's purpose.

---

5-5: LGTM!

The unconditional execution of app() is the correct pattern for a __main__.py entry point, enabling the package to be run via python -m fastmcp.cli.

---

3-3: No actionable issues identified with this import statement.

The relative import from .cli import app is a standard Python pattern for package-level imports. Without access to verify the codebase structure, I cannot confirm the specific module organization, but the import syntax itself is correct and follows Python conventions for intra-package imports.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[marvin-context-protocol]

Test Failure Analysis

Summary: 9 tests failed due to unexpected task field appearing in MCP request payloads (CallToolRequest, ReadResourceRequest). This is NOT caused by this PR's changes.

Root Cause: The test failures are caused by MCP Python SDK version 1.23.0 (released December 2, 2025) introducing a new task field via SEP-1686: Tasks. This PR only modifies CLI structure to make fastmcp.cli runnable via python -m fastmcp.cli, but CI is installing MCP SDK 1.23.0 which includes the new task field.

The pyproject.toml constraint mcp>=1.19.0,<2.0.0,!=1.21.1 allows version 1.23.0, so CI pulled the latest compatible version. Tests written before this MCP SDK update don't expect the task field in serialized payloads.

Failed Tests:

1. tests/server/test_auth_integration.py::TestAuthEndpoints::test_metadata_endpoint - Extra client_secret_basic in token auth methods
2. tests/server/test_auth_integration.py::TestAuthEndpoints::test_token_validation_error - Error code changed from invalid_request to unauthorized_client
3. tests/client/test_sampling.py::test_sampling_with_image - Unexpected _meta field in message content
   4-9. tests/server/middleware/test_logging.py - Multiple tests failing due to task:null appearing in JSON payloads

Suggested Solution:

The FastMCP codebase needs to be updated to handle MCP SDK 1.23.0's task field. Here are the options:

Option 1: Update Tests to Handle Task Field (Recommended)

Update test assertions to accommodate the new task field:

# In test_logging.py tests, update expected payloads to include task:null
# Example from test_create_message_with_payloads (line ~1448):
expected_payload = '{"method":"tools/call","params":{"task":null,"_meta":null,"name":"test_method","arguments":{"param":"value"}}}'

Option 2: Pin MCP SDK Version (Temporary)

Add version constraint until FastMCP is updated:

"mcp>=1.19.0,<1.23.0,!=1.21.1"

Option 3: Use Model Exclusions in Pydantic

If FastMCP doesn't need task tracking, configure Pydantic models to exclude the task field during serialization.

Detailed Analysis

Test Failure Pattern

All logging middleware tests fail because they compare exact JSON payloads, and the new task field changes the serialized output:

Before (MCP SDK < 1.23.0):

{"method":"tools/call","params":{"_meta":null,"name":"test_method","arguments":{"param":"value"}}}

After (MCP SDK >= 1.23.0):

{"method":"tools/call","params":{"task":null,"_meta":null,"name":"test_method","arguments":{"param":"value"}}}

This adds 12 characters ("task":null,), causing:

• Payload length assertions to fail (98 → 110 bytes)
• Token count assertions to fail (24 → 27 tokens)
• Exact string comparisons to fail

Why This PR is Innocent

This PR only:

1. Removes if __name__ == "__main__": from src/fastmcp/cli/__init__.py
2. Adds src/fastmcp/cli/__main__.py with the app invocation

These changes have ZERO impact on:

• MCP request/response serialization
• Middleware logging behavior
• Test data structures
• Authentication flows

The timing is coincidental - the PR was created after MCP SDK 1.23.0 was released but before FastMCP tests were updated.

Related Files

Files needing updates:

• tests/server/middleware/test_logging.py - Update expected JSON payloads to include task:null
• tests/client/test_sampling.py - Handle _meta field in sampling messages
• tests/server/test_auth_integration.py - Update auth endpoint expectations
• pyproject.toml (if pinning version) - Adjust MCP SDK constraint

MCP SDK References:

• v1.23.0 Release Notes
• SEP-1686 Pull Request
• MCP Specification 2025-11-25

---

Recommendation: This PR's changes are correct and should be merged once FastMCP is updated to handle MCP SDK 1.23.0. The test failures are a separate issue requiring updates to the test suite across the codebase.

Sources:

• MCP Python SDK Releases
• GitHub - modelcontextprotocol/python-sdk