# Finviz MCP

MCP-palvelin, joka antaa Claudelle (tai millä tahansa MCP-asiakkaalle) pääsyn Finviz-osakedataan: yhden osakkeen tunnusluvut, uutiset ja screener-haut, sekä oikeaan historialliseen hintadataan (Yahoo Finance). Data haetaan livenä `finvizfinance`- ja `yfinance`-kirjastoilla, eli mitään API-avaimia ei tarvita.

## Työkalut

- **`get_stock(ticker)`** – yhden osakkeen Finviz-tunnusluvut (P/E, market cap, marginaalit, tuotot jne.)
- **`get_stock_news(ticker)`** – osakkeen viimeaikaiset uutisotsikot
- **`get_price_history(ticker, days=7)`** – oikea päivätason historiadata (Open/High/Low/Close/Volume) Yahoo Financesta enintään 365 päivän ajalta, plus valmis analyysi siitä mikä päivä olisi ollut paras ostopäivä (alin hinta ja paras tuotto viimeisimpään päätöskurssiin verrattuna). Finvizillä itsellään ei ole historiadata-API:a, vain nykyhetken snapshot ja staattinen chart-kuva.
- **`screen_stocks(...)`** – Finviz-screener luonnollisilla parametreilla (`market_cap`, `sector`, `pe_max`, `rsi`, `dividend_yield_min`, `signal`, ...). Claudelle ei tarvitse selittää Finvizin sisäisiä suodatinnimiä – palvelin kääntää parametrit automaattisesti lähimpään Finvizin tukemaan arvoon. **Toimii vain paikallisesti ajettuna, ei julkaistuna pilvipalvelimella** – ks. Rajoitukset.
- **`list_screener_filters(search=None)`** / **`list_screener_signals()`** – apuvälineitä Claudelle, jos se tarvitsee jonkin suodattimen jota `screen_stocks` ei vielä kata nimetyllä parametrilla. Löydetyn arvon voi antaa `screen_stocks(extra_filters={...})`-parametrina.

`screen_stocks`-parametrit napsahtavat aina lähimpään Finvizin tarjoamaan "koriin" (esim. `pe_max=18` → "Under 20"), koska Finvizin screener tukee vain valmiita arvovälejä, ei mielivaltaisia lukuja.

## 1. Paikallinen testaus

Vaatii Python 3.10+:

```bash
pip install -r requirements.txt
python server.py
```

Palvelin käynnistyy osoitteeseen `http://localhost:8000/mcp` (Streamable HTTP).

> Testattu päästä päähän tässä ympäristössä (asennus, käynnistys, `initialize`-kättely ja kaikki viisi työkalua oikealla Finviz-datalla). Testauksen aikana kävi ilmi, että PyPI:n `finvizfinance` 1.3.0 ei ollut vielä ajan tasalla Finvizin uudistuneen sivupohjan kanssa: `get_stock` kaatui kokonaan (vanha `quote-links`-CSS-luokka on nyt `quote-header_categories`, eri sisällöllä), ja `screen_stocks`:n Ticker-sarakkeessa oli ylimääräinen alkukirjain (esim. "NVDA" → "NNVDA", Finvizin uudesta logon paikkamerkistä). `server.py` korjaa molemmat suoraan (ks. tiedoston yläosan kommentti) – jos Finviz muuttaa sivuaan taas, näihin korjauksiin kannattaa palata ensimmäisenä.

Jos Python ei ole koneella mutta Docker on, voit testata ilman paikallista Python-asennusta:

```bash
docker build -t finviz-mcp .
docker run -p 8000:8000 finviz-mcp
```

Nopea toimivuustesti komentoriviltä (vaatii `curl`in ja että palvelin on käynnissä):

```bash
curl -X POST http://localhost:8000/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}"
```

Vastauksessa pitäisi näkyä kuusi työkalua: `get_stock`, `get_stock_news`, `get_price_history`, `screen_stocks`, `list_screener_filters`, `list_screener_signals`.

## 2. Julkaisu (esim. Render)

1. Työnnä tämä kansio omaan Git-repoosi (GitHub/GitLab).
2. Render → **New +** → **Web Service** → yhdistä repo.
3. Render tunnistaa `Dockerfile`:n automaattisesti. Erillisiä ympäristömuuttujia ei tarvita – palvelin lukee portin Renderin asettamasta `PORT`-muuttujasta.
4. Julkaisun jälkeen saat osoitteen kuten `https://finviz-mcp.onrender.com`. MCP-endpoint on tämän perässä `/mcp`, eli: `https://finviz-mcp.onrender.com/mcp`.

Railway, Fly.io tms. toimivat samalla periaatteella (Dockerfile-pohjainen Python-hosting, `PORT`-ympäristömuuttuja).

## 3. Yhdistäminen Claudeen

Claude → **Settings** → **Connectors** → **Add custom connector** → liitä MCP-URL (`https://<oma-osoite>/mcp`).

Claude tukee remote MCP -palvelimia Streamable HTTP:n kautta, joten tämä toimii sellaisenaan.

## 4. Esimerkkikehotteet

- "Get me the Finviz fundamentals for NVDA."
- "Find oversold technology stocks with market cap over $10B."
- "Show me 15 large-cap dividend stocks with yield over 4% and P/E under 20."
- "What's the latest news on TSLA?"
- "Find stocks flagged as Top Gainers today with average volume over 1M."

## Rajoitukset

- **`screen_stocks` (ja `list_screener_filters`/`list_screener_signals`) ei toimi julkaistuna pilvipalvelimella** (testattu Renderissä): Finviz palauttaa 403 Forbidden nimenomaan screener-endpointille (`finviz.com/screener.ashx`) datakeskus-IP-osoitteista, vaikka `get_stock`/`get_stock_news`/`get_price_history` toimivat samasta palvelimesta täysin normaalisti (ne käyttävät eri, vähemmän suojattuja endpointteja). Tätä ei saanut korjattua HTTP-otsikoita säätämällä – vaikuttaa olevan Finvizin oma, tarkoituksellinen datakeskus-IP-esto juuri screenerille. Jos tarvitset `screen_stocks`-toimintoa, aja palvelin paikallisesti (`python server.py`) ja yhdistä siihen esim. `cloudflared`/`ngrok`-tunnelilla, jolloin pyynnöt lähtevät kotiverkkosi IP:stä.
- Data skreipataan Finvizin/Yahoo Financen verkkosivuilta (ei virallisia API-avaimia), joten se voi hajota jos ne muuttavat sivujensa rakennetta.
- `screen_stocks` rajaa tulokset oletuksena 20:een ja enintään 50:een riviin, jotta pyyntö pysyy nopeana.
- `get_price_history` rajaa `days`-parametrin enintään 365:een.
- Ei sisällä autentikointia – jos palvelu on julkisesti internetissä, kuka tahansa URL:n tietävä voi kutsua sitä. Data on julkista, mutta pidä tämä mielessä jos lisäät myöhemmin maksullisia/rajoitettuja ominaisuuksia.