Servidor MCP para la API Alpha Vantage (@missionsquad/avantage)

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) que envuelve la biblioteca @missionsquad/avantage , exponiendo las funcionalidades de la API Alpha Vantage como herramientas para los modelos de aprendizaje de idiomas (LLM).

Descripción general

Este servidor permite a los LLM interactuar con la API Alpha Vantage para recuperar datos financieros, incluidos:

• Datos básicos de acciones (series temporales, cotizaciones, búsqueda)

• Datos fundamentales (descripción de la empresa, finanzas, calendarios)

• Datos de Forex (FX)

• Datos de criptomonedas

• Datos de materias primas

• Indicadores económicos

• Indicadores técnicos

• Inteligencia Alfa (Noticias, Sentimientos, etc.)

• Datos de opciones (Premium)

Aprovecha la biblioteca TypeScript @missionsquad/avantage y sigue la arquitectura de la plantilla de servidor MCP genérica, incluido el manejo de claves API multiusuario y la gestión de recursos para instancias de cliente AVantage .

Características principales:

• Cobertura integral: implementa herramientas MCP para casi todas las funciones disponibles en la biblioteca @missionsquad/avantage .

• Soporte multiusuario: maneja claves API de Alpha Vantage de forma segura a través de extraArgs (preferido) o recurriendo a variables de entorno.

• Administración de recursos: administra de manera eficiente las instancias de cliente AVantage mediante ResourceManager .

• Fuertemente tipado: creado con TypeScript, aprovechando los tipos de @missionsquad/avantage y los esquemas Zod para los parámetros de las herramientas.

• Interfaz MCP estándar: utiliza @missionsquad/fastmcp para la comunicación MCP.

Related MCP server: Zentickr - Yahoo Finance MCP Server

Empezando

Prerrequisitos

• Node.js v20 o posterior

• npm o hilo

• Una clave API de Alpha Vantage (Obtén una aquí )

Configuración

1. Clonar o copiar: Clonar este repositorio o copiar los archivos.

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

2. Dependencias de instalación:

   npm install
   # or
   yarn install

3. Configurar entorno:

   • Copiar .env.example a .env .

   • Edite .env y configure API_KEY con su clave API de Alpha Vantage.

   • Opcionalmente, configure AV_PREMIUM=true si tiene una suscripción premium.

   • Ajuste LOG_LEVEL o RESOURCE_CLEANUP_INTERVAL si es necesario.

4. Construir el proyecto:

   npm run build
   # or
   yarn build

5. Iniciar el servidor:

   npm start
   # or
   yarn start

   El servidor escuchará las solicitudes MCP en stdio.

Autenticación

El servidor utiliza el patrón estándar de manejo de tokens multiusuario:

1. extraArgs.apiKey (Recomendado): Pase la clave de API de Alpha Vantage específica del usuario en el campo apiKey del objeto extraArgs durante la solicitud call_tool de MCP. Esta clave no forma parte del esquema de la herramienta.

2. .env Fallback: si no se proporciona extraArgs.apiKey , el servidor utiliza el valor API_KEY del archivo .env .

Herramientas disponibles

Este servidor expone numerosas herramientas que corresponden a los métodos de la biblioteca @missionsquad/avantage . Las herramientas generalmente se denominan module_method (p. ej., coreStock_intraday , fundamentalData_companyOverview ).

Consulte la documentación de Alpha Vantage y los tipos de la biblioteca @missionsquad/avantage ( src/types/* dentro de la biblioteca) para obtener detalles sobre los parámetros y las estructuras de retorno.

Ejemplo de llamada a herramienta (solicitud MCP conceptual):

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

Categorías de herramientas (módulos):

• alphaIntelligence_*

• commodities_*

• coreStock_*

• crypto_*

• economicIndicators_*

• forex_*

• fundamentalData_*

• optionsData_* (Premium)

• technicalIndicators_*

Utilice el comando MCP list_tools para obtener la lista completa de herramientas disponibles, sus descripciones y esquemas de parámetros.

Configuración

Configurar mediante el archivo .env :

Estructura del proyecto

Sigue la estructura genérica de la plantilla del servidor MCP. Archivos clave:

• src/index.ts : Punto de entrada del servidor principal, definiciones de herramientas.

• src/config.ts : Carga de configuración.

• src/logger.ts : Utilidad de registro.

• src/resource-manager.ts : Administra instancias AVantage .

• src/schemas.ts : Esquemas Zod para parámetros de herramientas.

• .nexus/ : Documentación de Nexus.

Documentación de Nexus

• .nexus/features/avantage_integration/feature.md

• .nexus/architecture/server_structure.md

• .nexus/guides/using_avantage_tools.md

• .nexus/decisions/decision_log.md

Licencia

MIT (Suponiendo que la licencia de la plantilla es MIT. Verificar).