MCP-Powered Financial Analyst

実際のMCP（Model Context Protocol）サーバーを中心に構築した、ローカルファーストのAI金融アナリストです。 1つのチャットボットが株価のトレンドを推測する代わりに、2つのエージェントが連携して動作します：

• Validator agent — インターネットから取得したデータ（Yahoo Finance、ニュースAPI）に、LLMに届く前にギャップ、不正な値、ティッカーの不一致がないかをチェックします。

• Analyst agent — 検証済みデータとMCPツールの出力に基づいて推論し、構造化されたサマリー（トレンド、移動平均、ボラティリティ、関連ニュースのセンチメント）を作成します。

両方のエージェントは、カスタムMCPサーバーが公開するツールを呼び出します。これがこのプロジェクトの中核であり、単なるLangChainのグルーコードではありません。

基本的なチュートリアル版から追加したもの

• 1つのエージェントがすべてを行う代わりに、2つのエージェントに分割（Validator → Analyst）

• 検証を独自のツールとして含む、3つのツールを備えた本格的なMCPサーバー

• 両エージェントでのLangSmithトレーシング

• Neon Postgresキャッシュ層（レート制限のあるAPIへの再アクセスを回避）

• 手計算による正解データを使った小さな評価スイート

• デプロイ済みのWebアプリ（Render上のFastAPI、Vercel上の静的フロントエンド）

Related MCP server: MonteWalk

アーキテクチャ

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

プロジェクト構成

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

セットアップ

1. クローンしてインストール

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

2. 環境変数 — .env.example を .env にコピーして、以下を入力します：

   • GROQ_API_KEY — 無料、支払い不要（console.groq.comでサインアップ）、Analyst agentとニュース関連性チェックで使用

   • DATABASE_URL — RDS Postgresの接続文字列

   • NEWSAPI_KEY — newsapi.orgの無料プラン（100リクエスト/日、カード不要）

   • LANGCHAIN_API_KEY、LANGCHAIN_PROJECT — LangSmithトレーシング用（任意、無料プラン）

3. データベーステーブルを設定

   python -m backend.db.database --init

4. バックエンドをローカルで実行

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

5. フロントエンドをローカルで実行 — ブラウザで frontend/index.html を開くか、以下のように配信します：

   cd frontend && python -m http.server 5500

   index.html の先頭付近にある API_BASE_URL 定数を、バックエンドを指すように更新します（ローカルでは http://localhost:8000、デプロイ後はRenderのURL）。

6. 評価スイートを実行

   python -m backend.evals.run_evals

デプロイ（AWS無料利用枠）

以下の手順はすべて、AWSの12か月間無料利用枠の範囲内です（記載されている無料利用枠のインスタンスサイズを選択する限り）。ここでコードの変更は一切不要で、同じFastAPIアプリとMCPサーバーがそのまま動作します。

1. データベース → RDS（Postgres）

1. AWSコンソール → RDS → データベースを作成。

2. エンジン：PostgreSQL。テンプレート：無料利用枠。

3. インスタンスクラス：db.t3.micro（またはdb.t4g.micro。コンソールが無料利用枠として提供している方）。

4. マスターユーザー名とパスワードを設定し、メモしておきます。

5. 「接続」で、パブリックアクセス: あり を設定します（EC2インスタンスと自分のマシンからアクセスできるようにするために必要です。ポートフォリオプロジェクトならこれで問題ありません。後で必要になれば制限を強化できます）。

6. 起動したら、エンドポイント（xxxx.rds.amazonaws.com のような形式）をコピーし、接続文字列を作成します：

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

7. RDSインスタンスのセキュリティグループで、インバウンドルールを追加します：PostgreSQL（ポート5432）、ソース = 自分のIP（ローカルテスト用）、後でEC2インスタンスのセキュリティグループも追加します。

2. バックエンド → EC2

1. AWSコンソール → EC2 → インスタンスを起動。

2. AMI：Amazon Linux 2023（またはUbuntu 22.04）。インスタンスタイプ：t2.micro（無料利用枠の対象）。

3. キーペア（.pem ファイル）を作成/ダウンロードします — SSH接続に必要です。

4. セキュリティグループ：インバウンドのSSH（ポート22、自分のIP）と、フロントエンドがAPIに到達できるようにカスタムTCPポート8000を任意の場所（0.0.0.0/0）から許可します。

5. 起動して、SSHで接続します：

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

6. インスタンス上で：

   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

   これにより、Pythonと依存関係のインストール、データベーステーブルの作成、バックエンドの systemd サービス（financial-analyst）としての起動が行われます。このサービスは切断後も実行され続け、インスタンスが再起動した場合も自動的に再起動します。

7. 起動を確認します：curl http://<instance-public-ip>:8000/health

3. フロントエンド → S3静的ウェブサイト

1. frontend/index.html の先頭付近にある API_BASE_URL を http://<your-ec2-public-ip>:8000 に更新します。

2. 自分のマシンから（AWS CLIがインストールされ、aws configure で認証情報を一度設定している場合）：

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

3. スクリプトがバケットを作成し、静的ウェブサイトホスティングを有効にして、index.html をアップロードします。最後に公開URL（http://<bucket>.s3-website-<region>.amazonaws.com）を表示します。

4. フロントエンドを変更したら、同じスクリプトを再実行して再アップロードするだけです。

注意事項

• EC2のパブリックIPは、インスタンスを停止/起動すると変わります（Elastic IPをアタッチしない限り。Elastic IPは実行中のインスタンスにアタッチされている限り無料です）。IPが変わった場合は、API_BASE_URL を更新してS3デプロイスクリプトを再実行します。

• コストをゼロに保つには、t2.micro/db.t3.micro の無料利用枠サイズを守り、AWS無料利用枠は最初の12か月間のみであることを覚えておいてください。

AWS無料利用枠で費用はかかりますか？

いいえ、以下の制限内に収まる限りかかりません（すべて新規アカウント向けのAWS 12か月間無料利用枠に含まれます）：

費用がかかるもの（避けるべきもの）：

• 同時に2つ目のEC2インスタンスまたはRDSデータベースを起動する（各サービスの無料利用枠時間は最初の1台分のみで、2つ稼働すると2倍の時間を消費します）

• t2.micro/t3.micro（EC2）または db.t3.micro/db.t4g.micro（RDS）より大きいインスタンスタイプを使用する

• Elastic IPをリクエストして、実行中のインスタンスにアタッチしない — AWSは未アタッチのElastic IPに課金することで、これを意図的に防止しています

• AWSアカウントが新規でない場合 — 無料利用枠はアカウント作成から12か月間なので、アカウントをそれ以上保有していると、これらのサービスは通常どおり請求されます

設定しておく価値のある安全策： AWSコンソール → 請求 → 予算 → 1ドルの予算アラートを作成します。何かに費用がかかり始めた瞬間にメールで通知されるので、驚くことはありません。

MCPレイヤーに関するメモ

MCPサーバー（backend/mcp_server/server.py）は、stdioを介してModel Context Protocolで通信するスタンドアロンプロセスです。エージェントは langchain-mcp-adapters を使用してMCPクライアントとして接続し、MCPツールをLangChain互換のツールに自動的に変換します。つまり、同じMCPサーバーを、変更なしでClaude Desktop、Cursor、その他のMCP互換ホストに接続できます。これが、ツールスキーマをエージェントにハードコードするのではなく、この方法で構築する意義そのものです。