Servidor de API de tareas: implementación de TypeScript de MCP

Implementación del Protocolo de Contexto de Modelo (MCP) para la API de Gestión de Tareas, escrita en TypeScript. Este proyecto funciona como implementación de referencia y como servidor de gestión de tareas funcional.

Descripción general

Este servidor MCP se conecta a un servicio API de tareas externo y proporciona una interfaz estandarizada para la gestión de tareas. Admite dos modos de ejecución:

Modo STDIO : Comunicación de entrada/salida estándar para aplicaciones basadas en CLI y agentes de IA
Modo HTTP+SSE : servidor accesible desde la Web con eventos enviados por el servidor para navegadores y clientes basados en HTTP

El servidor ofrece un conjunto completo de operaciones de gestión de tareas, validación exhaustiva y manejo robusto de errores.

Características

Operaciones de gestión de tareas :
- Enumere las tareas existentes con capacidades de filtrado
- Crea nuevas tareas con propiedades personalizables
- Actualizar detalles de la tarea (descripción, estado, categoría, prioridad)
- Eliminar tareas cuando estén completadas o ya no sean necesarias
Modos de interfaz dual :
- Compatibilidad con el protocolo STDIO para la integración de agentes de IA y de línea de comandos
- Protocolo HTTP+SSE con interfaz web para acceso basado en navegador
Implementación del protocolo MCP :
- Implementación completa del Protocolo de Contexto Modelo
- Recursos para estructuras de datos de tareas
- Herramientas para operaciones de tareas
- Manejo de errores y mensajes informativos
Seguro de calidad :
- Cliente de prueba integral para validación
- Apagado automático del servidor después de completar las pruebas
- Validación detallada de las respuestas de la API

Empezando

Prerrequisitos

Node.js 16.x o superior
gestor de paquetes npm o pnpm

Instalación

Clonar el repositorio:
git clone https://github.com/yourusername/mcp-template-ts.git cd mcp-template-ts
Instalar dependencias:
npm install
o usando pnpm:
pnpm install
Cree un archivo .env con sus credenciales de API de tareas:
TASK_MANAGER_API_BASE_URL=https://your-task-api-url.com/api TASK_MANAGER_API_KEY=your_api_key_here TASK_MANAGER_HTTP_PORT=3000
Construir el proyecto:
npm run build

Ejecución del servidor

Modo STDIO (para integración CLI/AI)

npm start

node dist/index.js

Modo HTTP (para acceso web)

npm run start:http

node dist/http-server.js

De forma predeterminada, el servidor HTTP se ejecuta en el puerto 3000. Puede cambiar esto configurando la variable de entorno TASK_MANAGER_HTTP_PORT .

Pruebas

Ejecute el conjunto de pruebas completo para verificar la funcionalidad:

npm test

Esto hará lo siguiente:

Construir el proyecto
Iniciar una instancia de servidor
Conectar un cliente de prueba al servidor
Ejecutar todas las operaciones de la tarea
Verificar respuestas correctas
Apagar automáticamente el servidor

Uso del cliente MCP

Cliente STDIO

Para conectarse al servidor STDIO desde su aplicación:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import * as path from 'path';

// Create transport
const transport = new StdioClientTransport({
  command: 'node',
  args: [path.resolve('path/to/dist/index.js')]
});

// Initialize client
const client = new Client(
  {
    name: "your-client-name",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {},
      resources: {},
      tools: {}
    }
  }
);

// Connect to server
await client.connect(transport);

// Example: List all tasks
const listTasksResult = await client.callTool({
  name: "listTasks",
  arguments: {}
});

// Example: Create a new task
const createTaskResult = await client.callTool({
  name: "createTask",
  arguments: {
    task: "Complete project documentation",
    category: "Documentation",
    priority: "high"
  }
});

// Clean up when done
await client.close();

Cliente HTTP

Para conectarse al servidor HTTP desde un navegador:

<!DOCTYPE html>
<html>
<head>
  <title>Task Manager</title>
  <script type="module">
    import { Client } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/sdk/dist/esm/client/index.js';
    import { SSEClientTransport } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/sdk/dist/esm/client/sse.js';

    document.addEventListener('DOMContentLoaded', async () => {
      // Create transport
      const transport = new SSEClientTransport('http://localhost:3000/mcp');
      
      // Initialize client
      const client = new Client(
        {
          name: "browser-client",
          version: "1.0.0"
        },
        {
          capabilities: {
            prompts: {},
            resources: {},
            tools: {}
          }
        }
      );

      // Connect to server
      await client.connect(transport);
      
      // Now you can use client.callTool() for tasks
    });
  </script>
</head>
<body>
  <h1>Task Manager</h1>
  <!-- Your interface elements here -->
</body>
</html>

Herramientas disponibles

lista de tareas

Enumera todas las tareas disponibles.

const result = await client.callTool({
  name: "listTasks",
  arguments: {
    // Optional filters
    status: "pending", // Filter by status
    category: "Work",  // Filter by category
    priority: "high"   // Filter by priority
  }
});

crearTarea

Crea una nueva tarea.

const result = await client.callTool({
  name: "createTask",
  arguments: {
    task: "Complete the project report",  // Required: task description
    category: "Work",                     // Optional: task category
    priority: "high"                      // Optional: low, medium, high
  }
});

tarea de actualización

Actualiza una tarea existente.

const result = await client.callTool({
  name: "updateTask",
  arguments: {
    taskId: 123,                       // Required: ID of task to update
    task: "Updated task description",  // Optional: new description
    status: "done",                    // Optional: pending, started, done
    category: "Personal",              // Optional: new category
    priority: "medium"                 // Optional: low, medium, high
  }
});

eliminarTarea

Elimina una tarea.

const result = await client.callTool({
  name: "deleteTask",
  arguments: {
    taskId: 123  // Required: ID of task to delete
  }
});

Variables de entorno

Variable	Descripción	Por defecto
URL BASE DE LA API DEL ADMINISTRADOR DE TAREAS	URL para la API de tareas externas	Ninguno (obligatorio)
CLAVE DE API DEL ADMINISTRADOR DE TAREAS	Clave API para autenticación	Ninguno (obligatorio)
PUERTO HTTP DEL ADMINISTRADOR DE TAREAS	Puerto para el servidor HTTP	3000
PUERTO	Nombre de puerto alternativo (tiene prioridad)	Ninguno

Estructura del proyecto

mcp-template-ts/
├── dist/               # Compiled JavaScript files
├── src/                # TypeScript source files
│   ├── index.ts        # STDIO server entry point
│   ├── http-server.ts  # HTTP+SSE server entry point
│   ├── test-client.ts  # Test client implementation
├── .env                # Environment variables
├── package.json        # Project dependencies
├── tsconfig.json       # TypeScript configuration
└── README.md           # Project documentation

Desarrollo

Inicie el compilador de TypeScript en modo de observación:
npm run watch
Ejecutar pruebas para verificar los cambios:
npm test

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Expresiones de gratitud

Este proyecto utiliza @modelcontextprotocol/sdk para la implementación del protocolo MCP
Diseñado para la integración con herramientas de IA y aplicaciones web.

Task API Server

Integrations