Kookmin MCP 股票代理

国民大学作业 · “用 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)。免费，无需 Key。

• 指数：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 快照，安全运行。

🧪 实验 ② — 工具成功/失败结果质量对比

exp2_quality.py 在三种环境下运行相同的用户提问，并自动生成表格和失败日志。

• (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 — 原始统计数据

🧪 实验 ③ — 编排 3 种模式

结果：

• results/exp3_benchmark.csv — 用于制作柱状图的 wide CSV

• results/exp3_pattern_table.md — 表格 + 回顾

• results/exp3_summary.json — 各模式的完整追踪

🤖 LLM 联动 — Hermes / 其他主机

本仓库即使没有 LLM API Key，也能通过确定性模拟得出 Token 和追踪记录。 若要挂载到实际的 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 (在 README 和 slide 6 中记录仓库 URL)

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

🛟 故障排除