# ashareport

ashareport exposes nine A-share (China mainland) stock-data tools —
history, realtime quotes, news, balance sheet, income statement, cash
flow, inner trades, and financial metrics, plus a local time tool — as
a command line program and as a stdio MCP server.

## How the data tools work (read this first)

The original design runs a Python market-data library in-process. This
TypeScript rebuild uses an **endpoint executor** instead: set

```bash
export ASHAREPORT_API_URL="https://your-data-endpoint.example"
```

and each data tool POSTs JSON `{tool, source, params}` to
`{ASHAREPORT_API_URL}/<tool>` and returns the endpoint's JSON answer.
With the variable unset, data tools return an error:
`upstream data endpoint not configured: set ASHAREPORT_API_URL ...`.
`get_time_info` is fully local and needs no endpoint.

Source fallback is implemented locally, in the documented order:

| Domain | Source order |
| --- | --- |
| historical | eastmoney → eastmoney_direct → sina → ths |
| realtime | eastmoney_direct → eastmoney → xueqiu → ths (xueqiu/ths skipped when no symbol is given) |
| news | eastmoney → ths |
| statements / metrics | sina → eastmoney_direct |

The requested source is tried first, then the domain order when
`fallback` is not `false`, stopping at the first non-empty result. If
every source fails, the error lists each source and its error.
Defaults: `interval` `day`, `adjust` `none`, `recent_n` 100 for
historical data and 10 for the other recent-N tools.

`indicators_list` is passed through to the endpoint, not computed
locally. `get_time_info` walks back from today skipping Saturday and
Sunday to find the last trading day; exchange holidays are not
modelled.

## Install

```bash
npx @reneturcios/ashareport get_time_info
docker run -i ghcr.io/cloudcorprecords/ashareport   # MCP server
```

## CLI

```bash
ashareport get_hist_data --symbol 600519 --interval day --recent-n 20
ashareport get_realtime_data --symbol 600519
ashareport get_realtime_data            # market-wide, symbol optional
ashareport get_news_data --symbol 600519
ashareport get_balance_sheet --symbol 600519
ashareport get_income_statement --symbol 600519
ashareport get_cash_flow --symbol 600519
ashareport get_inner_trade_data --symbol 600519
ashareport get_financial_metrics --symbol 600519
ashareport get_time_info
ashareport --version
```

Exit codes: `0` success, `1` tool error, `2` usage error.

## MCP server

```bash
npx -y @reneturcios/ashareport mcp
```

```json
{
  "mcpServers": {
    "ashareport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/ashareport", "mcp"],
      "env": { "ASHAREPORT_API_URL": "https://your-data-endpoint.example" }
    }
  }
}
```

### Tools

| Tool | Required | Other parameters |
| --- | --- | --- |
| `get_hist_data` | `symbol` | `interval`, `interval_multiplier`, `start_date`, `end_date`, `adjust`, `source`, `fallback`, `indicators_list`, `recent_n` |
| `get_realtime_data` | — (`symbol` optional) | `source`, `fallback` |
| `get_news_data` | `symbol` | `source`, `fallback`, `recent_n` |
| `get_balance_sheet` | `symbol` | `source`, `fallback`, `recent_n` |
| `get_income_statement` | `symbol` | `source`, `fallback`, `recent_n` |
| `get_cash_flow` | `symbol` | `source`, `fallback`, `recent_n` |
| `get_inner_trade_data` | `symbol` | — |
| `get_financial_metrics` | `symbol` | `source`, `fallback`, `recent_n` |
| `get_time_info` | — | — (local: ISO time, Unix timestamp, last trading day) |

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner, fake-fetch only, no network
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.