Definir herramientas con MCP

Crear un servidor MCP se vuelve mucho más sencillo cuando usas el SDK oficial de Python. En lugar de escribir esquemas JSON complejos a mano, puedes definir herramientas con decoradores y dejar que el SDK se encargue del trabajo pesado.



En este ejemplo, estamos creando un servidor de gestión de documentos con dos herramientas principales: una para leer documentos y otra para actualizarlos. Todos los documentos existen en memoria como un simple diccionario donde las claves son los ID de los documentos y los valores son el contenido.

Configuración del servidor MCP

El SDK de Python para MCP facilita la creación de servidores. Puedes inicializar un servidor con una sola línea:

from mcp.server.fastmcp import FastMCP
from pydantic import Field

mcp = FastMCP("DocumentMCP", log_level="ERROR")

Esto crea un servidor MCP completamente funcional que puede manejar definiciones de herramientas, conexiones de clientes y enrutamiento de mensajes.

Definición de herramientas con decoradores



El enfoque de decoradores del SDK elimina la necesidad de escribir manualmente esquemas JSON. Así es como defines una herramienta sencilla:

@mcp.tool(
    name="add_ints",
    description="Add two integers together",
)
def tool_fn(
    a=Field(description="First number to add"),
    b=Field(description="Second number to add"),
) -> int:
    return a + b

Detrás de escena, MCP genera el esquema completo de la herramienta que Claude necesita para entender cuándo y cómo usar tu herramienta.

Construcción de la herramienta de lectura de documentos

La primera herramienta lee el contenido de los documentos por ID. Toma un identificador de documento y devuelve el contenido correspondiente de nuestro diccionario en memoria:

@mcp.tool(
    name="read_doc_contents",
    description="Read the contents of a document and return it as a string."
)
def read_document(
    doc_id: str = Field(description="Id of the document to read")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    return docs[doc_id]

La función incluye manejo básico de errores para detectar solicitudes de documentos inexistentes. Cuando Claude llama a esta herramienta con un ID de documento válido, recibe el contenido completo del documento como una cadena de texto.

Creación de la herramienta de edición de documentos

La segunda herramienta realiza operaciones sencillas de buscar y reemplazar en los documentos. Requiere tres parámetros: el ID del documento, el texto a buscar y el texto de reemplazo:

@mcp.tool(
    name="edit_document",
    description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
    doc_id: str = Field(description="Id of the document that will be edited"),
    old_str: str = Field(description="The text to replace. Must match exactly, including white space."),
    new_str: str = Field(description="The new text to insert in place of the old text.")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

Esta implementación usa el método replace de cadenas incorporado en Python, que requiere coincidencias exactas incluyendo los espacios en blanco. La herramienta modifica el documento directamente dentro de nuestro diccionario.

Beneficios clave del enfoque del SDK

• No se requiere escribir esquemas JSON manualmente
• Las sugerencias de tipo (type hints) proporcionan validación automática de parámetros
• Las descripciones de los campos ayudan a Claude a entender el uso de la herramienta
• El manejo de errores se integra de forma natural con las excepciones de Python
• El registro de herramientas ocurre automáticamente mediante decoradores

El SDK de Python para MCP transforma la creación de herramientas de un complejo ejercicio de escritura de esquemas en definiciones sencillas de funciones de Python. Tus herramientas se vuelven más fáciles de mantener y probar, mientras que Claude obtiene todos los metadatos que necesita para usarlas de manera eficaz.