Агент Kookmin MCP Stock

Задание университета Kookmin · "Повышение эффективности с помощью Hermes + самописного MCP-сервера"

Мы докажем, как меняется качество работы, с помощью 3 экспериментов, подключив самописный MCP-сервер к агенту Hermes для рекомендации корейских акций, созданному в прошлом задании.

🎯 Что внутри

⚙️ Установка

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). Бесплатно, ключи не нужны.

• Индексы: JSON polling.finance.naver.com/api/realtime/domestic/index/{KOSPI|KOSDAQ}

• Лидеры роста: HTML finance.naver.com/sise/sise_rise.naver?sosok={0|1}

• Детали акции / PER·EPS·PBR·дивиденды: finance.naver.com/item/main.naver?code=... (стабильные теги emphasis, такие как id="_per")

• Новости по акциям: finance.naver.com/item/news_news.naver?code=...

• Безопасная работа через автоматический fallback-снимок при нерабочих днях или изменениях на страницах Naver.

🧪 Эксперимент ② — Сравнение качества результатов (успех/провал инструментов)

exp2_quality.py запускает один и тот же вопрос пользователя в трех средах и автоматически создает таблицы и логи ошибок.

• (a) NO MCP — 0 инструментов. LLM отвечает только на основе обучающих данных → галлюцинации, отсутствие доказательств.

• (b) GOOD MCP — Нормальный самописный сервер. 12 вызовов инструментов, цитирование 4 ключевых слов с позитивными новостями.

• (c) BROKEN MCP — Согласно определению server_broken.py:

  • Описание get_top_gainers ошибочно указано как "лидеры падения" → модель выбирает неверно

  • get_recent_news вызывает TimeoutError после time.sleep(5)

  • get_fundamentals возвращает пустой dict

Результаты:

• results/exp2_quality_table.md — Сравнительная таблица

• results/exp2_failure_logs.md — Трейс неудачных вызовов + текст ответа

• results/exp2_summary.json — Исходная статистика

🧪 Эксперимент ③ — 3 паттерна оркестрации

Результаты:

• results/exp3_benchmark.csv — Широкий CSV для построения гистограмм

• results/exp3_pattern_table.md — Таблица + рефлексия

• results/exp3_summary.json — Полный трейс по паттернам

🤖 Интеграция с LLM — Hermes / другие хосты

Этот репозиторий создан так, чтобы токены и трейсы можно было получить через детерминированное моделирование даже без API-ключа LLM. Для подключения к реальным Hermes / Claude Desktop / Cursor:

1) Использование в качестве хоста Hermes (запуск экспериментов ②③ на реальной LLM)

Достаточно заполнить _callHermes() в 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()

После настройки переменных окружения HERMES_ENDPOINT, HERMES_API_KEY замените экземпляр AgentRunner на HermesRunner().

2) Использование только инструментов в Claude Desktop / Cursor

Добавьте в claude_desktop_config.json для Claude Desktop или в настройки MCP для Cursor:

{
  "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 в другой ИИ. Пример промпта:

Следующий markdown — это спецификация 12 слайдов для 5-минутной презентации. Создай слайды PowerPoint по заголовкам # Slide N. Блоки ### Visual по возможности представь в виде диаграмм mermaid или таблиц, а ### Speaker Notes помести в область заметок к слайду.

📤 Порядок сдачи

1. Обновите результаты с помощью python -m experiments.exp2_quality && python -m experiments.exp3_orchestration

2. Запишите 30-секундное демо через ./demo/record_demo.sh → demo/demo.mov

3. Сделайте GitHub push (укажите URL репозитория в README и на 6-м слайде)

4. Отправьте URL GitHub + слайды + видео демо на email kts123@kookmin.ac.kr (дедлайн 14.05 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

🛟 Устранение неполадок