Crear un servidor MCP se vuelve mucho más sencillo cuando usas el SDK oficial de Python. En lugar de escribir manualmente esquemas JSON complejos para las herramientas, el SDK se encarga de toda esa complejidad por ti con decoradores y type hints.
En este ejemplo, estamos creando un servidor MCP que gestiona documentos almacenados en memoria. El servidor proporcionará dos herramientas esenciales: una para leer el contenido de los documentos y otra para actualizarlos mediante operaciones de buscar y reemplazar.
Configurando el servidor MCP
El SDK de Python para MCP hace que la creación de servidores sea increíblemente sencilla. Puedes inicializar un servidor MCP completo con una sola línea:
from mcp.server.fastmcp import FastMCP
from pydantic import Field
mcp = FastMCP("DocumentMCP", log_level="ERROR")Para esta implementación, los documentos se almacenan en un diccionario simple de Python donde las claves son los IDs de los documentos y los valores contienen el contenido del documento:
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 expenditure",
"outlook.pdf": "This document presents the projected future performance of the",
"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 transforma la creación de herramientas de un proceso extenso en algo limpio y legible. En lugar de escribir esquemas JSON largos, usas decoradores de Python y type hints.
Creando la herramienta de lectura de documentos
La primera herramienta permite a Claude leer cualquier documento por su 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 @mcp.tool genera automáticamente el esquema JSON que Claude necesita. La clase Field de Pydantic proporciona descripciones de parámetros que ayudan a Claude a entender qué espera cada argumento.
Construyendo la herramienta de edición de documentos
La segunda herramienta realiza operaciones simples de buscar y reemplazar en los 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 usa el método integrado de Python para cadenas replace() por simplicidad.
Manejo de errores
Ambas herramientas incluyen manejo básico de errores para gestionar los casos en los que Claude solicita un documento que no existe. Cuando se proporciona un ID de documento inválido, las herramientas lanzan un ValueError con un mensaje descriptivo que Claude puede entender y sobre el cual puede actuar.
Beneficios clave del enfoque con el SDK
- Generación automática de esquemas JSON a partir de type hints de Python
- Código limpio y legible que es fácil de mantener
- Validación de parámetros integrada mediante Pydantic
- Menos código repetitivo en comparación con la escritura manual de esquemas
- Seguridad de tipos y soporte de IDE para el desarrollo
El SDK de Python para MCP transforma lo que solía ser un proceso complejo de escritura de definiciones de herramientas en algo que se siente natural para los desarrolladores de Python. Tú te enfocas en la lógica de negocio mientras el SDK se encarga de los detalles del protocolo.