MCP Server for Alpha Vantage API (@missionsquad/avantage)

Alpha Vantage API 用 MCP サーバー（@missionsquad/avantage）

このプロジェクトは、@missionsquad/avantage ライブラリをラップする Model Context Protocol（MCP）サーバーを提供し、Alpha Vantage API の機能を LLM 向けのツールとして公開します。

概要

このサーバーを使うと、LLM は Alpha Vantage API と連携し、次のような金融データを取得できます。

• 株式の主要データ（時系列、株価、検索）
• ファンダメンタルデータ（企業概要、財務情報、カレンダー）
• 外国為替（FX）データ
• 暗号資産データ
• コモディティデータ
• 経済指標
• テクニカル指標
• Alpha Intelligence（ニュース、センチメントなど）
• オプションデータ（プレミアム）

@missionsquad/avantage TypeScript ライブラリを活用し、汎用 MCP サーバーテンプレートのアーキテクチャに従っています。これには、マルチユーザーの API キー処理や、AVantage クライアントインスタンスのリソース管理が含まれます。

主な機能：

• 幅広い機能を網羅： @missionsquad/avantage ライブラリで利用できるほぼすべての関数に対応する MCP ツールを実装しています。
• マルチユーザー対応： extraArgs（推奨）またはフォールバックとして環境変数を使用し、Alpha Vantage API キーを安全に処理します。
• リソース管理： ResourceManager を使用して、AVantage クライアントインスタンスを効率的に管理します。
• 厳密な型付け： TypeScript で構築されており、@missionsquad/avantage の型と、ツールパラメーター用の Zod スキーマを活用しています。
• 標準 MCP インターフェース： MCP 通信には @missionsquad/fastmcp を使用します。

はじめに

前提条件

• Node.js v20 以降
• npm または yarn
• Alpha Vantage API キー（こちらから取得できます）

セットアップ

1. クローンまたはコピー： このリポジトリをクローンするか、ファイルをコピーします。

   git clone <repository-url> mcp-avantage-server
   cd mcp-avantage-server
   

2. 依存関係のインストール：

   npm install
   # or
   yarn install
   

3. 環境の設定：
   • .env.example を .env にコピーします。
   • .env を編集し、API_KEY に Alpha Vantage API キーを設定します。
   • プレミアムサブスクリプションを利用している場合は、任意で AV_PREMIUM=true を設定します。
   • 必要に応じて LOG_LEVEL または RESOURCE_CLEANUP_INTERVAL を調整します。
4. プロジェクトのビルド：

   npm run build
   # or
   yarn build
   

5. サーバーの起動：

   npm start
   # or
   yarn start
   

   サーバーは stdio で MCP リクエストを待ち受けます。

認証

このサーバーでは、標準的なマルチユーザートークン処理パターンを使用します。

1. extraArgs.apiKey（推奨）： MCP の call_tool リクエスト時に、extraArgs オブジェクトの apiKey フィールドにユーザー固有の Alpha Vantage API キーを渡します。このキーはツールのスキーマには含まれません。
2. .env によるフォールバック： extraArgs.apiKey が指定されていない場合、サーバーは .env ファイルの API_KEY の値を使用します。

利用可能なツール

このサーバーは、@missionsquad/avantage ライブラリのメソッドに対応する多数のツールを公開します。ツール名は通常 module_method の形式です（例：coreStock_intraday、fundamentalData_companyOverview）。

パラメーターと戻り値の構造の詳細については、Alpha Vantage のドキュメントと、@missionsquad/avantage ライブラリの型（ライブラリ内の src/types/*）を参照してください。

ツール呼び出しの例（MCP リクエストの概念例）：

{
  "type": "call_tool",
  "requestId": "req-123",
  "tool": {
    "name": "coreStock_quote",
    "arguments": {
      "symbol": "IBM"
    }
  },
  "context": {
    "extraArgs": {
      "apiKey": "USER_SPECIFIC_AV_KEY" // Optional: User's key
    }
  }
}

ツールのカテゴリ（モジュール）：

• alphaIntelligence_*
• commodities_*
• coreStock_*
• crypto_*
• economicIndicators_*
• forex_*
• fundamentalData_*
• optionsData_*（プレミアム）
• technicalIndicators_*

MCP の list_tools コマンドを使用すると、利用可能なすべてのツール、その説明、パラメータースキーマを確認できます。

設定

.env ファイルで設定します。

変数	説明	デフォルト
API_KEY	extraArgs にない場合に使用する Alpha Vantage API キーのフォールバック	null
LOG_LEVEL	ログレベル（error、warn、info、debug）	info
RESOURCE_CLEANUP_INTERVAL	非アクティブな AVantage クライアントインスタンスをクリーンアップする間隔（ms）	1800000 (30m)
AV_PREMIUM	true に設定すると、avantage でプレミアムエンドポイントへのアクセスを有効にします	false

プロジェクト構成

汎用的な MCP サーバーテンプレートの構成に準拠しています。主なファイルは次のとおりです。

• src/index.ts：サーバーのメインエントリポイントとツール定義です。
• src/config.ts：設定の読み込みです。
• src/logger.ts：ログユーティリティです。
• src/resource-manager.ts：AVantage インスタンスを管理します。
• src/schemas.ts：ツールパラメーターの Zod スキーマです。
• .nexus/：Nexus のドキュメントです。

Nexus のドキュメント

• .nexus/features/avantage_integration/feature.md
• .nexus/architecture/server_structure.md
• .nexus/guides/using_avantage_tools.md
• .nexus/decisions/decision_log.md

ライセンス

MIT（テンプレートのライセンスが MIT であると仮定しています。確認してください。）