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

Alpha Vantage API 的 MCP 服务（@missionsquad/avantage）

本项目提供一个 Model Context Protocol（MCP）服务，用于封装 @missionsquad/avantage 库，并将 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 接口： 使用 @missionsquad/fastmcp 进行 MCP 通信。

开始使用

前提条件

• Node.js v20 或更高版本
• npm 或 yarn
• Alpha Vantage API 密钥（在此获取）

设置

1. 克隆或复制： 克隆此仓库或复制其中的文件。

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

2. 安装依赖：

   npm install
   # 或
   yarn install
   

3. 配置环境：
   • 将 .env.example 复制为 .env。
   • 编辑 .env，将 API_KEY 设置为你的 Alpha Vantage API 密钥。
   • 如果你有高级订阅，可选择设置 AV_PREMIUM=true。
   • 如有需要，可调整 LOG_LEVEL 或 RESOURCE_CLEANUP_INTERVAL。
4. 构建项目：

   npm run build
   # 或
   yarn build
   

5. 启动服务：

   npm start
   # 或
   yarn start
   

   服务将在 stdio 上监听 MCP 请求。

身份验证

此服务使用标准的多用户令牌处理模式：

1. extraArgs.apiKey（推荐）： 在 MCP call_tool 请求期间，将用户专属的 Alpha Vantage API 密钥放入 extraArgs 对象的 apiKey 字段中传递。此密钥不属于工具的架构。
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 客户端实例的间隔（毫秒）	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。请核实。）