mcp-server-plus

Introducción

mcp-server-plus es un kit de herramientas para servidores MCP: un pequeño framework en TypeScript para construir servidores del Model Context Protocol sin repetir código repetitivo.

Nota sobre el nombre del paquete: mcp-server-toolkit ya estaba ocupado en npm, por lo que este se distribuye como mcp-server-plus.

Related MCP server: MCP Framework

Por qué existe este paquete

Los desarrolladores que inician servidores MCP reimplementan repetidamente el registro de herramientas, prompts, recursos, autenticación, registro de actividad y pruebas. Bibliotecas populares como Express y Hono tienen éxito porque hacen que el camino feliz sea obvio. mcp-server-plus busca esa misma experiencia de desarrollo sobre el @modelcontextprotocol/sdk oficial.

Instalación

npm install mcp-server-plus zod

Requiere Node.js 18+.

Características

• Registro de herramientas

• Registro de prompts

• Recursos

• Autenticación / autorización

• Registro de actividad

• Métricas

• Streaming (a través del transporte stdio de MCP)

• Middleware

• Generador de andamiaje CLI

• Utilidades de prueba

Inicio rápido

import { z } from "zod";
import { createServer, toolResult } from "mcp-server-plus";

const weatherTool = {
  description: "Get weather",
  inputSchema: { city: z.string() },
  async handler({ city }: { city: string }) {
    return toolResult(`Weather in ${city}: sunny`);
  },
};

const server = createServer({
  name: "demo",
  version: "1.0.0",
});

server.tool("weather", weatherTool);

await server.start(); // stdio

CLI

npx mcp-server-plus init my-weather-server
cd my-weather-server
npm install
npm start

Referencia de la API

createServer(options) / createMcpServer(options)

Crea un McpKitServer.

server.tool(name, definition)

Registra una herramienta (también integrada en el SDK de MCP).

server.prompt(name, definition)

Registra una plantilla de prompt.

server.resource(uri, definition)

Registra un recurso.

server.use(middleware)

Añade middleware alrededor de las llamadas a herramientas.

server.start()

Conecta un transporte stdio de MCP (el streaming lo maneja el SDK).

server.invokeTool(name, args, meta?)

Invocación en proceso para pruebas/scripts.

Utilidades de prueba

import { callTool, expectText } from "mcp-server-plus/testing";

Ejemplos

server.tool("weather", weatherTool);
server.prompt("greet", {
  description: "Greeting",
  arguments: [{ name: "name", required: true }],
  handler: async ({ name }) => ({
    messages: [
      { role: "user", content: { type: "text", text: `Hello ${name}` } },
    ],
  }),
});
server.resource("memo://hello", {
  mimeType: "text/plain",
  handler: async (uri) => ({
    contents: [{ uri: uri.href, text: "Hello", mimeType: "text/plain" }],
  }),
});

Ejemplos avanzados

Autenticación + RBAC

const server = createServer({
  name: "secure",
  version: "1.0.0",
  // MCP_API_KEY is the expected secret only. Callers must still send meta.apiKey.
  auth: { apiKey: process.env.MCP_API_KEY, required: true },
});

server.tool("deploy", {
  roles: ["admin"],
  scopes: ["deploy"],
  handler: async () => toolResult("deployed"),
});

Middleware + métricas

server.use(async (ctx, next) => {
  const started = Date.now();
  try {
    return await next();
  } finally {
    ctx.log.info("tool timing", ctx.toolName, Date.now() - started);
  }
});

console.log(server.metricsSnapshot());

Integración con frameworks

Funciona con cualquier host de MCP que admita servidores stdio. Apunta el host a tu proceso node dist/index.js (o npm start).

Ejemplo de configuración de host MCP:

{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["/path/to/server/src/index.js"]
    }
  }
}

Uso de TypeScript

TypeScript de primera clase. Los argumentos de las herramientas se infieren del inputSchema de Zod cuando escribes el handler explícitamente. Activa strict para obtener los mejores resultados.

Manejo de errores

Errores tipados: McpKitError, AuthError, ForbiddenError.
Los fallos de las herramientas devuelven { isError: true, content: [...] } para que los hosts puedan mostrarlos de forma segura.

Rendimiento

• Capa delgada sobre el SDK oficial (sin saltos de red adicionales)

• Middleware solo en invocaciones de herramientas

• Las métricas usan contadores simples (baja sobrecarga)

Mejores prácticas

• Mantén las herramientas pequeñas y conscientes de los efectos secundarios

• Valida las entradas con esquemas de Zod

• Usa autenticación optional para local/desarrollo, required para hosts compartidos

• Prefiere invokeTool en pruebas unitarias; usa stdio para integración

Preguntas frecuentes

¿Es un SDK oficial?
No — se basa en @modelcontextprotocol/sdk con una mejor experiencia de desarrollo.

¿Admite streaming?
Sí, a través del transporte stdio de MCP utilizado por server.start().

¿CJS o ESM?
Publicado dual; ESM primero.

Guía de migración

Desde el SDK sin procesar McpServer

Reemplaza el código repetitivo de registerTool con server.tool(name, definition) y mantén los esquemas de Zod. Llama a server.start() en lugar de conectar manualmente StdioServerTransport.

SemVer

Los cambios incompatibles se publican en versiones principales y se documentan en CHANGELOG.md.

Solución de problemas

Contribuciones

Consulta CONTRIBUTING.md.

Licencia

MIT