@pipeworx/mcp-govinfo 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +1 -1
- package/README.md +139 -9
- package/bin/cli.js +17 -0
- package/package.json +15 -3
- package/server.json +1 -1
- package/src/index.ts +1263 -12
- package/src/server.ts +45 -0
- package/tsconfig.json +5 -1
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,14 +1,85 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @pipeworx/govinfo
|
|
2
2
|
|
|
3
|
-
GovInfo.gov MCP — full text of US government publications
|
|
3
|
+
GovInfo.gov MCP — full text of US government publications.
|
|
4
4
|
|
|
5
|
-
Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to
|
|
5
|
+
Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1683+ live data sources.
|
|
6
6
|
|
|
7
7
|
## Tools
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
- `list_collections()`
|
|
10
|
+
- `search_packages(query, collections?, congress?, date_from?, date_to?, page_size?, offset_mark?)`
|
|
11
|
+
- `collections` takes one code or several, comma- or space-separated (`"CHRG"`, `"CHRG,CRPT"`). Several codes search the **union** — `"CHRG,CRPT"` returns 9,239 hits for "Cooper", exactly the 5,359 + 3,880 the two collections return on their own.
|
|
12
|
+
- `page_size` also answers to `limit`.
|
|
13
|
+
- `get_package(package_id)`
|
|
14
|
+
- `list_granules(package_id, page_size?, offset_mark?)` — `page_size` also answers to `limit`.
|
|
15
|
+
- `get_granule(package_id, granule_id)`
|
|
16
|
+
|
|
17
|
+
## Auth
|
|
18
|
+
|
|
19
|
+
- **Platform key:** reuses `PLATFORM_DATAGOV_KEY`.
|
|
20
|
+
- **BYO:** `?_apiKey=<key>` (api.data.gov key).
|
|
21
|
+
|
|
22
|
+
## Data source
|
|
23
|
+
|
|
24
|
+
`https://api.govinfo.gov` — `?api_key=` query param.
|
|
25
|
+
|
|
26
|
+
## GAO appropriations law (fleet #1972)
|
|
27
|
+
|
|
28
|
+
Two tools that make GAO's secondary authority reachable by TOPIC rather than by
|
|
29
|
+
package id.
|
|
30
|
+
|
|
31
|
+
### `gao_red_book(topic?, chapter?, include_scope_text?)`
|
|
32
|
+
|
|
33
|
+
Resolves a fiscal-law question to the governing chapter of GAO's *Principles of
|
|
34
|
+
Federal Appropriations Law* — the Red Book. **Keyless**: it reads
|
|
35
|
+
`www.gao.gov`, not the GovInfo API, so it works with no data.gov key.
|
|
36
|
+
|
|
37
|
+
**Why it does not use GovInfo.** Measured 2026-09-14: the `GAOREPORTS`
|
|
38
|
+
collection holds 16,569 packages but **zero issued after 2010-01-01**, and a
|
|
39
|
+
full-text search for *"Principles of Federal Appropriations Law"* returns
|
|
40
|
+
**exactly one relevant package in its top 100 of 1,565 hits** — the *2004 Update
|
|
41
|
+
of the Third Edition*. GovInfo cannot serve the current Red Book at all.
|
|
42
|
+
|
|
43
|
+
**Edition handling is the point.** GAO now publishes the Red Book chapter by
|
|
44
|
+
chapter, so the current treatise is a mix:
|
|
45
|
+
|
|
46
|
+
> *"Our current Red Book consists of Chapters 1-3 (of the 4th Edition) and
|
|
47
|
+
> Chapters 5-15 (of the 3rd Edition)."* — gao.gov, read live on every call
|
|
48
|
+
|
|
49
|
+
That sentence and the whole table of contents are parsed from GAO's page at call
|
|
50
|
+
time rather than hardcoded, so Chapter 4 appears the day GAO posts it. Every row
|
|
51
|
+
names its edition; the 2004 annual update is returned separately under
|
|
52
|
+
`superseded` with the reason it is not the answer.
|
|
53
|
+
|
|
54
|
+
**Freshness.** `source_last_modified` is the `Last-Modified` of the chapter PDF
|
|
55
|
+
itself. The TOC page's `Last-Modified` is a Drupal render timestamp that reads as
|
|
56
|
+
*today* on every call — using it would tell a caller a 2019 chapter was revised
|
|
57
|
+
this morning.
|
|
58
|
+
|
|
59
|
+
**How matching works, and what it is worth.** Chapter titles come off GAO's live
|
|
60
|
+
page and are authoritative. On top of them sits `RED_BOOK_TOPIC_ALIASES` in
|
|
61
|
+
`src/index.ts` — **a list maintained in this pack, not something GAO publishes**, which is why every matched
|
|
62
|
+
row carries `match_basis` saying whether it matched `title:`, `alias:` or
|
|
63
|
+
`gao_scope:`. The chapters are PDFs and GovInfo does not index them, so an alias
|
|
64
|
+
cannot be verified against the text; entries are therefore restricted to terms
|
|
65
|
+
that are the standard NAME of the rule the chapter's own title states (*bona
|
|
66
|
+
fide needs rule* → *Availability of Appropriations: Time*), the US Code section
|
|
67
|
+
that rule lives at, or a plain-English framing of the question the chapter's
|
|
68
|
+
title asks. When nothing clears the score floor the tool returns
|
|
69
|
+
`match_confidence: "none"` **and the complete table of contents** rather than a
|
|
70
|
+
plausible wrong chapter.
|
|
71
|
+
|
|
72
|
+
### `gao_comptroller_decisions(query, date_from?, date_to?, include_reports?, page_size?)`
|
|
73
|
+
|
|
74
|
+
GovInfo files GAO audit reports and Comptroller General **decisions** under one
|
|
75
|
+
collection code — its own name says so, *"Government Accountability Office
|
|
76
|
+
Reports and Comptroller General Decisions"* — so a relevance search interleaves
|
|
77
|
+
them. Measured on `"augmentation of appropriations"`: 100 hits examined, **15 of
|
|
78
|
+
the top 25 were decisions**; this tool returns the **26 decisions and drops the
|
|
79
|
+
74 reports**, reporting both counts. The split is the package id (`GAOREPORTS-B-…`).
|
|
80
|
+
|
|
81
|
+
Coverage stops at 2009 — GAOREPORTS carries nothing newer. For recent bid
|
|
82
|
+
protests use `gao_protests_search`; for the current rule use `gao_red_book`.
|
|
12
83
|
|
|
13
84
|
## Quick Start
|
|
14
85
|
|
|
@@ -24,7 +95,25 @@ Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
|
|
|
24
95
|
}
|
|
25
96
|
```
|
|
26
97
|
|
|
27
|
-
|
|
98
|
+
### What this endpoint actually serves
|
|
99
|
+
|
|
100
|
+
`tools/list` at `https://gateway.pipeworx.io/govinfo/mcp` returns the tools in the table
|
|
101
|
+
above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
|
|
102
|
+
`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
|
|
103
|
+
gateway-wide set. So the tool count you see is larger than this table: a
|
|
104
|
+
single-pack endpoint currently lists roughly 30 shared tools alongside the
|
|
105
|
+
pack's own. The connection's `initialize` response states its exact scope, and
|
|
106
|
+
is the authoritative answer for a given day.
|
|
107
|
+
|
|
108
|
+
This is deliberate, not multiplexing by accident. The meta-tools are what let a
|
|
109
|
+
scoped connection answer a question this pack does not cover — via
|
|
110
|
+
`ask_pipeworx`, which routes across the whole catalog — without you adding a
|
|
111
|
+
second MCP server. There is currently no way to mount a pack endpoint without
|
|
112
|
+
them; if the extra schemas cost you more context than the routing is worth,
|
|
113
|
+
connect to the full gateway once rather than to several pack endpoints.
|
|
114
|
+
|
|
115
|
+
Or connect to the full Pipeworx gateway to get every pack's tools listed
|
|
116
|
+
directly, instead of just this one's:
|
|
28
117
|
|
|
29
118
|
```json
|
|
30
119
|
{
|
|
@@ -36,9 +125,50 @@ Or connect to the full Pipeworx gateway for access to all 250+ data sources:
|
|
|
36
125
|
}
|
|
37
126
|
```
|
|
38
127
|
|
|
128
|
+
Both URLs reach the same gateway and the same 1683+ data sources. The
|
|
129
|
+
only difference is which pack's tools are listed **directly**; `ask_pipeworx`
|
|
130
|
+
reaches all of them from either one.
|
|
131
|
+
|
|
132
|
+
## No MCP client? Call it over HTTP
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
curl -X POST https://gateway.pipeworx.io/v1/tools/govinfo_list_collections \
|
|
136
|
+
-H 'Content-Type: application/json' \
|
|
137
|
+
-d '{}'
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/govinfo_list_collections`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.
|
|
141
|
+
|
|
142
|
+
## Standalone (no gateway account)
|
|
143
|
+
|
|
144
|
+
This package also runs as a local stdio MCP server — no Pipeworx account, no
|
|
145
|
+
gateway round-trip:
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{
|
|
149
|
+
"mcpServers": {
|
|
150
|
+
"govinfo": {
|
|
151
|
+
"command": "npx",
|
|
152
|
+
"args": ["-y", "@pipeworx/mcp-govinfo"]
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Or run it directly to confirm it starts:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
npx -y @pipeworx/mcp-govinfo
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
It speaks MCP over stdin/stdout and answers `initialize`/`tools/list`/`tools/call`
|
|
165
|
+
for **only** this pack's tools — none of the shared meta-tools the gateway
|
|
166
|
+
connection above adds. Same source, same tools, no ask_pipeworx routing.
|
|
167
|
+
|
|
39
168
|
## Using with ask_pipeworx
|
|
40
169
|
|
|
41
|
-
Instead of calling tools directly, you can ask questions in plain English
|
|
170
|
+
Instead of calling tools directly, you can ask questions in plain English —
|
|
171
|
+
this works on the pack endpoint above as well as on the full gateway:
|
|
42
172
|
|
|
43
173
|
```
|
|
44
174
|
ask_pipeworx({ question: "your question about Govinfo data" })
|
|
@@ -48,7 +178,7 @@ The gateway picks the right tool and fills the arguments automatically.
|
|
|
48
178
|
|
|
49
179
|
## More
|
|
50
180
|
|
|
51
|
-
- [
|
|
181
|
+
- [Docs and guides](https://pipeworx.io/docs)
|
|
52
182
|
- [pipeworx.io](https://pipeworx.io)
|
|
53
183
|
|
|
54
184
|
## License
|
package/bin/cli.js
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
//
|
|
3
|
+
// Entry point for `npx @pipeworx/mcp-<slug>`.
|
|
4
|
+
//
|
|
5
|
+
// Packs ship as raw TypeScript (no build step — see publish-pack.sh for why:
|
|
6
|
+
// tsx sidesteps every extensionless-import / bare-JSON-import edge case a
|
|
7
|
+
// per-pack tsc build would have to solve one pack at a time). This file
|
|
8
|
+
// registers tsx's ESM loader programmatically, then hands off to src/server.ts,
|
|
9
|
+
// which wraps the pack's {tools, callTool} export in a stdio MCP server.
|
|
10
|
+
//
|
|
11
|
+
// Copied verbatim into every published pack repo by scripts/publish-pack.sh —
|
|
12
|
+
// edit this file, not a per-pack copy.
|
|
13
|
+
import { register } from 'tsx/esm/api';
|
|
14
|
+
|
|
15
|
+
register();
|
|
16
|
+
|
|
17
|
+
await import('../src/server.ts');
|
package/package.json
CHANGED
|
@@ -1,20 +1,32 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pipeworx/mcp-govinfo",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "GovInfo.gov MCP — full text of US government publications",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "src/index.ts",
|
|
7
7
|
"types": "src/index.ts",
|
|
8
|
+
"bin": {
|
|
9
|
+
"mcp-govinfo": "bin/cli.js"
|
|
10
|
+
},
|
|
8
11
|
"keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "govinfo"],
|
|
9
12
|
"license": "MIT",
|
|
10
13
|
"repository": {
|
|
11
14
|
"type": "git",
|
|
12
|
-
"url": "https://github.com/pipeworx-io/mcp-govinfo"
|
|
15
|
+
"url": "git+https://github.com/pipeworx-io/mcp-govinfo.git"
|
|
13
16
|
},
|
|
14
17
|
"scripts": {
|
|
15
18
|
"typecheck": "tsc --noEmit"
|
|
16
19
|
},
|
|
20
|
+
"dependencies": {
|
|
21
|
+
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
22
|
+
"tsx": "^4.19.0"
|
|
23
|
+
},
|
|
17
24
|
"devDependencies": {
|
|
18
|
-
"typescript": "^5.
|
|
25
|
+
"typescript": "^5.9.3",
|
|
26
|
+
"@cloudflare/workers-types": "^4.20260405.1"
|
|
27
|
+
},
|
|
28
|
+
"pipeworx": {
|
|
29
|
+
"sourceHash": "v1-4763886da482e32262cee98280acfb985ec90091a604ef4cbdf1eb3dbfdc89ae",
|
|
30
|
+
"sourceCommit": "1064560fd9dcd0d6fc2606298c2ba244b3a1fbeb"
|
|
19
31
|
}
|
|
20
32
|
}
|
package/server.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"name": "io.github.pipeworx-io/govinfo",
|
|
4
4
|
"title": "Govinfo",
|
|
5
5
|
"description": "GovInfo.gov MCP — full text of US government publications",
|
|
6
|
-
"version": "0.1.
|
|
6
|
+
"version": "0.1.2",
|
|
7
7
|
"websiteUrl": "https://pipeworx.io/packs/govinfo",
|
|
8
8
|
"repository": {
|
|
9
9
|
"url": "https://github.com/pipeworx-io/mcp-govinfo",
|