内容
# Codal MCP
用于 [Codal](https://codal.ir) 公告的流式HTTP MCP服务器，通过BrsApi构建。 使用 **TypeScript + Bun** 构建。
支持 `Codal_API_Guide.md` 中的完整代理场景：
1. 接收新公告
2. 下载PDF
3. 提取文本
4. 总结
5. 提取EPS / 净利润 / 收入 / 资本增加 / 股息
6. 与以前的报告比较
7. 分析可能的股价影响
8. 将报告发送到Telegram或仪表板
传输方式：**仅支持流式HTTP** （不支持stdio / 旧版SSE服务器）。
## 设置
```bash
bun install
cp .env.example .env
# 设置 BRS_API_KEY=...
bun run start
```
健康检查： `GET http://127.0.0.1:3000/health`
MCP端点： `http://127.0.0.1:3000/mcp`
## 工具
| 工具 | 代理步骤 | 目的 |
| --- | --- | --- |
| `list_announcements` | 1 | 查询BrsApi的所有文档过滤器 |
| `download_pdf` | 2 | 下载 `link_pdf` → base64 |
| `extract_pdf_text` | 3 | PDF → 文本（URL或base64） |
| `summarize_announcement` | 4 | 启发式提取摘要 |
| `extract_financial_metrics` | 5 | 启发式EPS / 净利润 / 收入 / 资本增加 / 股息 |
| `get_previous_announcements` | 6 | 查询指定代码的先前公告（可选 `exclude_code`） |
| `compare_announcements` | 6 | 启发式当前与先前指标比较 |
| `analyze_price_impact` | 7 | 启发式影响分析（非投资建议） |
| `format_dashboard_report` | 8 | 结构化markdown/JSON报告（+可选webhook POST） |
| `send_telegram_report` | 8 | 向Telegram发送简报 |
| `list_category_codes` | — | 快速列出代码1-11 |
## 提示（LLM引导分析）
| 提示 | 代理步骤 |
| --- | --- |
| `summarize_announcement` | 4 |
| `extract_financial_metrics` | 5 |
| `compare_with_previous` | 6 |
| `analyze_price_impact` | 7 |
| `codal_agent_pipeline` | 全流程1-8编排 |
优先使用提示进行深度LLM分析；启发式工具是快速草稿。
## 资源（分类黑文档）
| URI | 内容 |
| --- | --- |
| `codal://categories` | 所有11个代码的索引 |
| `codal://categories/{1-11}` | 每个分类的详细黑文档 |
Markdown源文件位于 `src/resources/docs/`。
## Cursor / 客户端配置示例
```json
{
"mcpServers": {
"codal": {
"url": "http://127.0.0.1:3000/mcp"
}
}
}
```
## 测试
```bash
bun test
```
测试覆盖每个工具、每个分类资源和每个提示，通过进程内流式HTTP客户端（`handler.fetch`）。
## 环境变量
| 变量 | 是否必需 | 描述 |
| --- | --- | --- |
| `BRS_API_KEY` | 是（需要live API） | BrsApi密钥（也接受 `CODAL_API_KEY` 别名） |
| `PORT` | 否 | 默认 `3000` |
| `HOST` | 否 | 默认 `127.0.0.1` |
| `MCP_PATH` | 否 | 默认 `/mcp` |
| `TELEGRAM_BOT_TOKEN` | 否 | 用于 `send_telegram_report` |
| `TELEGRAM_CHAT_ID` | 否 | 默认聊天ID（可按调用覆盖） |
| `DASHBOARD_WEBHOOK_URL` | 否 | 用于 `format_dashboard_report` 且 `post=true` |
