ko-finder-mcp

# ko-finder-mcp MCP server for searching German exchange-listed **knock-out certificates** (Turbos, Open-End-Turbos, Mini Futures, KO-Scheine). Data sources, in priority order: 1. **Börse Frankfurt** undocumented JSON API (`api.boerse-frankfurt.de/v1/search/`) — full market, salt-MD5 auth scraped from `main.<hash>.js` (technique borrowed from [joqueka/bf4py](https://github.com/joqueka/bf4py)). 2. **onvista** Derivate-Finder (`api.onvista.de/api/v1/derivatives/finder/configuration_query`) — fallback / cross-source verification. Both upstreams cover every issuer with German KO listings (HSBC, SG, BNP, Citi, Vontobel, DZ, GS, JPM, UniCredit, Morgan Stanley, Deutsche Bank, …), so no per-issuer integration is needed. > ⚠️ Both upstream APIs are undocumented. Endpoints may change without notice; quotes are typically delayed ~15 min; redistribute the data only for personal use. Knock-Out certificates carry total-loss risk once the barrier is breached. ## Install ```bash uv venv .venv --python 3.13 uv pip install --python .venv/bin/python -e . ``` ## Run (stdio) ```bash .venv/bin/ko-finder-mcp ``` ## Wire into Claude Code ```bash claude mcp add --scope user ko-finder /absolute/path/to/.venv/bin/ko-finder-mcp ``` Restart your terminal — every new Claude Code session will see the server. ## Tools | Tool | Purpose | | --- | --- | | `search_ko_certificates` | Filter by underlying / issuer / direction (Long vs Short) / Hebel / KO-barrier / open-end vs fixed maturity. Returns normalized rows with bid/ask, pre-computed `spread_abs` and `spread_pct`, plus `direction_inferred` + `direction_source` (derived from KO-vs-strike geometry when the name omits a token). | | `get_ko_details` | Full master data for a single ISIN — Greeks, implied vol, premium, currency, maturity. | | `list_issuers` | Curated issuer registry (slug → display name → onvista ID), all 12 IDs verified live. | | `search_underlyings` | Resolve a free-text underlying (e.g. "DAX") to onvista entityValue + WKN/ISIN. | ### Presentation contract The tool docstrings instruct calling agents to render results as a Markdown table that includes — at minimum — **WKN, Issuer, Direction, Strike, KO-Barriere, Leverage, Bid, Ask, Spread€, Spread%**. The Issuer column must not be dropped even when every row shares one issuer. ### Direction inference Many issuers (notably BNP's "Unlimited Turbo Optionsschein auf …") omit Call/Put/Long/Short from the product name. The server then falls back to **KO-vs-strike geometry**: - `KO > strike` ⇒ LONG (Mini-Future financing line below current price, KO above it) - `KO < strike` ⇒ SHORT Source is reported in `direction_source` (`exercise_right` | `name` | `ko_vs_strike`) so the consumer knows how trustworthy the value is. ## Tests ```bash .venv/bin/python -m pytest tests/ -v ``` Live tests hit real upstreams; MCP-protocol tests spawn the server as a subprocess and exercise the full stdio round-trip. The spread/direction test uses the BNP Alfa-Laval book as a torture case (names without Call/Put tokens, mixed Unlimited Turbos and Mini Futures). ## Layout ``` shared/ bf_client.py Async Börse Frankfurt client (salt-signed) onvista_client.py Async onvista finder client onvista_resolver.py ISIN/free-text → onvista entityValue resolver normalize.py → unified `Derivative` model (with direction inference) models.py Issuer registry + Derivative schema ko_finder_mcp/server.py FastMCP server, KO-certificate tools tests/ Live + MCP-protocol smoke tests ``` ## License **[PolyForm Noncommercial License 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/)** — free to use, copy, modify and share for any **noncommercial** purpose (personal trading, research, hobby projects, education, charities, government). **Commercial use requires a separate license — please contact the author** ([@Makki93](https://github.com/Makki93)) to discuss terms. The Börse Frankfurt client (`shared/bf_client.py`) is derived from [joqueka/bf4py](https://github.com/joqueka/bf4py) and remains usable under that project's MIT terms for the derived portions — see [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md) for the full notice.