upv-mcp: Skill for Claude Code

Anadir una tool a upv-mcp

Una tool nueva son cinco ficheros. Sigue el orden: el modelo de salida primero, la descripcion al final (es lo que mas se reescribe).

1. Modelo de salida en src/upv_mcp/models.py

Un modelo pydantic con Field(description=...) en cada campo: el SDK los convierte en el output schema que ve el cliente.

Envuelvelo en un ...Result que incluya meta: ResultMeta. No es opcional: meta lleva truncated, stale y coverage_note, que son lo que evita que el modelo presente datos recortados o incompletos como si fueran la verdad completa.

2. Consulta en src/upv_mcp/cache/db.py

Filtra en SQL, no en Python. Anade el metodo ..._between(...) y su count_..._between(...) hermano: hacen falta los dos, porque el contador es lo que permite reportar el truncado con honestidad.

Si cambias el esquema: edita schema.sql, sube SCHEMA_VERSION y anade la rama de migracion en migrate().

3. Modulo en src/upv_mcp/tools/<nombre>.py

Una tool por modulo. Exporta dos cosas: DESCRIPTION (constante) y una funcion async que recibe repo: AcademicRepository primero y limit: int como keyword.

async def mi_tool(repo: AcademicRepository, param: str, *, limit: int) -> MiResult:
    if <parametro invalido>:
        raise ValueError("mensaje que el usuario final pueda entender")
    await repo.ensure_fresh()
    total = repo.cache.count_...(...)
    items = repo.cache....(..., limit=limit)
    return MiResult(items=items, meta=build_meta(repo, total_matching=total, returned=len(items)))

Prohibido en este fichero: importar mcp, httpx2 o icalendar. Si crees que los necesitas, el trabajo va en sources/, no aqui.

4. Registro en src/upv_mcp/server.py

Unico sitio que toca el SDK. El Context se recibe por parametro (en el SDK 2.x no existe get_context()):

@mcp.tool(title="Titulo corto", description=mi_tool_module.DESCRIPTION)
async def mi_tool(param: str, ctx: Context[AppContext]) -> MiResult:
    app = ctx.request_context.lifespan_context
    return await mi_tool_module.mi_tool(app.repo, param, limit=app.settings.max_results)