SiftingIO MCP

siftingio-mcp

Este é um servidor Model Context Protocol (MCP) que coloca o SDK de dados de mercado da SiftingIO (@siftingio/sdk) ao alcance do seu assistente de IA. Depois de executá-lo, o modelo pode obter preços ao vivo, explorar fundamentos da SEC/EDGAR, buscar barras OHLCV, consultar participações 13F, verificar o status do mercado e examinar o calendário macroeconômico — tudo como ferramentas.

Configuração

npm install
npm run build

Você precisará de uma chave de API, que pode obter em https://sifting.io:

export SIFTING_API_KEY=sft_...

Se precisar apontar para um backend diferente, SIFTING_BASE_URL e SIFTING_WS_URL estão disponíveis para substituir os padrões.

Trabalhando localmente? Copie .env.example para .env — npm run dev e npm start o detectam automaticamente (o Node faz o carregamento via --env-file-if-exists). Ao conectar isso a um cliente MCP real, porém, passe a chave pelo bloco env do servidor, em vez de um arquivo (há um exemplo mais adiante).

Execução

• npm run build — compilar TypeScript em dist/.
• npm start — executar o servidor compilado (node dist/index.js) via stdio.
• npm run start:http — executá-lo via Streamable HTTP (node dist/http.js).
• npm run dev / npm run dev:http — executar direto do código-fonte com tsx, sem etapa de build.
• npm test — executar a suíte vitest (adicione npm run test:watch para mantê-la em execução).
• npm run lint / npm run format — ESLint (typescript-eslint) e Prettier.
• npm run typecheck — tsc --noEmit.

Em cada push e PR, o CI (.github/workflows/ci.yml) percorre o mesmo percurso: verificação de formatação → lint → typecheck → build → teste.

Uma coisa que vale saber: o servidor fala JSON-RPC via stdio, então o stdout pertence inteiramente ao protocolo. Qualquer coisa de diagnóstico vai para o stderr para não atrapalhar.

Inspecionar interativamente

Quer testar manualmente? O inspetor MCP é a maneira mais fácil:

SIFTING_API_KEY=sft_... npx @modelcontextprotocol/inspector node dist/index.js

Transporte HTTP (Streamable HTTP)

Se você estiver executando isso em algum lugar remoto ou hospedado, use o transporte Streamable HTTP do MCP em vez de stdio:

SIFTING_API_KEY=sft_... PORT=3000 npm run start:http
# → MCP endpoint at http://127.0.0.1:3000/mcp  (POST messages, GET SSE, DELETE session)

É stateful: cada cliente recebe sua própria sessão (rastreada pelo cabeçalho mcp-session-id) e seu próprio McpServer, enquanto a conexão upstream da SiftingIO é compartilhada em todo o processo. Como medida de segurança, ele só vincula ao loopback e rejeita Origins de navegadores não locais — essa é a proteção contra rebinding de DNS. Defina a porta com PORT (ou MCP_HTTP_PORT); o padrão é 3000.

Se quiser autenticação, defina MCP_AUTH_TOKEN e o servidor exigirá Authorization: Bearer <token> em cada solicitação (qualquer coisa ausente ou errada recebe 401). Combine isso com um proxy reverso que lida com TLS e o token, e você pode expor o servidor com segurança além do localhost:

MCP_AUTH_TOKEN=s3cret SIFTING_API_KEY=sft_... npm run start:http

Então basta apontar qualquer cliente MCP compatível com HTTP para http://127.0.0.1:3000/mcp:

claude mcp add --transport http siftingio http://127.0.0.1:3000/mcp

Uso com um cliente MCP

Coloque isso na configuração do seu cliente — o claude_desktop_config.json do Claude Desktop, por exemplo, ou use claude mcp add se estiver no Claude Code:

{
  "mcpServers": {
    "siftingio": {
      "command": "node",
      "args": ["/absolute/path/to/siftingio-mcp/dist/index.js"],
      "env": { "SIFTING_API_KEY": "sft_..." }
    }
  }
}

Ferramentas (36)

Namespace	Ferramentas
Live (snapshot)	last_trade, last_quote, last_tvl
Stocks	stocks_search, stocks_profile, stocks_filings, stocks_filing, stocks_sections, stocks_section, stocks_risk_factors_diff, stocks_ratios, stocks_earnings, stocks_financials, stocks_financial_concept, stocks_insiders, stocks_ownership, stocks_events, stocks_compensation, stocks_screener, stocks_bars
Crypto / Forex	crypto_bars, forex_bars
DEX	dex_wallet
Markets	markets_list, markets_status_all, markets_status, markets_hours, markets_calendar
Filers	filers_holdings
Macro	economic_calendar_list
Live (stream)	ws_subscribe, ws_unsubscribe, ws_poll, ws_collect, ws_status, ws_disconnect

Alguns padrões merecem destaque:

Ferramentas paginadas usam cursor/limit e retornam um meta.next_cursor para buscar a próxima página. As ferramentas de lista stocks_* — stocks_filings, stocks_earnings, stocks_insiders, stocks_ownership, stocks_events, stocks_compensation — também entendem max_items: defina-o e elas farão paginação automática, coletando até esse número de itens entre páginas em uma única chamada.

As ferramentas de alto tráfego (last_trade, last_quote, last_tvl, stocks_profile, stocks_search) vêm com um esquema de saída e retornam structuredContent junto com o texto legível por humanos, para que os clientes também possam lê-las de forma programática.

Cada ferramenta também carrega anotações do MCP. As ferramentas de dados são readOnlyHint: true (e openWorldHint: true, pois alcançam a API externa), enquanto as ferramentas WebSocket que alteram o estado da conexão são readOnlyHint: false, destructiveHint: false.

Os resultados têm limite de tamanho de aproximadamente 60 mil caracteres (veja MAX_RESULT_CHARS em src/util.ts). Quando um endpoint pesado — XBRL completo, screeners, barras OHLCV — retorna mais que isso, o servidor corta o maior array e adiciona uma nota _truncated explicando como restringir a consulta.

Streaming WebSocket ao vivo

Streaming é o caso complicado: não se encaixa perfeitamente em uma única solicitação/resposta. Então o servidor mantém um WebSocket persistente aberto, armazena os frames conforme chegam, e as ferramentas apenas leem desse buffer. Os canais (o campo product) são cex (cripto), dex (negociações DEX), fx (forex), us (ações dos EUA) e tvl (TVL de pools DEX).

Há duas maneiras de trabalhar com isso:

• Assinar + consultar, para streams contínuos: chame ws_subscribe uma vez e continue chamando ws_poll. A primeira consulta fornece um histórico recente; alimente o next_seq retornado de volta como after_seq e você receberá apenas frames mais novos a partir daí. ws_status mostra a conexão e o que está assinado, e ws_disconnect encerra tudo.

• Coletar, para uma captura rápida: ws_collect assina, espera até duration_ms (ou até ver max frames), retorna o que capturou e limpa qualquer assinatura que precisou criar. Perfeito para "pegue alguns segundos de BTCUSD."

A conexão se reconecta sozinha e reproduz suas assinaturas quando isso acontece. O buffer é uma janela deslizante, então os frames mais antigos eventualmente caem — e quando caem, você fica sabendo por meio de dropped/gap.

Prompts

Estes são fluxos de trabalho guiados e com várias ferramentas que seu cliente pode exibir como comandos de barra:

• company_snapshot (ticker) — reúne stocks_profile, stocks_ratios, o stocks_filings mais recente e last_trade em um único briefing.

• compare_companies (tickers) — alinha vários tickers lado a lado nos principais indicadores.

• market_now — o que está aberto e fechado agora, além dos eventos macroeconômicos de alto impacto que estão por vir.

Logging e encerramento

O servidor anuncia o recurso de logging do MCP e envia notifications/message estruturados ao cliente sempre que algo acontece com a conexão (abertura/fechamento/reconexão/erro do WebSocket) ou no encerramento — e também espelha tudo isso no stderr.

Quando recebe um SIGINT ou SIGTERM, ele fecha o WebSocket ao vivo e encerra o servidor de forma limpa antes de sair.