Construir 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 IDs de los documentos y los valores son el contenido.
Obteniendo el proyecto
Las lecciones de este curso se construyen sobre un pequeño proyecto inicial, un chatbot de línea de comandos con un cliente MCP y un servidor MCP. Descarga cli_project.zip desde la sección de Descargas al final de esta lección y extráelo en tu directorio de desarrollo preferido. Abre tu editor de código en la carpeta del proyecto.
El proyecto incluye un archivo README con instrucciones de configuración. Agrega tu clave de API de Anthropic al archivo .env. Luego instala las dependencias usando uv (recomendado) o pip. El proyecto usa la versión 1 del SDK de Python de MCP, y su configuración instala esa versión por ti.
Configurando el servidor MCP
El SDK de Python de MCP hace que la creación del servidor sea sencilla. Abre mcp_server.py. Ya inicializa un servidor con una sola línea. Las herramientas a continuación también necesitan la importación de Field:
from mcp.server.fastmcp import FastMCP
from pydantic import Field
mcp = FastMCP("DocumentMCP", log_level="ERROR")Tus documentos pueden almacenarse en una estructura de diccionario simple:
docs = {
"deposition.md": "This deposition covers the testimony of Angela Smith, P.E.",
"report.pdf": "The report details the state of a 20m condenser tower.",
"financials.docx": "These financials outline the project's budget and expenditures",
"outlook.pdf": "This document presents the projected future performance of the system",
"plan.md": "The plan outlines the steps for the project's implementation.",
"spec.txt": "These specifications define the technical requirements for the equipment"
}Definición de herramientas con decoradores
El SDK usa decoradores para definir herramientas. En lugar de escribir esquemas JSON manualmente, puedes usar sugerencias de tipo de Python y descripciones de campos. El SDK genera automáticamente el esquema adecuado que Claude puede entender.
Creando una herramienta de lectura de documentos
La primera herramienta lee el contenido de un documento por ID. Aquí está la implementación completa:
@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]El decorador especifica el nombre y la descripción de la herramienta, mientras que los parámetros de la función definen los argumentos requeridos. La clase Field de Pydantic proporciona descripciones de argumentos que ayudan a Claude a entender qué espera cada parámetro.
Construyendo una herramienta de edición de documentos
La segunda herramienta realiza operaciones simples de buscar y reemplazar en documentos:
@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 whitespace."),
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 herramienta toma tres parámetros: el ID del documento, el texto a buscar y el texto de reemplazo. La implementación incluye manejo de errores para documentos faltantes y realiza un reemplazo de cadena sencillo.
Beneficios clave del enfoque del SDK
- No se requiere escribir esquemas JSON manualmente
- Las sugerencias de tipo proporcionan validación automática
- Las descripciones claras de parámetros ayudan a Claude a entender el uso de la herramienta
- El manejo de errores se integra naturalmente con las excepciones de Python
- El registro de herramientas ocurre automáticamente a través de decoradores
El SDK de Python de MCP transforma la creación de herramientas de un complejo ejercicio de escritura de esquemas en simples definiciones de funciones de Python. Este enfoque hace que sea mucho más fácil construir y mantener servidores MCP, a la vez que garantiza que Claude reciba especificaciones de herramientas con el formato adecuado.