# Finance News MCP Server

Ein **Model Context Protocol (MCP) Server** für Finanznachrichten, der echte Nachrichten von NewsAPI abruft und strukturierte, zusammengefasste Antworten liefert.

## Features

- 🔍 **Nachrichtensuche**: Volltextsuche über Finanznachrichten
- 📰 **Top Headlines**: Aktuelle Schlagzeilen nach Land und Kategorie
- 📡 **Quellenverzeichnis**: Liste der verfügbaren News-Quellen
- 📊 **Strukturierte Output**: JSON mit Bullet-Points und Zusammenfassungen

---

## Schnellstart

### 1. Virtualenv + Abhängigkeiten

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

**macOS/Linux-Spezifika:**
- Falls `python` nicht existiert, nutze `python3`
- `source` für Bash/Zsh (nicht Windows PowerShell)

### 2. .env Datei erstellen

```bash
cp .env.example .env
```

Öffne `.env` und trage deine **NewsAPI** Credentials ein:

```
NEWS_API_KEY=dein_api_key_von_newsapi_org
```

[NewsAPI Key besorgen](https://newsapi.org/register) (kostenlos mit täglichem Limit).

### 3. Server starten

```bash
python mcp_server.py
```

Erwartet einen MCP-Client, der über STDIO Anfragen sendet.

---

## Testing & Debugging

### Option A: Direkt die Handler testen

Führe die Handler-Funktionen direkt auf, ohne STDIO zu nutzen:

```bash
python test_handlers.py
```

**Nützlich für:**
- Schnelle Funktionstests
- Debugging ohne External-Dependencies
- API-Antworten prüfen

### Option B: Mit dem STDIO-Client testen

Starte den Server als Unterprozess und kommuniziere per JSON-RPC:

```bash
python stdio_client.py
```

**Beispiele mit verschiedenen Parametern:**

```bash
# Standard-Ausführung (Apple earnings, US, englisch, 3 Ergebnisse)
python stdio_client.py

# Andere Suchanfrage
python stdio_client.py --search "Tesla stock"

# Mit Land und Sprache
python stdio_client.py --search "Fed interest rate" --country gb --language de

# Mehr Ergebnisse
python stdio_client.py --country us --page-size 10

# Deutsche Quellen
python stdio_client.py --language de --country de

# Bitcoin News aus Großbritannien
python stdio_client.py --search "Bitcoin" --country gb

# Hilfe anzeigen
python stdio_client.py --help
```

---

## STDIO Client Parameter

Der `stdio_client.py` akzeptiert folgende Argumente:

| Parameter | Typ | Default | Beispiel | Beschreibung |
|-----------|-----|---------|----------|-------------|
| `--search` | text | "Apple earnings" | `--search "Tesla"` | Suchanfrage für Finanznachrichten |
| `--country` | text | "us" | `--country gb` | Ländercode (ISO 3166-1 alpha-2) für Headlines |
| `--language` | text | "en" | `--language de` | Sprachcode (ISO 639-1) für Quellen |
| `--page-size` | integer | 3 | `--page-size 10` | Anzahl Ergebnisse (1-50) |

### Wie der Parser funktioniert

Der `argparse.ArgumentParser` in `stdio_client.py` verarbeitet Kommandozeilen-Argumente:

```python
parser.add_argument("--search", type=str, default=None, 
                    help='Search query for finance news')
```

Das bedeutet:
- `--search` ist der Schalter
- `type=str` erwartet einen Text-String
- `default=None` = wenn nicht angegeben, ist der Wert `None`
- In `main()` wird mit `or` ein Fallback-Wert gesetzt

**Praktisch:**
```bash
# Mit Argumenten
python stdio_client.py --search "Bitcoin" --country de

# Ohne Argumente
python stdio_client.py  # nutzt alle Defaults
```

---

## Response-Struktur

Typische Antwort bei `search_finance_news`:

```json
{
  "metadata": {
    "query": "Apple earnings",
    "language": "en",
    "sort_by": "publishedAt",
    "total_results": 5
  },
  "articles": [
    {
      "title": "Apple Q2 Earnings Beat Expectations",
      "source": "Bloomberg",
      "url": "https://...",
      "published_at": "2026-05-30T14:00:00Z",
      "summary": "• Apple beat earnings estimates\n• Revenue up 12% YoY\n• Services segment grew 15%",
      "key_points": [
        "Apple beat earnings estimates",
        "Revenue up 12% YoY",
        "Services segment grew 15%"
      ]
    }
  ]
}
```

---

## Tools

Der Server implementiert 3 MCP-Tools:

### 1. search_finance_news
Volltextsuche über Finanznachrichten.

**Parameter:**
- `query` (erforderlich): Suchanfrage, z.B. "Apple earnings", "Fed rate", "Bitcoin"
- `language` (optional): ISO 639-1 Code (default: "en")
- `page_size` (optional): 1-50 (default: 5)
- `sort_by` (optional): "relevancy", "popularity", "publishedAt" (default: "publishedAt")

### 2. get_top_finance_headlines
Aktuelle Top-Headlines nach Land/Kategorie.

**Parameter:**
- `country` (optional): ISO 3166-1 alpha-2 Code, z.B. "us", "gb", "de"
- `category` (optional): "business", "technology", etc. (default: "business")
- `page_size` (optional): 1-50 (default: 5)

### 3. get_finance_sources
Liste der verfügbaren Nachrichtenquellen.

**Parameter:**
- `language` (optional): ISO 639-1 Code
- `country` (optional): ISO 3166-1 Code
- `category` (optional): Nachrichtenkategorie

---

## Projektstruktur

```
mcp_server/
├── mcp_server.py          # MCP Server (Haupt-Einstiegspunkt)
├── stdio_client.py        # Test-Client mit Kommandozeilen-Args
├── test_handlers.py       # Direkte Handler-Tests (ohne STDIO)
├── test_news_api.py       # Debug-Skript für NewsAPI
├── news_client.py         # NewsAPI HTTP-Client
├── models.py              # Pydantic Modelle für Validierung
├── summarizer.py          # Artikel→Bullet-Points Transformation
├── config.py              # Konfiguration (Env Vars)
├── pyproject.toml         # Package-Metadaten & Dependencies
├── .env.example           # Beispiel Env-Datei
└── README.md              # Diese Datei
```

---

## Beispiel-Kommandos

```bash
# Nachrichten zu Tesla suchen
python stdio_client.py --search "Tesla" --page-size 5

# Top Headlines Großbritannien
python stdio_client.py --country gb --page-size 10

# Fed & Zinsen (mit Deutsche Quellen)
python stdio_client.py --search "Federal Reserve" --language de

# Kryptowährungen weltweit
python stdio_client.py --search "Bitcoin crypto" --page-size 15

# Test aller Tools auf einmal
python stdio_client.py
```

---

## Lizenz & Credits

- **NewsAPI**: [newsapi.org](https://newsapi.org)
- **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io/)
- **FastAPI/Pydantic**: Type-safe Python