
geostudy
io.github.CloudCorpRecords/geostudy
Free AI-visibility study catalogue: list, search and read study sheets and metric definitions.
Documentation
geostudy
A local doorway into Lightning's published catalogue of AI-visibility studies. geostudy holds no data itself: it answers tools/list on your machine from the captured tool definitions and forwards every read to the hosted Lightning service, handing back whatever the service returns, untouched.
The catalogue is free and read-only. The studies track how ChatGPT, Gemini and Claude answer people in Argentina and the Southern Cone — which brands get recommended, in what order, with which arguments and which sources — across banking, cosmetics, insurance, pharma, dermatology, rheumatology, tourism, hotels and running. You can list what exists, search it two different ways, open a study's free sheet, and read the definitions behind Lightning's metrics.
The tools
Seven of the eight tools the service publishes are served here. The eighth, comprar_estudio, performs an x402 pay-per-call purchase in USDC and is deliberately omitted from this rebuild — it is not listed, not callable through the MCP server, and has no CLI subcommand.
listar_estudios— Every available study, with industry, country, date, response count, findings and price. Takes no arguments.buscar_estudios— Search the studies by industry, topic, product, brand or country.q(the search text) is required.ver_ficha— The free sheet of one study: methodology, sample, models used, the question universe, and the index of analyses and findings (the numbers themselves are in the paid study).slugis required and must be one of the catalogue's study slugs.ver_metricas— What Lightning's metrics mean: Protagonismo IA, mention, order, Top1, citation, HHI, variability, survival, tone. Takes no arguments.como_comprar— The published explainer on how buying a study works: price, networks, payment wallet and the x402 steps, over HTTP or MCP. Reading it buys nothing.slugis optional.search— The English-interface search over the same catalogue; returns ids forfetch. Also finds the metric definitions (metricas) and the how-to-buy page (como-comprar).queryis required.fetch— The free sheet of a study by the idsearchreturned.idis required.
Tool names, titles and descriptions are served exactly as the service publishes them, Spanish text included.
Install and run
As an MCP server via npm:
npx -y @reneturcios/geostudy mcp
MCP client configuration:
{
"mcpServers": {
"geostudy": {
"command": "npx",
"args": ["-y", "@reneturcios/geostudy", "mcp"]
}
}
}
As a container:
docker run -i ghcr.io/cloudcorprecords/geostudy
docker run --rm ghcr.io/cloudcorprecords/geostudy listar_estudios '{}'
CLI
One binary serves both the command line and the MCP server. Each tool is a subcommand taking a single JSON string with that tool's arguments:
geostudy listar_estudios '{}'
geostudy buscar_estudios '{"q":"seguros de auto"}'
geostudy ver_ficha '{"slug":"banca-2026"}'
geostudy ver_metricas '{}'
geostudy como_comprar '{"slug":"banca-2026"}'
geostudy search '{"query":"car insurance Argentina"}'
geostudy fetch '{"id":"banca-2026"}'
geostudy --version
Exit codes: 0 when the forwarded call succeeds, 1 when the upstream result is an error, and 2 for usage problems such as an unknown subcommand or a malformed JSON argument.
Configuration
LIGHTNINGEO_MCP_URL— Overrides the upstream endpoint. The default is the pinned hosted endpoint,https://api.lightningeo.com/mcp. (The override variable is a reconstruction added by this rebuild.)
The Lightning registry record declares no headers on its remote, so geostudy sends no authentication header of any kind — the catalogue reads are keyless.
Upstream failures — a JSON-RPC error from the service, a non-2xx response, an unreadable body, or a request that fails outright — are reported to the caller as an error result whose text starts with geostudy error:.
How forwarding works
The first forwarded call opens a session: an initialize request (protocol version 2025-03-26), followed by a notifications/initialized notification, then the tools/call itself. If the service answers the initialize request with an Mcp-Session-Id header, that value is carried on every later request, and the open session is reused for the rest of the process. Replies are accepted either as plain JSON or as server-sent events. Successful results pass through verbatim, including any isError flag and any extra fields the service includes.
Development
npm install
npm run build # tsc -> dist/ (dist/cli.js is the bin)
npm test # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev # run the CLI from source
The test suite checks the served tool list against the captured surface, asserts the omitted purchase tool's absence at the registry, MCP and CLI levels, exercises the session handshake and its reuse, asserts that no Authorization header is sent under any environment, and verifies that arguments go upstream untouched and results come back untouched.
License
MIT — see LICENSE. Copyright (c) 2026 Rene Turcios.
@reneturcios/geostudynpm install @reneturcios/geostudyghcr.io/cloudcorprecords/geostudy:0.1.0docker pull ghcr.io/cloudcorprecords/geostudy:0.1.0:undefinedRelated Servers
io.github.CloudCorpRecords/abandoncheck
Judge whether a dependency is maintained, from factual signals: releases, commits, archival.
io.github.CloudCorpRecords/actionbridge
Zapier exposed actions as MCP tools via a generic action runner.
io.github.CloudCorpRecords/actionpin
GitHub Actions supply-chain hardener: audit workflows for unpinned actions and build a SHA pin plan.