govql-mcp-server 0.1.0__tar.gz

govql_mcp_server-0.1.0/.env

@@ -0,0 +1,8 @@
+#/-------------------[DOTENV_PUBLIC_KEY]--------------------/
+#/            public-key encryption for .env files          /
+#/       [how it works](https://dotenvx.com/encryption)     /
+#/----------------------------------------------------------/
+DOTENV_PUBLIC_KEY="02554c3f8b0af44845544039073d017590bcc4495a6a8832f9d50ee8d9cc606fdd"
+
+# .env
+UV_PUBLISH_TOKEN="encrypted:BDQbQySFzQ3YqYAmJRx2rDujwXL34EYQ/r8CX4rbvlPrzy/s7NTdnCOl/hNgYmKqTyEunMyWdIiRpeV5vRmNSCyR39lVD+LvAm2pUz1PMjQ6Y7ja31SA89AJCe7fpIvmxxsk4hezjXqB5+thrzS5MiNLzBIZJb7/x+ozzQ8tGfmACY2Sp19mNZaS0S4JCJYNSdv/leS2mP98Uh3bpCpXpqYfCWwrlcS5qBNkG/jXnk9LM40AjlK5RddWVLWwIShIAv32mQX5dMLaymdvM7wIz2RDnvPWKpS6t6g6yuS9ZDpbDvgb26NFW1FFAWQEM4AzAWEGw9bWvAWb2YK7YvQtuE3JuA6sVQS/XcM4Z6tun9wQXWds"

govql_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+dist/
+build/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+test-reports/
+
+.env.keys

govql_mcp_server-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

govql_mcp_server-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `govql-mcp-server` are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-05-28
+
+Initial release.
+
+### Added
+
+- `execute_graphql` tool — passthrough that runs any GraphQL query against
+  the GovQL endpoint and returns the result along with a `last_ingest`
+  freshness timestamp.
+- `list_types` tool — returns the names and kinds of every type in the
+  GovQL schema, with an optional case-insensitive `kind` filter.
+- `describe_type` tool — returns one GraphQL type's full description
+  (fields, arg signatures, input fields, enum values) by name.
+- stdio transport (works with Claude Desktop, Claude Code, Cursor, and any
+  other MCP-compatible client that supports stdio servers).
+- Configuration via `GOVQL_ENDPOINT`, `GOVQL_TIMEOUT_MS`, and `LOG_LEVEL`
+  environment variables (all optional — defaults point at the public API).
+- Full test suite (23 tests) using FastMCP's in-memory client, including a
+  guardrail test that fails if any module writes to stdout.

govql_mcp_server-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to govql-mcp-server
+
+This is the Python sub-project of the [GovQL monorepo](https://github.com/govql/govql).
+The rest of the repo (under `us-congress/`) is JavaScript; this package is
+deliberately self-contained.
+
+## Quick start
+
+You'll need [uv](https://github.com/astral-sh/uv) (the Python package
+manager). Install it with the one-liner from its README, then:
+
+```bash
+uv sync              # install deps into a local .venv
+uv run pytest        # run the test suite
+uv build             # build wheel + sdist for publishing
+```
+
+uv reads `.python-version` (currently `3.14`) to pick the interpreter; if
+you don't have it installed it will fetch it automatically.
+
+## Layout
+
+- `src/govql_mcp_server/` — the package
+  - `server.py` — FastMCP instance; importing the tools modules registers them
+  - `graphql_client.py` — thin httpx wrapper around the GovQL endpoint
+  - `tools/` — one file per tool
+  - `logger.py` — stderr-only logging (stdout is the MCP transport — see
+    "Hard rule" below)
+- `tests/` — pytest suite using FastMCP's in-memory client
+- `docs/design.md` — why the project exists, what's in / out of scope, roadmap
+
+## Hard rule: never write to stdout
+
+stdout is the MCP transport. Any stray `print()` corrupts the JSON-RPC
+framing and silently breaks every client. Use the logger
+(`from .logger import logger`). The test suite includes
+`tests/test_no_stdout.py` which fails the build if anything in the package
+writes to stdout.
+
+## Adding a new tool
+
+Each tool gets its own file in `src/govql_mcp_server/tools/` and its own
+test file in `tests/`. Pattern:
+
+1. Create `tools/your_tool.py`. Import `mcp` from `..server` and decorate
+   an async function with `@mcp.tool`.
+2. Add the module to the import line at the bottom of `server.py` so the
+   decorator runs at startup.
+3. Add `tests/test_your_tool.py` using the in-memory `client` fixture from
+   `conftest.py`.
+4. Update `README.md`'s tools table and `CHANGELOG.md`.

govql_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GovQL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

govql_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: govql-mcp-server
+Version: 0.1.0
+Summary: MCP server for GovQL — query US Congressional data via GraphQL from any MCP client.
+Project-URL: Homepage, https://govql.us
+Project-URL: Repository, https://github.com/govql/govql
+Project-URL: Issues, https://github.com/govql/govql/issues
+Author: GovQL
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,congress,government,graphql,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=3.3.0
+Requires-Dist: httpx>=0.27.0
+Description-Content-Type: text/markdown
+
+# govql-mcp-server
+
+An MCP (Model Context Protocol) server for [GovQL](https://govql.us) — gives
+AI clients like Claude Desktop, Claude Code, and Cursor direct access to the
+US Congressional GraphQL API at [api.govql.us/graphql](https://api.govql.us/graphql)
+without bespoke HTTP wiring.
+
+For the design rationale (why FastMCP-Python, the passthrough+curated philosophy,
+roadmap through v0.4), see
+[design.md](https://github.com/govql/govql/blob/main/mcp-server/docs/design.md).
+
+## What you can do with it
+
+Ask an agent questions like:
+
+- *"How did Vermont's two senators vote on the most recent nomination?"*
+- *"Which legislators in the 118th Congress switched parties during their service?"*
+- *"Compare Senator Sanders' voting record to Senator Murkowski's on cloture votes
+   in the most recent Congress."*
+
+The agent picks the right tool, writes the GraphQL query against the live
+schema, and parses the response — no manual API wrangling.
+
+## Install
+
+The server runs as a per-client subprocess over stdio. Pick your client:
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "govql": {
+      "command": "uvx",
+      "args": ["govql-mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The `govql` tools appear in the tools panel.
+
+### Claude Code
+
+Add to `.mcp.json` in your project (or `~/.mcp.json` for global):
+
+```json
+{
+  "mcpServers": {
+    "govql": {
+      "command": "uvx",
+      "args": ["govql-mcp-server"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Settings → MCP → Add Server. Use the same `command` / `args` as above.
+
+### Other clients
+
+Any MCP-compatible client that supports stdio servers will work. The command
+is `uvx govql-mcp-server` with no required arguments.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `execute_graphql` | Run any GraphQL query against the GovQL endpoint. Returns the result plus an `last_ingest` timestamp so the agent can reason about data freshness. |
+| `list_types` | Returns the names and kinds of every type in the GovQL schema. Optional `kind` filter (`"OBJECT"`, `"INPUT_OBJECT"`, `"ENUM"`, etc.) to narrow further. Start here when you don't know what's queryable. |
+| `describe_type` | Returns one type's full details — fields, arg signatures, input fields, enum values. Call after `list_types` to learn the shape of a specific type before writing a query. |
+
+## Configuration
+
+All env vars are optional — the package is zero-config for end users.
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `GOVQL_ENDPOINT` | `https://api.govql.us/graphql` | Endpoint to query. Override to point at a local dev stack. |
+| `GOVQL_TIMEOUT_MS` | `30000` | Per-request HTTP timeout. |
+| `LOG_LEVEL` | `INFO` | Logging level. Logs go to stderr only (stdout is reserved for the MCP transport). |
+
+## Limits (enforced by the upstream API)
+
+- Max query depth: 10
+- Max query complexity: ~10 billion points (`first: N` multiplies child cost
+  by N — keep page sizes reasonable on deeply nested queries)
+- Rate limit: 100 requests / 60 s per source IP
+
+A depth or complexity violation surfaces as a GraphQL `errors` entry in the
+tool response so the agent can adjust and retry.
+
+## Data freshness
+
+Every `execute_graphql` response includes a `last_ingest` ISO timestamp.
+Vote data refreshes hourly; legislator data refreshes daily.
+
+## Status
+
+Version 0.1.0 ships three foundational tools: a GraphQL passthrough
+(`execute_graphql`) and two narrow schema-discovery tools (`list_types`,
+`describe_type`). Curated higher-level tools (`find_legislator`,
+`get_voting_record`, `compare_voters`, etc.) are planned for subsequent
+releases — see
+[design.md](https://github.com/govql/govql/blob/main/mcp-server/docs/design.md)
+for the roadmap.
+
+## Links
+
+- [GovQL project site](https://govql.us)
+- [GraphQL API](https://api.govql.us/graphql)
+- [Source / issues](https://github.com/govql/govql)

govql_mcp_server-0.1.0/README.md

@@ -0,0 +1,116 @@
+# govql-mcp-server
+
+An MCP (Model Context Protocol) server for [GovQL](https://govql.us) — gives
+AI clients like Claude Desktop, Claude Code, and Cursor direct access to the
+US Congressional GraphQL API at [api.govql.us/graphql](https://api.govql.us/graphql)
+without bespoke HTTP wiring.
+
+For the design rationale (why FastMCP-Python, the passthrough+curated philosophy,
+roadmap through v0.4), see
+[design.md](https://github.com/govql/govql/blob/main/mcp-server/docs/design.md).
+
+## What you can do with it
+
+Ask an agent questions like:
+
+- *"How did Vermont's two senators vote on the most recent nomination?"*
+- *"Which legislators in the 118th Congress switched parties during their service?"*
+- *"Compare Senator Sanders' voting record to Senator Murkowski's on cloture votes
+   in the most recent Congress."*
+
+The agent picks the right tool, writes the GraphQL query against the live
+schema, and parses the response — no manual API wrangling.
+
+## Install
+
+The server runs as a per-client subprocess over stdio. Pick your client:
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "govql": {
+      "command": "uvx",
+      "args": ["govql-mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The `govql` tools appear in the tools panel.
+
+### Claude Code
+
+Add to `.mcp.json` in your project (or `~/.mcp.json` for global):
+
+```json
+{
+  "mcpServers": {
+    "govql": {
+      "command": "uvx",
+      "args": ["govql-mcp-server"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Settings → MCP → Add Server. Use the same `command` / `args` as above.
+
+### Other clients
+
+Any MCP-compatible client that supports stdio servers will work. The command
+is `uvx govql-mcp-server` with no required arguments.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `execute_graphql` | Run any GraphQL query against the GovQL endpoint. Returns the result plus an `last_ingest` timestamp so the agent can reason about data freshness. |
+| `list_types` | Returns the names and kinds of every type in the GovQL schema. Optional `kind` filter (`"OBJECT"`, `"INPUT_OBJECT"`, `"ENUM"`, etc.) to narrow further. Start here when you don't know what's queryable. |
+| `describe_type` | Returns one type's full details — fields, arg signatures, input fields, enum values. Call after `list_types` to learn the shape of a specific type before writing a query. |
+
+## Configuration
+
+All env vars are optional — the package is zero-config for end users.
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `GOVQL_ENDPOINT` | `https://api.govql.us/graphql` | Endpoint to query. Override to point at a local dev stack. |
+| `GOVQL_TIMEOUT_MS` | `30000` | Per-request HTTP timeout. |
+| `LOG_LEVEL` | `INFO` | Logging level. Logs go to stderr only (stdout is reserved for the MCP transport). |
+
+## Limits (enforced by the upstream API)
+
+- Max query depth: 10
+- Max query complexity: ~10 billion points (`first: N` multiplies child cost
+  by N — keep page sizes reasonable on deeply nested queries)
+- Rate limit: 100 requests / 60 s per source IP
+
+A depth or complexity violation surfaces as a GraphQL `errors` entry in the
+tool response so the agent can adjust and retry.
+
+## Data freshness
+
+Every `execute_graphql` response includes a `last_ingest` ISO timestamp.
+Vote data refreshes hourly; legislator data refreshes daily.
+
+## Status
+
+Version 0.1.0 ships three foundational tools: a GraphQL passthrough
+(`execute_graphql`) and two narrow schema-discovery tools (`list_types`,
+`describe_type`). Curated higher-level tools (`find_legislator`,
+`get_voting_record`, `compare_voters`, etc.) are planned for subsequent
+releases — see
+[design.md](https://github.com/govql/govql/blob/main/mcp-server/docs/design.md)
+for the roadmap.
+
+## Links
+
+- [GovQL project site](https://govql.us)
+- [GraphQL API](https://api.govql.us/graphql)
+- [Source / issues](https://github.com/govql/govql)

govql_mcp_server-0.1.0/RELEASE.md

@@ -0,0 +1,242 @@
+# Releasing govql-mcp-server
+
+The steps to ship a new version. Written for v0.1.0 but reusable for subsequent
+releases — just substitute the version number throughout.
+
+All commands assume you're in `mcp-server/` unless noted otherwise.
+
+---
+
+## 0. Prerequisites (one-time setup)
+
+Skip this section if you've published before.
+
+### PyPI account + token
+
+1. Create an account at [pypi.org](https://pypi.org/account/register/) (and
+   verify your email).
+2. Enable 2FA — PyPI requires it for publishers.
+3. Create a **scoped API token**:
+   [pypi.org/manage/account/token/](https://pypi.org/manage/account/token/).
+   First release: scope to "Entire account" (the package doesn't exist yet so
+   you can't scope to it). After v0.1.0 is up, **revoke that token and create
+   a new one scoped to the `govql-mcp-server` project only.**
+4. Store the token somewhere you'll find it again. For local releases, the
+   easiest path is to export it before publishing:
+   ```bash
+   export UV_PUBLISH_TOKEN="pypi-AgEI..."
+   ```
+   If you'd rather not type this every time, drop it in your shell's
+   per-project environment (e.g. `.env` with dotenvx, or direnv).
+
+### MCP registry (mcp.so) account
+
+You'll need a free account at [mcp.so](https://mcp.so) to submit the listing
+in step 4. Sign up now if you haven't.
+
+---
+
+## 1. Pre-flight checks
+
+Run from `mcp-server/`. All of these should pass before you go further.
+
+```bash
+# Tests green
+uv run pytest
+
+# Build artifacts clean (no stale files from a previous build)
+rm -rf dist/
+uv build
+
+# Wheel contents look right — should only contain govql_mcp_server/ and a dist-info
+unzip -l dist/govql_mcp_server-0.1.0-py3-none-any.whl
+
+# Sdist contents look right — full source tree including tests/, docs/, CHANGELOG
+tar tzf dist/govql_mcp_server-0.1.0.tar.gz
+```
+
+Quick checklist of things to eyeball:
+
+- `CHANGELOG.md` has an entry for the version you're about to release
+- `pyproject.toml`'s `version` matches that CHANGELOG entry
+- `README.md` describes the *current* tool set (no "coming soon" wording)
+- No half-finished branches or commented-out code on the release commit
+
+---
+
+## 2. Real MCP client test (gate before publishing)
+
+This is the only test that proves "an actual agent can use this." Don't
+publish without it.
+
+Pick a client. **Claude Desktop** is recommended for the first release because
+it makes the tool calls visible in the UI.
+
+### Wire up the *local* build (not the PyPI version)
+
+```bash
+# Confirm the local entry point works
+GOVQL_ENDPOINT=https://api.govql.us/graphql uv run govql-mcp-server
+# (Ctrl-C to stop — you're just confirming it starts cleanly. No prompt means it's
+# waiting on stdin for MCP messages, which is correct.)
+```
+
+In Claude Desktop, edit `claude_desktop_config.json` (Settings → Developer →
+Edit Config) and add an entry pointing at this checkout:
+
+```json
+{
+  "mcpServers": {
+    "govql-local": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/home/astout5/govql/mcp-server",
+        "run",
+        "govql-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Confirm `govql-local` shows up in the tools panel
+with `execute_graphql`, `list_types`, and `describe_type` listed.
+
+### The test prompt
+
+Ask:
+
+> *How did Vermont's two senators vote on the most recent nomination?*
+
+Expected behavior:
+
+1. The agent calls `list_types` / `describe_type` as needed (or already
+   knows the schema from a prior session).
+2. It writes a query against `allVotes` + `votePositions` filtering for
+   Vermont senators and the latest nomination.
+3. It returns a concise answer naming both senators and their positions.
+
+If anything is off (the agent gets confused, the query fails, the answer is
+wrong), fix it before publishing — the issue is almost certainly in the
+`execute_graphql` docstring in
+`src/govql_mcp_server/tools/passthrough.py`, which is the agent's primary
+guide.
+
+### Capture the transcript
+
+Once it works, copy the transcript into `README.md` under a "Try it" or
+"Example" section so PyPI visitors see a concrete demo on the project page.
+Commit the README change before publishing.
+
+### Remove the local config
+
+After the test, remove the `govql-local` entry from
+`claude_desktop_config.json` so you don't have two GovQL servers competing
+once the real one is installed.
+
+---
+
+## 3. Publish to PyPI
+
+```bash
+# 1. Re-build with the final README/CHANGELOG/version in place.
+rm -rf dist/
+uv build
+
+# 2. Publish. UV_PUBLISH_TOKEN must be set (see Prerequisites).
+uv publish
+
+# 3. Verify it's live by installing it in a throwaway location.
+#    Should print version 0.1.0 and exit cleanly (subprocess waits on stdin
+#    for MCP messages; just confirm it starts).
+uvx --refresh govql-mcp-server --help 2>&1 | head -5
+```
+
+If the publish fails on `name already exists`: someone took the name. Pick
+one of the fallbacks from the original plan (`govql`, `mcp-govql`,
+`govql-mcp`), update `pyproject.toml` + every README install snippet to match,
+re-run pre-flight, and try again.
+
+---
+
+## 4. Tag the release in git
+
+From the **repo root** (not `mcp-server/`):
+
+```bash
+cd /home/astout5/govql
+
+# Sanity: the working tree should be clean and on the merge commit that includes the release.
+git status
+git log -1 --oneline
+
+# Tag and push.
+git tag -a govql-mcp-server-v0.1.0 -m "govql-mcp-server v0.1.0"
+git push origin govql-mcp-server-v0.1.0
+```
+
+The tag is namespaced with `govql-mcp-server-` so it doesn't collide with
+future tags for other sub-projects (e.g. a hypothetical
+`us-congress-api-v1.0.0`).
+
+---
+
+## 5. Submit to the MCP registry (mcp.so)
+
+1. Log into [mcp.so](https://mcp.so).
+2. Click "Submit MCP Server" (or whatever the current entry point is called).
+3. Fill in:
+   - **Name:** `govql`
+   - **Description:** "MCP server for GovQL — query US Congressional voting
+     data (legislators, roll-call votes, etc.) via GraphQL from any MCP
+     client."
+   - **GitHub URL:** `https://github.com/govql/govql/tree/main/mcp-server`
+   - **Install / config snippet** (JSON):
+     ```json
+     {
+       "mcpServers": {
+         "govql": {
+           "command": "uvx",
+           "args": ["govql-mcp-server"]
+         }
+       }
+     }
+     ```
+4. Submit and wait for moderation (typically a few hours to a few days).
+5. Once approved, copy the registry URL into the next CHANGELOG entry under
+   the relevant version so future contributors can find it.
+
+---
+
+## 6. Post-release sanity checks
+
+About 5 minutes after `uv publish`:
+
+```bash
+# Confirm the package is visible on PyPI.
+curl -sS https://pypi.org/pypi/govql-mcp-server/json | jq '.info.version, .info.home_page'
+
+# Confirm a fresh install from PyPI works (use --refresh to bypass uv's cache).
+uvx --refresh --from govql-mcp-server==0.1.0 govql-mcp-server --help 2>&1 | head -5
+```
+
+Then in Claude Desktop, replace the local-build config with the PyPI version
+(the snippet in `README.md`) and re-run the Vermont prompt to confirm the
+published artifact behaves identically to the local build.
+
+---
+
+## 7. Graceful-exit check
+
+Before stopping work, confirm every item below — this is the discipline that
+makes a paused-mid-project portfolio piece still look intentional:
+
+- [ ] Latest version is on PyPI
+- [ ] Matching git tag is pushed
+- [ ] `CHANGELOG.md` has the entry
+- [ ] `README.md` accurately describes the *current* tool set
+- [ ] No half-merged branches, no commented-out scaffolding, no TODO
+      comments pointing at the next version
+- [ ] MCP-server Docusaurus page reflects the current tool set
+- [ ] MCP registry listing submitted (or approved)