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) |
| FastMCP stdio, 6 Werkzeuge |
MCP-Server (defekte Version) |
| Falsche Beschreibung / Timeout / Leere Antwort |
30-Sekunden-Demo |
| Sequenz-Ausgabe für Aufnahmen |
Experiment ② Qualitätsvergleich |
| Vergleich NO MCP / GOOD / BROKEN |
Experiment ③ Mustervergleich |
| Single / Planner+Executor / Parallel |
Präsentationsunterlagen (spec) |
| Direkt in andere KI einfügen, um PPT zu erstellen |
Ergebnisse |
| 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 |
| 'today' / YYYY-MM-DD |
|
| KOSPI/KOSDAQ, 1..50 | Top N Aktien |
| Code oder koreanischer Name | close / changePct / volume / per / pbr |
| Stichwort oder Aktienname | Schlagzeile + |
| Code oder koreanischer Name | per / pbr / eps / bps / roe |
| 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}JSONTop-Gewinner:
finance.naver.com/sise/sise_rise.naver?sosok={0|1}HTMLAktiendetails / PER·EPS·PBR·Dividende:
finance.naver.com/item/main.naver?code=...(stabileid="_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_gainersBeschreibung fälschlicherweise als "Top-Verlierer" angegeben → Modell wählt falsch ausget_recent_newslöst nachtime.sleep(5)einenTimeoutErrorausget_fundamentalsgibt ein leeres dict zurück
Ergebnisse:
results/exp2_quality_table.md— Vergleichstabelleresults/exp2_failure_logs.md— Fehler-Call-Trace + Antworttextresults/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 Balkendiagrammeresults/exp3_pattern_table.md— Tabelle + Reflexionresults/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 NHeadern. Die### VisualBlöcke sollten nach Möglichkeit als Mermaid-Diagramme oder Tabellen dargestellt werden, und die### Speaker Notessollten in den Notizenbereich der Folie eingefügt werden.
📤 Einreichungsablauf
Ergebnisse aktualisieren mit
python -m experiments.exp2_quality && python -m experiments.exp3_orchestration30-Sekunden-Demo aufnehmen mit
./demo/record_demo.sh→demo/demo.movGitHub Push (Repository-URL in README und Folie 6 eintragen)
GitHub-URL + Slides + Demo-Video per E-Mail an
kts123@kookmin.ac.krsenden (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 |
| Aktie nicht auf Naver-Seite oder Strukturänderung | Automatischer Fallback auf Snapshot verwendet — funktioniert normal |
| 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 toolsget_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
Scored across 6 tools
Each tool has a clearly distinct purpose: fundamentals, market overview, news, stock quote, top gainers, and a composite recommendation. No overlap or ambiguity.
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.
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.
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.
Maintenance
Related MCP Connectors
A Model Context Protocol server exposing real-time and historical Colombo Stock Exchange (CSE) data to AI agents and LLM applications. Provides quotes and OHLCV price history, full financial statements (income, balance sheet, cash flow), pre-computed technicals (moving averages, RS ratings, volume signals), macroeconomic indicators, corporate actions, and rule-based screening across CSE stocks and sector indices, everything needed to build CSE-aware trading assistants, research tools, and market-analysis agents. This is the official MCP server of www.ceyloncharts.com
Official Intrinio MCP server. US stock prices, options and fundamentals for AI agents.
Financial data MCP server for Claude, ChatGPT, Cursor and Codex. Real-time stock quotes, financial statements, options flow, SEC filings, insider trades, 13F holdings, macro data and market news from gloom.sh, the open-source Bloomberg Terminal alternative.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm1MIT

pykrx-mcpofficial
AlicenseNot gradedqualityDmaintenanceProvides 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 PyPI3MIT- AlicenseAqualityDmaintenanceProvides 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.9MIT
- AlicenseNot gradedqualityDmaintenanceAn 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