Add initial Transport and Streamable HTTP support

[3dgiordano]

This pull request introduces a new streamable HTTP transport for Perfecto MCP, allowing the server to handle multiple users and clouds over HTTP with per-request authentication via Bearer tokens and cloud selection via headers. It also refactors authentication and runtime context handling to support both stdio and HTTP transports, and updates documentation and CLI options accordingly.

New HTTP Transport and Authentication:

• Adds a streamable HTTP transport mode to Perfecto MCP, allowing clients to connect over HTTP with credentials and cloud name resolved per request from headers. This enables a single server instance to serve multiple users and clouds concurrently. [1] [2]
• Implements per-request Bearer authentication middleware (BearerAuthMiddleware) and cloud name resolution logic, with clear error handling for missing or malformed credentials. Health probe endpoints (/health, /healthz) bypass authentication for orchestration.
• Updates the authentication and token parsing logic to support Bearer tokens and cloud name headers, including new helpers for context and user config resolution. [1] [2] [3]

Runtime and Context Refactoring:

• Introduces a new AppRuntime class to encapsulate process-level transport, authentication, and user config, with logic to resolve and hydrate per-request context.
• Updates main server wiring to select transport (stdio, http, docker) based on CLI, environment variables, or defaults, and builds the correct runtime and authentication wiring for each. [1] [2] [3]

Documentation and CLI Improvements:

• Adds a new docs/hosted-http.md with detailed client configuration, header usage, auth behavior, environment variables, and limitations for HTTP transport. Updates README.md to reference the new transport and documentation. [1] [2]
• Refines CLI argument parsing for --mcp, allowing explicit transport selection and improving help text. [1] [2] [3]

Supporting Changes:

• Updates error messages and documentation to clarify the new authentication and cloud name mechanisms.
• Ensures PyInstaller collects necessary uvicorn submodules for HTTP transport.
• Minor type and import improvements for clarity and correctness.

References:
[1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12]

[Baraujo25]

Do we leave aside some sort of file upload in this MCP? If so, shouldn't we attempt to give support through a separated service?

[3dgiordano]

It is not supported because there is simply no such use of files.