Kookmin MCP Stock Agent

Kookmin-Universität Aufgabe · "Impact steigern mit Hermes + selbstgebautem MCP-Server"

In dieser Aufgabe statten wir den im letzten Projekt erstellten Hermes-Agenten für koreanische Aktienempfehlungen mit einem selbstgebauten MCP-Server aus und beweisen anhand von 3 Experimenten, wie sich die Arbeitsqualität verändert.

🎯 Was ist enthalten?

⚙️ Installation

Python 3.10+ (Testumgebung 3.13).

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

▶️ Ausführung

# 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

🎥 30-Sekunden-Demo-Aufnahme

In demo/demo_script.md sind die Aktionen nach Timecodes sortiert. Der einfachste Pfad:

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

🧪 Experiment ① — MCP-Server (6 Werkzeuge)

Daten: Naver Finance Crawling als einzige Quelle (src/mcp_stock/sources/naver.py). Kostenlos, kein API-Key erforderlich.

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

• Top-Gewinner: finance.naver.com/sise/sise_rise.naver?sosok={0|1} HTML

• Aktiendetails / PER·EPS·PBR·Dividende: finance.naver.com/item/main.naver?code=... (stabile id="_per" etc. Emphasis-Tags)

• Aktienspezifische Nachrichten: finance.naver.com/item/news_news.naver?code=...

• Automatischer Fallback auf Snapshots bei Feiertagen oder Änderungen der Naver-Seite für sicheren Betrieb.

🧪 Experiment ② — Vergleich der Tool-Erfolgs-/Fehlerqualität

exp2_quality.py führt dieselben Benutzerfragen in drei Umgebungen aus und generiert automatisch Tabellen und Fehlerprotokolle.

• (a) NO MCP — 0 Werkzeuge. LLM antwortet nur mit Trainingsdaten → Halluzinationen, keine Belege.

• (b) GOOD MCP — Normaler selbstgebauter Server. 12 Tool-Aufrufe, Zitat von 4 positiven Stichworten.

• (c) BROKEN MCP — Gemäß Definition in server_broken.py:

  • get_top_gainers Beschreibung fälschlicherweise als "Top-Verlierer" angegeben → Modell wählt falsch aus

  • get_recent_news löst nach time.sleep(5) einen TimeoutError aus

  • get_fundamentals gibt ein leeres dict zurück

Ergebnisse:

• results/exp2_quality_table.md — Vergleichstabelle

• results/exp2_failure_logs.md — Fehler-Call-Trace + Antworttext

• results/exp2_summary.json — Ursprüngliche Statistiken

🧪 Experiment ③ — 3 Orchestrierungsmuster

Ergebnisse:

• results/exp3_benchmark.csv — Wide CSV für Balkendiagramme

• results/exp3_pattern_table.md — Tabelle + Reflexion

• results/exp3_summary.json — Vollständiger Trace pro Muster

🤖 LLM-Integration — Hermes / Andere Hosts

Dieses Repository wurde so erstellt, dass Token und Traces auch ohne LLM-API-Key durch deterministische Simulation generiert werden können. Um es mit echtem Hermes / Claude Desktop / Cursor zu verbinden:

1) Als Hermes-Host verwenden (Experiment ②③ mit echtem LLM ausführen)

Es muss nur _callHermes() in src/experiments/runner/hermes_runner.py ausgefüllt werden.

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

Nach dem Setzen der Umgebungsvariablen HERMES_ENDPOINT, HERMES_API_KEY die AgentRunner-Instanz durch HermesRunner() ersetzen.

2) Nur Werkzeuge in Claude Desktop / Cursor verwenden

Zur claude_desktop_config.json von Claude Desktop oder zur Cursor MCP-Konfiguration hinzufügen:

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

📑 PPT erstellen

slides/slides.md kann direkt in eine andere KI kopiert werden. Beispiel-Prompt:

Das folgende Markdown ist eine Spezifikation für 12 Folien für eine 5-minütige Präsentation. Bitte erstelle PowerPoint-Folien basierend auf den # Slide N Headern. Die ### Visual Blöcke sollten nach Möglichkeit als Mermaid-Diagramme oder Tabellen dargestellt werden, und die ### Speaker Notes sollten in den Notizenbereich der Folie eingefügt werden.

📤 Einreichungsablauf

1. Ergebnisse aktualisieren mit python -m experiments.exp2_quality && python -m experiments.exp3_orchestration

2. 30-Sekunden-Demo aufnehmen mit ./demo/record_demo.sh → demo/demo.mov

3. GitHub Push (Repository-URL in README und Folie 6 eintragen)

4. GitHub-URL + Slides + Demo-Video per E-Mail an kts123@kookmin.ac.kr senden (Frist 14.05. 23:59:59)

📁 Verzeichnisbaum

.
├── 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

🛟 Fehlerbehebung