convez.ai
MCP ServerDados & AnalyticsIntermediário
rschoenbeck

Polling Data MCP

rschoenbeck/polling-data-mcp

Acesso padronizado a dados de pesquisa pública americana via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP em Python que expõe ferramentas para buscar e baixar dados de pesquisas eleitorais e surveys públicos dos EUA. Integra-se com agentes de análise via Model Context Protocol, entregando datasets estruturados sem saturar o contexto do modelo.

Instalação

$npx convez-ai rschoenbeck/polling-data-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
0.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Análise de tendências eleitorais e opinião pública
  • Pesquisa social longitudinal com dados GSS (1972-2024)
  • Integração de datasets públicos em pipelines de análise de IA

Veredito

Implementação técnica rigorosa de um broker de dados que prioriza auditoria e qualidade sobre amplitude. Ideal para análises sérias que exigem proveniência verificada e acesso fora-de-banda a datasets grandes, evitando sobrecarga de contexto.

README

A tradução para o português deste README ainda está na fila.

polling-data-mcp

CI

A read-only Model Context Protocol (MCP) server that lets an AI agent discover and pull public U.S. survey data — without the dataset ever passing through the model.

MCP is the open standard for connecting AI assistants (such as Claude) to outside tools and data. This project is one such tool. It exposes a small, fixed catalog of public polling and survey datasets and hands them to an agent in a clean, standardized shape.

The design is narrow on purpose. The server brokers data — it standardizes format and provenance, never meaning. It does not interpret, filter, summarize, or reshape anything, and it makes no AI/model calls of its own. It gives the agent a structured description of a dataset (its columns, license, and origin), and serves the actual rows out of band: the agent reads them straight into its own analysis environment, so a multi-megabyte table never gets stuffed into the model's limited context window.

Concretely, each dataset is returned as a Frictionless Tabular Data Package descriptor — a portable, standard schema-plus-provenance format — and the rows are served as an MCP resource the client fetches on demand.

Data sources

Two sources are live today — both fully public, free, and requiring no account:

SourceWhat it isStatusAuth
Harvard DataverseA large open-data repository hosting thousands of social-science datasets.livenone (public)
General Social Survey (GSS)A flagship long-running survey of U.S. adults, run since 1972 by NORC at the University of Chicago.livenone

This is the complete source list, and it is intentionally small. The whole point of the broker is to be a fixed, auditable whitelist rather than a general-purpose crawler — so a source only qualifies if it is fully public and offers machine-readable access. Dataverse and GSS both clear that bar.

Notes for researchers

A few things to keep in mind about coverage:

  • GSS is a curated subset, not the full archive. The broker ships specific annual cross-sections — currently the 2010, 2012, 2014, 2016, 2018, 2021, 2022, and 2024 waves — each with hand-verified provenance (survey mode and field dates). GSS publishes no search API, so the catalog is maintained by hand rather than discovered dynamically.
  • GSS survey mode changed over this span, which affects comparability. 2010–2018 are the traditional in-person (face-to-face) cross-sections; 2021 shifted to push-to-web during the pandemic; 2022 and 2024 use a mixed mode (mail-to-web and in-person, supplemented by phone). Mode shifts can move measured estimates, so treat cross-year comparisons across the 2021 boundary with care.
  • GSS rows are faithful coded values. They come straight from the original SPSS files, including the survey's own missing-data sentinels. The broker does not recode or label them; this is deferred to clients.

Requirements

  • Python ≥ 3.13
  • uv

Setup

uv sync                                    # install deps from pyproject.toml + uv.lock

No credentials are required. The server makes no model calls (no ANTHROPIC_API_KEY), and public Dataverse data needs no auth. An optional DATAVERSE_API_TOKEN (see .env.example) is read only if present and is unused for public datasets.

Running the server

uv run polling-data-mcp                                                # stdio (default)
uv run polling-data-mcp --transport http --host 127.0.0.1 --port 8000  # streamable HTTP
uv run polling-data-mcp --refresh-catalog                              # rebuild local indexes, then exit

Both transports expose the same tools. --refresh-catalog rebuilds the local lexical index for index-backed sources (GSS), then exits; Dataverse needs no index (it uses its native search API).

The HTTP transport enables DNS-rebinding protection: it validates the request Host header against an allowlist that, by default, only admits loopback hosts. A client connecting under a different hostname (e.g. a Docker container reaching the host as host.docker.internal) is rejected with 421 Misdirected Request until that host is allowed. Bind to 0.0.0.0 and allow the client's host:

uv run polling-data-mcp --transport http --host 0.0.0.0 --port 8000 \
  --allowed-host host.docker.internal:8000

--allowed-host is repeatable; an entry without a port (--allowed-host host.docker.internal) allows any port. Loopback clients keep working without it.

Tools and resources

The server exposes three tools:

ToolReturns
list_sources()The whitelisted sources and their lifecycle status.
search_datasets(query, source=None)Ranked dataset descriptors. source=None fans out across all live sources; an unmatched query returns [], not an error.
describe_dataset(source, dataset_id)A Frictionless package descriptor: provenance, license, source URL, and one tabular-data-resource per tabular file (its column schema + a resource path). No rows.

Rows are served by a resource, not a tool. The address scheme is source-agnostic:

pollingdata://{source}/{dataset_id}/{file_id}

A client reads the path carried on each tabular resource in a describe_dataset descriptor; the broker fetches the file at read time — egress-checking every hop and enforcing byte/timeout caps — and streams the rows back with a tabular media type. A handled read-time failure surfaces as a protocol error whose message is prefixed with a typed code (too_large, not_tabular, access_restricted, parse_error, source_unavailable).

Dataverse and GSS each register a resource template under this scheme (pollingdata://dataverse/{dataset_id}/{file_id} and pollingdata://gss/{dataset_id}/{file_id}), both serving rows as text/tab-separated-values.

Resource URI encoding contract

Most users can skip this — it matters only if you build the resource URI by hand.

Each path segment is single percent-encoded, so an identifier containing reserved characters survives as one path segment and the broker does exactly one unquote per segment on read. A Dataverse DOI, for instance, contains / and :, which are escaped (%2F, %3A) so the whole DOI is one segment. The file 11719727 in dataset doi:10.7910/DVN/NQSBUC is addressed as:

pollingdata://dataverse/doi%3A10.7910%2FDVN%2FNQSBUC/11719727
  • Programmatic clients: use the path from the descriptor verbatim. It is already encoded correctly — do not encode it again.
  • Manual clients (e.g. MCP Inspector): type the raw DOI in the dataset_id field — doi:10.7910/DVN/NQSBUC, not doi%3A10.7910%2FDVN%2FNQSBUC. Inspector percent-encodes form field values for you; pre-encoding on top of that double-encodes the DOI (%253A/%252F), which reaches Dataverse as a malformed persistentId and comes back as a 400, surfaced here as source_unavailable.

Worked read (in-memory SDK client):

described = await client.call_tool(
    "describe_dataset", {"source": "dataverse", "dataset_id": "doi:10.7910/DVN/NQSBUC"}
)
resource = described.structuredContent["result"]["resources"][0]
rows = await client.read_resource(resource["path"])   # path used verbatim — already encoded
text = rows.contents[0].text                           # tab-delimited rows, header included

Connecting a client

The server speaks stdio by default, so any MCP client launches it the same way — point the client's launch command at uv run:

{
  "mcpServers": {
    "polling-data": {
      "command": "/path/to/uv",
      "args": ["--directory", "/abs/path/to/polling-data-mcp", "run", "polling-data-mcp"]
    }
  }
}

Use absolute paths for both uv and the project directory — GUI clients don't inherit your shell PATH, and --directory lets uv resolve the project environment regardless of the client's working directory. Run uv sync once first so the environment is built before a client launches it (otherwise the first launch builds it and may time out).

Getting rows, though, requires a client that can issue resources/read on the model's behalf, because rows are served out-of-band as a resource — there is no row-returning tool. The three tools work in any client; the row pull does not:

ClientTools (search/describe)Rows (resource read)
Claude Code✅✅ — reads the descriptor path autonomously (ReadMcpResource)
Programmatic / in-memory SDK client✅✅ — see the worked read above
MCP Inspector✅✅ manually — read the resource by URI (type the raw DOI; see the encoding contract)
Claude Desktop✅❌ — see note

Claude Desktop surfaces the tools, so it can search and describe a dataset's schema, but it has no autonomous resource-read action: resources are user-attached through the UI, and this server's row resource is a parameterized template (pollingdata://dataverse/{dataset_id}/{file_id}) that the attachment picker does not list as selectable. So Desktop can describe a dataset but cannot pull its rows. For an agent that fetches and analyzes rows, use a client that can read resources on its own, such as Claude Code or a programmatic SDK client.

Scope and boundaries

This server deliberately does format + provenance standardization only. The broker:

  • is read-only — it only reads public data and returns it;
  • delivers rows faithfully — no filtering, sorting, pagination, aggregation, or reshaping;
  • delivers rows by reference — tool results carry a descriptor and a resource link, never inline rows, so datasets never enter the client's model context;
  • owns the egress allowlist — every outbound request (search, metadata, DDI, file download, and any redirect target) must be https to a whitelisted host, or it is rejected as egress_blocked;
  • enforces download caps (max bytes, timeout) at read time — over a cap is a typed too_large, never a silent partial or an out-of-memory;
  • makes no model calls and holds no ANTHROPIC_API_KEY.

Out of scope: restricted (auth-gated) datasets, semantic normalization/aggregation, and authenticated/remote HTTP deployment.

Development

uv run ruff format .                  # format (line length 100)
uv run ruff check .                   # lint
uv run pytest -m "not integration"    # fast offline suite (default for CI)
uv run pytest -m integration          # live-network tests (hit Harvard Dataverse)
uv run pytest                         # everything

The offline suite mocks the network at the httpx transport layer using recorded real responses. The integration tests hit the live public Dataverse API and are out of the default suite.

Ver o original no GitHub

Bom para

Relacionados