内容
# belex-mcp
> **贝尔格莱德证券交易所（Belex）** 和 **塞尔维亚国家银行（NBS）** 数据的MCP服务器。第一个针对塞尔维亚金融市场的开源 [模型上下文协议](https://modelcontextprotocol.io) 服务器。
[](https://www.npmjs.com/package/belex-mcp)
[](https://github.com/filipovicfilip222/belex-mcp/actions/workflows/ci.yml)
[](LICENSE)
## 什么是belex-mcp？
`belex-mcp` 是一个 Node.js / TypeScript MCP 服务器，提供 Belex 报价、指数和 NBS 汇率 / 关键宏观指标作为标准化工具，供 LLM 客户端（Claude Desktop、Cursor、自定义代理）调用。直到现在，询问 LLM 关于塞尔维亚市场意味着在代理中进行自定义抓取或假装数据不存在。这将两者合并为一个 `npx belex-mcp`。
## 快速入门（Claude Desktop）
1. 确保您已安装 Node.js 20 或更高版本。
2. 打开 Claude Desktop 配置文件：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
3. 在 `mcpServers` 部分添加 `belex-mcp`：
```json
{
"mcpServers": {
"belex": {
"command": "npx",
"args": ["-y", "belex-mcp"]
}
}
}
```
4. 重启 Claude Desktop。询问：_“昨天的 EUR/RSD 中间汇率是多少？”_。更多信息请参见 [`examples/demo-prompts.md`](examples/demo-prompts.md)。
## 工具列表
所有工具均返回 JSON。时间戳为 `Europe/Belgrade` 时区的 ISO 8601 格式。除非注明，否则价格均为 RSD。
| 工具 | 用途 |
|---|---|
| `belex_list_companies` | Belex 上挂牌的证券 |
| `belex_get_company_profile` | 单个证券的简介 |
| `belex_get_quote` | 最新报价（最新、OHLCV、涨跌幅） |
| `belex_get_historical_prices` | 某段时间内的每日 OHLCV 条形图 |
| `belex_get_index` | BELEX15 / BELEXLINE 当前值 |
| `belex_get_index_constituents` | 指数成分股及权重 |
| `belex_get_market_summary` | 交易日结束时的成交额、涨幅、跌幅、成交量最大的证券 |
| `nbs_list_currencies` | NBS 公布的货币列表 |
| `nbs_get_exchange_rate` | 某日的中间汇率 / 买入汇率 / 卖出汇率 |
| `nbs_get_exchange_rate_series` | 某段时间内的每日中间汇率 |
| `nbs_get_reference_rate` | NBS 关键政策利率 |
| `nbs_get_inflation` | 年同比和环比 CPI |
完整工具参考：[`docs/tools.md`](docs/tools.md)。
## 示例
三个演示对话在 [`examples/demo-prompts.md`](examples/demo-prompts.md) 中。
## 数据来源和免责声明
数据来源于 `belex.rs` 和 `nbs.rs` 的公开页面，并在进程中缓存（LRU；无外部依赖）。`belex-mcp` 与贝尔格莱德证券交易所或塞尔维亚国家银行无关。价格和汇率仅供信息使用；如需用于交易或结算，请直接使用权威来源。
HTTP 层强制实施每秒一个请求、指数级退避和稳定 `User-Agent` 的礼貌预算。
## 架构
```
LLM 客户端（Claude Desktop / Cursor）
│ MCP JSON-RPC via stdio
▼
belex-mcp 服务器
├── MCP SDK 运行时
├── 工具注册 + Zod 输入模式
├── belexClient ──► belex.rs (HTML)
└── nbsClient ──► nbs.rs (XML + HTML)
▼
HTTP 层（undici、重试 + 退避、LRU 缓存、速率限制器）
```
决策和权衡作为 ADRs 记录在 [`docs/adr/`](docs/adr/) 中。
## 开发
```bash
git clone https://github.com/filipovicfilip222/belex-mcp.git
cd belex-mcp
npm install
npm run typecheck # 严格的 TS 检查
npm run lint # ESLint 扁平配置
npm test # vitest 单元测试
npm run test:integration # 按需；访问实时源
```
仓库布局遵循 [项目文档的第 7 节](belex-mcp-project-docs.md#7-repository-layout)。每个工具都有一个 Zod 输入模式、一个固定装置支持的单元测试和 `src/clients/` 中的包装器。有关固定装置约定，请参见 [`fixtures/README.md`](fixtures/README.md)。
## 贡献
仅限 Conventional Commits（`feat:`、`fix:`、`chore:`、`docs:`、`test:`）。每个提交只进行一个逻辑更改。在更改超过三个文件之前，请先开启一个问题。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
