Servidor MCP de Tareas — Muestra de aprendizaje de MCP

Propósito de esta muestra

Esta es una muestra de aprendizaje para experimentar con los elementos básicos de MCP (Model Context Protocol): Recursos / Herramientas / Prompts, a través de un servidor de gestión de tareas pendientes (ToDo) sencillo.

Qué se puede aprender

• Recursos: Mecanismo mediante el cual los clientes de IA leen datos del servidor

• Herramientas: Mecanismo mediante el cual los clientes de IA ejecutan operaciones en el servidor

• Prompts: Mecanismo de plantillas para dar a la IA una perspectiva o contexto específico

• Configuración básica de un servidor MCP y comunicación mediante transporte STDIO

Cómo funciona MCP

MCP es un protocolo para que las aplicaciones de IA (hosts) accedan de forma unificada a datos y herramientas externas.

Panorama general

graph TB
  subgraph host[" "]
    HostLabel["🖥️ ホスト（Claude Desktop / VS Code など）"]
    LLM["LLM"]
    ClientA["MCP クライアント"]
    ClientB["MCP クライアント"]
    ClientC["MCP クライアント"]
    HostLabel ~~~ LLM
    LLM --- ClientA
    LLM --- ClientB
    LLM --- ClientC
  end

  ClientA -- "STDIO" --> ServerA["MCP サーバー A\n（本サンプル）"]
  ClientB -- "STDIO" --> ServerB["MCP サーバー B\n（別のサーバー）"]
  ClientC -- "SSE/HTTP" --> ServerC["MCP サーバー C\n（リモート）"]

  style host fill:#1a1a2e,stroke:#e0e0e0,stroke-width:2px,color:#ffffff
  style HostLabel fill:none,stroke:none,font-weight:bold,color:#ffffff
  style LLM fill:#ffffff,stroke:#333333,color:#000000
  style ClientA fill:#ffffff,stroke:#333333,color:#000000
  style ClientB fill:#ffffff,stroke:#333333,color:#000000
  style ClientC fill:#ffffff,stroke:#333333,color:#000000

• Host: La aplicación de IA en sí. Realiza la interacción con el usuario y la llamada al LLM

• Cliente MCP: Integrado en el host, se comunica 1:1 con cada servidor MCP

• Servidor MCP: Proporciona Recursos / Herramientas / Prompts. Esta muestra corresponde a este componente

Los 3 elementos que proporciona un servidor MCP

block-beta
  columns 1

  block:server["MCP サーバー"]
    R["📖 Resources（データ参照）\nタスク一覧 ・ 統計情報"]
    T["🔧 Tools（操作の実行）\nタスク追加 ・ タスク完了 ・ 検索"]
    P["💬 Prompts（テンプレート）\nデイリーレビュー ・ タスク分解"]
  end

Flujo de comunicación (en esta muestra)

sequenceDiagram
    participant U as ユーザー
    participant H as ホスト / LLM
    participant C as MCP クライアント
    participant S as MCP サーバー
    participant F as tasks.json

    U->>H: 「タスクを追加して」
    H->>C: add_task 呼び出し
    C->>S: JSON-RPC request
    S->>F: ファイル書き込み
    F-->>S: OK
    S-->>C: JSON-RPC response
    C-->>H: 結果を返す
    H-->>U: 「追加しました」

1. El usuario realiza una solicitud en lenguaje natural

2. El LLM del host selecciona la herramienta adecuada y la llama a través del cliente MCP

3. El servidor MCP ejecuta el proceso (en esta muestra, lee/escribe en tasks.json) y devuelve el resultado

4. El LLM responde al usuario basándose en el resultado

Punto clave: La comunicación entre el cliente MCP y el servidor se realiza mediante JSON-RPC 2.0. En esta muestra, se utiliza STDIO (entrada/salida estándar) como transporte, por lo que el stdout del servidor es exclusivo para la comunicación MCP. Para la salida de registros (logs) se utiliza stderr.

Estructura de archivos

├── server.py            # MCP サーバー本体（Resources / Tools / Prompts を登録）
├── task_store.py        # Task モデルと JSON 永続化
├── requirements.txt     # 依存パッケージ
├── tasks_sample.json    # サンプルデータ（動作確認用）
├── README.md
└── tests/
    └── test_task_store.py  # ストレージ層のテスト

Requisitos previos

• Python 3.10 o superior

Configuración

# 仮想環境の作成（推奨）
python -m venv .venv
source .venv/bin/activate

# 依存パッケージのインストール
pip install -r requirements.txt

# テスト用パッケージ（テストを実行する場合）
pip install pytest

# 仮想環境の作成（推奨）
python -m venv .venv
.venv\Scripts\Activate.ps1

# 依存パッケージのインストール
pip install -r requirements.txt

# テスト用パッケージ（テストを実行する場合）
pip install pytest

Cómo iniciar

# サンプルデータを使う場合はコピー
cp tasks_sample.json tasks.json

# サーバー起動（STDIO transport）
python server.py

# サンプルデータを使う場合はコピー
Copy-Item tasks_sample.json tasks.json

# サーバー起動（STDIO transport）
python server.py

El servidor utiliza la entrada/salida estándar para hablar el protocolo MCP. Si se ejecuta directamente, no producirá una salida legible para humanos. Se utiliza conectándose desde un cliente MCP.

Cómo usar desde un cliente MCP

En el caso de Claude Desktop

1. Abre Settings desde el menú de Claude Desktop

2. Selecciona Developer en el menú de la izquierda

3. Haz clic en el botón Edit Config para abrir el archivo de configuración

4. Añade el siguiente contenido al archivo de configuración (reemplaza cwd con la ruta absoluta del directorio donde colocaste este repositorio)

5. Guarda el archivo y reinicia Claude Desktop

6. Si aparece un icono de martillo en el campo de entrada del chat, la conexión fue exitosa

Nota: Reiniciar Claude Desktop no significa cerrar la aplicación con el botón × en la esquina superior derecha de la ventana (permanece en segundo plano). Asegúrate de cerrarla completamente desde File > Exit (en macOS Claude > Quit Claude) en la barra de menús antes de volver a abrirla.

Ubicación del archivo de configuración:

Contenido de la configuración (ajusta las rutas según tu entorno):

{
  "mcpServers": {
    "task-server": {
      "command": "python",
      "args": ["/path/to/mcp-sample/server.py"],
      "cwd": "/path/to/mcp-sample"
    }
  }
}

Nota: Especifica server.py en args con una ruta absoluta. Si usas una ruta relativa, es posible que cwd no se refleje y se ejecute en un directorio no deseado.

Ejemplo de uso — Escribe lo siguiente en el campo de chat:

add_task で「買い物リストを作る」というタスクを追加して
  → add_task ツールが呼ばれ、タスクが追加される

list_tasks でタスク一覧を表示して
  → list_tasks ツールが呼ばれ、一覧が表示される

daily_review プロンプトを使って、今日やることを整理して
  → daily_review Prompt をもとに提案が返る

Consejo: Las herramientas MCP a veces no se llaman con lenguaje natural ambiguo. Es más seguro incluir el nombre de la herramienta o del prompt en la instrucción.

En el caso de Claude Code (CLI)

Crea un archivo .mcp.json en el directorio raíz del proyecto:

# mcp-sample ディレクトリ内で実行
claude mcp add task-server -- python server.py

O también puedes crear .mcp.json manualmente:

{
  "mcpServers": {
    "task-server": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

Verificación de conexión:

# Claude Code を起動して /mcp コマンドで確認
claude
> /mcp

Si add_task o list_tasks aparecen en la lista de herramientas, la conexión fue exitosa.

Ejemplo de uso — Escribe directamente en el prompt de Claude Code:

> add_task で「レポート作成」というタスクを優先度 high で追加して
> list_tasks で高優先度のタスクだけ表示して
> search_tasks で「レポート」を検索して
> complete_task でタスク a1b2c3d4 を完了にして
> weekly_summary プロンプトを使って今週の振り返りをして

En el caso de VS Code (GitHub Copilot)

En VS Code, coloca la configuración en .vscode/mcp.json:

{
  "servers": {
    "task-server": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "${workspaceFolder}"
    }
  }
}

1. Al guardar .vscode/mcp.json, aparecerá un botón Start en la parte superior del archivo

2. Haz clic en Start para iniciar el servidor

3. Las herramientas estarán disponibles desde Copilot Chat (modo Agente)

Ejemplo de uso — Cambia Copilot Chat al modo Agente y escribe:

add_task で期限 2026-04-10 の「設計レビュー」タスクを追加して
list_tasks で status が doing のタスクを表示して
break_down_task プロンプトでタスク a1b2c3d4 を小さく分解して

En el caso de Manus

Manus es una plataforma de agentes de IA que realiza tareas de forma autónoma basándose en las instrucciones del usuario. También funciona como cliente MCP y puede conectarse a servidores MCP externos para utilizar herramientas y datos.

Añade el servidor MCP desde la pantalla de configuración de Manus:

1. Abre Settings (configuración) de Manus

2. Haz clic en Add Server en la sección MCP Servers

3. Configura lo siguiente:

Nota: Dado que Manus funciona en la nube, para conectarse a un servidor MCP local, debes hacer que el servidor sea accesible remotamente o utilizar la función de conexión local que proporciona Manus. Consulta la documentación oficial de Manus para más detalles.

Al guardar la configuración, el agente de Manus podrá seleccionar y llamar automáticamente a las herramientas de este servidor al ejecutar tareas.

Ejemplo de uso — Instruye a Manus de la siguiente manera:

タスク一覧を確認して、期限が近いものを優先度順に整理して
  → list_tasks ツールで一覧を取得し、整理した結果を返す

「企画書を書く」というタスクを追加して、さらに小さなステップに分解して
  → add_task でタスクを追加し、break_down_task で分解まで自動実行

Consejo: Como Manus combina herramientas de forma autónoma, puede procesar instrucciones que abarcan múltiples pasos de una sola vez.

Lista de funciones MCP proporcionadas

Recursos (lectura de datos)

Herramientas (operaciones)

Prompts (plantillas para IA)

Ubicación de almacenamiento de datos

• tasks.json (se crea automáticamente en el mismo directorio que el servidor)

• Guarda todas las tareas en formato JSON

Pruebas

python -m pytest tests/ -v

El comando de ejecución de pruebas es común para Bash / PowerShell.

Restricciones

• Para un solo usuario: No admite acceso simultáneo ni gestión de usuarios

• Solo local: No está pensado para exposición en red

• Para aprendizaje: No se ha considerado la robustez ni la seguridad para entornos de producción

• Sin base de datos: Los datos se guardan en un archivo JSON

• Sin autenticación: No incluye mecanismos de autenticación ni autorización