Задание университета Kookmin · "Повышение эффективности с помощью Hermes + самописного MCP-сервера"
Мы докажем, как меняется качество работы, с помощью 3 экспериментов, подключив самописный MCP-сервер к агенту Hermes для рекомендации корейских акций, созданному в прошлом задании.
Результат | Путь | Описание |
MCP-сервер (нормальный) |
| FastMCP stdio, 6 типов инструментов |
MCP-сервер (сломанная версия) |
| Неверное описание / тайм-аут / пустой ответ |
30-секундное демо |
| Последовательность для записи |
Сравнение результатов эксперимента ② |
| Сравнение NO MCP / GOOD / BROKEN |
Сравнение паттернов эксперимента ③ |
| Single / Planner+Executor / Parallel |
Материалы презентации (spec) |
| Вставьте в другой ИИ для создания PPT |
Результаты |
| Автоматически созданные таблицы, CSV, логи |
Related MCP server: pykrx-mcp
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Действия по тайм-кодам описаны в demo/demo_script.md.
Самый простой путь:
./demo/record_demo.sh # QuickTime/Cmd+Shift+5 로 화면 녹화하면서 실행
./demo/record_demo.sh --asciinema # 텍스트 캡처 (asciinema 필요)Инструмент | Ввод | Вывод |
| 'today' / YYYY-MM-DD |
|
| KOSPI/KOSDAQ, 1..50 | Топ N акций |
| Код или название на корейском | close / changePct / volume / per / pbr |
| Ключевое слово или название акции | Заголовок + |
| Код или название на корейском | per / pbr / eps / bps / roe |
| KOSPI/KOSDAQ | scoreBreakdown + обоснование |
Данные: Парсинг 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 — Исходная статистика
Паттерн | Описание | Характеристики токенов | Характеристики времени отклика |
Single | Накопление результатов инструментов в одном цикле | Входные токены ↑↑ | Самый медленный |
Planner + Executor | Планировщик составляет последовательность, исполнитель только резюмирует | Входные токены ↓ | Средний |
Parallel sub-agents | Параллельный запуск sub-агентов KOSPI / KOSDAQ / NEWS | Входные токены ↓↓ | Самый быстрый |
Результаты:
results/exp3_benchmark.csv — Широкий CSV для построения гистограмм
results/exp3_pattern_table.md — Таблица + рефлексия
results/exp3_summary.json — Полный трейс по паттернам
Этот репозиторий создан так, чтобы токены и трейсы можно было получить через детерминированное моделирование даже без API-ключа LLM. Для подключения к реальным Hermes / Claude Desktop / Cursor:
Достаточно заполнить _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().
Добавьте в 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" }
}
}
}Просто вставьте slides/slides.md в другой ИИ. Пример промпта:
Следующий markdown — это спецификация 12 слайдов для 5-минутной презентации. Создай слайды PowerPoint по заголовкам
# Slide N. Блоки### Visualпо возможности представь в виде диаграмм mermaid или таблиц, а### Speaker Notesпомести в область заметок к слайду.
Обновите результаты с помощью python -m experiments.exp2_quality && python -m experiments.exp3_orchestration
Запишите 30-секундное демо через ./demo/record_demo.sh → demo/demo.mov
Сделайте GitHub push (укажите URL репозитория в README и на 6-м слайде)
Отправьте 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Симптом | Причина | Решение |
| Акции нет на странице Naver или изменилась структура | Используется автоматический fallback-снимок — работает нормально |
| Сеть офлайн | Все инструменты безопасно работают через fallback-снимок |
Искажение корейского текста | Шрифт терминала | Рекомендуются D2 Coding / Pretendard / SF Mono |
Вызов в выходной/нерабочий день | Нерабочий день | API опроса возвращает цену закрытия последнего дня |
Return PER, PBR, EPS, BPS, ROE and dividend yield for a ticker.
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior, but it only lists outputs. It omits details like data source, update frequency, error handling, or whether values are real-time. It essentially repeats what the name suggests without added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that efficiently conveys the tool's purpose. No extraneous information is included, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter and no output schema, the description is adequate but minimal. It lists return metrics but does not expand on acronyms (e.g., PER = Price-to-Earnings Ratio) or provide any usage context. It is acceptable for a simple tool but lacks depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it adds no meaning beyond the parameter name 'ticker'. It does not specify format, example values, or domain constraints, leaving the agent with minimal guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns specific fundamental metrics (PER, PBR, EPS, BPS, ROE, dividend yield) for a given ticker. It uses a specific verb 'Return' and resource 'fundamentals', and the listed metrics distinguish it from sibling tools like get_stock_quote or get_market_overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it or suggest other tools for different scenarios, leaving the agent to infer context from name and siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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}
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | today |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses return fields and date fallback; does not mention side effects but is a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with clear Args/Returns sections. Every sentence adds value; no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description details return structure (nested objects for kospi/kosdaq). Could mention read-only nature but overall adequate for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter with zero schema description coverage. Description fully explains its format and fallback behavior, adding essential meaning beyond bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns KOSPI and KOSDAQ index close, daily change percent, and trading value. Distinguishes from sibling tools like get_stock_quote (individual stocks) and get_top_gainers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Specifies acceptable date formats ('today' or YYYY-MM-DD) and fallback behavior for non-business days. Implicitly guides when to use but lacks explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_n | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the positivityScore calculation and that results include matched keywords, offering some behavioral insight. However, it lacks disclosure on whether it's read-only, rate limits, error handling, or other side effects. No annotations to compensate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences plus arg list), front-loaded with the purpose, and includes structured arg descriptions. No unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers purpose, parameters, and key behavioral detail (positivityScore). It could mention limitations like article count or recency but remains fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by detailing that query accepts ticker codes, Korean stock names, or free-text, and that top_n ranges from 1 to 20. This adds significant meaning beyond the schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns recent Naver finance news headlines about a given query. It specifies a unique function not overlapping with siblings like get_fundamentals or get_stock_quote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for news retrieval but does not explicitly differentiate from siblings or provide when-to-use/when-not-to-use guidance. No mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. '삼성전자').
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description alone must convey behavioral traits. It mentions 'most recent' data but does not specify real-time vs delayed, caching, authentication requirements, or other side effects. This is minimal disclosure for a data retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two sentences and a bullet point to convey purpose and parameter details. Every word is necessary, and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description adequately covers what data is returned and how to input the ticker. It could mention data source or latency, but overall it is sufficiently complete given the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the schema by specifying the ticker parameter can be a 6-digit code or Korean name, including examples. Since schema description coverage is 0%, this is critical and well-done.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns specific stock data (close, change percent, volume, PER, PBR) for a ticker. It distinguishes from siblings implicitly by the data fields, but no explicit differentiation is provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to specify the ticker but gives no guidance on when to use this tool versus alternatives like get_fundamentals or get_market_overview. No when-not-to-use or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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}.
| Name | Required | Description | Default |
|---|---|---|---|
| market | No | KOSPI | |
| top_n | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states the output is a list of objects with specific fields, but does not mention if the tool is read-only, any authentication requirements, rate limits, or edge cases (e.g., empty list on holidays). The description is factual but lacks depth on behavioral aspects beyond the basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a clear docstring format with a one-line purpose followed by Args and Returns. Every sentence adds value, and the structure is easy to parse. No redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters with defaults) and the presence of an output schema (implied by context signals), the description is largely complete. It explains parameters, return format, and purpose. However, it could mention the ordering direction (descending) is already clear from the name, but no major gaps. A small addition like 'daily change percent' clarification is fine.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning: market is 'KOSPI' or 'KOSDAQ' (though schema has enum), and top_n range 1..50, which goes beyond the schema's default-only definition. This provides helpful context for parameter use, though the default values are already clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns top N stocks ranked by daily change percent descending. The verb 'Return' and resource 'top N stocks' are specific. Compared to siblings like get_fundamentals or get_stock_quote, this tool's purpose is distinct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly conveys what the tool does but does not explicitly specify when to use it (e.g., 'for identifying top gainers') or when to avoid it (e.g., 'use get_stock_quote for individual stock details'). No alternatives or exclusions are mentioned, leaving the agent to infer usage from the tool's name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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}.
| Name | Required | Description | Default |
|---|---|---|---|
| market | No | KOSPI | |
| top_n | No | ||
| criteria | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that each entry includes a transparent scoreBreakdown and Korean rationale, which adds useful behavioral context. However, it does not explicitly state it is read-only or discuss side effects, but given the nature, it is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starting with a clear purpose sentence, then providing details in a structured Args section. Every sentence adds value with no redundant or vague statements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as a composite, the description covers purpose, parameters, and output structure. An output schema exists to explain return values. Missing elements like rate limits or error handling are minor, but overall it is sufficiently complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The Args section explains market (enum), top_n (range 1-10), and criteria (optional override with fields). This adds significant meaning beyond the raw schema, though details of criteria fields could be more explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a composite buy-recommendation tool that combines top gainers, quotes, news positivity, and fundamentals into a ranked list. This distinguishes it from sibling tools like get_fundamentals or get_top_gainers which are single-purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not provide explicit guidance on when to use it vs alternatives, nor does it state when not to use it. The composite nature implies it for recommendations, but no clear exclusions or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_fundamentalsget_market_overviewget_recent_newsget_stock_quoteget_top_gainersrecommend_buysScored 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.
MCP server giving AI agents one-connection access to China A-share market intelligence: financials,
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
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.
Korea-native MCP gateway: Korean commerce, payments, messaging, gov & finance APIs for AI agents.
