Kookmin MCP Stock Agent

国民大学課題 · 「Hermes + MCP自作サーバーでインパクトを引き上げる」

前回の課題で作成した国内株式推奨Hermesエージェントに自作MCPサーバーを接続し、 作業の質がどのように変化するかを3つの実験で証明する。

🎯 含まれているもの

⚙️ インストール

Python 3.10+ (テスト環境 3.13)。

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

▶️ 実行

# 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秒デモ録画

demo/demo_script.mdにタイムコード別の行動がまとめられている。 最も単純なパス:

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

🧪 実験① — MCPサーバー (ツール6種)

データ: Naver Finance クローリング 単一ソース (src/mcp_stock/sources/naver.py)。無料・キー不要。

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

• 上昇率上位: finance.naver.com/sise/sise_rise.naver?sosok={0|1} HTML

• 銘柄詳細 / PER・EPS・PBR・配当: finance.naver.com/item/main.naver?code=... (安定した id="_per" などのemphasisタグ)

• 銘柄別ニュース: finance.naver.com/item/news_news.naver?code=...

• 休場日 / Naverページ変更時に自動fallbackスナップショットで安全に動作。

🧪 実験② — Tool成功/失敗結果の品質比較

exp2_quality.pyが同じユーザーの質問を3つの環境で実行し、表・失敗ログを自動生成する。

• (a) NO MCP — ツール0個。LLMが学習データのみで回答 → ハルシネーション・根拠欠如。

• (b) GOOD MCP — 正常な自作サーバー。ツール12回呼び出し、4つの好材料キーワードを引用。

• (c) BROKEN MCP — server_broken.pyの定義通り:

  • get_top_gainersのdescriptionを「下落率上位」と誤記 → モデルが誤選択

  • get_recent_newsが time.sleep(5) 後に TimeoutError 発生

  • get_fundamentalsが空のdictを返却

結果:

• results/exp2_quality_table.md — 比較表

• results/exp2_failure_logs.md — 失敗呼び出しトレース + 回答本文

• results/exp2_summary.json — 元の統計

🧪 実験③ — Orchestration 3パターン

結果:

• results/exp3_benchmark.csv — 棒グラフ作成用wide CSV

• results/exp3_pattern_table.md — 表 + 回顧

• results/exp3_summary.json — パターン別フルトレース

🤖 LLM連携 — Hermes / 他のホスト

このリポジトリは、LLM APIキーなしでも決定論的なシミュレーションでトークン・トレースが出るように作成した。 実際のHermes / Claude Desktop / Cursorに接続するには:

1) Hermesホストとして使用 (実験②③を実際のLLMで実行する)

src/experiments/runner/hermes_runner.pyの _callHermes() を埋めるだけでよい。

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

環境変数 HERMES_ENDPOINT, HERMES_API_KEY を設定後、 AgentRunner インスタンスを HermesRunner() に置き換える。

2) Claude Desktop / Cursorでツールのみ使用

Claude Desktopの claude_desktop_config.json または Cursor MCP設定に追加:

{
  "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作成

slides/slides.mdを他のAIにそのまま貼り付ければよい。例示プロンプト:

次のmarkdownは5分発表用12枚のスライドspecです。 # Slide N ヘッダー単位でPowerPointスライドを作成してください。 ### Visual ブロックは可能な限りmermaidダイアグラムや表をそのまま表現し、 ### Speaker Notes はスライドノート領域に入れてください。

📤 提出フロー

1. python -m experiments.exp2_quality && python -m experiments.exp3_orchestration で結果を更新

2. ./demo/record_demo.sh で30秒デモ録画 → demo/demo.mov

3. GitHub push (リポジトリURLをREADMEとslide 6に記録)

4. メール kts123@kookmin.ac.kr へ GitHub URL + slides + demo動画を送信 (締切 5/14 23:59:59)

📁 ディレクトリツリー

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

🛟 トラブルシューティング