Define and document the public Python SDK API surface

[dgenio]

Description

Summary

The Python SDK exposes a variety of classes and functions across packages and submodules. Some are clearly meant to be public, others are internal but not marked as such. Tests and user code sometimes rely on internals (e.g. private attributes).

This makes it hard for users to know what is safe to depend on and hard for maintainers to evolve internals without risking breakage.

Problems

• Ambiguous boundaries: It’s not always clear which symbols in mcp.* and subpackages are part of the supported public API.
• Private attribute usage: Some tests/examples access internal attributes (e.g. _mcp_server), which blurs the line between public and internal.
• Versioning risk: Changes to internal structures can accidentally turn into breaking changes for users who imported them directly.

Proposal

1. Define an explicit public API

   • Use __all__ and/or a mcp.public (or similar) module to list what is considered stable public API.
   • Document the intended public surface in the README or a dedicated “API Reference”.

2. Mark internals clearly

   • Move clearly internal modules into an _internal subpackage where possible.
   • Use leading underscores and documentation to indicate non-public attributes.

3. Gradual tightening

   • Update examples and tests to use only public APIs where feasible.
   • Where users are expected to interact with lower-level constructs, expose them via documented, stable paths.

Why this matters

• Stability: Users can rely on documented APIs without fear of accidental breakage.
• Refactorability: Internal changes become safer when the public surface is well-defined.
• Onboarding: New users can quickly see which APIs are meant for them.

Acceptance criteria

• A documented list of public, supported APIs for the Python SDK.
• Internal modules/types are clearly marked (e.g., _internal packages) where appropriate.
• Examples and tests avoid relying on private attributes when a public alternative exists.
• Future changes can be evaluated against this public surface for compatibility.

References

No response