内容
# 管道股票分析
可自行托管的、只读的金融市场 **MCP（模型上下文协议，AI 客户端调用外部工具的标准）** 服务器，适用于台湾上市证券和全球股票。它检索市场数据并计算可重复的指标；它不做出投资决策或进行交易。
[繁體中文](README.zh-TW.md)
## 为什么存在该仓库
运行您自己的实例。该项目 **不** 将其他人路由到维护者的服务器，不捆绑 API 凭证，不需要 OpenConnector，也不需要托管帐户。
- 公共默认调用 FinMind 和 Finnhub，直接使用您本地的 `.env` 中的凭证。
- FinMind 是可选的，支持匿名访问，但限制较低。Finnhub 支持的工具需要您自己的 API 密钥。
- 高级部署可以选择 OpenConnector 适配器，以便在此过程中仅保留一个狭窄的运行时令牌。
- `.env`、OAuth 状态、私钥、SQLite 数据库和生成的凭证被 Git 忽略。
## 三步自我托管
```bash
# 1. 克隆
git clone https://github.com/Gratia2533/pipe-stock-analysis.git && cd pipe-stock-analysis
# 2. 创建本地配置；可选地添加 FINMIND_TOKEN / FINNHUB_API_KEY
cp .env.example .env
# 3. 在标准 Docker 桥接网络上使用默认 Direct 适配器启动
docker compose up -d --build
```
要输入 Finnhub API 密钥而不将其暴露在 shell 历史记录中，请使用交互式帮助程序并选择是否重启服务：
```bash
./scripts/set-finnhub-key.sh
```
验证两个本地服务：
```bash
curl http://127.0.0.1:8010/healthz
curl http://127.0.0.1:8011/healthz
```
- 内部 MCP，无 OAuth：`http://127.0.0.1:8010/mcp`
- 受 OAuth 保护的 MCP：`http://127.0.0.1:8011/mcp`
这两个端点仅在 `127.0.0.1` 上发布。保持端口 8010 私有；仅通过公共 HTTPS 反向代理或隧道公开端口 8011。
## 数据后端
### Direct（默认）
```dotenv
DATA_BACKEND=direct
FINMIND_TOKEN=
FINNHUB_API_KEY=
```
服务在没有任一可选凭证的情况下启动，因此 TWSE、TPEx、MOPS、新闻和确定性分析仍然可用。FinMind 在其令牌为空时使用匿名限制。Finnhub 工具仅在没有 `FINNHUB_API_KEY` 调用时报告配置错误。
### OpenConnector（高级，Linux/WSL）
在已经公开了精选的 FinMind 和 Finnhub 操作的专用 OpenConnector 可用时使用此模式。高级 Compose 仅注入其运行时令牌；上游凭证保留在 OpenConnector 的加密凭证存储中。为了实现故障隔离，`FINMIND_TOKEN` 和 `FINNHUB_API_KEY` 在此模式下必须取消设置。
```dotenv
DATA_BACKEND=openconnector
OPEN_CONNECTOR_BASE_URL=http://127.0.0.1:8001
OPEN_CONNECTOR_RUNTIME_TOKEN=您的本地运行时令牌
```
由于桥接容器无法访问绑定到主机回环的连接器，高级 Compose 文件故意在 Linux/WSL 主机网络上使用，而两个服务仍然绑定到 `127.0.0.1`：
```bash
docker compose -f compose.openconnector.yaml up -d --build
```
Direct 和 OpenConnector 模式使用相同的 MCP 工具和分析代码。OpenConnector 是一个适配器，而不是一个单独的分支或仓库。
## 工具
- 使用 FinMind → TWSE 备用历史价格
- 最新 TWSE / TPEx 官方收盘报价
- TWSE 市场和行业指数、ETF 排名、上市/IPO 流水线和交易日历
- 估值、月度收入、机构资金流、财务报告、保证金交易
- MOPS 重大公告和近期新闻
- 确定性技术、基本面、财务健康、机构资金流和保证金摘要
- Finnhub 全球符号搜索、报价、蜡烛图、公司简介、财务指标、报告声明和公司新闻
## 本地开发
需要 Python 3.11+ 和 [uv](https://docs.astral.sh/uv/)。
```bash
cp .env.example .env
uv sync --dev
set -a; source .env; set +a
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 uv run finance-mcp
```
适用于同一主机上的_stdio 客户端：
```bash
MCP_TRANSPORT=stdio uv run finance-mcp
```
## Hermes 配置
适用于本地 HTTP 部署：
```bash
hermes mcp add pipe-stock-analysis --url http://127.0.0.1:8010/mcp
hermes mcp test pipe-stock-analysis
```
适用于 stdio，请将您的 MCP 客户端指向 `uv run finance-mcp`，从此存储库中。 在您自己的本地客户端配置中配置命令及其环境； 永远不要将令牌提交到此存储库中。
## 分析技能
可重用的跨市场 Hermes 分析工作流程包含在 [`skills/stock-analysis/SKILL.md`](skills/stock-analysis/SKILL.md) 中。直接从原始 GitHub URL 安装：
```bash
hermes skills install https://raw.githubusercontent.com/Gratia2533/pipe-stock-analysis/main/skills/stock-analysis/SKILL.md
```
## OAuth 部署
Compose 在端口 8011 上启动一个单独的受 OAuth 保护的实例，同时将端口 8010 实例留给受信任的本地客户端使用。为公共部署设置 `FINANCE_OAUTH_ISSUER_URL`、`FINANCE_OAUTH_RESOURCE_URL`、`FINANCE_OAUTH_USERNAME` 和 `FINANCE_OAUTH_PASSWORD`。OAuth 运行时数据存储在持久的私有卷中，并被 `.gitignore` 排除。
发行者和资源 URL 必须使用与转发到 `127.0.0.1:8011` 的同一个公共 HTTPS 主机名。
## 验证
```bash
uv run ruff check .
uv run pytest -q
```
## 范围和免责声明
- 仅限只读数据和确定性计算。
- 无订单、经纪账户、投资组合访问或个性化投资建议。
- 数据可用性、延迟和准确性取决于上游提供商。请独立验证材料信息。
- 这是软件，而不是投资建议。
## 参考和灵感
- [FinMind](https://github.com/FinMind/FinMind/tree/master)：可选的 FinMind 市场数据集成背后的上游开源项目。此存储库不提供 FinMind 代码或凭证。
- [Finnhub](https://finnhub.io/)：全球股票数据的可选上游提供商。端点可用性取决于用户 的 Finnhub 计划。
- [TradingAgents](https://github.com/TauricResearch/TradingAgents)：基于角色的研究工作流的概念参考。此服务器故意将数据检索和确定性计算与代理编排和投资决策分开。
## 许可证
[MIT](LICENSE)
