BlackForge

@blackforge-so/mcp

Um servidor stdio Model Context Protocol que coloca os dados de mercado da BlackForge nas mãos do seu agente. Todo o mercado de criptomoedas, em tempo real — nove exchanges à vista (binance, bitget, bybit, coinbase, gate, kraken, kucoin, mexc, okx) e todas as colunas que ele mede, por par, em cada janela fechada de 5 minutos.

Cada coluna é uma medição com uma definição — profundidade e formato do livro de ordens, tempo de vida da liquidez em repouso, volume explicado por negociações vs. implícito no livro, spreads, contexto do mercado — retornada em contexto para que um agente possa ler a microestrutura bruta diretamente. É um cliente leve sobre a API pública BlackForge /v1; ele não armazena nada e não reformata nada.

Início rápido

Adicione o servidor ao seu cliente MCP e cole uma chave de API. Claude Desktop (claude_desktop_config.json) ou Claude Code (.mcp.json):

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

Sem etapa de instalação — o npx -y @blackforge-so/mcp baixa e executa o servidor sob demanda.

Onde obter uma chave

Gere uma chave em app.blackforge.so → API. O servidor nunca cria chaves; ele lê BLACKFORGE_API_KEY do seu ambiente. A ferramenta blackforge_catalog funciona sem chave, para que você possa verificar a instalação antes de colar uma.

Ferramentas

Ferramenta	Retorna
blackforge_catalog	Todas as exchanges e todas as definições de colunas — 9 exchanges, e metricCount é a contagem atual de colunas. Sem chave. Chame primeiro para aprender os identificadores válidos de exchange e metric.
blackforge_symbols	Os pares de negociação que uma exchange lista, ex.: ["BTCUSDT", …].
blackforge_latest	A janela de 5 minutos mais recente concluída para um (exchange, symbol) — um objeto values de coluna → número, com ts em epoch-ms. Passe columns para restringir.
blackforge_series	Uma série temporal para uma coluna em um intervalo: pontos { ts, value } em ordem crescente em 5m, 1h ou 1d. Limitada a 50.000 pontos.
blackforge_usage	As contagens recentes de solicitações da chave e a cota mensal restante de linhas.

Os direitos do plano (quais exchanges, colunas e intervalos uma chave pode ler) são aplicados pela API. Quando uma coluna é removida porque seu plano não a inclui, o resultado da ferramenta a reporta em columnsOmitted para que o agente entenda por que uma chave está ausente. Restrições de exchange ou intervalo retornam como um erro claro da ferramenta com o status HTTP e a mensagem do servidor (incluindo a URL de upgrade, verbatim).

Gráficos

O blackforge_series também inclui um gráfico interativo. Um host que implementa a extensão MCP Apps (io.modelcontextprotocol/ui) renderiza o resultado como um gráfico de linhas com buckets sinalizados desenhados na mesma convenção que o console BlackForge usa; qualquer outro host vê exatamente o JSON que via antes.

Nada no contrato da ferramenta muda. O payload do gráfico viaja no _meta do resultado, que é metadados de protocolo e não chega a nenhum modelo, então o content[0].text é byte-idêntico independentemente de o seu host renderizar widgets — o custo de tokens de uma série é o mesmo de qualquer forma. Isso é deliberado: structuredContent seria o local óbvio, mas o MCP central trata esse campo como dados de resultado produzidos pelo servidor, e um host sem suporte a Apps pode entregá-lo ao modelo, dobrando o custo de uma série grande.

O gráfico é um único arquivo HTML autocontido com uPlot e todo o CSS embutido, porque o MCP Apps renderiza sob uma CSP com negação por padrão, onde um <script> externo simplesmente nunca carregaria. Ele é somente leitura e nunca chama de volta o servidor: desenha os pontos que recebeu e não pode gastar sua cota de linhas pelas suas costas. Séries com mais de 2.000 pontos são reduzidas apenas para o gráfico — a ferramenta ainda retorna todos os pontos — e o payload informa isso em vez de afinar a linha silenciosamente.

Qualidade dos dados

Quando a API reporta a qualidade de medição de uma linha, o blackforge_latest a transmite como um objeto quality (flags nomeando o que deu errado na janela, contaminates listando quais números ele sinaliza) além de um qualityNote em linguagem simples. O blackforge_series agrega isso em um único qualitySummary ({ flaggedBuckets, of, flags }) em vez de repetir em cada ponto. Ambas as chaves são omitidas completamente quando nada é sinalizado, e um quality.raw de 32768 significa que a linha é anterior ao controle de qualidade e nunca foi avaliada — desconhecida, não ruim. A tabela de decodificação de sinalizações está na métrica qualityFlags em blackforge_catalog, como um array bits; este servidor a lê de lá e nunca mantém uma cópia própria.

Configuração

Variável de ambiente	Padrão	Finalidade
BLACKFORGE_API_KEY	(nenhum)	Sua chave. Necessária para todas as ferramentas, exceto blackforge_catalog.
BLACKFORGE_BASE_URL	https://api.blackforge.so	Base da API. Os caminhos são anexados como /v1/.... Substitua para uma API auto-hospedada ou de desenvolvimento local (ex.: http://localhost:3001/api).

Desenvolvimento local

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

O build executa o tsup primeiro e a compilação vite do widget em segundo, e a ordem é essencial: o clean do tsup apaga todo o dist/, então invertê-los exclui o widget e deixa o servidor servindo um recurso que não existe.

O teste de integração inicia o servidor compilado via stdio e o conduz com o cliente MCP. Suas asserções de dados precisam de uma API BlackForge local em http://localhost:3001/api; sem uma, essas asserções são ignoradas e as verificações de listagem de ferramentas ainda são executadas.

Licença

MIT