Metadata-Version: 2.5
Name: friends-data-api
Version: 1.1.0
Summary: Typed CLI, async client, and MCP v2 server for Friends Data API
License: Proprietary
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<3,>=2
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: test
Requires-Dist: pytest-asyncio<2,>=0.24; extra == 'test'
Requires-Dist: pytest<10,>=8; extra == 'test'
Requires-Dist: ruff<1,>=0.12; extra == 'test'
Description-Content-Type: text/markdown

# Friends Data API client 1.0

Independent, read-only Python client, CLI, and MCP v2 server for
`https://api.alphahubs.uk`. It talks only to the public HTTPS API and does not
import WarrenHub internals or connect to ClickHouse, Redis, or AlphaHub.

```bash
python -m venv .venv
.venv/bin/pip install \
  https://api.alphahubs.uk/static/downloads/friends_data_api-1.1.0-py3-none-any.whl
export FRIENDS_DATA_API_KEY="fds_live_…"
friends-data list-datasets
friends-data search-instruments --query AAPL
friends-data-mcp
```

Configuration:

- `FRIENDS_DATA_API_KEY` — required; sent only as a Bearer header.
- `FRIENDS_DATA_API_URL` — optional; defaults to `https://api.alphahubs.uk`.
- `FRIENDS_DATA_API_TIMEOUT_SECONDS` — optional; defaults to `30`.

The CLI prints JSON to stdout. The MCP server reserves stdout for the stdio
protocol; diagnostics go to stderr through the SDK.

## CLI commands

```bash
friends-data list-datasets
friends-data search-instruments --query AAPL --limit 5
friends-data get-market-quotes AAPL MSFT
friends-data get-market-candles AAPL --timeframe 1D --limit 20
friends-data get-dataset-rows market ohlcv_1d \
  --filter instrument_id=1 --limit 100
friends-data get-point-in-time-rows fundamental income_statement \
  --as-of 2026-08-01 --filter instrument_id=1
friends-data get-sec-earnings-context --symbol AAPL --limit 20
```

Every command returns the public v1 list envelope unchanged, including
`request_id`, `meta.dataset`, `meta.as_of`, `has_more`, and `next_cursor`.
Pass `--cursor "$NEXT_CURSOR"` unchanged to either dataset-row command when
`has_more` is true. Generic rows default to descending order; PIT pages are
bounded to 1,000 rows.

## MCP host configuration

Install the wheel in a dedicated environment, then register its stdio command.
Codex CLI, desktop, and IDE share the same MCP configuration:

```bash
codex mcp add friends-data \
  --env FRIENDS_DATA_API_KEY="$FRIENDS_DATA_API_KEY" \
  -- /absolute/path/.venv/bin/friends-data-mcp
codex mcp list
```

The equivalent explicit `~/.codex/config.toml` entry is:

```toml
[mcp_servers.friends_data]
command = "/absolute/path/.venv/bin/friends-data-mcp"
env_vars = ["FRIENDS_DATA_API_KEY"]
```

Claude Code can register the same server at user scope:

```bash
claude mcp add --scope user \
  --env FRIENDS_DATA_API_KEY="$FRIENDS_DATA_API_KEY" \
  --transport stdio friends-data -- \
  /absolute/path/.venv/bin/friends-data-mcp
claude mcp get friends-data
```

The server exposes exactly seven read-only tools: `list_datasets`,
`search_instruments`, `get_market_quotes`, `get_market_candles`,
`get_dataset_rows`, `get_point_in_time_rows`, and
`get_sec_earnings_context`. All tools declare read-only, non-destructive,
idempotent, closed-world annotations.

The optional `query-friends-data` Skill installs at
`~/.agents/skills/query-friends-data/` for Codex or
`~/.claude/skills/query-friends-data/` for Claude Code. Complete copy-ready
instructions live at `https://api.alphahubs.uk/api/docs#skills`.
