Skip to main content
Glama
kookmin-stock

kookmin-stock

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?

Ergebnis

Pfad

Beschreibung

MCP-Server (normal)

src/mcp_stock/server.py

FastMCP stdio, 6 Werkzeuge

MCP-Server (defekte Version)

src/mcp_stock/server_broken.py

Falsche Beschreibung / Timeout / Leere Antwort

30-Sekunden-Demo

src/experiments/exp1_demo.py

Sequenz-Ausgabe für Aufnahmen

Experiment ② Qualitätsvergleich

src/experiments/exp2_quality.py

Vergleich NO MCP / GOOD / BROKEN

Experiment ③ Mustervergleich

src/experiments/exp3_orchestration.py

Single / Planner+Executor / Parallel

Präsentationsunterlagen (spec)

slides/slides.md

Direkt in andere KI einfügen, um PPT zu erstellen

Ergebnisse

results/exp2_*, results/exp3_*

Automatisch generierte Tabellen, CSV, Logs

Related MCP server: pykrx-mcp

⚙️ 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)

Werkzeug

Eingabe

Ausgabe

get_market_overview(date)

'today' / YYYY-MM-DD

{kospi:{close, changePct, tradingValueKrw}, kosdaq:{...}}

get_top_gainers(market, top_n)

KOSPI/KOSDAQ, 1..50

Top N Aktien

get_stock_quote(ticker)

Code oder koreanischer Name

close / changePct / volume / per / pbr

get_recent_news(query, top_n)

Stichwort oder Aktienname

Schlagzeile + positivityScore

get_fundamentals(ticker)

Code oder koreanischer Name

per / pbr / eps / bps / roe

recommend_buys(market, top_n, criteria)

KOSPI/KOSDAQ

scoreBreakdown + Begründung

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

Muster

Beschreibung

Token-Eigenschaften

Antwortzeit-Eigenschaften

Single

Akkumulation der Tool-Ergebnisse in einer Schleife

Eingabe-Token ↑↑

Am langsamsten

Planner + Executor

Planner erstellt nur die Aufrufsequenz, Executor fasst Ergebnisse zusammen

Eingabe-Token ↓

Mittel

Parallel sub-agents

KOSPI / KOSDAQ / NEWS Sub-Agenten laufen gleichzeitig

Eingabe-Token ↓↓

Am schnellsten

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

Symptom

Ursache

Lösung

naver detail fetch failed for XXXXXX

Aktie nicht auf Naver-Seite oder Strukturänderung

Automatischer Fallback auf Snapshot verwendet — funktioniert normal

httpx.ConnectError

Netzwerk offline

Alle Werkzeuge funktionieren sicher mit Fallback-Snapshots

Koreanische Zeichen fehlerhaft

Terminal-Schriftart

D2 Coding / Pretendard / SF Mono empfohlen

Aufruf an Feiertagen/Wochenenden

Kein Geschäftstag

Polling-API gibt den letzten Schlusskurs unverändert zurück

Available Tools

6 tools
get_fundamentalsB

Return PER, PBR, EPS, BPS, ROE and dividend yield for a ticker.

Inputs: ticker (required).

get_market_overviewA

Return KOSPI and KOSDAQ index close, daily change percent, and trading value.

Args: date: 'today' or YYYY-MM-DD. Non-business days fall back to the most recent trading day automatically. Returns: {asOf, kospi:{close, changePct, tradingValueKrw}, kosdaq:{...}, source}

Inputs: date.

get_recent_newsA

Return recent Naver finance news headlines about a ticker or keyword.

Each item carries a positivityScore (sum of catalyst-keyword matches minus negative-keyword matches) plus the matched keywords.

Args: query: ticker code, Korean stock name, or free-text keyword. top_n: 1..20.

Inputs: query (required), top_n. Returns: result

get_stock_quoteB

Return the most recent close, change percent, volume, PER and PBR for a ticker.

Args: ticker: 6-digit code (e.g. '005930') or Korean name (e.g. '삼성전자').

Inputs: ticker (required).

get_top_gainersA

Return the top N stocks ranked by daily change percent (descending).

Args: market: 'KOSPI' or 'KOSDAQ'. top_n: 1..50. Returns: List of {ticker, name, changePct, close, asOf}.

Inputs: market, top_n. Returns: result

recommend_buysA

Composite buy-recommendation tool.

Combines top gainers + per-ticker quote, news positivity, and fundamentals into a ranked list. Each entry includes a transparent scoreBreakdown and a Korean-language rationale so the LLM can quote the reasoning.

Args: market: 'KOSPI' or 'KOSDAQ'. top_n: 1..10. criteria: optional override of {minPositivityScore, maxPer, minRoe}.

Inputs: market, top_n, criteria. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: fundamentals, market overview, news, stock quote, top gainers, and a composite recommendation. No overlap or ambiguity.

    Naming Consistency4/5

    Most tools follow a 'get_' prefix verb_noun pattern (e.g., get_fundamentals, get_market_overview). The exception is recommend_buys, which is still verb_noun but lacks the prefix, creating a minor inconsistency.

    Tool Count5/5

    With 6 tools covering fundamental data, market overview, news, quotes, top gainers, and a recommend feature, the count is well-scoped for a stock information server.

    Completeness4/5

    The tool surface covers core stock information needs (fundamentals, quotes, news, top gainers, overview, and a composite recommendation). Minor gaps like historical prices or sector data are not critical for the stated purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to query real-time and historical Korean stock market data from KRX (Korea Exchange) including indices, stocks, ETFs, bonds, derivatives, and commodities via MCP tools and resources.
      12 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides Korean stock market data (KOSPI, KOSDAQ, KONEX) including prices, fundamentals, investor trading, short selling, and indices via MCP protocol, enabling natural language queries from AI agents like ChatGPT and Claude.
      62 PyPI
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides Korean stock market data, including DART electronic disclosures and KRX trading information, enabling users to query company profiles, financial statements, and stock trade details via MCP clients.
      9
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that retrieves Korean stock fundamentals and financial data from OpenDART, enabling LLMs to access corporate disclosures, financial statements, and dividend information.
      Apache 2.0