MCP Avantage

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.

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):

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).