Tarea de la Universidad Kookmin · "Elevar el impacto con Hermes + servidor MCP hecho a medida"
Adjuntamos un servidor MCP hecho a medida al agente Hermes de recomendación de acciones nacionales creado en la tarea anterior para demostrar cómo cambia la calidad del trabajo mediante 3 experimentos.
Producto | Ruta | Descripción |
Servidor MCP (normal) |
| FastMCP stdio, 6 tipos de herramientas |
Servidor MCP (versión rota) |
| Descripción incorrecta / tiempo de espera / respuesta vacía |
Demo de funcionamiento de 30s |
| Salida de secuencia para grabación |
Comparación de resultados exp ② |
| Comparación NO MCP / GOOD / BROKEN |
Comparación de patrones exp ③ |
| Single / Planner+Executor / Parallel |
Material de presentación (spec) |
| Pegar tal cual en otra IA para generar PPT |
Productos resultantes |
| Tablas, CSV y registros generados automáticamente |
Related MCP server: pykrx-mcp
Python 3.10+ (entorno de prueba 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_orchestrationLas acciones por código de tiempo están organizadas en demo/demo_script.md.
La ruta más sencilla:
./demo/record_demo.sh # QuickTime/Cmd+Shift+5 로 화면 녹화하면서 실행
./demo/record_demo.sh --asciinema # 텍스트 캡처 (asciinema 필요)Herramienta | Entrada | Salida |
| 'today' / YYYY-MM-DD |
|
| KOSPI/KOSDAQ, 1..50 | N acciones principales |
| Código o nombre en coreano | close / changePct / volume / per / pbr |
| Palabra clave o nombre de acción | Titular + |
| Código o nombre en coreano | per / pbr / eps / bps / roe |
| KOSPI/KOSDAQ | scoreBreakdown + rationale |
Datos: Fuente única de rastreo de Naver Finance (src/mcp_stock/sources/naver.py). Gratuito, no requiere clave.
Índice: JSON de polling.finance.naver.com/api/realtime/domestic/index/{KOSPI|KOSDAQ}
Mayores ganancias/pérdidas: HTML de finance.naver.com/sise/sise_rise.naver?sosok={0|1}
Detalles de acciones / PER·EPS·PBR·Dividendos: finance.naver.com/item/main.naver?code=... (etiquetas de énfasis estables como id="_per")
Noticias por acción: finance.naver.com/item/news_news.naver?code=...
Funcionamiento seguro con instantánea de respaldo automática en caso de días festivos o cambios en la página de Naver.
exp2_quality.py ejecuta la misma pregunta del usuario en tres entornos y genera automáticamente tablas y registros de fallos.
(a) NO MCP — 0 herramientas. El LLM responde solo con datos de entrenamiento → alucinaciones, falta de fundamento.
(b) GOOD MCP — Servidor personalizado normal. 12 llamadas a herramientas, cita 4 palabras clave positivas.
(c) BROKEN MCP — Según la definición de server_broken.py:
Descripción de get_top_gainers escrita incorrectamente como "mayores caídas" → selección errónea del modelo
get_recent_news genera TimeoutError después de time.sleep(5)
get_fundamentals devuelve un dict vacío
Resultados:
results/exp2_quality_table.md — Tabla comparativa
results/exp2_failure_logs.md — Traza de llamadas fallidas + cuerpo de respuesta
results/exp2_summary.json — Estadísticas originales
Patrón | Descripción | Características de tokens | Características de tiempo de respuesta |
Single | Acumulación de resultados de herramientas en un bucle | Tokens de entrada ↑↑ | Más lento |
Planner + Executor | El planificador solo crea la secuencia de llamadas y el ejecutor solo resume los resultados | Tokens de entrada ↓ | Intermedio |
Parallel sub-agents | Ejecución simultánea de sub-agentes KOSPI / KOSDAQ / NEWS | Tokens de entrada ↓↓ | Más rápido |
Resultados:
results/exp3_benchmark.csv — CSV ancho para crear gráficos de barras
results/exp3_pattern_table.md — Tabla + reflexión
results/exp3_summary.json — Traza completa por patrón
Este repositorio fue creado para que los tokens y trazas salgan mediante simulación determinista incluso sin claves de API de LLM. Para conectarlo a Hermes / Claude Desktop / Cursor reales:
Solo es necesario completar _callHermes() en 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()Después de configurar las variables de entorno HERMES_ENDPOINT, HERMES_API_KEY,
reemplace la instancia de AgentRunner con HermesRunner().
Agregar a claude_desktop_config.json de Claude Desktop o a la configuración MCP de 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" }
}
}
}Simplemente pegue slides/slides.md en otra IA. Ejemplo de prompt:
El siguiente markdown es la especificación de 12 diapositivas para una presentación de 5 minutos. Por favor, crea diapositivas de PowerPoint por cada encabezado
# Slide N. Los bloques### Visualdeben representarse preferiblemente como diagramas mermaid o tablas tal cual, y los### Speaker Notesdeben colocarse en el área de notas de la diapositiva.
Actualizar resultados con python -m experiments.exp2_quality && python -m experiments.exp3_orchestration
Grabar demo de 30s con ./demo/record_demo.sh → demo/demo.mov
GitHub push (registrar la URL del repositorio en el README y en la diapositiva 6)
Enviar URL de GitHub + slides + video de demo al correo kts123@kookmin.ac.kr (fecha límite 14/5 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}.pySíntoma | Causa | Respuesta |
| La acción no está en la página de Naver o la estructura cambió | Uso de instantánea de respaldo automática — funcionamiento normal |
| Red desconectada | Todas las herramientas funcionan de forma segura con instantáneas de respaldo |
Caracteres coreanos ilegibles | Fuente de terminal | Se recomienda D2 Coding / Pretendard / SF Mono |
Llamada en día festivo/fin de semana | No es día hábil | La API de polling devuelve el último precio de cierre tal cual |
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.
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
Official Intrinio MCP server. US stock prices, options and fundamentals for AI agents.
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.
Hosted MCP server for Indian NSE/BSE stock research: 59 tools for quotes, financials and ratios, peers, shareholding and pledge, filings with extracted facts, screens, F&O and FII/DII context. Source and freshness on every answer; no buy/sell calls.
