内容
# bvb-mcp
布尔格街交易所（Bursa de Valori București，BVB）只读MCP服务器。它公开了BVB自己的公共后端——TradingView-UDF数据馈送（`wapi.bvb.ro`）和市场列表页面（`www.bvb.ro`）——作为MCP工具：仪器宇宙、符号搜索和元数据，以及OHLCV蜡烛图。
无需账户、无需API密钥、无需令牌：BVB后端是公共且无需身份验证的。每个工具都是只读的；这里没有任何交易功能。
## 功能
- 任意BVB股票代码或指数的OHLCV蜡烛图（`get_candles`），具有干净的`resolution`参数，隐藏了数据馈送的`1D`不是`D`的怪癖。
- 从交易所的市场列表页面抓取完整的仪器宇宙（`list_instruments`）——股票代码 + ISIN + 名称——以及指数宇宙（`list_indices`）。
- 数据馈送符号搜索（`search_symbol`）和每个符号的元数据（`get_symbol_info`），带有诊断信息（`server_time`，`datafeed_config`）。
- 每个请求都带有类似浏览器的`User-Agent`和`Referer: https://www.bvb.ro/`（防御性；无cookie，无令牌）。
- 在HTTP 429时自动重试一次，遵守`Retry-After`（上限为30秒）。
- 默认stdio传输，HTTP（`/mcp`）按需。
## 工具
所有工具都是只读的（无写入工具）：
| 工具 | 描述 |
|---|---|
| `list_instruments` | 列出市场的仪器宇宙（股票代码 + ISIN + 名称），通过抓取BVB市场列表页面。市场：`shares`，`bonds`，`fund-units`（ETFs），`warrants`，`certificates`（`structured`） |
| `list_indices` | 列出BVB指数宇宙（BET，BET-TR，BET-FI，ROTX，…） |
| `search_symbol` | 通过股票代码/名称进行数据馈送符号搜索（服务器上限约30个结果） |
| `get_symbol_info` | 将股票代码解析为其元数据：名称、类型、会话、时区、货币、部门/行业 |
| `get_candles` | 获取股票代码/指数的OHLCV蜡烛图，分钟/日/周/月分辨率 |
| `get_fundamentals` | 从详细页面抓取公司详细信息 + 估值快照：身份，Indicatori bursieri（市值，市盈率，市净率，每股收益，股息收益率，股息），发行信息和所有权结构 |
| `financial_summary` | 基础分析的“一键”捆绑：`get_fundamentals` + 价格摘要（最新收盘价，52周范围，1年/5年变化）。返回数据，而不是结论 |
| `server_time` | 数据馈送服务器时间（可达性检查） |
| `datafeed_config` | 数据馈送配置：仪器类型代码和支持的分辨率 |
### 数据表面说明
- **搜索有限。** `search_symbol`镜像数据馈送的搜索，返回广泛查询的约30个结果。使用`list_instruments`（或`list_indices`）枚举完整宇宙。
- **`1D`怪癖。** 数据馈送宣传裸`D`用于日线，但历史端点只接受`1D`（裸`D`返回HTTP 500）。`get_candles`采用友好的`resolution`（`1`，`5`，`15`，`30`，`60`，`1D`，`1W`，`1M`；`D`/`W`/`M`也被接受）并发送正确的代码。
- **指数元数据不完整。** `list_indices`始终返回每个指数的`symbol`，但`name`/`isin`仅为BVB渲染服务器端配置文件索引填充；其余通过客户端选项卡加载，返回`null`。
- **权利/结构。** BVB不发布独立的“权利”市场页面，“结构化产品”（数据馈送类型`T`）分布在`warrants`和`certificates`页面——`structured`被接受为`certificates`的别名。
- **无多年声明。** `get_fundamentals` / `financial_summary`公开BVB的当前快照（估值比率，股息，所有权）——BVB不发布结构化的多年收入/余额/现金流声明，因此无法提供完整的10年ROE/利润率/FCF记录。将`get_candles`与`client`（LLM）一起使用进行分析。
## 配置
所有配置均通过环境变量进行，所有配置均为可选——BVB后端不需要凭证。
| 变量 | 默认值 | 用途 |
|---|---|---|
| `BVB_DATAFEED_URL` | `https://wapi.bvb.ro` | 数据馈送基准URL |
| `BVB_WEB_URL` | `https://www.bvb.ro` | 市场列表站点基准URL |
| `BVB_MCP_USER_AGENT` | 类似Chrome的UA | 每个请求发送的`User-Agent` |
| `BVB_LANG` | `ro` | 数据馈送配置端点的语言 |
## 快速入门
使用[uv](https://docs.astral.sh/uv/)直接从存储库运行：
```bash
uvx --from git+https://github.com/florinel-chis/bvb-mcp bvb-mcp
```
服务器默认使用stdio通信；添加`--transport http --port 8000`以在`/mcp`上通过HTTP提供MCP服务。HTTP默认绑定到`127.0.0.1`，除非还传递`--allow-remote`，否则拒绝非环回`--host`——请在启用此标志之前阅读[安全](#安全)部分。
## MCP客户端配置
将服务器添加到MCP客户端的配置中（stdio，通过`uvx`）：
```json
{
"mcpServers": {
"bvb": {
"command": "uvx",
"args": ["--from", "git+https://github.com/florinel-chis/bvb-mcp", "bvb-mcp"]
}
}
}
```
或运行Docker镜像（首先构建它，参见下文）：
```json
{
"mcpServers": {
"bvb": {
"command": "docker",
"args": ["run", "-i", "--rm", "bvb-mcp"]
}
}
}
```
## Docker
一个小型（~200 MB）多阶段镜像，适用于MCP客户端可能使用的两种方式——通过**stdio**启动每个调用，或作为长期运行的**HTTP**服务器。两种路径都针对BVB的实时后端进行了验证。容器只需要出站网络即可访问`wapi.bvb.ro` / `www.bvb.ro`；无需凭证或卷。
**构建：**
```bash
docker build -t bvb-mcp .
```
**stdio** —— MCP客户端启动的内容（在上面的docker配置中使用`bvb-mcp`作为镜像名称）：
```bash
docker run -i --rm bvb-mcp
```
**HTTP** —— 在`http://127.0.0.1:8000/mcp/`上共享的长期服务器：
```bash
docker run --rm -p 127.0.0.1:8000:8000 bvb-mcp \
--transport http --host 0.0.0.0 --port 8000 --allow-remote
```
`--host 0.0.0.0`在容器内绑定，以便端口映射有效——这就是为什么需要`--allow-remote`；`-p`上的`127.0.0.1:`前缀使端点仅可从此计算机访问（它是未经身份验证的——参见安全）。如果主机端口8000被占用，请映射另一个端口，例如`-p 127.0.0.1:8010:8000`。
**无需注册** — 将镜像作为文件交给某人，他们可以`docker load`，无需Docker Hub / GHCR：
```bash
docker save bvb-mcp:latest | gzip > bvb-mcp.tar.gz # 你：导出
docker load < bvb-mcp.tar.gz # 他们：镜像现在是本地的
```
## 安全
- HTTP传输 **无身份验证** ：任何可以访问`/mcp`端点的人都可以调用每个工具。将其绑定到`127.0.0.1`（CLI默认值；使用Docker，发布为`-p 127.0.0.1:8000:8000`）或将其放在身份验证的反向代理后面。永远不要直接在公共网络上公开它。
- 所有工具都是只读的——此服务器无法下订单或转移资金。
- 自担风险。这里没有任何投资建议。
## 数据与条款
本服务器提供**代码，而不是数据**。它在请求时从BVB自己的公共后端获取数据，并返回BVB提供的内容。重新分发或以其他方式使用BVB价格数据受BVB条款和任何适用的市场数据许可的约束，并由运营者**自行负责**——软件对您存储、重新分发或交易其转发的数据的权利不做任何声明。
## 开发
```bash
uv sync
uv run pytest -q
uv run ruff check .
```
测试完全离线：HTTP被`respx` stubbed，对抗`tests/fixtures/`中捕获的BVB响应fixtures。
## 许可证
MIT
