@cyanheads/congressgov-mcp-server 0.8.1 → 0.9.0

package/AGENTS.md

@@ -1,10 +1,10 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.8.1
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.16`
+**Version:** 0.9.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
+**MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
 **Zod:** ^4.6.7
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -83,7 +83,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 **Summary bounding** (`src/mcp-server/tools/summary-window.ts`, constants in `tool-helpers.ts`). Both summary surfaces enforce two limits. `SUMMARY_PAGE_CHARACTERS` stops a page once its serialized rows reach the budget — the first row always returns, `pagination.nextOffset` counts the rows actually returned, and an enrichment notice discloses the stop. `DEFAULT_SUMMARY_TEXT_CHARACTERS` bounds one row's upstream `text`; a windowed row gains `textTotalCharacters` / `textTruncated` / `textNextOffset`, and its window end is retracted off any HTML tag or character reference it would otherwise split (unless the construct is wider than the whole window, where the requested limit wins). A row inside both limits is returned untouched, so an unbounded page stays byte-identical. `congressgov_bill_lookup` `summaries` overrides the row window with `characterOffset`/`characterLimit` and selects one version with `versionCode` — Congress.gov publishes no version filter, so selection reads the bill's whole summary list and matches client-side.
 
-### Resources (5)
+### Resources (6)
 
 | URI Template | Description |
 |:-------------|:------------|
@@ -92,6 +92,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 | `congress://member/{bioguideId}` | Member profile |
 | `congress://bill/{congress}/{billType}/{billNumber}` | Bill detail |
 | `congress://committee/{committeeCode}` | Committee detail |
+| `skill://congressgov-guide/SKILL.md` | Published legislative research guide |
 
 ### Prompts (2)
 
@@ -256,9 +257,18 @@ import { getServerConfig } from '@/config/server-config.js';
 
 ## Skills
 
-Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
+Two skill trees live at the project root, written for different readers:
 
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `framework-skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).
+| Tree | For | Written by |
+|:-----|:----|:-----------|
+| `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
+| `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | `congressgov-guide/SKILL.md`, maintained with the `add-skill` skill |
+
+Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.
+
+`skills/congressgov-guide/SKILL.md` reaches plugin installs and the `.mcpb` bundle as-is and ships in the npm package and Docker image. `createApp({ skills: 'skills' })` serves it through the MCP Skills extension and the `skill://congressgov-guide/SKILL.md` resource. `lint:packaging` validates the tree.
+
+**Agent skill directory:** Copy `framework-skills/` into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
 Available skills:
 
@@ -270,6 +280,7 @@ Available skills:
 | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
 | `add-resource` | Scaffold a new resource definition |
 | `add-prompt` | Scaffold a new prompt definition |
+| `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -317,7 +328,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run format` | Auto-fix formatting (safe fixes only) |
 | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
 | `bun run lint:mcp` | Validate MCP tool/resource/prompt definitions |
-| `bun run lint:packaging` | Validate env var alignment between `manifest.json` and `server.json` |
+| `bun run lint:packaging` | Validate bundle exclusions, plugin manifests, published skills, env var alignment, and version parity |
 | `bun run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
 | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
@@ -334,7 +345,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Bundling
 
-`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP deployments are unaffected. The bundle file ships as `dist/congressgov-mcp-server.mcpb`.
+`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `.mcpbignore` excludes root development paths with anchored patterns; root `skills/` ships. `scripts/clean-mcpb.ts` prunes dev dependencies and strips dependency agent docs, platform-specific native bindings, node-gyp build output that records host paths, and framework build-only files. Compiled native addons stay. Run `lint:packaging` after the completed bundle. MCPB is stdio-only; HTTP deployments are unaffected. The bundle file ships as `dist/congressgov-mcp-server.mcpb`.
 
 **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"`, and an optional string option carries `"default": ""`. The host substitutes only the `user_config` reference; `"${X}"` reaches the server literally.
 
@@ -400,6 +411,7 @@ The `release-and-publish` run handles npm, MCP Registry, bundle, GitHub Release,
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] Root `plugin.json` metadata matches `package.json`; `mcp.json` uses the unscoped server key, `npx -y <full package name>`, and the fixed env from `.codex-plugin/mcp.json`. User variables remain in the overlays; `.codex-plugin/plugin.json` retains `mcpServers: './.codex-plugin/mcp.json'`
 - [ ] `.codex-plugin/plugin.json` populated — `name` and `interface.displayName` = unscoped repo name; `version`, `description`, `repository`, `license` and `interface.shortDescription` from `package.json`
 - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable is listed in `env_vars`. Never write `"KEY": ""` into `env` — it overrides the user's exported key
 - [ ] `.claude-plugin/plugin.json` populated — unscoped `name`, `version`, `description`, `author`, `repository`, `license`, `keywords`; inline `mcpServers` entry keyed by the unscoped repo name. User-supplied variables use `userConfig` and `"KEY": "${user_config.<option>}"` env references, matching `manifest.json`

package/CLAUDE.md

@@ -1,10 +1,10 @@
 # Agent Protocol
 
 **Server:** congressgov-mcp-server
-**Version:** 0.8.1
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.16`
+**Version:** 0.9.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
-**MCP SDK:** `@modelcontextprotocol/server` ^2.3.1
+**MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
 **Zod:** ^4.6.7
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
@@ -83,7 +83,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 
 **Summary bounding** (`src/mcp-server/tools/summary-window.ts`, constants in `tool-helpers.ts`). Both summary surfaces enforce two limits. `SUMMARY_PAGE_CHARACTERS` stops a page once its serialized rows reach the budget — the first row always returns, `pagination.nextOffset` counts the rows actually returned, and an enrichment notice discloses the stop. `DEFAULT_SUMMARY_TEXT_CHARACTERS` bounds one row's upstream `text`; a windowed row gains `textTotalCharacters` / `textTruncated` / `textNextOffset`, and its window end is retracted off any HTML tag or character reference it would otherwise split (unless the construct is wider than the whole window, where the requested limit wins). A row inside both limits is returned untouched, so an unbounded page stays byte-identical. `congressgov_bill_lookup` `summaries` overrides the row window with `characterOffset`/`characterLimit` and selects one version with `versionCode` — Congress.gov publishes no version filter, so selection reads the bill's whole summary list and matches client-side.
 
-### Resources (5)
+### Resources (6)
 
 | URI Template | Description |
 |:-------------|:------------|
@@ -92,6 +92,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
 | `congress://member/{bioguideId}` | Member profile |
 | `congress://bill/{congress}/{billType}/{billNumber}` | Bill detail |
 | `congress://committee/{committeeCode}` | Committee detail |
+| `skill://congressgov-guide/SKILL.md` | Published legislative research guide |
 
 ### Prompts (2)
 
@@ -256,9 +257,18 @@ import { getServerConfig } from '@/config/server-config.js';
 
 ## Skills
 
-Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
+Two skill trees live at the project root, written for different readers:
 
-**Agent skill directory:** Copy skills into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). This makes skills available as context without needing to reference `framework-skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).
+| Tree | For | Written by |
+|:-----|:----|:-----------|
+| `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
+| `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | `congressgov-guide/SKILL.md`, maintained with the `add-skill` skill |
+
+Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.
+
+`skills/congressgov-guide/SKILL.md` reaches plugin installs and the `.mcpb` bundle as-is and ships in the npm package and Docker image. `createApp({ skills: 'skills' })` serves it through the MCP Skills extension and the `skill://congressgov-guide/SKILL.md` resource. `lint:packaging` validates the tree.
+
+**Agent skill directory:** Copy `framework-skills/` into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
 
 Available skills:
 
@@ -270,6 +280,7 @@ Available skills:
 | `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
 | `add-resource` | Scaffold a new resource definition |
 | `add-prompt` | Scaffold a new prompt definition |
+| `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
 | `add-service` | Scaffold a new service integration |
 | `add-test` | Scaffold test file for a tool, resource, or service |
 | `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
@@ -317,7 +328,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run format` | Auto-fix formatting (safe fixes only) |
 | `bun run format:unsafe` | Also apply Biome's unsafe autofixes — review the diff; they can change behavior |
 | `bun run lint:mcp` | Validate MCP tool/resource/prompt definitions |
-| `bun run lint:packaging` | Validate env var alignment between `manifest.json` and `server.json` |
+| `bun run lint:packaging` | Validate bundle exclusions, plugin manifests, published skills, env var alignment, and version parity |
 | `bun run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
 | `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
 | `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
@@ -334,7 +345,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Bundling
 
-`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. MCPB is stdio-only — HTTP deployments are unaffected. The bundle file ships as `dist/congressgov-mcp-server.mcpb`.
+`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `.mcpbignore` excludes root development paths with anchored patterns; root `skills/` ships. `scripts/clean-mcpb.ts` prunes dev dependencies and strips dependency agent docs, platform-specific native bindings, node-gyp build output that records host paths, and framework build-only files. Compiled native addons stay. Run `lint:packaging` after the completed bundle. MCPB is stdio-only; HTTP deployments are unaffected. The bundle file ships as `dist/congressgov-mcp-server.mcpb`.
 
 **Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"`, and an optional string option carries `"default": ""`. The host substitutes only the `user_config` reference; `"${X}"` reaches the server literally.
 
@@ -400,6 +411,7 @@ The `release-and-publish` run handles npm, MCP Registry, bundle, GitHub Release,
 - [ ] If wrapping external API: tests include at least one sparse payload case with omitted upstream fields
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
+- [ ] Root `plugin.json` metadata matches `package.json`; `mcp.json` uses the unscoped server key, `npx -y <full package name>`, and the fixed env from `.codex-plugin/mcp.json`. User variables remain in the overlays; `.codex-plugin/plugin.json` retains `mcpServers: './.codex-plugin/mcp.json'`
 - [ ] `.codex-plugin/plugin.json` populated — `name` and `interface.displayName` = unscoped repo name; `version`, `description`, `repository`, `license` and `interface.shortDescription` from `package.json`
 - [ ] `.codex-plugin/mcp.json` updated — server name key is the unscoped repo name; every user-supplied variable is listed in `env_vars`. Never write `"KEY": ""` into `env` — it overrides the user's exported key
 - [ ] `.claude-plugin/plugin.json` populated — unscoped `name`, `version`, `description`, `author`, `repository`, `license`, `keywords`; inline `mcpServers` entry keyed by the unscoped repo name. User-supplied variables use `userConfig` and `"KEY": "${user_config.<option>}"` env references, matching `manifest.json`

package/Dockerfile

@@ -28,6 +28,9 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
 # Copy the rest of the source code
 COPY . .
 
+# Published agent skills are read from the application root at runtime.
+RUN mkdir -p skills
+
 # Build the application
 RUN bun run build
 
@@ -134,6 +137,7 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
 
 # Copy the compiled application code from the build stage
 COPY --from=build /usr/src/app/dist ./dist
+COPY --from=build /usr/src/app/skills ./skills
 
 # Copy the mirror lifecycle scripts (mirror:init / mirror:refresh / mirror:verify)
 # and the shared context shim they import, then emit a runtime tsconfig so Bun

package/README.md

@@ -1,13 +1,13 @@
 <div align="center">
   <h1>@cyanheads/congressgov-mcp-server</h1>
   <p><b>Access U.S. congressional data (bills, votes, members, committees) via MCP. STDIO or Streamable HTTP.</b>
-  <div>11 Tools • 5 Resources • 2 Prompts</div>
+  <div>11 Tools • 6 Resources • 2 Prompts • 1 Skill</div>
   </p>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.8.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/congressgov-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/congressgov-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/congressgov-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.9.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/congressgov-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/congressgov-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/congressgov-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -56,6 +56,7 @@ US congressional data from Congress.gov and the Senate's official vote feed: bil
 | `congress://member/{bioguideId}` | Member profile by bioguide ID |
 | `congress://bill/{congress}/{billType}/{billNumber}` | Bill detail by congress, type, and number |
 | `congress://committee/{committeeCode}` | Committee detail by committee code |
+| `skill://congressgov-guide/SKILL.md` | Legislative research guide: identifier sources, discovery boundaries, votes, and document evidence |
 
 Bill, member, and committee data is also reachable through `congressgov_bill_lookup`, `congressgov_member_lookup`, and `congressgov_committee_lookup` (operation `get`), since many MCP clients are tool-only and never surface resources.
 
@@ -66,6 +67,10 @@ Bill, member, and committee data is also reachable through `congressgov_bill_loo
 | `congressgov_bill_analysis` | Structured framework for analyzing a bill |
 | `congressgov_legislative_research` | Research framework for a policy area across Congress |
 
+### Agent skill
+
+[`congressgov-guide`](./skills/congressgov-guide/SKILL.md) guides research across bills, laws, members, committees, votes, and floor debate. It covers identifier provenance, discovery limits, and version-specific document evidence. The guide ships with plugin installs, npm, MCPB, and Docker, and is served over MCP through the Skills extension and its `skill://` resource.
+
 ## Capability reference
 
 ### `congressgov_bill_lookup` <sub>tool</sub>
@@ -220,140 +225,32 @@ Agent-friendly output:
 
 ## Getting started
 
-### Public Hosted Instance
-
-A public instance is available at `https://congressgov.caseyjhand.com/mcp` — no installation required. It serves Streamable HTTP; each client takes its own config shape.
-
-For Claude Code:
+Connect to the hosted instance:
 
 ```sh
 claude mcp add --transport http congressgov-mcp-server https://congressgov.caseyjhand.com/mcp
 ```
 
-For Cline (`cline_mcp_settings.json`):
+Or run it locally:
 
-```json
-{
-  "mcpServers": {
-    "congressgov-mcp-server": {
-      "type": "streamableHttp",
-      "url": "https://congressgov.caseyjhand.com/mcp"
-    }
-  }
-}
-```
-
-For Cursor (`mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "congressgov-mcp-server": {
-      "url": "https://congressgov.caseyjhand.com/mcp"
-    }
-  }
-}
-```
-
-Claude Desktop adds remote servers under Settings → Connectors.
-
-### Self-Hosted / Local
-
-Add the following to your MCP client configuration file.
-
-```json
-{
-  "mcpServers": {
-    "congressgov-mcp-server": {
-      "type": "stdio",
-      "command": "bunx",
-      "args": ["@cyanheads/congressgov-mcp-server@latest"],
-      "env": {
-        "MCP_TRANSPORT_TYPE": "stdio",
-        "MCP_LOG_LEVEL": "info",
-        "CONGRESS_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
+```sh
+claude mcp add congressgov-mcp-server -- npx -y @cyanheads/congressgov-mcp-server
 ```
 
-Or with npx (no Bun required):
+For other clients, add this to the MCP config file:
 
 ```json
 {
   "mcpServers": {
     "congressgov-mcp-server": {
-      "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@cyanheads/congressgov-mcp-server@latest"],
-      "env": {
-        "MCP_TRANSPORT_TYPE": "stdio",
-        "MCP_LOG_LEVEL": "info",
-        "CONGRESS_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-Or with Docker:
-
-```json
-{
-  "mcpServers": {
-    "congressgov-mcp-server": {
-      "type": "stdio",
-      "command": "docker",
-      "args": [
-        "run", "-i", "--rm",
-        "-e", "MCP_TRANSPORT_TYPE=stdio",
-        "-e", "CONGRESS_API_KEY=your-api-key",
-        "ghcr.io/cyanheads/congressgov-mcp-server:latest"
-      ]
+      "args": ["-y", "@cyanheads/congressgov-mcp-server"]
     }
   }
 }
 ```
 
-For Streamable HTTP, set the transport and start the server:
-
-```sh
-MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 CONGRESS_API_KEY=your-api-key bun run start:http
-# Server listens at http://localhost:3010/mcp
-```
-
-### Prerequisites
-
-- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
-- Optional: a free [api.data.gov key](https://api.data.gov/signup/) raises the limit to 5,000 requests/hour from the demo key's 30/hour and 50/day per IP.
-
-### Installation
-
-1. **Clone the repository:**
-
-```sh
-git clone https://github.com/cyanheads/congressgov-mcp-server.git
-```
-
-2. **Navigate into the directory:**
-
-```sh
-cd congressgov-mcp-server
-```
-
-3. **Install dependencies:**
-
-```sh
-bun install
-```
-
-4. **Configure environment:**
-
-```sh
-cp .env.example .env
-# edit .env and set CONGRESS_API_KEY (and the mirror vars, if you want keyword search)
-```
+Optional: set `CONGRESS_API_KEY` to a free [api.data.gov key](https://api.data.gov/signup/) for 5,000 requests/hour instead of the demo key's 30/hour and 50/day per IP. For Docker or a source build, see [Running the server](#running-the-server).
 
 ## Configuration
 
@@ -381,6 +278,15 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
 
 ## Running the server
 
+Requires [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
+
+```sh
+git clone https://github.com/cyanheads/congressgov-mcp-server.git
+cd congressgov-mcp-server && bun install
+cp .env.example .env
+# Optionally set CONGRESS_API_KEY and the mirror variables in .env.
+```
+
 ### Local development
 
 - **Build and run the production version:**
@@ -411,17 +317,17 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
 ### Docker
 
 ```sh
-docker build -t congressgov-mcp-server .
-docker run --rm -e CONGRESS_API_KEY=your-api-key -p 3010:3010 congressgov-mcp-server
+docker run --rm -e CONGRESS_API_KEY=your-api-key -p 3010:3010 ghcr.io/cyanheads/congressgov-mcp-server:latest
 ```
 
-The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/congressgov-mcp-server`. OpenTelemetry peer dependencies are installed by default; build with `--build-arg OTEL_ENABLED=false` to omit them. The image carries the mirror scripts, so `docker exec <container> bun run mirror:init` builds the index in place.
+The image defaults to HTTP transport, stateless session mode, and logs to `/var/log/congressgov-mcp-server`. For stdio, use `docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/congressgov-mcp-server:latest`. To build locally, run `docker build -t congressgov-mcp-server .`; OpenTelemetry peer dependencies are installed by default, with `--build-arg OTEL_ENABLED=false` to omit them. The image carries the mirror scripts, so `docker exec <container> bun run mirror:init` builds the index in place.
 
 ## Project structure
 
 | Directory | Purpose |
 |:---|:---|
 | `src/index.ts` | `createApp()` entry point: registers tools, resources, and prompts, inits services, and schedules the mirror refresh. |
+| `skills/` | Published legislative research guide for agents calling the server. |
 | `src/config/` | Server-specific environment variable parsing and validation with Zod. |
 | `src/mcp-server/tools/` | Tool definitions (`definitions/*.tool.ts`) plus shared input, formatting, and summary-window helpers. |
 | `src/mcp-server/resources/definitions/` | Resource definitions (`*.resource.ts`). |

package/changelog/0.9.x/0.9.0.md

@@ -0,0 +1,25 @@
+---
+summary: "Publish a legislative research guide over MCP and refresh framework and bundle delivery."
+breaking: false
+security: false
+---
+
+# 0.9.0 — 2026-10-28
+
+## Added
+
+- Publish congressgov-guide as the skill://congressgov-guide/SKILL.md MCP resource for legislative research workflows.
+- **Agent Plugins manifests** add the root `plugin.json` and `mcp.json` pair alongside the existing client overlays.
+
+## Changed
+
+- **MCPB delivery** excludes root development paths, dependency agent documentation, node-gyp build output, and build-only package files while retaining executable SDK skill modules ([mcp-ts-core #794](https://github.com/cyanheads/mcp-ts-core/issues/794)).
+- **HTTP lifecycle** adopts the framework fix that releases request signals after responses finish.
+- **Maintenance references** sync framework guidance, simplify installation examples, and correct legislative data and service documentation.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.16 → ^0.13.18.
+- `@biomejs/biome` ^2.6.2 → ^2.6.3.
+- `ignore` ^7.0.13 → ^7.0.14.
+- `tsc-alias` ^1.9.8 → ^1.9.9.

package/dist/index.js

@@ -64,6 +64,7 @@ await createApp({
     name: 'congressgov-mcp-server',
     title: 'congressgov-mcp-server',
     sessionMode: 'stateless',
+    skills: 'skills',
     cacheHints,
     tools: [
         withSource(billLookupTool, 'tools', 'bill-lookup.tool.ts'),

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/congressgov-mcp-server",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Access U.S. congressional data (bills, votes, members, committees) via MCP. STDIO or Streamable HTTP.",
   "mcpName": "io.github.cyanheads/congressgov-mcp-server",
   "type": "module",
@@ -11,6 +11,7 @@
   },
   "files": [
     "changelog/",
+    "skills/",
     "dist/",
     "!dist/*.mcpb",
     "scripts/_mirror-context.ts",
@@ -95,7 +96,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@cyanheads/mcp-ts-core": "^0.13.16",
+    "@cyanheads/mcp-ts-core": "^0.13.18",
     "better-sqlite3": "^13.0.3",
     "fast-xml-parser": "^5.11.2",
     "node-cron": "^4.6.0",
@@ -103,12 +104,12 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.6.2",
+    "@biomejs/biome": "^2.6.3",
     "@socketsecurity/bun-security-scanner": "^1.1.3",
     "@types/node": "^26.6.5",
     "depcheck": "^1.4.7",
-    "ignore": "^7.0.13",
-    "tsc-alias": "^1.9.8",
+    "ignore": "^7.0.14",
+    "tsc-alias": "^1.9.9",
     "typescript": "^7.0.2",
     "vitest": "^5.0.5"
   }

package/server.json

@@ -6,7 +6,7 @@
     "url": "https://github.com/cyanheads/congressgov-mcp-server",
     "source": "github"
   },
-  "version": "0.8.1",
+  "version": "0.9.0",
   "remotes": [
     {
       "type": "streamable-http",
@@ -19,7 +19,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/congressgov-mcp-server",
       "runtimeHint": "npx",
-      "version": "0.8.1",
+      "version": "0.9.0",
       "environmentVariables": [
         {
           "name": "CONGRESS_API_KEY",
@@ -44,7 +44,7 @@
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/congressgov-mcp-server",
       "runtimeHint": "npx",
-      "version": "0.8.1",
+      "version": "0.9.0",
       "environmentVariables": [
         {
           "name": "MCP_TRANSPORT_TYPE",

package/skills/congressgov-guide/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: congressgov-guide
+description: Use congressgov_* tools for legislative research across bills, enacted laws, members, committees, votes, and Congressional Record documents. Resolve linked identifiers, select the relevant document version, and check discovery coverage before reporting absence.
+license: Apache-2.0
+metadata:
+  author: "cyanheads"
+  version: "1.0"
+---
+
+## Scope
+
+Use for U.S. congressional research that follows legislation into its sponsors, committees, votes, reports, or floor debate. A topic alone needs a discovery path: the optional bill mirror searches titles and CRS summaries, not full bill text, CRS reports, or the Congressional Record.
+
+## Identifiers
+
+Carry identifiers from returned records across tool calls:
+
+| Entity | Provenance |
+|:---|:---|
+| Bill | Congress, bill type, and bill number from bill discovery, member portfolios, or related bills |
+| Member | `bioguideId` from member discovery or a bill's sponsors and cosponsors |
+| Committee | `systemCode` from committee discovery; resolve a committee name and inspect the candidates before following its legislation |
+| Enacted law | `laws[].number` on an enacted-law row; the row's own bill number identifies the origin bill |
+| Roll call | Chamber, congress, session, and roll number from vote discovery; retain the complete identity when reading detail and positions |
+| Record article | Volume and issue from Record discovery, then the article's absolute position within the issue |
+
+## Gates
+
+- Before topical discovery, check whether `congressgov_search_bills` is offered. If absent, obtain a bill, member, committee, or CRS report seed; do not send a topic to browse-only tools. Committee name matching resolves committee names, not policy topics.
+- Before reporting no relevant bills, inspect search notices and coverage. An unbuilt mirror returns no results, and a ready mirror covers a bounded congress window and only titles and summaries. Broaden overly specific terms; report the search boundary with any negative finding.
+- Before interpreting recent activity, distinguish a record's update date from its `latestAction.actionDate`. The update date does not establish when legislative action occurred.
+- Before comparing provisions or quoting legislation, select the relevant published text version and inspect its label and any supplied date. A date may be absent; do not infer one from the bill's update date. A discovery preview or CRS summary is not the bill text; preserve the version and source URL with the evidence.
+- Before interpreting a member's vote as support for a bill, inspect the roll call's question, associated measure, and result. Match the requested chamber and session; a vote associated with a bill does not by itself establish final passage.
+- Before concluding a committee was resolved, inspect whether the response contains the requested detail or candidate rows. Choose a candidate by its returned name, chamber, and code; approximate matches need the same check.
+
+## Core chain
+
+Start from a discovered bill identity and read `congressgov_bill_lookup` detail. Use its summaries for orientation and its latest action for status; inspect published text when the answer depends on a provision. Follow sponsor identities into `congressgov_member_lookup` and related bill identities back into bill lookup. Resolve committees through committee discovery. Keep each claim attached to its bill and version when combining findings across these branches.
+
+## Workflows
+
+**Topic research.** When available, use `congressgov_search_bills` to obtain candidate bills, then verify candidates through live bill lookup. Search terms are AND-combined ordinary text; use fewer terms or separate searches for alternatives rather than FTS Boolean operators. Follow related bills and relevant sponsor portfolios to widen the investigation. Search silence says nothing about whether CRS analysis or floor debate exists.
+
+**Enacted law.** Use `congressgov_enacted_laws` to resolve a law citation, then follow the returned origin bill through bill lookup. Keep the law citation and bill identity distinct. Read the intended published version before describing the enacted provisions.
+
+**Member voting.** Resolve the person through member discovery or a bill's sponsor records. Find the relevant roll call with `congressgov_roll_votes`, inspect its detail, then read positions for that same roll call. House data comes from Congress.gov and Senate data from the Senate LIS feed; inspect the returned roster fields before joining them to member profiles.
+
+**Floor debate.** Navigate `congressgov_daily_record` from volumes to issues to articles. When an article comes from a later page, its content selection uses the absolute issue position, not its position within that page. Read the selected article's content and retain its title and source URL.
+
+**Document evidence.** Bill and committee-report text listings expose versions or formats; they do not contain the document body. Use the corresponding content operation to read it. Continue with the returned content offset while preserving the same document selection and format. Summary text has a separate continuation offset: use the summary row's continuation and retain its version code instead of advancing the list page. Distinguish an unfinished text window from the end of a list.