Define and document the public Python SDK API surface

Abierto
#1,701 4 comentarios 2 reacciones 1 asignado Ver en GitHub

@felixweinberger ya está trabajando en esto.

Desde el 16/1/2026.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

breaking change enhancement P1 ready for work v2
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

Lenguaje dominante
Python
Estrellas
24.3k
Forks
4k
Merge medio
1 d 19 min
PR fusionados (30 d)
29

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de modelcontextprotocol/python-sdk

Todos los issues de modelcontextprotocol/python-sdk

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.