Taller Ia Agentes MCP

🤖 Taller de IA: Agentes y MCP Servers

Ejemplos prácticos para entender cómo funcionan los Agentes de IA y los MCP Servers (Model Context Protocol).

✅ Compatible con Claude y DeepSeek ✅ DevContainer Incluido - Entorno preconfigurado en Docker ✅ OpenCode incluido - Agente AI de línea de comandos

🌐 Inicio Rápido con GitHub Codespaces (Recomendado)

Para el taller usaremos GitHub Codespaces. Funciona en cualquier navegador, sin instalaciones locales.

Setup en Codespaces (3 minutos)

1. Crear Codespace:

- Ve a tu repositorio en GitHub - Haz clic en el botón verde Code → pestaña Codespaces - Haz clic en Create codespace on main

1. Configurar GitHub Secrets (API Keys):

- En GitHub: Settings → Secrets and variables → Codespaces - Añade estos Secrets con tus claves reales: - ANTHROPIC_API_KEY (para Claude) - DEEPSEEK_API_KEY (para DeepSeek) - LLM_PROVIDER (opcional, "claude" o "deepseek")

1. En el Codespace (VS Code Online):

   # Verifica que todo funciona
   npm run agente:tareas:claude
   # O con DeepSeek
   npm run agente:tareas:deepseek

✅ ¡Listo! El entorno está completamente configurado en Codespaces.

📖 Documentación completa: Ver specs/001-devcontainer-setup/quickstart.md

🐳 Alternativa: DevContainer Local

Si prefieres desarrollo local (requiere Docker):

Prerequisitos

• Docker Desktop (descargar)
• VS Code (descargar)
• Extensión Dev Containers

Setup (5 minutos)

# 1. Clonar repositorio
git clone https://github.com/[usuario]/taller-ia.git
cd taller-ia

# 2. Abrir en VS Code
code .

# 3. VS Code sugerirá abrir en DevContainer → Haz clic en "Reopen in Container"

# 4. Configurar API keys (crear archivo .env en raíz)
cp .env.example .env
# Edita .env con tus claves

# 5. ¡Listo! Prueba un agente
npm run agente:tareas:claude

📦 Instalación Manual (para usuarios avanzados)

Nota: Para el taller usaremos GitHub Codespaces. Esta instalación manual es solo si quieres ejecutar localmente sin Docker.

Requisitos

• Node.js 20+ (node --version)
• npm 10+ (npm --version)
• TypeScript 5+ (tsc --version)

Instalación

# 1. Clonar repositorio
git clone https://github.com/[usuario]/taller-ia.git
cd taller-ia

# 2. Instalar dependencias
npm install

# 3. Configurar API keys
cp .env.example .env
# Edita .env con tus claves reales

# 4. Compilar proyecto
npm run build

# 5. Probar agente
npm run agente:tareas:claude

📁 Estructura del proyecto

taller-ia/
├── .devcontainer/
│   └── devcontainer.json          # Configuración del DevContainer
├── .vscode/
│   ├── settings.json              # Configuración de VS Code
│   └── extensions.json            # Extensiones recomendadas
├── agentes/
│   ├── shared/
│   │   └── llm-client.ts          # Cliente agnóstico (Claude/DeepSeek)
│   ├── agente-tareas/
│   │   ├── index.ts               # Agente con tool use (loop básico)
│   │   ├── agent-loop.ts          # Lógica del loop de herramientas
│   │   ├── tools.ts               # Definición de herramientas
│   │   └── AgenteTareas.md        # Documentación del agente
│   └── agente-investigador/
│       ├── index.ts               # Agente Plan-Execute-Synthesize
│       ├── investigar.ts          # Lógica de investigación
│       ├── planificar.ts          # Lógica de planificación
│       ├── sintetizar.ts          # Lógica de síntesis
│       ├── types.ts               # Tipos TypeScript
│       └── AgenteInvestigador.md  # Documentación del agente
├── mcp-servers/
│   ├── notas-mcp.ts               # MCP Server con FastMCP
│   └── utils-mcp.ts               # MCP Server con SDK oficial
├── specs/
│   ├── 001-devcontainer-setup/    # Feature: DevContainer Setup
│   │   ├── spec.md                # Especificación
│   │   ├── plan.md                # Plan de implementación
│   │   ├── tasks.md               # Lista de tareas
│   │   ├── research.md            # Investigación y decisiones
│   │   └── quickstart.md          # Guía rápida para usuarios
│   └── [otras-features]/
├── AGENTS.md                       # Guías de codificación para agentes IA
├── package.json
├── tsconfig.json
├── .env.example                   # Plantilla de variables de entorno
└── README.md

🚀 Instalación

# 1. Instalar dependencias
npm install

# 2. Configurar API keys
cp .env.example .env
# Edita .env con tus API keys

Variables de entorno

# Para usar Claude
export ANTHROPIC_API_KEY="sk-ant-..."

# Para usar DeepSeek
export DEEPSEEK_API_KEY="sk-..."

# Seleccionar proveedor (claude o deepseek)
export LLM_PROVIDER="claude"

📋 Guías de Desarrollo (AGENTS.md)

El archivo AGENTS.md contiene las reglas de codificación específicas para agentes de IA que trabajen en este proyecto:

• Comandos de build/lint/test para el proyecto
• Estándares de código TypeScript strict
• Reglas del proyecto específicas para agentes MCP
• Convenciones de nomenclatura y formato

Importante: Revisa AGENTS.md antes de contribuir código a agentes de IA.

✨ Características del DevContainer

🔐 Multi-Proveedor LLM

• ✅ Claude (Anthropic) - Muy preciso y robusto
• ✅ DeepSeek - Económico y eficiente
• ✅ Cambiar entre ellos sin reconfiguración: export LLM_PROVIDER=deepseek

🚀 Setup Ultra-Rápido

• ✅ Sin instalaciones previas (solo Docker + VS Code)
• ✅ 5-10 minutos para tener entorno funcional
• ✅ Reconstrucciones rápidas ( Nota: Los MCP servers son independientes del proveedor LLM. Funcionan con Claude Desktop, pero también con cualquier cliente MCP compatible.

MCP 1: Servidor de Notas (FastMCP)

Usa fastmcp, una librería que simplifica la creación de MCP servers.

npm run mcp:notas

Tools disponibles:

MCP 2: Servidor de Utilidades (SDK Oficial)

Usa el SDK oficial de MCP con Zod para validación de schemas.

npm run mcp:utils

Tools disponibles:

MCP 3: Servidor de Marcadores (SDK Oficial)

Gestor de marcadores usando el SDK oficial de MCP con TypeScript.

npm run mcp:marcadores

Tools disponibles:

MCP 4: Servidor de Marcadores (Python FastMCP)

El mismo gestor de marcadores implementado con Python FastMCP — mucho menos código.

# Setup (primera vez)
cd mcp-servers/python
uv venv .venv && uv pip install fastmcp pytest
source .venv/bin/activate

# Iniciar servidor
python server.py

# Ejecutar tests
.venv/bin/pytest test_server.py -v

Tools disponibles:

Resources:

Comparativa:

🧪 Tests

# TypeScript (vitest)
npm run test

# Python (pytest)
cd mcp-servers/python && .venv/bin/pytest test_server.py -v

⚙️ Configurar MCPs en Claude Desktop

1. Localiza el archivo de configuración:

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json

1. Añade la configuración (adapta las rutas absolutas):

{
  "mcpServers": {
    "notas": {
      "command": "npx",
      "args": ["tsx", "/ruta/completa/a/taller-ia/mcp-servers/notas-mcp.ts"]
    },
    "utilidades": {
      "command": "npx",
      "args": ["tsx", "/ruta/completa/a/taller-ia/mcp-servers/utils-mcp.ts"]
    }
  }
}

1. Reinicia Claude Desktop
2. Verifica que aparecen los iconos de herramientas 🔧

📊 Comparativas

Claude vs DeepSeek para Agentes

FastMCP vs SDK Oficial

🧠 Arquitectura

Agente = LLM + Tools + Loop

┌─────────────────────────────────────────────┐
│                   AGENTE                     │
│                                              │
│   ┌──────────────────────────────────────┐  │
│   │            LLM Client                │  │
│   │  ┌─────────┐     ┌─────────────┐    │  │
│   │  │ Claude  │ OR  │  DeepSeek   │    │  │
│   │  └─────────┘     └─────────────┘    │  │
│   └──────────────────────────────────────┘  │
│                     │                        │
│                     ▼                        │
│   ┌─────────┐    ┌─────────┐    ┌───────┐  │
│   │  Tools  │◀──▶│  Loop   │◀──▶│ State │  │
│   └─────────┘    └─────────┘    └───────┘  │
└─────────────────────────────────────────────┘

MCP = Protocolo estándar

┌──────────────┐     MCP      ┌────────────────┐
│    Claude    │◀────────────▶│   MCP Server   │
│   Desktop    │   (stdio)    │  (tu código)   │
└──────────────┘              └────────────────┘
                                      │
                                      ▼
                              ┌──────────────┐
                              │  APIs, DBs,  │
                              │  Servicios   │
                              └──────────────┘

📚 Recursos adicionales

• Documentación de Anthropic
• API de DeepSeek
• Especificación MCP
• SDK MCP TypeScript
• FastMCP

🎯 Ejercicios propuestos

1. Añadir una nueva tool al agente de tareas (ej: enviar email simulado)
2. Comparar respuestas del mismo agente con Claude vs DeepSeek
3. Crear un MCP server que consulte una API real (ej: el tiempo)
4. Combinar ambos: Un agente que use tu MCP server personalizado
5. Añadir un tercer proveedor al llm-client.ts (ej: OpenAI, Mistral)
6. Comparar los dos servidores de marcadores: Analiza las diferencias entre marcadores-mcp.ts y mcp-servers/python/server.py

⚡ Troubleshooting

Error: "Invalid API Key"

# Verifica que tienes las variables configuradas
echo $ANTHROPIC_API_KEY
echo $DEEPSEEK_API_KEY

Error: "Tool not found" en DeepSeek

DeepSeek a veces tiene problemas con nombres de tools en español. Prueba a renombrarlas en inglés.

MCP Server no aparece en Claude Desktop

1. Verifica que la ruta en claude_desktop_config.json es absoluta
2. Comprueba que puedes ejecutar el server manualmente: npm run mcp:notas
3. Revisa los logs de Claude Desktop
4. Asegúrate de que tienes Node.js >= 20.0.0 instalado

*Preparado para el taller de IA - NTT DATA 2025*