Plantilla MCP de Xava Labs

Plantilla MCP de Typescript de Xava Labs

Un repositorio de plantillas para el arranque de MCP (Protocolo de contexto de modelo) para xava-labs/typescript-agent-framework.

Empezando

Configurar el repositorio

Opción A: Utilice esta plantilla

Haga clic en el botón "Usar esta plantilla" en la parte superior de este repositorio
Clona tu nuevo repositorio

Opción B: Usar el botón de implementación en Cloudflare

El siguiente botón creará un nuevo repositorio en su organización y configurará CI/CD usando Cloudflare:

NOTA: La configuración solo necesita npm run deploy para que el comando Implementar funcione

Opción C: Usar la creación de Cloudflare

Puedes crear un nuevo proyecto basado en esta plantilla usando wrangler:

Copie el siguiente texto para facilitar su lectura.

xava-labs/mcp-template

Ejecute el siguiente comando, siga las indicaciones interactivas eligiendo el nombre, luego comience con "Plantilla del repositorio de GitHub" y luego pegue el texto anterior para la plantilla que desee usar.

npm create cloudflare@latest  --git https://github.com/xava-labs/mcp-template

Una vez que haya completado uno de los métodos anteriores, ejecute los siguientes comandos en su terminal para comenzar:

npm install
npm run dev

Lo anterior impulsará un servidor MCP compatible con Cloudflare sin servidor con las siguientes URL:

/ws - Punto final de conexión de WebSocket
/sse - Punto final de conexión SSE

Características

Compatibilidad con cliente WebSocket : incluye cliente WebSocket oficial para comunicación bidireccional en tiempo real
Compatibilidad con clientes SSE : incluye un cliente de eventos enviados por el servidor para la transmisión de servidor a cliente
Inspector MCP : depure y supervise su MCP durante el desarrollo
Integración de Cloudflare Workers : basada en Cloudflare Workers para capacidades de computación de borde
Suite de pruebas de integración : herramientas de prueba Websocket y SSE para realizar pruebas de integración completas con servicios miniflare locales (D1/KV/etc.) para facilitar la prueba de funciones sin simulaciones.

Scripts disponibles

npm run dev : ejecuta MCP Inspector (puerto 6274) y Cloudflare Worker (puerto 8787) simultáneamente
npm start : ejecuta solo Cloudflare Worker (puerto 8787)
npm test : ejecuta pruebas con Vitest
npm run deploy : implementa su MCP en Cloudflare Workers
npm run cf-typegen : genera tipos de TypeScript para Cloudflare Workers (ejecútalo cada vez que agregues nuevos cambios a wrangler.jsonc)

Desarrollo

Esta plantilla implementa un servidor MCP que utiliza objetos duraderos para conexiones con estado. La estructura básica del proyecto ofrece dos enfoques principales para ampliar la funcionalidad:

Implementación de McpHonoServerDO

De forma predeterminada, la plantilla usa McpHonoServerDO , que combina el servidor MCP con Hono , un framework web rápido y ligero. Esto proporciona un sistema de enrutamiento limpio y funciones de middleware.

Ampliación con herramientas, recursos y sugerencias

La implementación del servidor principal está en src/server.ts y extiende McpHonoServerDO :

export class ExampleMcpServer extends McpHonoServerDO {
  // Required abstract method implementation
  getImplementation(): Implementation {
    return {
      name: 'ExampleMcpServer',
      version: '1.0.0',
    };
  }

  // Configure server by adding tools, resources, and prompts
  configureServer(server: McpServer): void {
    setupServerTools(server);
    setupServerResources(server);
    setupServerPrompts(server);
  }
}

Para agregar funcionalidad, utilice los siguientes módulos:

Herramientas ( src/tools.ts ): Define funciones que los clientes pueden llamar

export function setupServerTools(server: McpServer) {
  server.tool(
    'tool_name',           // Name of the tool
    'Tool description',    // Description
    {                      // Parameters schema using zod
      param1: z.string().describe('Parameter description'),
    },       
    async ({ param1 }) => {
      // Tool implementation
      return {
        content: [
          {
            type: "text",
            text: `Result: ${param1}`
          }
        ]
      };
    }
  );
}

Recursos ( src/resources.ts ): define los recursos persistentes a los que los clientes pueden acceder

export function setupServerResources(server: McpServer) {
  server.resource(
    'resource_name',
    'resource://path/{id}',
    async (uri: URL) => {
      // Resource implementation
      return {
        contents: [
          {
            text: `Resource data`,
            uri: uri.href
          }
        ]
      };
    }
  );
}

Avisos ( src/prompts.ts ): define plantillas de avisos

export function setupServerPrompts(server: McpServer) {
  server.prompt(
    'prompt_name',
    'Prompt description',
    () => ({
      messages: [{
        role: 'assistant',
        content: {
          type: 'text',
          text: `Your prompt text here`
        }
      }]
    })
  );
}

Personalización de rutas con Hono

Para agregar puntos finales HTTP personalizados con McpHonoServerDO , amplíe el método setupRoutes :

export class ExampleMcpServer extends McpHonoServerDO {
  // Other methods...

  protected setupRoutes(app: Hono<{ Bindings: Env }>): void {
    // Call the parent implementation to set up MCP routes
    super.setupRoutes(app);
    
    // Add your custom routes
    app.get('/api/status', (c) => {
      return c.json({ status: 'ok' });
    });
    
    app.post('/api/data', async (c) => {
      const body = await c.req.json();
      // Process data
      return c.json({ success: true });
    });
  }
}

Implementación de McpServerDO (enrutamiento nativo de Cloudflare)

Si necesita más control sobre la gestión de solicitudes HTTP, puede extender directamente McpServerDO . Esto le proporciona control total sobre el método fetch :

export class CustomMcpServer extends McpServerDO {
  // Required abstract method implementations
  getImplementation(): Implementation {
    return {
      name: 'CustomMcpServer',
      version: '1.0.0',
    };
  }
  
  configureServer(server: McpServer): void {
    setupServerTools(server);
    setupServerResources(server);
    setupServerPrompts(server);
  }
  
  // Override the fetch method for complete control over routing
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const path = url.pathname;
    
    // Handle custom routes
    if (path === '/api/custom') {
      return new Response(JSON.stringify({ custom: true }), {
        headers: { 'Content-Type': 'application/json' }
      });
    }
    
    // Pass through MCP-related requests to the parent implementation
    return super.fetch(request);
  }
}

Este enfoque es útil cuando necesitas:

Manejar rutas específicas con lógica personalizada
Implementar middleware complejo o autenticación
Interceptar o modificar solicitudes antes de que lleguen al controlador MCP
Agregue puntos finales WebSocket o SSE personalizados más allá de la implementación estándar de MCP

Ejemplos

Ejemplo de lista de tareas pendientes CRUD

Para ver un ejemplo completo de trabajo, consulte el ejemplo de lista de tareas pendientes de CRUD MCP que demuestra:

Operaciones CRUD completas utilizando herramientas MCP
Integración de bases de datos SQLite para persistencia
Actualizaciones en tiempo real a través de WebSocket/SSE
Manejo integral de errores
Capacidades avanzadas de filtrado y clasificación
Indicaciones y recursos enriquecidos

Recursos relacionados

Paquetes básicos

Paquete MCP : la implementación principal de MCP con funciones avanzadas y utilidades de prueba
TypeScript Agent Framework : cree agentes inteligentes impulsados por LLM con Agent Framework

Documentación

Documentación : ¡Próximamente!

Comunidad

Únase a nuestra comunidad para obtener ayuda, compartir ideas y contribuir al proyecto:

Discord : Únete al canal #mcp para solicitudes de funciones, soporte y debates.

Contribuyendo

Agradecemos sus contribuciones para mejorar esta plantilla. Así es como puede contribuir:

Bifurcar el repositorio : crea una bifurcación para realizar tus cambios
Crear una rama : Realiza tus cambios en una nueva rama
git checkout -b feature/your-feature-name
Confirme sus cambios : haga confirmaciones significativas
git commit -m "Add feature: brief description"
Empujar a tu bifurcación : Empujar tus cambios a tu bifurcación
git push origin feature/your-feature-name
Crear una solicitud de extracción : abra una solicitud de extracción con una descripción detallada de sus cambios

Pautas para solicitudes de extracción

Proporcione un título claro y descriptivo para su PR
Incluya una descripción detallada de lo que hace su PR
Hacer referencia a cualquier problema relacionado
Incluya capturas de pantalla o ejemplos si corresponde
Asegúrese de que todas las pruebas pasen
Mantenga las relaciones públicas centradas en una sola característica o solución

Para cambios o características más grandes, recomendamos discutirlos primero en nuestro canal de Discord para garantizar la alineación con la dirección del proyecto.

O use el botón Implementar en Cloudflare arriba para implementar directamente desde GitHub.

Licencia

Instituto Tecnológico de Massachusetts (MIT)

Xava Labs MCP Template

Integrations