Kookmin MCP Stock Agent

Kookmin University Assignment · "Boosting Impact with Hermes + Custom MCP Server"

We prove how work quality changes through 3 experiments by attaching a custom MCP server to the domestic stock recommendation Hermes agent created in the previous assignment.

🎯 What's Included

Related MCP server: pykrx-mcp

⚙️ Installation

Python 3.10+ (Test environment 3.13).

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

▶️ Execution

# 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-Second Demo Recording

Actions by timecode are organized in demo/demo_script.md. The simplest path:

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

🧪 Experiment ① — MCP Server (6 Tools)

Data: Naver Finance crawling single source (src/mcp_stock/sources/naver.py). Free, no key required.

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

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

• Stock Details / PER·EPS·PBR·Dividends: finance.naver.com/item/main.naver?code=... (Stable emphasis tags like id="_per")

• News by Stock: finance.naver.com/item/news_news.naver?code=...

• Safe operation with automatic fallback snapshots during market holidays or Naver page changes.

🧪 Experiment ② — Tool Success/Failure Quality Comparison

exp2_quality.py runs the same user questions across three environments and auto-generates tables and failure logs.

• (a) NO MCP — 0 tools. LLM answers only with training data → Hallucinations, lack of evidence.

• (b) GOOD MCP — Normal custom server. 12 tool calls, cites 4 positive keywords.

• (c) BROKEN MCP — As defined in server_broken.py:

  • get_top_gainers description incorrectly written as "Top losers" → Model misselection

  • get_recent_news triggers TimeoutError after time.sleep(5)

  • get_fundamentals returns an empty dict

Results:

• results/exp2_quality_table.md — Comparison table

• results/exp2_failure_logs.md — Failed call traces + response body

• results/exp2_summary.json — Original statistics

🧪 Experiment ③ — 3 Orchestration Patterns

Results:

• results/exp3_benchmark.csv — Wide CSV for bar charts

• results/exp3_pattern_table.md — Table + Retrospective

• results/exp3_summary.json — Full trace per pattern

🤖 LLM Integration — Hermes / Other Hosts

This repository is designed to produce tokens and traces via deterministic simulation even without LLM API keys. To attach to actual Hermes / Claude Desktop / Cursor:

1) Use as Hermes Host (Running experiments ②③ with a real LLM)

Simply fill in _callHermes() in src/experiments/runner/hermes_runner.py.

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

After setting environment variables HERMES_ENDPOINT, HERMES_API_KEY, replace the AgentRunner instance with HermesRunner().

2) Use only tools in Claude Desktop / Cursor

Add to Claude Desktop's claude_desktop_config.json or Cursor MCP settings:

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

📑 Creating PPT

Paste slides/slides.md directly into another AI. Example prompt:

The following markdown is a 12-slide spec for a 5-minute presentation. Please create PowerPoint slides based on the # Slide N headers. Represent ### Visual blocks as mermaid diagrams or tables if possible, and put ### Speaker Notes into the slide notes area.

📤 Submission Flow

1. Update results with python -m experiments.exp2_quality && python -m experiments.exp3_orchestration

2. Record 30-second demo with ./demo/record_demo.sh → demo/demo.mov

3. GitHub push (Record repository URL in README and slide 6)

4. Send GitHub URL + slides + demo video to kts123@kookmin.ac.kr (Deadline 5/14 23:59:59)

📁 Directory Tree

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

🛟 Troubleshooting