mcp-trial

Aprendiendo el Model Context Protocol construyendo un servidor para la API de GitHub. SDK de Python v2, ejecutándose sobre stdio y conectado a Claude Code.

Qué hace

Dos herramientas, una para el resumen de un repositorio y otra para sus mensajes de commit recientes. También hay un recurso que sirve el README crudo de un repositorio, y una plantilla de prompt para evaluar un repositorio como pieza de portafolio.

Related MCP server: MCP GitHub Reader

Cómo ejecutarlo

uv sync
uv run mcp dev server.py          # opens the inspector
uv run python test_server.py      # calls the server directly, no host needed

Para registrarlo con Claude Code:

claude mcp add gh-lab -- uv run --directory /path/to/mcp-trial mcp run server.py

Lo que aprendí

Tus type hints son el contrato real de la API, ya que el SDK construye el esquema JSON directamente desde la firma de la función. Escribir limit: int = 5 también hace que ese parámetro sea opcional, así que el modelo puede omitirlo.

Los docstrings importan más de lo que esperaba, porque se envían al modelo como descripción de la herramienta y determinan qué herramienta elige. Le pregunté a Claude Code si un repositorio se mantenía activamente, y llamó a ambas herramientas y lo resolvió, lo cual solo sucedió porque las descripciones las hacían ver combinables.

Todo lo que una herramienta devuelve se convierte en texto dentro del contexto del modelo, así que cada campo cuesta tokens. GitHub devuelve alrededor de cien campos y yo devuelvo cinco.

Lanzar un error es mejor que devolver uno, porque lanzar activa una marca que el host verifica y el mensaje llega al modelo como algo sobre lo que puede actuar.

Async no hace nada más rápido. Una sola llamada tarda lo mismo de cualquier manera. Lo que hace await es estacionar la función y liberar el event loop para que otras llamadas puedan ejecutarse durante la espera.

Notas

mcp-reference.md contiene mis notas de trabajo al construir esto.