MCP Todo Server

Un servidor de aplicación de tareas demo construido con una arquitectura limpia usando MCPServer y JSON Placeholder.

GitHubPrueba este MCPPatrocinado

Documentación

mcp-todo-server/README.md

MCP Todo Server

Este proyecto es una demostración de una implementación de arquitectura limpia usando Node.js y TypeScript. Utiliza el MCPServer de @modelcontextprotocol/sdk para crear un servidor y gestionar tareas a través de una API de marcador de posición JSON.

Demo en MCP Inspector

MCP Inspector Demo

Demo en Cursor

MCP Cursor Demo

Stack Tecnológico

Este proyecto está construido con tecnologías modernas y sigue principios de arquitectura limpia:

Tecnologías Principales

  • Node.js: Entorno de ejecución para ejecutar código JavaScript en el servidor
  • TypeScript: Lenguaje de programación fuertemente tipado que se basa en JavaScript
  • Model Context Protocol (MCP): Protocolo para que los modelos de IA interactúen con herramientas externas y fuentes de datos

Framework Backend

  • @modelcontextprotocol/sdk: SDK oficial para crear servidores compatibles con MCP
  • Zod: Biblioteca de validación de esquemas centrada en TypeScript, utilizada para la validación de entradas

Pruebas

  • Jest: Framework de pruebas para JavaScript
  • Supertest: Biblioteca de aserciones HTTP para probar endpoints de API

Herramientas de Desarrollo

  • tsx: Entorno de ejecución de TypeScript con soporte nativo de ESM
  • tsc-alias: Herramienta para resolver alias de rutas de TypeScript durante la compilación
  • ts-node: Motor de ejecución de TypeScript para Node.js

Arquitectura

  • Arquitectura Limpia: El proyecto sigue un enfoque de arquitectura limpia con:
    • Capa de dominio: Lógica de negocio central y entidades
    • Capa de aplicación: Casos de uso y servicios de aplicación
    • Capa de infraestructura: Interacciones externas e implementaciones
    • Capa de presentación: Endpoints de API y manejo de solicitudes/respuestas

APIs Externas

  • JSONPlaceholder: API RESTful para pruebas y prototipado que proporciona datos de tareas ficticios

Diagrama de Arquitectura

Diagrama de Secuencia

El siguiente diagrama muestra cómo fluyen las solicitudes a través del MCP Todo Server:

sequenceDiagram
    participant Client as MCP Client/Inspector
    participant Server as McpServer
    participant Handler as TodoHandlers
    participant Service as TodoService
    participant Repository as JsonPlaceholderTodoRepository
    participant API as JSONPlaceholder API

    Client->>Server: Tool Call Request (e.g., get_todos)
    
    alt Get All Todos
        Server->>Service: todoService.getAllTodos()
        Service->>Repository: todoRepository.findAll()
        Repository->>API: fetch('https://jsonplaceholder.typicode.com/todos')
        API-->>Repository: JSON Response
        Repository-->>Service: Todo[] entities
        Service-->>Server: Todo[] entities
        Server-->>Client: Formatted JSON Response
    else Get Todo by ID
        Client->>Server: get_todo_by_id with id parameter
        Server->>Service: todoService.getTodoById(id)
        Service->>Repository: todoRepository.findById(id)
        Repository->>API: fetch('https://jsonplaceholder.typicode.com/todos/{id}')
        API-->>Repository: JSON Response
        Repository-->>Service: Todo entity
        Service-->>Server: Todo entity
        Server-->>Client: Formatted JSON Response
    else Create Todo
        Client->>Server: create_todo with title, completed
        Server->>Service: todoService.createTodo(data)
        Service->>Repository: todoRepository.create(data)
        Repository->>API: POST fetch('https://jsonplaceholder.typicode.com/todos')
        API-->>Repository: JSON Response
        Repository-->>Service: New Todo entity
        Service-->>Server: New Todo entity
        Server-->>Client: Formatted JSON Response
    else Update Todo
        Client->>Server: update_todo with id, title, completed
        Server->>Service: todoService.updateTodo(id, data)
        Service->>Repository: todoRepository.update(id, data)
        Repository->>API: PUT fetch('https://jsonplaceholder.typicode.com/todos/{id}')
        API-->>Repository: JSON Response
        Repository-->>Service: Updated Todo entity
        Service-->>Server: Updated Todo entity
        Server-->>Client: Formatted JSON Response
    else Delete Todo
        Client->>Server: delete_todo with id
        Server->>Service: todoService.deleteTodo(id)
        Service->>Repository: todoRepository.delete(id)
        Repository->>API: DELETE fetch('https://jsonplaceholder.typicode.com/todos/{id}')
        API-->>Repository: Response status
        Repository-->>Service: Boolean result
        Service-->>Server: Boolean result
        Server-->>Client: Success/Failure message
    end

Estructura del Proyecto

mcp-todo-server
├── src
│   ├── domain
│   │   ├── entities
│   │   │   └── todo.ts
│   │   ├── repositories
│   │   │   └── todoRepository.ts
│   │   └── valueObjects
│   │       └── todoId.ts
│   ├── application
│   │   ├── services
│   │   │   └── todoService.ts
│   │   └── useCases
│   │       ├── createTodo.ts
│   │       ├── deleteTodo.ts
│   │       ├── getTodoById.ts
│   │       ├── getTodos.ts
│   │       └── updateTodo.ts
│   ├── infrastructure
│   │   ├── repositories
│   │   │   └── jsonPlaceholderTodoRepository.ts
│   │   └── http
│   │       └── httpClient.ts
│   ├── presentation
│   │   └── handlers
│   │       └── todoHandlers.ts
│   ├── server.ts
│   └── index.ts
├── tests
│   ├── unit
│   │   ├── domain
│   │   │   └── entities
│   │   │       └── todo.test.ts
│   │   ├── application
│   │   │   └── services
│   │   │       └── todoService.test.ts
│   │   └── infrastructure
│   │       └── repositories
│   │           └── jsonPlaceholderTodoRepository.test.ts
│   └── integration
│       └── server.test.ts
├── http
│   └── todo-api.http
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md

Instrucciones de Configuración

  1. Clona el repositorio:

    git clone <repository-url>
cd mcp-todo-server

  2. Instala las dependencias:

    npm install

  3. Ejecuta el servidor:

    npm start

Uso

El servidor expone varios endpoints para gestionar tareas. Puedes usar el archivo http/todo-api.http proporcionado para probar los endpoints de la API manualmente.

Uso de MCP Inspector

¿Qué es MCP Inspector?

MCP Inspector es una herramienta que te permite interactuar directamente con servidores compatibles con MCP, probando llamadas de herramientas y viendo respuestas sin necesidad de integrarte con un modelo de IA.

Instalación

Para instalar MCP Inspector globalmente:

npm install -g @modelcontextprotocol/inspector

Conexión al MCP Todo Server

# 1. First, build and start MCP Todo server:
npm run build
npm start

# 2. In a separate terminal, run MCP Inspector and connect it to mcp todo server:
mcp-inspector --server "node ./build/index.js"
or 
npx @modelcontextprotocol/inspector node build/index.js

# Alternatively, if mcp todo server is already running, can pipe it to the inspector:
node ./build/index.js | mcp-inspector

# 3. Once connected, the inspector will open in your default web browser, allowing you to:

# Browse available tools
# Execute tool calls with custom parameters
# View responses in a formatted JSON view
# Debug request/response cycles

Configurar MCP Todo Server en Cursor

  1. Configura la integración de MCP:

  2. Abre la configuración de Cursor

  3. Navega a la sección de Extensiones o Herramientas de IA

  4. Busca la configuración de "Model Context Protocol" o "MCP Tools" mcp.json

{
  "mcpServers": {
   ... other mcp server,

    "todo-mcp-server": {
      "command": "node",
      "args": [
        "D:\\dev\\node\\mcp-todo-server\\build\\index.js"
      ]
    }
  }
}

Pruebas

Para ejecutar las pruebas unitarias y de integración, usa el siguiente comando:

npm test

Licencia

Este proyecto está licenciado bajo la Licencia MIT.