Content
# Codal MCP
Streamable HTTP MCP server for [Codal](https://codal.ir) announcements via BrsApi. Built with **TypeScript + Bun**.
Supports the full agent scenario from `Codal_API_Guide.md`:
1. Receive new announcements
2. Download PDF
3. Extract text
4. Summarize
5. Extract EPS / net profit / revenue / capital increase / dividend
6. Compare with previous reports
7. Analyze likely price impact
8. Send report to Telegram or dashboard
Transport: **Streamable HTTP only** (no stdio / legacy SSE server).
## Setup
```bash
bun install
cp .env.example .env
# set BRS_API_KEY=...
bun run start
```
Health: `GET http://127.0.0.1:3000/health`
MCP endpoint: `http://127.0.0.1:3000/mcp`
## Tools
| Tool | Agent step | Purpose |
| --- | --- | --- |
| `list_announcements` | 1 | Query BrsApi with all documented filters |
| `download_pdf` | 2 | Download `link_pdf` → base64 |
| `extract_pdf_text` | 3 | PDF → text (URL or base64) |
| `summarize_announcement` | 4 | Heuristic extractive summary |
| `extract_financial_metrics` | 5 | Heuristic EPS / سود خالص / درآمد / افزایش سرمایه / تقسیم سود |
| `get_previous_announcements` | 6 | Prior filings for a symbol (optional `exclude_code`) |
| `compare_announcements` | 6 | Heuristic current vs previous metrics |
| `analyze_price_impact` | 7 | Heuristic impact (not advice) |
| `format_dashboard_report` | 8 | Structured markdown/JSON report (+ optional webhook POST) |
| `send_telegram_report` | 8 | Send brief to Telegram |
| `list_category_codes` | — | Quick list of codes 1–11 |
## Prompts (LLM-led analysis)
| Prompt | Agent step |
| --- | --- |
| `summarize_announcement` | 4 |
| `extract_financial_metrics` | 5 |
| `compare_with_previous` | 6 |
| `analyze_price_impact` | 7 |
| `codal_agent_pipeline` | Full 1–8 orchestration |
Prefer prompts for deep LLM analysis; heuristic tools are fast drafts.
## Resources (category black docs)
| URI | Content |
| --- | --- |
| `codal://categories` | Index of all 11 codes |
| `codal://categories/{1-11}` | Detailed black docs per category |
Markdown sources live in `src/resources/docs/`.
## Cursor / client config example
```json
{
"mcpServers": {
"codal": {
"url": "http://127.0.0.1:3000/mcp"
}
}
}
```
## Tests
```bash
bun test
```
Tests cover every tool, every category resource, and every prompt via an in-process Streamable HTTP client (`handler.fetch`).
## Env
| Variable | Required | Description |
| --- | --- | --- |
| `BRS_API_KEY` | yes (live API) | BrsApi key (`CODAL_API_KEY` alias also accepted) |
| `PORT` | no | Default `3000` |
| `HOST` | no | Default `127.0.0.1` |
| `MCP_PATH` | no | Default `/mcp` |
| `TELEGRAM_BOT_TOKEN` | no | For `send_telegram_report` |
| `TELEGRAM_CHAT_ID` | no | Default chat id (overridable per call) |
| `DASHBOARD_WEBHOOK_URL` | no | For `format_dashboard_report` with `post=true` |
