BlackForge

@blackforge-so/mcp

Un servidor stdio de Model Context Protocol que pone los datos de mercado de BlackForge en manos de tu agente. Todo el mercado cripto, en tiempo real — nueve exchanges al contado (binance, bitget, bybit, coinbase, gate, kraken, kucoin, mexc, okx) y cada columna que mide, por par y por ventana cerrada de 5 minutos.

Cada columna es una medición con una definición — profundidad y forma del libro de órdenes, tiempos de vida de la liquidez en reposo, volumen explicado por operaciones vs. implicado por el libro, spreads, contexto de todo el mercado — devuelta en contexto para que un agente pueda leer la microestructura cruda directamente. Es un cliente ligero sobre la API pública de BlackForge /v1; no almacena nada y no reformatea nada.

Inicio rápido

Añade el servidor a tu cliente MCP y pega una clave de API. Claude Desktop (claude_desktop_config.json) o Claude Code (.mcp.json):

{
  "mcpServers": {
    "blackforge": {
      "command": "npx",
      "args": ["-y", "@blackforge-so/mcp"],
      "env": { "BLACKFORGE_API_KEY": "bf_live_your_key" }
    }
  }
}

Sin paso de instalación — npx -y @blackforge-so/mcp descarga y ejecuta el servidor bajo demanda.

Dónde obtener una clave

Genera una clave en app.blackforge.so → API. El servidor nunca crea claves; lee BLACKFORGE_API_KEY de su entorno. La herramienta blackforge_catalog funciona sin clave, para que puedas verificar la instalación antes de pegar una.

Herramientas

Herramienta	Devuelve
blackforge_catalog	Cada exchange y cada definición de columna — 9 exchanges, y metricCount es el recuento de columnas en vivo. Sin clave. Llámalo primero para aprender los identificadores válidos de exchange y metric.
blackforge_symbols	Los pares de trading que lista un exchange, p. ej. ["BTCUSDT", …].
blackforge_latest	La ventana de 5 minutos completada más reciente para un (exchange, symbol) — un objeto values de columna → número, con ts en epoch-ms. Pasa columns para acotarlo.
blackforge_series	Una serie temporal para una columna en un rango: puntos { ts, value } ascendentes en 5m, 1h o 1d. Limitada a 50.000 puntos.
blackforge_usage	Los recuentos recientes de solicitudes de la clave y la cuota mensual de filas restante.

Los derechos del plan (qué exchanges, columnas e intervalos puede leer una clave) los aplica la API. Cuando se descarta una columna porque tu plan no la incluye, el resultado de la herramienta lo informa en columnsOmitted para que el agente entienda por qué falta una clave. Las restricciones a nivel de exchange o intervalo vuelven como un error claro de herramienta que lleva el estado HTTP y el mensaje del servidor (incluida la URL de actualización, textual).

Gráficos

blackforge_series también incluye un gráfico interactivo. Un host que implemente la extensión MCP Apps (io.modelcontextprotocol/ui) renderiza el resultado como un gráfico de líneas con los buckets marcados dibujados con la misma convención que usa la consola de BlackForge; cualquier otro host ve exactamente el JSON que veía antes.

Nada del contrato de la herramienta cambia. La carga del gráfico viaja en el _meta del resultado, que es metadatos de protocolo y no llega a ningún modelo, así que content[0].text es byte-idéntico tanto si tu host renderiza widgets como si no — el coste de tokens de una serie es el mismo en ambos casos. Es deliberado: structuredContent habría sido el lugar obvio, pero el MCP central trata ese campo como datos de resultado producidos por el servidor, y un host sin soporte de Apps podría pasárselo al modelo, duplicando el coste de una serie grande.

El gráfico es un único archivo HTML autocontenido con uPlot y todo el CSS incrustado, porque MCP Apps renderiza bajo una CSP de denegación por defecto donde un <script> externo simplemente nunca cargaría. Es de solo lectura y nunca llama de vuelta al servidor: dibuja los puntos que se le dieron y no puede gastar tu cuota de filas a tus espaldas. Las series de más de 2.000 puntos se diezman solo para el gráfico — la herramienta sigue devolviendo todos los puntos — y la carga lo dice en lugar de adelgazar la línea silenciosamente.

Calidad de datos

Cuando la API informa de la calidad de medición de una fila, blackforge_latest la transmite como un objeto quality (flags nombra qué falló en la ventana, contaminates lista qué cifras marca) más un qualityNote en lenguaje natural. blackforge_series lo agrega en un único qualitySummary ({ flaggedBuckets, of, flags }) en lugar de repetirlo en cada punto. Ambas claves se omiten por completo cuando no se marca nada, y un quality.raw de 32768 significa que la fila es anterior al carril de calidad y nunca se evaluó — desconocido, no malo. La tabla de decodificación de marcas vive en la métrica qualityFlags de blackforge_catalog, como un array bits; este servidor la lee de ahí y nunca guarda una copia propia.

Configuración

Variable de entorno	Predeterminado	Propósito
BLACKFORGE_API_KEY	(ninguna)	Tu clave. Requerida para toda herramienta excepto blackforge_catalog.
BLACKFORGE_BASE_URL	https://api.blackforge.so	Base de la API. Las rutas se añaden como /v1/.... Sobrescríbela para una API autoalojada o de desarrollo local (p. ej. http://localhost:3001/api).

Desarrollo local

npm install
npm run build     # → dist/index.js (ESM, executable) + dist/widget/chart.html
npm test          # client unit tests + a stdio integration test

build ejecuta primero tsup y después la compilación de vite del widget, y el orden es crucial: el clean de tsup borra todo dist/, así que invertirlos elimina el widget y deja al servidor sirviendo un recurso que no existe.

La prueba de integración lanza el servidor compilado sobre stdio y lo maneja con el cliente MCP. Sus aserciones de datos necesitan una API local de BlackForge en http://localhost:3001/api; sin una, esas aserciones se omiten y las comprobaciones de listado de herramientas siguen ejecutándose.

Licencia

MIT