Agente de Acciones MCP Kookmin

Tarea de la Universidad Kookmin · "Elevar el impacto con Hermes + servidor MCP hecho a medida"

Adjuntamos un servidor MCP hecho a medida al agente Hermes de recomendación de acciones nacionales creado en la tarea anterior para demostrar cómo cambia la calidad del trabajo mediante 3 experimentos.

🎯 ¿Qué contiene?

⚙️ Instalación

Python 3.10+ (entorno de prueba 3.13).

python -m venv .venv
source .venv/bin/activate
pip install -e .

▶️ Ejecución

# 1) MCP 서버 검증 (서버는 stdio라 호스트가 붙어야 의미 있음 — Ctrl+C로 종료)
python -m mcp_stock.server

# 2) 30초 동작 데모 (실제로 돌려서 녹화)
python -m experiments.exp1_demo
#  또는 ./demo/record_demo.sh

# 3) 실험 ② 성공/실패 비교 → results/exp2_* 자동 생성
python -m experiments.exp2_quality

# 4) 실험 ③ Orchestration 토큰 비교 → results/exp3_* 자동 생성
python -m experiments.exp3_orchestration

🎥 Grabación de demo de 30 segundos

Las acciones por código de tiempo están organizadas en demo/demo_script.md. La ruta más sencilla:

./demo/record_demo.sh         # QuickTime/Cmd+Shift+5 로 화면 녹화하면서 실행
./demo/record_demo.sh --asciinema   # 텍스트 캡처 (asciinema 필요)

🧪 Experimento ① — Servidor MCP (6 tipos de herramientas)

Datos: Fuente única de rastreo de Naver Finance (src/mcp_stock/sources/naver.py). Gratuito, no requiere clave.

• Índice: JSON de polling.finance.naver.com/api/realtime/domestic/index/{KOSPI|KOSDAQ}

• Mayores ganancias/pérdidas: HTML de finance.naver.com/sise/sise_rise.naver?sosok={0|1}

• Detalles de acciones / PER·EPS·PBR·Dividendos: finance.naver.com/item/main.naver?code=... (etiquetas de énfasis estables como id="_per")

• Noticias por acción: finance.naver.com/item/news_news.naver?code=...

• Funcionamiento seguro con instantánea de respaldo automática en caso de días festivos o cambios en la página de Naver.

🧪 Experimento ② — Comparación de calidad de resultados de éxito/fallo de herramientas

exp2_quality.py ejecuta la misma pregunta del usuario en tres entornos y genera automáticamente tablas y registros de fallos.

• (a) NO MCP — 0 herramientas. El LLM responde solo con datos de entrenamiento → alucinaciones, falta de fundamento.

• (b) GOOD MCP — Servidor personalizado normal. 12 llamadas a herramientas, cita 4 palabras clave positivas.

• (c) BROKEN MCP — Según la definición de server_broken.py:

  • Descripción de get_top_gainers escrita incorrectamente como "mayores caídas" → selección errónea del modelo

  • get_recent_news genera TimeoutError después de time.sleep(5)

  • get_fundamentals devuelve un dict vacío

Resultados:

• results/exp2_quality_table.md — Tabla comparativa

• results/exp2_failure_logs.md — Traza de llamadas fallidas + cuerpo de respuesta

• results/exp2_summary.json — Estadísticas originales

🧪 Experimento ③ — 3 patrones de orquestación

Resultados:

• results/exp3_benchmark.csv — CSV ancho para crear gráficos de barras

• results/exp3_pattern_table.md — Tabla + reflexión

• results/exp3_summary.json — Traza completa por patrón

🤖 Integración LLM — Hermes / Otros hosts

Este repositorio fue creado para que los tokens y trazas salgan mediante simulación determinista incluso sin claves de API de LLM. Para conectarlo a Hermes / Claude Desktop / Cursor reales:

1) Usar como host de Hermes (ejecutar experimentos ②③ con un LLM real)

Solo es necesario completar _callHermes() en src/experiments/runner/hermes_runner.py.

# TODO(user): replace this body with the real Hermes call.
import httpx
response = httpx.post(self.endpoint, headers=..., json=...)
return response.json()

Después de configurar las variables de entorno HERMES_ENDPOINT, HERMES_API_KEY, reemplace la instancia de AgentRunner con HermesRunner().

2) Usar solo herramientas en Claude Desktop / Cursor

Agregar a claude_desktop_config.json de Claude Desktop o a la configuración MCP de Cursor:

{
  "mcpServers": {
    "kookmin-stock": {
      "command": "python",
      "args": ["-m", "mcp_stock.server"],
      "cwd": "/path/to/Kookmin-University-MCP",
      "env": { "PYTHONPATH": "/path/to/Kookmin-University-MCP/src" }
    }
  }
}

📑 Crear PPT

Simplemente pegue slides/slides.md en otra IA. Ejemplo de prompt:

El siguiente markdown es la especificación de 12 diapositivas para una presentación de 5 minutos. Por favor, crea diapositivas de PowerPoint por cada encabezado # Slide N. Los bloques ### Visual deben representarse preferiblemente como diagramas mermaid o tablas tal cual, y los ### Speaker Notes deben colocarse en el área de notas de la diapositiva.

📤 Flujo de entrega

1. Actualizar resultados con python -m experiments.exp2_quality && python -m experiments.exp3_orchestration

2. Grabar demo de 30s con ./demo/record_demo.sh → demo/demo.mov

3. GitHub push (registrar la URL del repositorio en el README y en la diapositiva 6)

4. Enviar URL de GitHub + slides + video de demo al correo kts123@kookmin.ac.kr (fecha límite 14/5 23:59:59)

📁 Árbol de directorios

.
├── README.md
├── pyproject.toml / requirements.txt
├── demo/
│   ├── demo_script.md
│   └── record_demo.sh
├── results/                 # 자동 생성
├── slides/slides.md
└── src/
    ├── mcp_stock/
    │   ├── server.py
    │   ├── server_broken.py
    │   ├── data/ticker_map.py
    │   ├── sources/naver.py        # 네이버 금융 크롤러 (단일 데이터 소스)
    │   └── tools/{market, quote, news, fundamentals, recommend}.py
    ├── experiments/
    │   ├── exp1_demo.py
    │   ├── exp2_quality.py
    │   ├── exp3_orchestration.py
    │   └── runner/{agent_base, mock_runner, hermes_runner}.py
    └── utils/{logger, token_counter}.py

🛟 Solución de problemas