Pular para o conteúdo
PT
Obter chave API
Explorar documentação

Integrações

Construa um cliente MCP

Conecte um aplicativo Node.js ao FlashData, verifique o acesso e salve seu primeiro resultado de busca Google.

Nesta página

Antes de começar

Use Node.js 22.18+, npm e uma chave API com permissão google_search. Sua aplicação é o cliente MCP; FlashData hospeda o servidor em https://data.flashdata.dev/mcp. O exemplo verifica a conexão de graça, envia uma busca com --search e lê seu resultado salvo com --read.

1. Instale o cliente SDK

Criar um novo projeto. No Windows, use npm.cmd se npm.ps1 estiver bloqueado.

Novo projeto
node --version
mkdir flashdata-mcp-demo
cd flashdata-mcp-demo
npm init -y
npm install --save-exact @modelcontextprotocol/[email protected]

2. Defina sua chave API

Coloque a chave neste terminal, ou deixe seu agente injetar FLASHDATA_API_KEY de sua loja secreta. O cliente o envia como um cabeçalho X-API-Key para o ponto final do HTTP. Execute o código em um processo local ou servidor.

Definir sua chave
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY

3. Salve e verifique o cliente

Guarde o arquivo completo abaixo como mcp-client.mjs dentro de flashdata-mcp-demo, ao lado de package.json. Todos os comandos nesta página usam este arquivo. Ele descobre ferramentas, verifica os preços atuais e o equilíbrio, e coleta grandes resultados.

Salve mcp-client.mjs

flashdata-mcp-demo/mcp-client.mjs
import { mkdir, readFile, writeFile } from 'node:fs/promises';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'flashdata-first-task', version: '1.0.0' });
const output = 'mcp-search-output';
let searchAttempted = false;
function bodyOf(reply) {
  const body = reply.structuredContent ?? JSON.parse(
    reply.content.filter(item => item.type === 'text').map(item => item.text).join(''));
  if (reply.isError) {
    throw new Error(JSON.stringify({
      code: body.code, http_status: body.http_status, request_id: body.request_id,
    }));
  }
  return body;
}
async function completeResult(reply) {
  let body = bodyOf(reply);
  if (!body.result_id) return body;
  const id = body.result_id;
  let text = body.chunk;
  let offset = body.next_offset;
  while (offset !== null) {
    body = bodyOf(await client.callTool({
      name: 'get_result', arguments: { result_id: id, offset },
    }));
    if (body.result_id !== id || body.offset !== offset ||
        (body.next_offset !== null && body.next_offset <= offset)) {
      throw new Error('Invalid continuation; preserve ' + output + '/mcp-receipt.json.');
    }
    text += body.chunk;
    offset = body.next_offset;
  }
  return JSON.parse(text);
}
function printResult(response, saved = false) {
  if (response.status !== 'done') throw new Error('Search is not done; inspect ' + output + '/result.json.');
  const hits = (response.results ?? []).flatMap(page => page.organic ?? []);
  for (const hit of hits) console.log(hit.title ?? '(no title)', hit.link ?? '(no URL)', hit.snippet ?? '');
  if (!hits.length) console.log('No organic results returned.');
  console.log(saved ? 'Original credits used:' : 'Credits used:', response.usage?.credits ?? 'not reported');
  console.log('Saved response: ' + output + '/result.json');
}
async function main() {
  const mode = process.argv[2] ?? '--check';
  if (process.argv.length > 3 || !['--check', '--search', '--read'].includes(mode)) {
    throw new Error('Usage: node mcp-client.mjs [--check | --search | --read]');
  }
  if (mode === '--read') {
    printResult(JSON.parse(await readFile(output + '/result.json', 'utf8')), true);
    console.log('Local file only. No API call or new charge.');
    return;
  }
  const key = process.env.FLASHDATA_API_KEY?.trim();
  if (!key) throw new Error('Set FLASHDATA_API_KEY in this terminal.');
  await client.connect(new StreamableHTTPClientTransport(
    new URL('https://data.flashdata.dev/mcp'),
    { requestInit: { headers: { 'X-API-Key': key } } },
  ));
  const names = [];
  let cursor;
  do {
    const page = await client.listTools(cursor ? { cursor } : {});
    names.push(...page.tools.map(tool => tool.name));
    cursor = page.nextCursor;
  } while (cursor);
  for (const name of ['google_search', 'get_balance', 'get_pricing']) {
    if (!names.includes(name)) throw new Error('Missing tool: ' + name);
  }
  const balance = bodyOf(await client.callTool({ name: 'get_balance', arguments: {} }));
  const pricing = bodyOf(await client.callTool({
    name: 'get_pricing', arguments: { source: 'google_search', request_count: 1 },
  }));
  const price = pricing.prices.find(p => p.source === 'google_search' && p.available);
  const cost = price?.estimatedCredits;
  if (!Number.isFinite(cost) || cost < 0) throw new Error('No current price; stop here.');
  if (!Number.isFinite(balance.availableCredits)) throw new Error('No current balance; stop here.');
  console.log('Available credits:', balance.availableCredits, 'One search:', cost);
  if (mode === '--check') {
    console.log('Connected. No paid query submitted.');
    console.log(balance.availableCredits >= cost ? 'Ready for one search.' : 'Add credits before searching.');
  } else {
    if (balance.availableCredits < cost) throw new Error('Insufficient credits.');
    // Reserve a new directory before submitting. A repeat run stops here.
    await mkdir(output);
    const request = {
      name: 'google_search',
      arguments: { query: 'battery recycling research', num: 5, mode: 'realtime' },
    };
    await writeFile(output + '/request.json', JSON.stringify(request, null, 2), { flag: 'wx' });
    searchAttempted = true;
    const reply = await client.callTool(request, undefined, { timeout: 120_000 });
    await writeFile(output + '/mcp-receipt.json', JSON.stringify(reply, null, 2), { flag: 'wx' });
    const response = await completeResult(reply);
    await writeFile(output + '/result.json', JSON.stringify(response, null, 2), { flag: 'wx' });
    printResult(response);
  }
}
try {
  await main();
} catch (error) {
  console.error(error instanceof Error ? error.message : String(error));
  if (searchAttempted) console.error('Search was attempted. Preserve saved files and check History before retrying.');
  else console.error('No search submitted by this run.');
  process.exitCode = 1;
} finally {
  await client.close();
}

Verifique a conexão de graça

Corra de flashdata-mcp-demo no terminal onde você ajustou a chave. Espere créditos disponíveis, uma busca e conectados. Nenhuma consulta paga submetida. A linha final diz se o saldo cobre uma busca. Um equilíbrio zero não significa que a autenticação falhou.

Em flashdata-mcp-demo
node mcp-client.mjs

4. Execute sua primeira pesquisa

Use o arquivo que você salvou no passo 3. A bandeira --search solicita uma busca Google para pesquisa de reciclagem de bateria. O cliente verifica o preço e o equilíbrio de novo, então salva a resposta e imprime links de origem e créditos usados.

Envie uma busca

Corra uma vez de flashdata-mcp-demo. O cliente cria o McP-busca-saída antes de enviar; se esse diretório já existe, ele pára para evitar repetir a tarefa.

Em flashdata-mcp-demo
node mcp-client.mjs --search

Inspecione o resultado salvo

Abra mcp-search-output/result.json. Espere status: done, results[].organic com títulos, links e trechos, e usage.credits. Resultados orgânicos vazios podem ser válidos. A resposta abaixo é abreviada e ilustrativa.

mcp-search-output/result.json
{
  "source": "google_search",
  "status": "done",
  "results": [
    {
      "organic": [
        {
          "title": "Battery recycling research",
          "link": "https://example.org/recycling",
          "snippet": "An example search excerpt."
        }
      ]
    }
  ],
  "usage": {
    "credits": 0.02
  },
  "http_status": 200,
  "request_id": "example-request-id"
}

Leia o resultado salvo novamente

Execute do mesmo diretório do projeto. Isso lê result.json e imprime os links de origem e créditos originais usados. Ele não precisa de chave API, não faz nenhum pedido de rede e não envia outra busca.

Em flashdata-mcp-demo
node mcp-client.mjs --read

Recupere uma tarefa interrompida

Mantenha a pesquisa-produção se uma busca parar antes de imprimir os resultados. Um result.json desaparecido não prova que o pedido falhou. Inspecione os arquivos abaixo e verifique History antes de decidir se outra busca é necessária.

Arquivo em MCP-search-outputO que ela diz a você
request.jsonA chamada de ferramentas pretendida. Salvo antes da submissão, não confirma que FlashData recebeu.
mcp-receipt.jsonA resposta original MCP, incluindo erros ou um result_id para continuação. Verifique isError e o corpo de resposta; HTTP 200 sozinho não é sucesso.
result.jsonA resposta reunida. Um status de feito está pronto para ler com --read; preservar request_id para solução de problemas.

Quão grandes são os resultados coletados

O cliente lê structuredContent, ou o texto JSON em conteúdo quando structuredContent está ausente. Ele verifica isError mesmo quando o transporte MCP retorna HTTP 200.

Quando uma resposta contém result_id, completeResult chama get_result com a mesma credencial e devolveu next_offset até ser null. Verifica a sequência, concatena pedaços e analisa o JSON completo. O recibo original fica em mcp-search-output/mcp-receipt.json..

Use este cliente em sua aplicação

TarefaO que mudar?
Faça uma busca diferenteMude request.arguments.query e saída em mcp-client.mjs para uma nova tarefa. Reutilize --read para a mesma tarefa completa; mantenha diretórios de saída anteriores.
Deixe seu modelo escolher uma ferramentaUse listTools para ler nomes, descrições e esquemas de entrada. Validar o nome e argumentos selecionados, então callTool sob a permissão da sua aplicação e política de gastos.
Corra em um horárioReutilize uma credencial própria do armazenamento secreto persistente. Mantenha um registro durável por slot de programação, leia a saída salva quando o mesmo slot repetir.
Conecte outros usuáriosEssa chave cobra a conta do dono. Use a credencial de cada usuário e isole seus resultados salvos. Uma integração OAuth também precisa de registro, consentimento e armazenamento de fichas, este exemplo API-chave não implementa esse fluxo.

Solução de problemas

ProblemaAção
ERR_MODULE_NOT_FOUNDExecutar npm instalação de flashdata-mcp-demo. Mantenha mcp-client.mjs ao lado de package.json e node_modules.
FLASHDATA_API_KEYDefina a variável no mesmo terminal ou processo que executa Node.js, então reexecute o nó mcp-client.mjs sem --search.
401Procure por uma chave expirada ou revogada. Restaure o acesso válido, então repita a verificação de conexão livre.
403Verifique a permissão da chave google_search e acesso à conta. Uma verificação de equilíbrio bem sucedida não prova que esta fonte é permitida.
402 / Insufficient creditsVerifique o saldo da conta e os preços atuais antes de enviar outra tarefa.
EEXISTUma tentativa anterior é dona do diretório de saída. Corra mcp-client.mjs --read se result.json estiver completo, caso contrário, inspecione seu recibo e History. Mantenha o diretório.
JSON com --readVerifique se você está em flashdata-mcp-demo e inspecione mcp-search-output/result.json. Se estiver faltando ou incompleto, siga Recupere uma tarefa interrompida, --read nunca envia uma busca.
429Espere pelo Retry-After quando for providenciado. Se uma busca foi tentada, verifique seus arquivos salvos e History antes de tentar novamente.
Tempo limite / result_unavailableFique com o pedido e o recibo. Verifique History ou um trabalho existente, uma continuação salva pode ter expirado.