# TSETMC History MCP

Streamable HTTP MCP server for [TSETMC historical market data](https://brsapi.ir/bourse-api-history-webservice/) via BrsApi. Built with **TypeScript + Bun**.

Twin of [Codal-MCP](https://github.com/mohammad-k13/Codal-MCP): same transport, packaging, and test style.

Supports:

1. Price & trade daily history (`History.php` `type=0`)
2. Retail / institutional daily history (`type=1`)
3. Field documentation as MCP resources
4. Analysis prompts (trend + money flow + full pipeline)

Transport: **Streamable HTTP only** (no stdio / legacy SSE server).

For a full onboarding walkthrough of the API and this repo, read **[History_API_Guide.md](./History_API_Guide.md)**.

## 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 | Upstream | Purpose |
| --- | --- | --- |
| `get_price_history` | `type=0` | Daily price/trade bars (`date`, `tvol`, `pc`, …) |
| `get_client_type_history` | `type=1` | Daily حقیقی/حقوقی counts, volumes, values |
| `list_history_fields` | local | Catalog of both modes and field names |

Both history tools accept `l18` plus optional `date_start` / `date_end` (client-side filter).

## Prompts

| Prompt | Purpose |
| --- | --- |
| `analyze_price_trend` | Analyze price/trade JSON |
| `analyze_money_flow` | Analyze retail vs institutional JSON |
| `history_agent_pipeline` | End-to-end fetch + analyze checklist |

## Resources

| URI | Content |
| --- | --- |
| `history://fields` | Index of modes |
| `history://fields/price` | Type 0 field black doc |
| `history://fields/client-type` | Type 1 field black doc |

Markdown sources live in `src/resources/docs/`.

## Cursor / client config example

```json
{
  "mcpServers": {
    "tsetmc-history": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```

## Tests

```bash
bun test
```

Tests cover every tool, field resource, and prompt via an in-process Streamable HTTP client (`handler.fetch`). No live API key required.

## Env

| Variable | Required | Description |
| --- | --- | --- |
| `BRS_API_KEY` | yes (live API) | BrsApi key (`HISTORY_API_KEY` alias also accepted) |
| `PORT` | no | Default `3000` |
| `HOST` | no | Default `127.0.0.1` |
| `MCP_PATH` | no | Default `/mcp` |