Claude Academy
Cargando

Definiendo recursos

Lección 555 min

Los recursos en los servidores MCP te permiten exponer datos a los clientes, de manera similar a los manejadores de solicitudes GET en un servidor HTTP típico. Son perfectos para escenarios en los que necesitas obtener información en lugar de realizar acciones.

Entendiendo los recursos

Piensa en los recursos como endpoints de solo lectura que pueden devolver cualquier tipo de dato: cadenas de texto, JSON, archivos binarios, etc. Estableces un 'mime_type' para darle al cliente una pista sobre qué tipo de datos estás devolviendo.

Los recursos funcionan definiendo un URI (como una URL) que los clientes pueden solicitar. Cuando un cliente necesita datos, envía una ReadResourceRequest con el URI específico, y tu servidor responde con un ReadResourceResult que contiene los datos.

Dos tipos de recursos

Hay dos tipos principales de recursos que puedes crear:

  • Recursos directos - Tienen URIs estáticos que no contienen ningún parámetro (como "docs://documents")
  • Recursos con plantilla - Incluyen parámetros en sus URIs que se analizan y se pasan a tu función (como "docs://documents/{doc_id}")

Para los recursos con plantilla, el SDK de Python analiza automáticamente los parámetros del URI y los pasa como argumentos de palabra clave a tu función. Los nombres de los parámetros en el URI deben coincidir exactamente con los nombres de los parámetros de tu función.

Creando recursos

Así es como se implementan ambos tipos de recursos:

python
@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    return list(docs.keys())

@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    return docs[doc_id]

El SDK de Python de MCP serializa automáticamente lo que devuelvas. No necesitas convertir manualmente los datos a cadenas JSON; simplemente devuelve objetos de Python y el SDK se encarga de la conversión.

Probando tus recursos

Puedes probar los recursos usando el MCP Inspector. Inicia tu servidor con:

uv run mcp dev mcp_server.py

Luego conéctate al inspector en tu navegador. Verás dos secciones:

  • Resources - Lista tus recursos directos/estáticos
  • Resource Templates - Muestra tus recursos con plantilla

Haz clic en cualquier recurso para probarlo. Para los recursos con plantilla, deberás proporcionar valores para los parámetros. El inspector te muestra la estructura exacta de la respuesta que recibirá tu cliente, incluyendo el tipo mime y los datos serializados.

Casos de uso prácticos

Los recursos son ideales para implementar funciones como las menciones de documentos en aplicaciones de chat. Por ejemplo, cuando un usuario escribe "@" para mencionar un documento, podrías:

  1. Usar un recurso directo para obtener una lista de todos los documentos disponibles para el autocompletado
  2. Usar un recurso con plantilla para obtener el contenido de un documento específico cuando se menciona

Este enfoque te permite inyectar de forma preventiva el contenido del documento en las indicaciones sin requerir que la IA use herramientas para obtener la información.