TSETMC History MCP

Streamable HTTP MCP server for TSETMC historical market data via BrsApi. Built with TypeScript + Bun.

Twin of 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.

Setup

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

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

Tests

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