Crea tu primer servidor MCP con Python: herramientas para consultar documentos Markdown

for nombre, argumentos in (
    ("listar_notas", {}),
    ("buscar_notas", {"consulta": "permisos"}),
    ("leer_nota", {"nombre": "python.md"}),
):
    result = await client.call_tool(nombre, argumentos)
    if result.is_error:
        raise RuntimeError(f"Error en {nombre}: {result.content}")
    print(f"{nombre}: {result.structured_content}")

mcp-python-secure-notes/
├── server.py
├── notas_core.py
├── cliente_demo.py
├── notas/
│   ├── python.md
│   └── seguridad.md
├── tests/
│   ├── test_notas_core.py
│   └── test_mcp.py
├── requirements.txt
├── requirements-dev.txt
├── README.md
├── LICENSE
├── .gitignore
└── .github/
    └── workflows/
        └── ci.yml

from __future__ import annotations

import os
import re
import stat
from pathlib import Path

MAX_BYTES = 64 * 1024
MAX_FILES = 100
MAX_RESULTS = 10
NAME_PATTERN = re.compile(r"[A-Za-z0-9_-]{1,60}\.md\Z", re.ASCII)

NAME_PATTERN = re.compile(r"[A-Za-z0-9_-]{1,60}\.md\Z", re.ASCII)

class NotesError(ValueError):
    """Error recuperable al consultar notas."""

class NotesStore:
    """Acceso no recursivo a una carpeta local confiable."""

    def __init__(self, root: Path):
        self.root = Path(root)

def _check_root(self) -> None:
        if self.root.is_symlink() or not self.root.is_dir():
            raise NotesError("La carpeta de notas no está disponible")

def _names(self) -> list[str]:
        self._check_root()
        try:
            names = []
            # scandir itera progresivamente; Path.iterdir puede materializar
            # toda la carpeta antes de aplicar MAX_FILES en algunas versiones.
            with os.scandir(self.root) as entries:
                for entry in entries:
                    if not NAME_PATTERN.fullmatch(entry.name):
                        continue
                    if entry.is_file(follow_symlinks=False):
                        if len(names) >= MAX_FILES:
                            raise NotesError(f"Hay más de {MAX_FILES} notas permitidas")
                        names.append(entry.name)
        except OSError as exc:
            raise NotesError("No se pudo enumerar las notas") from exc
        return sorted(names)

def listar_notas(self) -> list[str]:
        """No devuelve rutas completas ni archivos fuera de la carpeta."""
        return self._names()

def leer_nota(self, nombre: str) -> str:
        """Lee hasta 64 KiB de una nota regular y UTF-8."""
        if not isinstance(nombre, str) or not NAME_PATTERN.fullmatch(nombre):
            raise NotesError("Nombre inválido: letras, números, _ o - y termina en .md")
        self._check_root()
        path = self.root / nombre
        try:
            info = path.lstat()
            if not stat.S_ISREG(info.st_mode):
                raise NotesError("La nota no existe o no es un archivo regular")
            if info.st_size > MAX_BYTES:
                raise NotesError("La nota supera el límite de 64 KiB")
            flags = os.O_RDONLY | getattr(os, "O_BINARY", 0)
            flags |= getattr(os, "O_CLOEXEC", 0)
            flags |= getattr(os, "O_NOFOLLOW", 0)
            flags |= getattr(os, "O_NONBLOCK", 0)
            fd = os.open(path, flags)
            try:
                opened = os.fstat(fd)
                if not stat.S_ISREG(opened.st_mode):
                    raise NotesError("La nota no es un archivo regular")
                if opened.st_size > MAX_BYTES:
                    raise NotesError("La nota supera el límite de 64 KiB")
                with os.fdopen(fd, "rb") as stream:
                    fd = -1
                    data = stream.read(MAX_BYTES + 1)
            finally:
                if fd >= 0:
                    os.close(fd)
            if len(data) > MAX_BYTES:
                raise NotesError("La nota supera el límite de 64 KiB")
            return data.decode("utf-8").replace("\r\n", "\n")
        except FileNotFoundError as exc:
            raise NotesError("La nota no existe") from exc
        except UnicodeError as exc:
            raise NotesError("La nota no tiene codificación UTF-8 válida") from exc
        except OSError as exc:
            raise NotesError("No se pudo leer la nota autorizada") from exc

def buscar_notas(self, consulta: str) -> list[str]:
        """Busca texto literal en notas autorizadas; máximo diez resultados."""
        if not isinstance(consulta, str):
            raise NotesError("La búsqueda debe ser texto")
        # Validar antes de strip: un salto de línea al principio o al final
        # también es una entrada inválida, aunque strip lo eliminaría.
        if any(ord(ch) < 32 or ord(ch) == 127 for ch in consulta):
            raise NotesError("La búsqueda no admite caracteres de control")
        term = consulta.strip().casefold()
        if not 2 <= len(term) <= 80:
            raise NotesError("La búsqueda debe tener entre 2 y 80 caracteres")
        found = []
        for nombre in self._names():
            try:
                content = self.leer_nota(nombre)
            except NotesError:
                continue
            if term in content.casefold():
                found.append(nombre)
                if len(found) >= MAX_RESULTS:
                    break
        return found

from __future__ import annotations

from pathlib import Path
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
from mcp.types import ToolAnnotations
from notas_core import NotesError, NotesStore

NOTAS = Path(__file__).resolve().parent / "notas"
READ_ONLY = ToolAnnotations(read_only_hint=True, open_world_hint=False)

def create_server(root: Path = NOTAS) -> MCPServer:
    """Configura la carpeta para tests sin permitir que un agente la cambie."""
    store = NotesStore(root)
    server = MCPServer("TuCodigoCotidiano - Notas seguras")

@server.tool(annotations=READ_ONLY)
    def listar_notas() -> list[str]:
        """Lista los nombres de archivos Markdown autorizados."""
        try:
            return store.listar_notas()
        except NotesError as exc:
            raise ToolError(str(exc)) from exc

@server.tool(annotations=READ_ONLY)
    def buscar_notas(consulta: str) -> list[str]:
        """Busca texto en las notas Markdown (hasta diez resultados)."""
        try:
            return store.buscar_notas(consulta)
        except NotesError as exc:
            raise ToolError(str(exc)) from exc

@server.tool(annotations=READ_ONLY)
    def leer_nota(nombre: str) -> str:
        """Lee por nombre exacto una nota Markdown, por ejemplo python.md."""
        try:
            return store.leer_nota(nombre)
        except NotesError as exc:
            raise ToolError(str(exc)) from exc

return server


mcp = create_server()

if __name__ == "__main__":
    mcp.run()

import asyncio
from mcp import Client
from server import mcp

async def main() -> None:
    async with Client(mcp, raise_exceptions=True) as client:

for nombre, argumentos in (
            ("listar_notas", {}),
            ("buscar_notas", {"consulta": "permisos"}),
            ("leer_nota", {"nombre": "python.md"}),
        ):
            result = await client.call_tool(nombre, argumentos)

if result.is_error:
                raise RuntimeError(f"Error en {nombre}: {result.content}")
            print(f"{nombre}: {result.structured_content}")

"""Cliente MCP en memoria; no requiere IA ni claves de API."""
import asyncio
from mcp import Client
from server import mcp


async def main() -> None:
    async with Client(mcp, raise_exceptions=True) as client:
        for nombre, argumentos in (
            ("listar_notas", {}),
            ("buscar_notas", {"consulta": "permisos"}),
            ("leer_nota", {"nombre": "python.md"}),
        ):
            result = await client.call_tool(nombre, argumentos)
            if result.is_error:
                raise RuntimeError(f"Error en {nombre}: {result.content}")
            print(f"{nombre}: {result.structured_content}")


if __name__ == "__main__":
    asyncio.run(main())

py -3.12 -m venv .venv

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

.\.venv\Scripts\python.exe cliente_demo.py

python3 -m venv .venv

./.venv/bin/python -m pip install -r requirements.txt

./.venv/bin/python cliente_demo.py

listar_notas: {'result': ['python.md', 'seguridad.md']}
buscar_notas: {'result': ['seguridad.md']}
leer_nota: {'result': '# Python para proyectos reales\n\nPython permite crear APIs, automatizaciones y agentes de IA.\nEste ejemplo usa MCP v2, funciones Python y pytest.\n'}

-r requirements.txt
pytest==9.0.2

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt

.\.venv\Scripts\python.exe -m pytest -q -rs

./.venv/bin/python -m pip install -r requirements-dev.txt

./.venv/bin/python -m pytest -q -rs