MCP-gestützter Finanzanalyst

Ein lokaler KI-Finanzanalyst, der auf einem echten MCP-Server (Model Context Protocol) basiert. Statt dass ein einzelner Chatbot Aktientrends errät, arbeiten zwei Agenten zusammen:

• Validator-Agent – prüft Daten aus dem Internet (Yahoo Finance, News-APIs) auf Lücken, fehlerhafte Werte oder Ticker-Mismatches, bevor etwas an das LLM gelangt.

• Analyst-Agent – analysiert die validierten Daten und die Ausgaben der MCP-Tools, um eine strukturierte Zusammenfassung zu erstellen (Trend, gleitende Mittelwerte, Volatilität und relevante Nachrichtenstimmung).

Beide Agenten rufen Tools auf, die von einem eigenen MCP-Server bereitgestellt werden – das ist der Kern des Projekts, nicht nur LangChain-Klebe-Code.

Was ich über eine einfache Tutorial-Version hinaus hinzugefügt habe

• Zwei-Agenten-Aufteilung (Validator → Analyst) statt eines einzelnen Agenten, der alles erledigt

• Ein echter MCP-Server mit 3 Tools, einschließlich Validierung als eigenem Tool

• LangSmith-Tracing für beide Agenten

• Neon-Postgres-Caching-Schicht (vermeidet erneutes Aufrufen von APIs mit Ratenbegrenzung)

• Eine kleine Evaluations-Suite mit handberechneten Ground-Truth-Werten

• Eine bereitgestellte Web-App (FastAPI auf Render, statisches Frontend auf Vercel)

Related MCP server: MonteWalk

Architektur

User query (ticker + date range)
        │
        ▼
  Validator agent ──calls──▶ MCP server ──▶ fetch_price_data (Yahoo Finance)
        │                                 ▶ validate_data
        │  (retries once on bad data)
        ▼
  Analyst agent ──calls──▶ MCP server ──▶ analyze_chart (moving averages, volatility)
        │                                ▶ get_news_sentiment
        ▼
  Structured summary + chart data → FastAPI → frontend

Projektstruktur

backend/
  mcp_server/          # the MCP server + its 3 tools (this is the centerpiece)
  agents/               # Validator agent, Analyst agent
  orchestration/         # LangGraph wiring: Validator -> Analyst
  db/                    # Neon Postgres cache + eval result storage
  evals/                 # hand-checked test cases + eval runner
  main.py                # FastAPI app, deployed on Render
frontend/
  index.html             # single-page UI, deployed on Vercel
  vercel.json
render.yaml               # Render deployment config for the backend
requirements.txt
.env.example

Einrichtung

1. Klonen und installieren

   git clone <your-repo-url>
   cd financial-analyst-mcp
   python -m venv venv && source venv/bin/activate
   pip install -r requirements.txt

2. Umgebungsvariablen – kopiere .env.example nach .env und fülle aus:

   • GROQ_API_KEY – kostenlos, keine Zahlung erforderlich (Anmeldung unter console.groq.com), wird vom Analyst-Agenten und der Nachrichten-Relevanzprüfung verwendet

   • DATABASE_URL – deine RDS-Postgres-Verbindungszeichenfolge

   • NEWSAPI_KEY – kostenlose Stufe unter newsapi.org (100 Anfragen/Tag, keine Karte erforderlich)

   • LANGCHAIN_API_KEY, LANGCHAIN_PROJECT – für LangSmith-Tracing (optional, kostenlose Stufe)

3. Datenbanktabellen einrichten

   python -m backend.db.database --init

4. Backend lokal ausführen

   uvicorn backend.main:app --reload --port 8000

5. Frontend lokal ausführen – öffne einfach frontend/index.html in einem Browser oder stelle es bereit:

   cd frontend && python -m http.server 5500

   Aktualisiere die Konstante API_BASE_URL nahe dem Anfang von index.html, sodass sie auf dein Backend zeigt (http://localhost:8000 lokal, deine Render-URL nach der Bereitstellung).

6. Evaluations-Suite ausführen

   python -m backend.evals.run_evals

Bereitstellung (AWS kostenlose Stufe)

Alles unten bleibt innerhalb von AWS 12-monatiger kostenloser Stufe (solange du die angegebenen Instanzgrößen der kostenlosen Stufe wählst). Hierfür sind keine Codeänderungen erforderlich – dieselbe FastAPI-App und derselbe MCP-Server laufen unverändert.

1. Datenbank → RDS (Postgres)

1. AWS Console → RDS → Datenbank erstellen.

2. Engine: PostgreSQL. Vorlagen: Kostenlose Stufe.

3. Instanzklasse: db.t3.micro (oder db.t4g.micro, je nachdem, was die Konsole als kostenlose Stufe anbietet).

4. Hauptbenutzernamen und Passwort festlegen und notieren.

5. Unter „Konnektivität" Öffentlicher Zugriff: Ja setzen (erforderlich, damit deine EC2-Instanz und dein eigener Rechner darauf zugreifen können – für ein Portfolio-Projekt ist das in Ordnung; später kannst du es einschränken).

6. Sobald sie läuft, den Endpunkt kopieren (sieht aus wie xxxx.rds.amazonaws.com) und deine Verbindungszeichenfolge erstellen:

   DATABASE_URL=postgresql://<username>:<password>@<endpoint>:5432/postgres

7. In der Security Group der RDS-Instanz eine eingehende Regel hinzufügen: PostgreSQL (Port 5432), Quelle = deine IP (für lokale Tests) und später die Security Group deiner EC2-Instanz.

2. Backend → EC2

1. AWS Console → EC2 → Instanz starten.

2. AMI: Amazon Linux 2023 (oder Ubuntu 22.04). Instanztyp: t2.micro (für kostenlose Stufe geeignet).

3. Ein Schlüsselpaar erstellen/herunterladen (.pem-Datei) – du brauchst es für SSH.

4. Security Group: eingehendes SSH (Port 22, deine IP) und benutzerdefinierten TCP-Port 8000 von überall (0.0.0.0/0) erlauben, damit das Frontend die API erreichen kann.

5. Instanz starten und dann per SSH verbinden:

   ssh -i your-key.pem ec2-user@<instance-public-ip>

6. Auf der Instanz:

   git clone <your-repo-url> financial-analyst-mcp
   cd financial-analyst-mcp
   nano .env          # paste in GROQ_API_KEY (free, from console.groq.com), DATABASE_URL (from RDS), NEWSAPI_KEY, etc.
   bash aws/ec2-setup.sh

   Dies installiert Python, Abhängigkeiten, erstellt die Datenbanktabellen und startet das Backend als systemd-Dienst (financial-analyst), der auch nach dem Trennen der Verbindung weiterläuft und bei einem Neustart der Instanz automatisch neu startet.

7. Prüfen, ob es läuft: curl http://<öffentliche-instanz-ip>:8000/health

3. Frontend → S3-Statische-Website

1. API_BASE_URL nahe dem Anfang von frontend/index.html auf http://<deine-ec2-öffentliche-ip>:8000 aktualisieren.

2. Von deinem eigenen Rechner (mit installierter AWS CLI und einmalig ausgeführten aws configure mit deinen Anmeldedaten):

   BUCKET_NAME=your-unique-bucket-name bash aws/deploy-frontend-s3.sh

3. Das Skript erstellt den Bucket, aktiviert das Hosting statischer Websites und lädt index.html hoch. Es gibt am Ende deine Live-URL aus (http://<bucket>.s3-website-<region>.amazonaws.com).

4. Wenn du das Frontend änderst, führe einfach dasselbe Skript erneut aus, um es erneut hochzuladen.

Hinweise

• Die öffentliche IP von EC2 ändert sich, wenn du die Instanz stoppst/startest (außer du weist eine elastische IP zu, die ebenfalls kostenlos ist, solange sie an eine laufende Instanz angehängt ist). Wenn sich deine IP ändert, aktualisiere API_BASE_URL und führe das S3-Bereitstellungsskript erneut aus.

• Um die Kosten bei null zu halten, bleib bei den kostenlosen Größen t2.micro/db.t3.micro und denke daran, dass die AWS-kostenlose Stufe nur deine ersten 12 Monate abdeckt.

Wird das in der AWS-kostenlosen Stufe etwas kosten?

Nein, solange du innerhalb dieser Grenzen bleibst (alles Teil der 12-monatigen kostenlosen Stufe von AWS für neue Konten):

Dinge, die GELD kosten werden, also vermeide sie:

• Starten einer zweiten EC2-Instanz oder RDS-Datenbank gleichzeitig (nur die ersten kostenlosen Stunden pro Dienst sind kostenlos – zwei laufende Instanzen verbrauchen doppelte Stunden)

• Verwenden eines größeren Instanztyps als t2.micro/t3.micro (EC2) oder db.t3.micro/db.t4g.micro (RDS)

• Anfordern einer elastischen IP und diese nicht an eine laufende Instanz anhängen – AWS berechnet Gebühren für nicht angehängte elastische IPs, genau um dies zu verhindern

• Wenn dein AWS-Konto nicht brandneu ist – die kostenlose Stufe gilt 12 Monate ab Kontoerstellung. Wenn du das Konto also länger hast, werden diese Dienste normal abgerechnet

Ein Sicherheitsnetz, das sich auf jeden Fall lohnt: AWS Console → Billing → Budgets → ein Budget- Benachrichtigung für 1 $ erstellen. Du bekommst sofort eine E-Mail, sobald etwas Geld kostet, und bist nie überrascht.

Hinweise zur MCP-Ebene

Der MCP-Server (backend/mcp_server/server.py) ist ein eigenständiger Prozess, der das Model Context Protocol über stdio spricht. Die Agenten verbinden sich als MCP-Clients mit ihm und verwenden langchain-mcp-adapters, das die MCP-Tools automatisch in LangChain-kompatible Tools umwandelt. Das bedeutet, derselbe MCP-Server könnte ohne Änderungen in Claude Desktop, Cursor oder jeden anderen MCP-kompatiblen Host eingebunden werden – genau darum geht es, ihn so zu bauen, statt Tool-Schemata fest im Agenten zu verdrahten.