Financial Modeling Prep MCP Server

Financial Modeling Prep MCP Server

Financial Modeling Prep API を使用した財務分析のためのツール、リソース、プロンプトを提供する Model Context Protocol（MCP）サーバーです。

機能

• 企業情報：詳細な企業プロフィールと同業他社との比較にアクセスします
• 財務諸表：損益計算書、貸借対照表、キャッシュフロー計算書を取得して分析します
• 財務指標：投資分析に役立つ主要な財務比率と指標にアクセスします
• 市場データ：市場のスナップショット、指数、ニュースを取得します
• 株価情報：現在の株価、時間外取引の株価、簡易的な価格情報を取得します
• 株価チャート：過去の価格データにアクセスし、価格変動を計算します
• アナリスト評価：アナリストの推奨と評価の詳細を取得します
• 市場指数：市場指数のデータと株価情報にアクセスします
• 市場の値上がり・値下がり銘柄：値上がり率・値下がり率が最も大きい銘柄や、最も取引が活発な銘柄を取得します
• 市場取引時間：主要取引所の取引時間と休場日を確認します
• ETF 分析：ETF のセクター別構成比、国別エクスポージャー、保有銘柄を分析します
• コモディティ：コモディティの一覧、現在価格、過去の価格データを取得します
• 暗号資産：暗号資産の一覧と現在の株価情報にアクセスします
• 外国為替：外国為替ペアの一覧と為替レートを取得します
• テクニカル指標：指数移動平均（EMA）を計算して解釈します
• 分析プロンプト：事前定義されたプロンプトテンプレートを使用して投資分析を生成します
• チャットエージェント：FMP MCP Server 用の対話型 CLI チャットインターフェースです
• 複数のトランスポートオプション：stdio、SSE、Streamable HTTP トランスポートをサポートします
• ステートフルモードとステートレスモード：さまざまな用途に対応する柔軟なデプロイオプションです
• Docker サポート：トランスポートモードを設定できるコンテナ化されたデプロイに対応します
• ヘルスチェックエンドポイント：ロードバランサーのヘルスチェック用に、組み込みの /health エンドポイントを提供します

コード構成

コードベースは、FMP API Documentation に記載された FMP API ドキュメントの構成に合わせて整理されています。各モジュールは、API の特定のセクションに対応しています。

• analyst.py：アナリストの推奨と目標株価
• charts.py：株価チャートと過去の価格データ
• commodities.py：コモディティの一覧、価格データ、過去の価格データ
• company.py：企業プロフィールと関連情報
• crypto.py：暗号資産の一覧と株価情報
• etf.py：ETF のセクター別構成比、国別エクスポージャー、保有銘柄
• forex.py：外国為替ペアの一覧と為替レート
• indices.py：市場指数の一覧と株価情報
• market.py：市場データとニュース
• market_hours.py：主要取引所の取引時間と休場日
• market_performers.py：値上がり率・値下がり率が最も大きい銘柄と、最も取引が活発な銘柄
• quote.py：株価情報、時間外取引の株価、価格変動
• search.py：ティッカーと企業を検索する API
• statements.py：財務諸表（損益計算書、貸借対照表、キャッシュフロー、財務比率）
• technical_indicators.py：テクニカル指標と分析

API エンドポイントの標準化

コードベースでは、さまざまな資産タイプの株価情報を取得するために、標準化された方法を採用しています。

• すべての資産タイプの株価情報を取得するために、統一された quote エンドポイントを使用します。対象には次のものが含まれます。

  • 株式
  • 外国為替ペア
  • 暗号資産
  • コモディティ
  • 市場指数

• 各モジュールは、それぞれの資産タイプに合わせた形式で情報を提供します。

  • get_quote：標準的な株価情報
  • get_aftermarket_quote：売買気配データを含む時間外取引の株価情報
  • get_forex_quotes：為替レート
  • get_crypto_quote：暗号資産の価格
  • get_commodities_prices：コモディティ価格
  • get_historical_price_eod_light：過去のコモディティ価格データ
  • get_index_quote：市場指数の値

この標準化により、コードの保守性が向上し、アプリケーション全体で資産価格を一貫した方法で取得できます。

その他の最近の変更

• get_aftermarket_quote：アフターマーケットの取引データを取得する新しい関数を追加しました

  • 「aftermarket-quote」エンドポイントを使用して、買値／売値と数量を取得します
  • 取引高とタイムスタンプ情報を含みます
  • タイムスタンプをミリ秒から人間が読みやすい形式に変換します
  • 絵文字のインジケーターを使った、構造化された Markdown 出力を提供します

• get_historical_price_eod_light：過去の商品価格データを取得する新しい関数を追加しました

  • 「historical-price-eod/light」エンドポイントを使用して、効率的にデータを取得します
  • from_date と to_date のパラメーターを使用した日付範囲のフィルタリングに対応します
  • 結果数を制御する limit パラメーターを含みます
  • 連続する日の間の日次価格変動と変動率を計算します
  • 価格の動きを示す絵文字のインジケーター（🔺、🔻、➖）を使い、書式を整えた Markdown テーブルでデータを表示します

以前の変更

• get_quote_change：「quote-change」エンドポイントではなく、「stock-price-change」エンドポイントを使用するよう更新しました

  • すべての期間（1D、5D、1M、3M、6M、YTD、1Y、3Y、5Y、10Y、max）の価格変動を1回のリクエストで返すようになりました
  • 視認性を高めるため、テーブルの書式を改善しました
  • トレンドをより明確に視覚化するため、絵文字のインジケーター（🔺、🔻、➖）を追加しました

• get_financial_estimates：実際の「analyst-estimates」エンドポイントの構造に合わせて更新しました

  • API レスポンスのすべてのフィールド（revenueAvg、revenueHigh、revenueLow など）に対応しました
  • 新しい page パラメーターを使ったページネーションに対応しました
  • アナリスト数の情報を追加し、表示を改善しました
  • すべての指標について、高値／安値／平均値の表示を強化しました

• get_price_target_news：「price-target-news」エンドポイントを使用するよう改善しました

  • シンボルによるフィルタリングに対応しました
  • 調整後の目標株価情報を含みます
  • 視認性向上のため、日付の書式を改善しました
  • API レスポンスのすべてのフィールドに対応しました

• get_key_metrics：包括的な財務指標ツールを強化しました

  • key-metrics エンドポイントのすべての指標への対応を改善しました
  • 指標の詳細な分類（バリュエーション、収益性、流動性など）を追加しました
  • 財務データの書式と構成を改善しました
  • 会計年度と通貨情報に対応しました

テストも同様に、包括的なカバレッジを確保するため、一貫したパターンに従ってモジュールごとに1つのテストファイルを配置しています。

インストール

1. リポジトリをクローンします：

   git clone https://github.com/cdtait/fmp-mcp-server.git
   cd fmp-mcp-server
   

2. pip または uv を使って環境をセットアップします：

   オプション1：pip を使用（標準）

   # Create and activate a virtual environment
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Install pip if not available (rare but possible in some environments)
   # curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py && python get-pip.py
   
   # Install dependencies
   python -m pip install -r requirements.txt
   
   # For development (includes testing dependencies)
   python -m pip install -e ".[dev]"
   

   オプション2：uv を使用（高速）

   # Install uv if you don't have it yet
   curl -LsSf https://astral.sh/uv/install.sh | sh
   export PATH=~/.local/bin/:${PATH}
   
   # Create and activate the environment
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   
   # Install dependencies
   uv pip install -r requirements.txt
   
   # For development (includes testing dependencies)
   uv pip install -e ".[dev]"
   

3. Financial Modeling Prep API キーをセットアップします：

   # Copy the template
   cp .env.template .env
   
   # Edit the .env file to add your API key
   # Replace 'your_api_key_here' with your actual API key from FMP
   

   API キーは、Financial Modeling Prep に登録して取得できます。

4. OpenAI API キーをセットアップします（チャットエージェントを使用する場合）：

   # Add your OpenAI API key to the .env file
   echo "OPENAI_API_KEY=your_openai_api_key_here" >> .env
   

5. テストを実行してインストールを確認します：

   # Run unit tests
   python -m pytest tests/ -v
   
   # Run acceptance tests with mock data
   TEST_MODE=true python -m pytest tests/acceptance_tests.py -v
   

開発

このプロジェクトでは、テスト駆動開発（TDD）のアプローチを採用しています。テストスイートは tests/ ディレクトリにまとめられています。

テスト戦略

このプロジェクトでは、次の3種類のテストによる包括的なテスト戦略を実施しています。

1. ユニットテスト（test_company.py、test_quotes.py など）

   • 個々の関数を分離してテストします
   • コード構造に合わせてモジュールごとに整理されています
   • すべての外部依存関係をモックします
   • 通常の動作、境界条件、エラー処理で正しく動作することを検証します
   • 実行が速く、外部依存関係はありません
   • モックには @patch デコレーターを使う一貫したパターンに従います
   • 適切にモックを分離するため、パッチを適用した後に関数をインポートします

2. 統合テスト（test_server.py、test_resources.py）

   • コンポーネントが連携して動作することをテストします
   • サーバーの適切なセットアップ、ツールの登録、リソースの処理を検証します
   • 外部 API をモックしたエンドツーエンドのフローをテストします
   • システムコンポーネントが正しく統合されることを確認します
   • コンポーネント間の適切なエラー処理を検証します

3. 受け入れテスト（acceptance_tests.py）

   • 実際の FMP API との統合を検証します
   • API 接続とレスポンス形式を確認します
   • 無効な入力でのエラー処理をテストします
   • 特定の値ではなくデータ構造を重視します
   • 実際の API モード、または TEST_MODE=true を使ったモックデータのどちらでも実行できます
   • 明示的に実行された場合、または API キーが指定されている場合にのみ、実際の API を使って実行します

この多層的なアプローチにより、個々のコンポーネントとシステム全体の両方に対する信頼性を確保し、アプリケーションが単独でも実際の API と統合された状態でも正しく動作することを確認できます。

テストの実行

# Run all unit and integration tests
python -m pytest

# Run with coverage report
python -m pytest --cov=src tests/

# Run specific test file
python -m pytest tests/test_company.py

# Run tests with specific marker
python -m pytest -m acceptance

受け入れテスト

このプロジェクトには、実際の FMP API との統合を検証する受け入れテストが含まれています。これらのテストには有効な API キーが必要ですが、モックデータを使って実行することもできます。

受け入れテストを実行するには：

# Option 1: Run with the real API
# Set your API key
export FMP_API_KEY=your_api_key_here

# Run the acceptance tests with real API
python -m pytest tests/acceptance_tests.py -v

# Option 2: Run with mock data
# This doesn't require an API key and uses mock responses
TEST_MODE=true python -m pytest tests/acceptance_tests.py -v

これらのテストでは、次の項目を検証します。

• API 接続
• データの形式と構造
• 無効な入力でのエラー処理
• 実際のデータを使ったツールのフォーマット

受け入れテストは、株価のように時間の経過とともに変わる可能性のある特定の値を検証せず、形式と構造を確認するように設計されています。このため、有効な API キーのシークレットを使う CI/CD パイプラインに適しています。

TEST_MODE=true を指定すると、conftest.py で定義されたモックレスポンスを使い、実際の API キーなしで CI 環境において受け入れテストを実行できます。

プロジェクト構成

fmp-mcp-server/
├── src/                      # Source code
│   ├── api/                  # API client functionality 
│   │   ├── client.py         # FMP API client
│   ├── tools/                # MCP tools implementation
│   │   ├── analyst.py        # Analyst ratings tools
│   │   ├── charts.py         # Stock chart tools
│   │   ├── commodities.py    # Commodities tools
│   │   ├── company.py        # Company profile tools
│   │   ├── crypto.py         # Cryptocurrency tools
│   │   ├── etf.py            # ETF analysis tools
│   │   ├── forex.py          # Forex tools
│   │   ├── indices.py        # Market indices tools
│   │   ├── market.py         # Market data tools
│   │   ├── market_hours.py   # Market hours tools 
│   │   ├── market_performers.py # Market performers tools
│   │   ├── quote.py          # Stock quote tools
│   │   ├── search.py         # Search tools
│   │   ├── statements.py     # Financial statements tools
│   │   └── technical_indicators.py # Technical analysis tools
│   ├── resources/            # MCP resources implementation
│   │   ├── company.py
│   │   └── market.py
│   ├── prompts/              # MCP prompts implementation
│   │   └── templates.py
│   └── agent_chat_client.py  # OpenAI Agent-based chat client
├── scripts/                  # Deployment and automation scripts
│   └── mcp-aws-ecs-setup.sh  # AWS ECS deployment script
├── tests/                    # Test suite
│   ├── conftest.py           # Pytest fixtures
│   ├── acceptance_tests.py   # API integration tests
│   ├── test_analyst.py       # Tests for analyst tools
│   ├── test_api_client.py    # Tests for API functionality
│   ├── test_calendar.py      # Tests for calendar tools
│   ├── test_charts.py        # Tests for chart tools
│   ├── test_commodities.py   # Tests for commodities tools
│   ├── test_company.py       # Tests for company profile tools
│   ├── test_crypto.py        # Tests for cryptocurrency tools
│   ├── test_etf.py           # Tests for ETF tools
│   ├── test_forex.py         # Tests for forex tools
│   ├── test_indices.py       # Tests for indices tools
│   ├── test_market.py        # Tests for market tools
│   ├── test_market_hours.py  # Tests for market hours tools
│   ├── test_market_performers.py # Tests for market performers tools
│   ├── test_prompts.py       # Tests for prompts
│   ├── test_quotes.py        # Tests for quote tools
│   ├── test_resources.py     # Tests for resources
│   ├── test_search.py        # Tests for search tools
│   ├── test_server.py        # Integration tests
│   ├── test_statements.py    # Tests for financial statements tools
│   └── test_technical_indicators.py # Tests for technical indicators tools
├── Dockerfile                # Docker configuration
├── docker-compose.yml        # Docker Compose configuration
└── server.py                 # Main server implementation

使用方法

サーバーの実行

サーバーはさまざまな方法で実行できます。

ローカル開発（stdio）

# Run the server directly (stdio mode)
python -m src.server

# Or use the MCP CLI for development
mcp dev src/server.py

# Install in Claude Desktop
mcp install src/server.py

SSE サーバーモード

# Run as an SSE server
python -m src.server --sse --port 8000

Streamable HTTP サーバーモード

注：Streamable HTTP トランスポートは、本番環境へのデプロイで推奨されるトランスポートであり、SSE トランスポートに代わるものです。

サーバーは、ステートフルとステートレスの両方の動作モードで Streamable HTTP トランスポートをサポートしています。

# Stateful Streamable HTTP (maintains session state)
python -m src.server --streamable-http --port 8000

# Stateless Streamable HTTP (no session persistence)
python -m src.server --streamable-http --stateless --port 8000

# Stateless with JSON responses (instead of SSE streams)
python -m src.server --streamable-http --stateless --json-response --port 8000

トランスポートモード：

• ステートフル（デフォルト）：セッション状態を維持し、イベントの再開をサポートします。対話型クライアントに最適です
• ステートレス：セッションを保持しないため、マルチノードでのデプロイや負荷分散に適しています
• JSON レスポンス：SSE ストリームの代わりに JSON を返します。よりシンプルな HTTP クライアントに便利です

エンドポイント：

• Streamable HTTP エンドポイント：http://localhost:8000/mcp
• ヘルスチェックエンドポイント：http://localhost:8000/health
• すべての MCP 操作（ツール、リソース、プロンプト）を HTTP POST/GET で利用できます

Docker のサポート：

# Default SSE mode
docker run -p 8000:8000 -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

# Streamable HTTP stateful mode
docker run -p 8000:8000 -e TRANSPORT=streamable-http -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

# Streamable HTTP stateless mode
docker run -p 8000:8000 -e TRANSPORT=streamable-http -e STATELESS=true -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

# Streamable HTTP stateless JSON mode
docker run -p 8000:8000 -e TRANSPORT=streamable-http -e STATELESS=true -e JSON_RESPONSE=true -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

トラブルシューティング

サーバーの実行時にインポートエラーが発生した場合は、次の点を確認してください。

1. 仮想環境が有効になっていること：

   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

2. すべての依存関係が正しくインストールされていること：

   python -m pip install -r requirements.txt
   

3. コマンドの実行時に、プロジェクトのルートディレクトリにいること

これにより、サーバーが SSE（Server-Sent Events）モードで起動します。このモードでは、MCP Inspector やその他の MCP クライアントを HTTP 経由で接続できます。

チャットエージェントの使用

このプロジェクトには、SSE 経由で FMP MCP サーバーに接続し、金融データを照会するための対話型 CLI インターフェースを提供するチャットエージェントが含まれています。

前提条件

• OpenAI API キー（環境変数または .env ファイルに設定）
• SSE モードで実行中の FMP MCP サーバー

チャットエージェントの実行

1. FMP MCP サーバーを SSE モードで起動します。

# In one terminal window
python -m src.server --sse

2. 別のターミナルウィンドウで、チャットエージェントを実行します。

# Ensure you have the OpenAI API key set
export OPENAI_API_KEY=your_openai_api_key_here

# Run the chat agent
python -m src.agent_chat_client

3. 金融アドバイザーエージェントとのチャットを開始します。

View trace: https://platform.openai.com/traces/trace?trace_id=trace_abc123...

You: What is the current price of Apple?
Running: What is the current price of Apple?
The current price of Apple Inc. (AAPL) is $202.52.

You: Compare AAPL and MSFT's financial performance
Running: Compare AAPL and MSFT's financial performance
...

チャットエージェントの機能

• FMP の金融データを扱う対話型チャットインターフェース
• 自然言語を通じてすべての FMP データツールを利用
• 高度なクエリに対応する OpenAI エージェントベースの実装
• エージェントの動作をデバッグして理解するためのトレースビュー

チャットセッションを終了するには、exit または quit と入力します。

Docker の使用

Docker でサーバーを実行する方法はいくつかあります。

オプション 1：ローカルでビルドして実行

# Build and run with Docker (includes health check endpoint)
docker build -t fmp-mcp-server .
docker run -p 8000:8000 -e FMP_API_KEY=your_api_key_here fmp-mcp-server

# Or use docker-compose with default port (8000)
# Method 1: Export environment variables (less secure)
export FMP_API_KEY=your_api_key_here
docker-compose up

# Method 2 (PREFERRED): Use a .env file (more secure)
# First, create a .env file in the project root with your API key
echo "FMP_API_KEY=your_api_key_here" > .env
docker-compose up

# Use docker-compose with a custom port
# Using environment variable
PORT=9000 docker-compose up

# Using both .env file and custom port
echo "FMP_API_KEY=your_api_key_here" > .env
PORT=9000 docker-compose up

オプション 2：GitHub Container Registry のビルド済みイメージを使用

# Pull the latest image
docker pull ghcr.io/cdtait/fmp-mcp-server:latest

# Run with environment variable for API key
docker run -p 8000:8000 -e FMP_API_KEY=your_api_key_here ghcr.io/cdtait/fmp-mcp-server:latest

# Run with custom port
docker run -p 9000:8000 -e FMP_API_KEY=your_api_key_here ghcr.io/cdtait/fmp-mcp-server:latest

# Run with a mounted .env file (PREFERRED)
# First create your .env file with your API key
echo "FMP_API_KEY=your_api_key_here" > .env

# Then mount it when running the container
docker run -p 8000:8000 -v $(pwd)/.env:/app/.env ghcr.io/cdtait/fmp-mcp-server:latest

サーバーはコンテナ内で常にポート 8000 をリッスンしますが、Docker はこれを指定したホストポート（デフォルトは 8000、または PORT 環境変数の値）にマッピングします。

注： API キーをシェルでエクスポートするよりも、.env ファイルで保存する方法をおすすめします。コマンド履歴や環境変数からキーが誤って漏えいするリスクを軽減できます。

MCP Inspector の使用

MCP Inspector は、MCP サーバーをテストするのに便利なツールです。利用可能なツール、リソース、プロンプトを確認し、対話形式でテストできます。

Node.js で MCP Inspector を実行

MCP Inspector を実行する最も簡単な方法は、Node.js を使用することです。

# Using npx (no installation required)
npx @modelcontextprotocol/inspector

# Or if you have the package installed globally
mcp-inspector

MCP Inspector が起動したら、次の操作を行います。

1. Transport のドロップダウンで「HTTP/SSE」を選択します。
2. サーバーの URL を入力します：http://localhost:8000/sse
   • カスタムポート（例：PORT=9000）でサーバーを起動した場合は、代わりにそのポートを使用します：http://localhost:9000/sse
3. 「Connect」をクリックして、サーバーとの接続を確立します。
4. 各タブで利用可能なツール、リソース、プロンプトを確認します。

ヘルスチェックのテスト

サーバーの起動後、ヘルスチェックのエンドポイントをテストできます。

# Test the dedicated health endpoint (ALB-compatible GET request)
curl http://localhost:8000/health

# Expected response:
# {"status":"healthy","service":"fmp-mcp-server"}

# Test MCP redirect endpoint (ALB-compatible GET request)
curl http://localhost:8000/mcp/

# Expected response: HTTP 307 redirect (indicates service is running)

# Test full MCP functionality (JSON-RPC POST request)
curl -L -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "ping",
    "params": {}
  }' \
  http://localhost:8000/mcp

# Expected response:
# event: message
# data: {"jsonrpc":"2.0","id":1,"result":{}}

# Test with ALB (after deployment)
curl http://your-alb-dns-name.region.elb.amazonaws.com/health

# Test full MCP functionality via ALB
curl -L -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "ping",
    "params": {}
  }' \
  http://your-alb-dns-name.region.elb.amazonaws.com/mcp

クエリの例

サーバーを起動し、Claude Desktop や MCP Inspector などの MCP クライアントに接続すると、次の操作ができます。

1. 企業プロフィールを取得する：

   • 「企業プロフィールツールを使って、Apple の財務プロフィールについて教えてください」
   • 「TSLA の主要な財務指標は何ですか？」

2. 財務諸表を取得する：

   • 「AAPL の昨年の損益計算書を表示してください」
   • 「TSLA の貸借対照表を教えてください」
   • 「MSFT のキャッシュフロー計算書を取得して分析してください」

3. 株価と価格情報を取得する：

   • 「MSFT 株の現在の価格はいくらですか？」
   • 「GOOGL の最近の価格変動を表示してください」
   • 「AAPL、AMZN、META の現在の株価を比較してください」
   • 「AAPL の時間外取引の株価を取得してください」
   • 「TSLA の時間外取引における買値と売値のスプレッドを表示してください」

4. アナリストの評価を取得する：

   • 「AMZN 株についてアナリストはどう見ていますか？」
   • 「NVDA のアナリスト評価の概要を取得してください」
   • 「MSFT の最新の目標株価を表示してください」

5. 市場指数と値上がり銘柄を取得する：

   • 「現在の主要な市場指数を表示してください」
   • 「今日、最も値上がりした銘柄は何ですか？」
   • 「今日、最も取引が活発な銘柄はどれですか？」

6. 市場の状況を確認する：

   • 「今、市場は開いていますか？」
   • 「次の市場休場日はいつですか？」
   • 「NYSE の取引時間を教えてください」

7. ETF を分析する：

   • 「SPY の上位組入銘柄は何ですか？」
   • 「QQQ のセクター別内訳を表示してください」
   • 「VEU はどの国に投資していますか？」

8. コモディティ、暗号資産、外国為替の情報を取得する：

   • 「金の現在の価格はいくらですか？」
   • 「過去 1 か月間の金の過去の価格データを表示してください」
   • 「現在のビットコイン価格を表示してください」
   • 「EURUSD の為替レートはいくらですか？」

9. テクニカル分析を取得する：

   • 「AAPL の RSI を計算してください」
   • 「TSLA のテクニカル分析の概要を教えてください」
   • 「20 日 SMA から AMZN について何がわかりますか？」

10. 分析プロンプトを使用する：

    • 「株価比較プロンプトを使って AAPL、MSFT、GOOGL を比較してください」
    • 「財務諸表分析プロンプトを使って TSLA の財務諸表を分析してください」

設定

サーバーでは、以下の環境変数を使用します。

• FMP_API_KEY：Financial Modeling Prep の API キー（必須）
  • Financial Modeling Prep に登録すると、API キーを取得できます
  • コマンドライン、環境変数、または .env ファイルから渡せます
• OPENAI_API_KEY：OpenAI の API キー（チャットエージェントの使用に必須）
  • OpenAI から API キーを取得してください
• PORT：Docker Compose の実行時に使用するホストポート（デフォルトは 8000）
  • ホストポートのマッピングにのみ影響します。コンテナーは内部で常にポート 8000 を使用します
• TEST_MODE：受け入れテストでモックデータを使用するには、"true" に設定します
  • CI/CD 環境や、有効な API キーなしでテストする場合に便利です
  • tests/conftest.py で定義されたモックレスポンスを使用します
  • さまざまな資産タイプに対応する包括的なモックデータが含まれます。
    • 株式（AAPL、MSFT など）
    • 外国為替ペア（EURUSD、GBPUSD、USDJPY）
    • 暗号資産（BTCUSD、ETHUSD）
    • 商品（GCUSD は金、CLUSD は原油、BZUSD はブレント原油）
    • 市場指数（S&P 500 は ^GSPC、ダウ・ジョーンズは ^DJI）

これらの変数は、プロジェクトのルートにある .env ファイルで設定できます。

# Example .env file contents
FMP_API_KEY=your_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
PORT=9000
TEST_MODE=true  # For testing with mock data

コントリビューション

1. 機能ブランチを作成します
2. 機能のテストを記述します
3. テストが通ることを確認しながら、機能を実装します
4. プルリクエストを送信します

CI/CD パイプライン

このプロジェクトでは、複数のステージからなる包括的な CI/CD パイプラインを実装しています。

1. 継続的インテグレーション（ci.yml）

プルリクエストが作成されるたび、または main にプッシュされるたびに、以下が自動的に実行されます。

• ユニットテスト：pytest による個々のコンポーネントのテスト

  • 複数の Python バージョン（3.11、3.12）で実行します
  • 受け入れテストは除外します
  • カバレッジを Codecov に報告します

• 統合テスト：コンポーネント間の連携を検証します

  • TEST_MODE=true を設定して受け入れテストを実行します
  • API コストを避けるためにモックデータを使用します
  • カバレッジ指標を個別に報告します

• デプロイ（main へのマージ時）：

  • 最新のコードで Docker イメージをビルドします
  • GitHub Container Registry に公開します
  • 追跡用のデプロイマーカーを作成します

ワークフローの設定は .github/workflows/ci.yml にあります。

2. 受け入れテスト（acceptance-tests.yml）

実際の FMP API を使用するテストは、以下のとおり実行されます。

• スケジュール実行：毎週月曜日の UTC 5 時に自動実行します
• オンデマンド実行：特定のコミットを指定して手動で実行できます
• 検証：実際の API との互換性を確認します
• ステータス更新：デプロイに成功または失敗を記録します

この独立したワークフローにより、外部 API との互換性を確保しつつ、メインの CI パイプラインを高速に保ち、不要な API コストを避けられます。

受け入れテストのワークフローを手動で実行するには：

1. GitHub リポジトリに移動します
2. 「Actions」タブをクリックします
3. ワークフローの一覧から「API Acceptance Tests」を選択します
4. 「Run workflow」をクリックします（必要に応じてコミット SHA を指定します）

受け入れテストのワークフロー設定は .github/workflows/acceptance-tests.yml にあります。

3. リリースプロセス（release.yml）

安定版を公開する準備ができたら、以下を行います。

• 手動トリガー：バージョン番号とコミット SHA を指定します
• 検証：コミットが受け入れテストに合格していることを確認します
• タグ付け：Git タグと GitHub Release を作成します
• 本番用イメージ：バージョン付きおよび安定版の Docker イメージを公開します

新しいリリースを作成するには：

1. GitHub リポジトリに移動します
2. 「Actions」タブをクリックします
3. ワークフローの一覧から「Release」を選択します
4. 「Run workflow」をクリックします
5. リリースするバージョン番号とコミット SHA を入力します

リリースのワークフロー設定は .github/workflows/release.yml にあります。

コンテナレジストリ

Docker イメージは、さまざまなタグを付けて GitHub Container Registry に公開されます。

# Development (from CI pipeline)
docker pull ghcr.io/cdtait/fmp-mcp-server:latest           # Latest build from main branch
docker pull ghcr.io/cdtait/fmp-mcp-server:a7f33fe2ce0265e0 # Specific commit

# Production releases (from release workflow)
docker pull ghcr.io/cdtait/fmp-mcp-server:stable           # Latest stable release
docker pull ghcr.io/cdtait/fmp-mcp-server:v1.2.3           # Specific version

コンテナーの実行方法について詳しくは、「Docker の使用」セクションをご覧ください。

AWS ECS のデプロイ

このプロジェクトには、ロードバランシング、サービスディスカバリー、重複検出など、本番環境に対応した機能を備える包括的な AWS ECS デプロイ自動化が含まれています。

利用可能なデプロイスクリプト

script/ ディレクトリでは、次のスクリプトを利用できます。

• mcp-aws-ecs-setup.sh - 重複検出機能を備えた ECS のメインデプロイスクリプト
• add-load-balancer.sh - 安定した外部アクセスのために Application Load Balancer を追加します
• add-service-discovery.sh - 内部通信のために AWS Cloud Map のサービスディスカバリーを追加します
• cleanup-duplicates.sh - 重複サービスを特定して削除します

前提条件

• AWS CLI v2 がインストールされ、設定済みであること
• 次の包括的な権限を持つ AWS IAM ユーザー：
  • AmazonECS_FullAccess
  • AmazonEC2ReadOnlyAccess
  • IAMFullAccess（または CloudWatchLogsFullAccess + SecretsManagerReadWrite）
  • CloudWatchReadOnlyAccess
• FMP API キー
• コンテナイメージ（GitHub Container Registry のもの、またはカスタムビルド）

クイックセットアップ

ステップ 1：基本的な ECS デプロイ

# Make scripts executable
chmod +x scripts/*.sh

# Run the main setup script
./scripts/mcp-aws-ecs-setup.sh

スクリプトでは、次の項目を入力するよう求められます。

• AWS リージョン（例：eu-west-2、us-east-1）
• ECS クラスター名（例：mcp-cluster）
• タスク定義名（例：mcp-task-stream）
• コンテナイメージ（例：ghcr.io/cdtait/fmp-mcp-server:latest）
• ポート番号（例：8000、8001）
• FMP API キー（AWS Secrets Manager に安全に保存されます）

ステップ 2：ロードバランサーを追加（推奨）

# Add Application Load Balancer for stable external access
./scripts/add-load-balancer.sh

これにより、IP アドレスが変わる代わりに、mcp-alb-123456789.eu-west-2.elb.amazonaws.com のような安定した DNS 名を利用できます。

ステップ 3：サービスディスカバリーを追加（任意）

# Add AWS Cloud Map for internal service discovery
./scripts/add-service-discovery.sh

これにより、VPC 内で mcp-streamable.fmp-mcp-services のような DNS 名を使って、サービス同士を検出できるようになります。

重複の検出と防止

すべてのスクリプトに、インテリジェントな重複検出機能が含まれています。

ECS セットアップスクリプトの機能：

• 同じタスク定義を持つ既存のサービスを検出します
• 新しいサービスを作成する前に、機能的に重複するサービスについて警告します
• 次の 3 つの選択肢を提示します：
  1. 既存のサービスを更新する（推奨）
  2. それでも新しいサービスを作成する（重複が発生する可能性があります）
  3. 終了して手動でクリーンアップする

重複検出の出力例：

🔄 DUPLICATE DETECTED: Service 'mcp-streamable-service-a1a90073' already uses task family 'mcp-task-stream'

🚨 DUPLICATE SERVICE DETECTED! 🚨
Service 'mcp-streamable-service-a1a90073' already runs the same task definition family 'mcp-task-stream'

Recommended actions:
1. Update existing service 'mcp-streamable-service-a1a90073' (RECOMMENDED)
2. Create new service anyway (will cause duplicates and extra costs)
3. Exit and cleanup manually

重複サービスをクリーンアップする：

# Check for and remove duplicate services
./scripts/cleanup-duplicates.sh

このスクリプトは次の処理を行います。

• 同一のタスク定義を使用するサービスを特定します
• ロードバランサーを持つサービス（保持対象）を表示します
• 重複サービスの自動クリーンアップを提示します
• 手動でクリーンアップするためのコマンドを提示します

環境変数

環境変数を設定して、デプロイを事前に構成できます。

# Create deployment configuration
cat > .env << EOF
REGION=eu-west-2
CLUSTER_NAME=mcp-cluster
TASK_FAMILY=mcp-task-stream
CONTAINER_IMAGE=ghcr.io/cdtait/fmp-mcp-server:latest
PORT=8001
FMP_API_KEY=your_api_key_here
EOF

# Source the environment
source .env

# Run scripts without prompts
./scripts/mcp-aws-ecs-setup.sh
./scripts/add-load-balancer.sh

スクリプトによって作成されるもの

基本的な ECS セットアップ（mcp-aws-ecs-setup.sh）：

1. AWS CLI v2 のインストール（必要な場合）
2. ECS クラスターと Fargate キャパシティプロバイダー
3. CloudWatch Logs と Secrets Manager の権限を持つ IAM ロール
4. ポートアクセスを設定できる セキュリティグループ
5. API キーを安全に保存するための Secrets Manager 連携
6. ストリーム可能な HTTP トランスポートを使用する ECS サービス
7. 直接アクセス用の パブリック IP エンドポイント

ロードバランサーのセットアップ（add-load-balancer.sh）：

1. Application Load Balancer（インターネット向け）
2. ヘルスチェックを備えた ターゲットグループ（HTTP 307 リダイレクトを検出）
3. ALB ↔ ECS 間の通信を許可する セキュリティグループルール
4. 外部アクセス用の 安定した DNS エンドポイント
5. 自動ヘルスモニタリングとフェイルオーバー

サービスディスカバリーのセットアップ（add-service-discovery.sh）：

1. AWS Cloud Map のプライベート DNS 名前空間
2. 自動検出のための サービス登録
3. サービス間通信に使用する 内部 DNS 名
4. ヘルスチェックと自動登録・登録解除

デプロイ後

基本的なデプロイの出力：

=== SETUP COMPLETE ===

Cluster: mcp-cluster
Region: eu-west-2

Service: mcp-streamable-service-abc123
- Endpoint: http://3.10.53.254:8001/mcp/
- Transport: streamable-http (stateless)
- Task Definition: mcp-task-stream:1

Test command:
curl http://3.10.53.254:8001/mcp/meta

MCP Inspector Connection URL:
http://3.10.53.254:8001/mcp/

ロードバランサーを使用する場合：

=== APPLICATION LOAD BALANCER SETUP COMPLETE ===

Load Balancer: mcp-alb
DNS Name: mcp-alb-689612947.eu-west-2.elb.amazonaws.com

Your service is now accessible at:
http://mcp-alb-689612947.eu-west-2.elb.amazonaws.com/mcp/meta

Test commands:
curl http://mcp-alb-689612947.eu-west-2.elb.amazonaws.com/mcp/meta
curl http://mcp-alb-689612947.eu-west-2.elb.amazonaws.com/mcp/

サービスディスカバリーを使用する場合：

=== SERVICE DISCOVERY SETUP COMPLETE ===

Namespace: fmp-mcp-services
Service: mcp-streamable
DNS Name: mcp-streamable.fmp-mcp-services

Your service can now be reached at:
- Internal DNS: mcp-streamable.fmp-mcp-services
- From within the VPC: http://mcp-streamable.fmp-mcp-services:8001

スケーリングと管理

# Scale service to 2 instances for high availability
aws ecs update-service --region eu-west-2 --cluster mcp-cluster --service SERVICE_NAME --desired-count 2

# Force new deployment (useful for updates)
aws ecs update-service --region eu-west-2 --cluster mcp-cluster --service SERVICE_NAME --force-new-deployment

# View service status
aws ecs describe-services --region eu-west-2 --cluster mcp-cluster --services SERVICE_NAME

# Check load balancer health
aws elbv2 describe-target-health --region eu-west-2 --target-group-arn TARGET_GROUP_ARN

# View logs
aws logs tail /ecs/mcp-task-stream --region eu-west-2 --follow

ヘルスチェック

サーバーでは、複数のヘルスチェック方法を利用できます。

オプション 1：専用のヘルスエンドポイント（推奨）

• ヘルスチェックパス：/health
• メソッド：GET（シンプルな HTTP リクエスト）
• 期待されるレスポンス：JSON 本文 {"status": "healthy", "service": "fmp-mcp-server"} を含む HTTP 200
• 利点：ロードバランサーのヘルスチェック専用に設計された、シンプルで高速、軽量なエンドポイント

オプション 2：MCP リダイレクトエンドポイント（従来方式）

• ヘルスチェックパス：/mcp/
• メソッド：GET（ALB のヘルスチェックでサポートされるのは GET のみです）
• 期待されるレスポンス：HTTP 307 リダイレクト（MCP サービスが応答していることを示します）
• 用途：MCP プロトコルが利用可能であることを前提とする既存のセットアップとの互換性確保

ロードバランサーの機能：

• 自動フェイルオーバー：異常なインスタンスは自動的に置き換えられます
• AZ 間の分散：インスタンスをアベイラビリティーゾーン間に分散します

セキュリティ機能

• AWS Secrets Manager に保存された API キー（環境変数には保存しません）
• 必要最小限のアクセス権を設定したセキュリティグループ
• 最小権限の原則に従った IAM ロール
• 内部サービス間通信のための VPC 分離
• HTTPS 対応のロードバランサー設定

ベストプラクティス

1. 本番環境から外部アクセスする場合は、必ずロードバランサーを使用してください
2. 高可用性を実現するため、インスタンスを 2 台以上にスケールしてください
3. 複数サービスのアーキテクチャでは、サービスディスカバリーを使用してください
4. 重複を避けるため、再デプロイの前にクリーンアップスクリプトを実行してください
5. アプリケーションの健全性を確認するため、CloudWatch ログを監視してください
6. 機密設定には Secrets Manager を使用してください

Terraform インフラストラクチャ

このプロジェクトには、エンタープライズグレードの機能とコスト最適化を備えた、本番環境対応の Terraform 設定が含まれています。これを使用して FMP MCP サーバーを AWS にデプロイできます。

インフラストラクチャの機能

• 🏗️ 単一リージョンアーキテクチャ：オプションのマルチリージョン対応を備えたシンプルなデプロイ
• 🐳 ECS Fargate：自動スケーリングに対応したサーバーレスコンテナプラットフォーム
• ⚖️ Application Load Balancer：ヘルスチェックによる高可用性
• 🔒 セキュリティのベストプラクティス：VPC 分離、IAM ロール、セキュリティグループ
• 🗺️ サービスディスカバリー：内部サービス間通信のための AWS Cloud Map
• 📊 監視：CloudWatch ログとヘルス監視
• 💰 コスト最適化：週末のみのスケジューリングで 69～83% のコスト削減
• 🌐 マルチリージョン対応：Route53 のレイテンシーベースルーティング
• 🔐 シークレット管理：API キー用の AWS Secrets Manager

クイックスタート

# Navigate to terraform directory
cd terraform/fmp-mcp-modular

# Copy and configure variables
cp terraform.tfvars.example terraform-my-region.tfvars
# Edit with your values (region, domain, etc.)

# Deploy infrastructure
terraform init
terraform plan -var-file="terraform-my-region.tfvars" -out="my-region.tfplan"
terraform apply my-region.tfplan

# Set API key in AWS Secrets Manager
SECRET_ARN=$(terraform output -raw secret_arn)
aws secretsmanager put-secret-value \
  --secret-id $SECRET_ARN \
  --secret-string '{"API_KEY":"your-fmp-api-key-here"}'

# Get application URL
terraform output application_url

マルチリージョンデプロイ

自動フェイルオーバーを備えたグローバルデプロイの場合：

# Deploy to multiple regions with separate state files
terraform apply -var-file="terraform-eu-west-1.tfvars" \
  -state="terraform-eu-west-1.tfstate" \
  -state-out="terraform-eu-west-1.tfstate"

terraform apply -var-file="terraform-eu-west-2.tfvars" \
  -state="terraform-eu-west-2.tfstate" \
  -state-out="terraform-eu-west-2.tfstate"

# Route53 automatically provides latency-based routing

コスト最適化

インフラストラクチャには、週末のみのインテリジェントなスケジューリングが含まれています：

# Enable weekend-only mode (69-83% cost savings)
terraform apply -var-file="terraform-my-region.tfvars" \
  -var="enable_weekend_only=true" \
  -var="destroy_albs_when_scaled_down=false"

# Manual scaling operations
aws ecs update-service \
  --cluster $(terraform output -raw ecs_cluster_name) \
  --service $(terraform output -raw ecs_service_name) \
  --desired-count 0  # Scale down

アーキテクチャ

Terraform の設定では、以下が作成されます：

• VPC：複数の AZ にまたがるパブリックサブネット
• ECS クラスター：Fargate タスク
• Application Load Balancer：ヘルスチェック
• Route53：レイテンシーベースのルーティングを使用した DNS（マルチリージョン）
• IAM ロール：最小権限のアクセス
• Secrets Manager：API キーの安全な保存
• CloudWatch：ログ記録と監視

詳細なアーキテクチャ図、設定オプション、管理コマンドについては、terraform/fmp-mcp-modular/README.md の完全なドキュメントをご覧ください。

カバレッジレポート

コードカバレッジは、テストの各段階で計測されます：

• ユニットテスト：基本的なコードパスのカバレッジ
• 統合テスト：モックデータを使用したカバレッジ
• 受け入れテスト：実際の API 呼び出しを使用したカバレッジ

Codecov を使用してカバレッジ指標を集計し、可視化します。テストの各段階には個別のフラグが設定されています。