Vellum

Un servidor MCP que da respuestas exactas sobre texto · Por Shuja Jamal

Un modelo de lenguaje lee tokens, no caracteres. Pregúntale cuántas letras tiene un párrafo y te dará una estimación, a menudo errónea. Lo mismo ocurre al comparar dos archivos a simple vista, o al adivinar qué coincidencias tendrá una expresión regular sin ejecutarla.

No son problemas difíciles. Simplemente no son el tipo de problema que un modelo está diseñado para resolver. Así que debería preguntar en su lugar.

Las cinco herramientas

count_text informa de los caracteres visibles por separado de los puntos de código, porque café es cuatro caracteres a los ojos de una persona, cinco para len() y seis bytes. Cuál de esos quieres depende de por qué preguntaste, así que devuelve los tres.

Related MCP server: text-stats-ai-mcp

Uso

Claude Code

claude mcp add --transport http vellum https://vellum-mcp.vercel.app/mcp

O localmente, por stdio:

claude mcp add vellum -- python -m vellum.server

Algo que me costó tiempo al instalar el servidor de otra persona: un servidor añadido a mitad de sesión aparece como conectado, pero sus herramientas no se pueden invocar hasta que se reinicie la sesión. Una instalación correcta y una instalación usable son estados distintos.

Claude Desktop

En claude_desktop_config.json:

{
  "mcpServers": {
    "vellum": {
      "command": "python",
      "args": ["-m", "vellum.server"],
      "cwd": "/path/to/vellum-mcp"
    }
  }
}

Ejecución

pip install -r requirements.txt

python -m vellum.server

Eso es stdio, lo que habla un cliente local. Para el transporte HTTP y la página de inicio:

python -m vellum.server --http --port 8000

Luego http://localhost:8000 para la página y http://localhost:8000/mcp para el endpoint.

Pruebas

python tests/test_vellum.py

46 comprobaciones. La primera mitad llama directamente a las funciones de análisis. La segunda mitad es la que importa: lanza el servidor como subproceso y le habla a MCP, hace el apretón de manos real, lista los tools, las invoca y lee los resultados de vuelta. Un servidor que tiene funciones correctas puede fallar a la hora de hablar el protocolo, y solo la segunda mitad lo detectaría. La primera mitad no.

python tests/test_deploy.py

Comprueba el despliegue antes de desplegarlo: que una petición reescrita llegue a la aplicación MCP en la ruta que espera, que ?action=demo llegue a la demo en su lugar, que la tarjeta servidor estática describe las herramientas que realmente existen y que haya exactamente una función, porque eso es lo que el runtime construye.

Despliegue

Vercel, para el alojamiento

vercel

No hay variables de entorno ni secretos: cada tool es una función pura de sus argumentos.

El enrutado es deliberado y merece explicarse, porque la versión obvia no funciona.

Una reescritura de Vercel no entrega a la función la ruta que pidió el navegador. Reescribir /(.*) a una sola función significa que cada petición llega como /api/index, así que una aplicación que enruta por la ruta responderá a cada URL con su propio 404, mientras que, visto desde fuera, el sitio parece totalmente muerto. Perdí una tarde exactamente con eso en un proyecto anterior.

Y el runtime de Python produce una única función para todo el proyecto, no una por archivo. Tenía api/demo.py junto a api/index.py, declarado en vercel.json e incluido en el despliegue, y /api/demo seguía devolvía el 404 de Vercel. vercel inspect muestre el motivo con claridad: una sola lambda de Python. Enrutado por sistema de carpetas entre varios puntos de entrada a Python no ocurre.

Por lo tanto, el despliegue es una función y algunos archivos estáticos:

/                                  static    public/index.html
/.well-known/mcp/server-card.json  static    generated by build_card.py
/mcp             -> /api/index     function
/api/demo        -> /api/index     function, told apart by ?action=demo

api/index.py se decide mediante el query string, porque es la parte que conserva la reescritura mientras POSSITIVE se sustituye la ruta, y vuelve a poner la ruta antes de que la plataforma MCP enrute sobre ella. Hay tests para ambos, porque ninguno de los dos es algo que se deba descubrir con una URL en vivo.

Las dos cosas que funcionaron a la primera fueron la página de inicio y la tarjeta del servidor, y son exactamente las dos que no tocan una función.

Smithery, para el listado

El modelo actual de Smithery es bring your own hosting: le entregas una URL HTTPS pública con un servidor HTTP transmisible y su gateway actúa de proxy hacia él. No hay contenedor que construir.

1. Despliega primero Vercel y apunta la URL.

2. Entra en smithery.ai/new.

3. Coloca https://tu-despliegue.vercel.app/mcp.

4. Completa el flujo de publicación.

Smithery lee después las tools del servidor para la página de listado. La ruta documentada es un análisis en vivo, con una tarjeta estática en /.well-known/mcp/server-card.json como fallback si el análisis no se puede completar.

En la práctica el fallback fue la ruta principal. El log de la publicación dice:

Server metadata discovered (server card: 5 tools).
Using .well-known/mcp/server-card.json: (5 tools)

... que la tarjeta no era una seguro contra un fallo, sino el mecanismo. build_card.py la genera a partir de las propias definiciones de tools del servidor, por eso no habría podido listar tools que no existen.

El log también advierte de que no se había propuesto un esquema de configuración. Eso es correcto e intencional: todas las tools son funciones puras de sus argumentos, por lo tanto no se pide nada al usuario. La advertencia importa para un servidor que envuelve una API y necesita una key.

smithery.yaml recoge los detalles que solicitó el flujo de publicación. Fíjate que no impulsa una construccción: la ruta anterior, la de contenedores, ya no es como funciona este proceso.

Ambos niveles son gratuitos. El nivel hobby de Vercel aloja la función y los archivos estáticos; el listado y registro en Smithery no cuestan nada.

Cómo está compuesto

vellum/
  analysis.py    the actual work, with no MCP anywhere in it
  server.py      the five tools, their descriptions, and the transports
api/
  index.py       the one Vercel function: MCP, and the demo behind a query flag
public/
  index.html     the landing page
  .well-known/mcp/server-card.json   generated
tests/
  test_vellum.py  analysis, then a real MCP handshake over stdio
  test_deploy.py  the routing and the card

La función de análisis importa nada de MCP. Eso es lo que permite que los tests la llamen directo y que no se produzca un segundo navegador que se desvíe.

Notas para escribir tools para un modelo de lenguaje

La descripción es la interfaz. No es documentación para un desarrollador; es lo único que un modelo lee cuando decide si una tool sirve. Una descripción vaga hace que la tool nunca se use; una incorrecta hace que se use en el momento equivocado. Así, count_text no dice "devuelve un diccionario de contadores". Dice que se use “count_text” cuando la respuesta necesite un número preciso, porque leer tokens no es lo mismo contar caracteres.

El fallo debe ser legible. Una expresión regular inválida se devuelve como {"valid": false, "error": ...} en lugar de lanzar una excepción, y un algoritmo de hash desconocido menciona los que existen. Un modelo puede actuar sobre eso; no puede actuar sobre un stack trace.

Elige algo que el modelo realmente no sepa hacer. La tentación es envolver una API y llamarle "tool", pero uno una herramienta de "resume este texto" añade un viaje de red a todo un proceso de ida y vuelta a algo que el modelo ya hace mejor él solo. Contar, hacer hash y ejecutar un regex son lagunas reales. Llenar una laguna real es lo que hace que una herramienta se use en lugar de ser ignorada con cortesía.

Por Shuja Jamal, agosto de 2026.