@cyanheads/openfec-mcp-server 0.4.0 → 0.4.2

package/CLAUDE.md

@@ -1,8 +1,9 @@
 # Agent Protocol
 
 **Server:** openfec-mcp-server
-**Version:** 0.3.1
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
+**Version:** 0.4.2
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.8.19`
+**Engines:** Bun ≥1.3.0, Node ≥24.0.0
 
 > **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.
 
@@ -14,13 +15,14 @@ When the user asks what to do next, what's left, or needs direction, suggest rel
 
 1. **Re-run the `setup` skill** — ensures CLAUDE.md, skills, structure, and metadata are populated and up to date with the current codebase
 2. **Run the `design-mcp-server` skill** — if the tool/resource surface hasn't been mapped yet, work through domain design
-3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-resource`, `add-prompt` skills
+3. **Add tools/resources/prompts** — scaffold new definitions using the `add-tool`, `add-app-tool`, `add-resource`, `add-prompt` skills
 4. **Add services** — scaffold domain service integrations using the `add-service` skill
 5. **Add tests** — scaffold tests for existing definitions using the `add-test` skill
 6. **Field-test definitions** — exercise tools/resources/prompts with real inputs using the `field-test` skill, get a report of issues and pain points
 7. **Run `devcheck`** — lint, format, typecheck, and security audit
-8. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
-9. **Run the `maintenance` skill** — sync skills and dependencies after framework updates
+8. **Run the `security-pass` skill** — audit handlers for MCP-specific security gaps: output injection, scope blast radius, input sinks, tenant isolation
+9. **Run the `polish-docs-meta` skill** — finalize README, CHANGELOG, metadata, and agent protocol for shipping
+10. **Run the `maintenance` skill** — investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest`
 
 Tailor suggestions to what's actually missing or stale — don't recite the full list every time.
 
@@ -34,9 +36,10 @@ The OpenFEC OpenAPI spec (Swagger 2.0) is at `docs/openapi-spec.json` — 100 pa
 
 ## Core Rules
 
-- **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Plain `Error` is fine; the framework catches, classifies, and formats. Use error factories (`notFound()`, `validationError()`, etc.) when the error code matters.
+- **Logic throws, framework catches.** Tool/resource handlers are pure — throw on failure, no `try/catch`. Prefer typed contracts (`errors[]` + `ctx.fail(reason)`) when the failure is part of the public surface; fall back to error factories (`notFound()`, `validationError()`) or plain `Error` otherwise. The framework catches, classifies, and formats.
 - **Use `ctx.log`** for request-scoped logging. No `console` calls.
 - **Use `ctx.state`** for tenant-scoped storage. Never access persistence directly.
+- **Check `ctx.elicit` / `ctx.sample`** for presence before calling.
 - **Secrets in env vars only** — never hardcoded.
 
 ---
@@ -47,12 +50,24 @@ The OpenFEC OpenAPI spec (Swagger 2.0) is at `docs/openapi-spec.json` — 100 pa
 
 ```ts
 import { tool, z } from '@cyanheads/mcp-ts-core';
-import { invalidParams } from '@cyanheads/mcp-ts-core/errors';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { getOpenFecService } from '@/services/openfec/openfec-service.js';
+import { validateCandidateId } from './utils/id-validators.js';
 
 export const searchCandidates = tool('openfec_search_candidates', {
   description: 'Find federal candidates by name, state, office, party, or cycle.',
   annotations: { readOnlyHint: true, idempotentHint: true },
+
+  errors: [
+    {
+      reason: 'candidate_not_found',
+      code: JsonRpcErrorCode.NotFound,
+      when: 'Single-candidate lookup by candidate_id returned no record',
+      recovery:
+        'Verify the candidate_id format (H/S/P + digits) or drop it and search by name, state, or cycle.',
+    },
+  ],
+
   input: z.object({
     query: z.string().optional().describe('Full-text candidate name search.'),
     candidate_id: z.string().optional().describe('FEC candidate ID (e.g., P00003392).'),
@@ -66,10 +81,14 @@ export const searchCandidates = tool('openfec_search_candidates', {
   }),
   async handler(input, ctx) {
     const fec = getOpenFecService();
-    if (input.candidate_id && !/^[HSP]\d+$/i.test(input.candidate_id)) {
-      throw invalidParams('Invalid candidate ID format', { candidate_id: input.candidate_id });
-    }
+    if (input.candidate_id) validateCandidateId(input.candidate_id);
     const result = await fec.searchCandidates(input, ctx);
+    if (input.candidate_id && result.candidates.length === 0) {
+      throw ctx.fail('candidate_not_found', `Candidate ${input.candidate_id} not found.`, {
+        candidate_id: input.candidate_id,
+        ...ctx.recoveryFor('candidate_not_found'),
+      });
+    }
     ctx.log.info('Candidate search completed', { count: result.pagination.count });
     return result;
   },
@@ -167,24 +186,38 @@ Handlers receive a unified `ctx` object. Key properties:
 
 ## Errors
 
-Handlers throw — the framework catches, classifies, and formats. Three escalation levels:
+Handlers throw — the framework catches, classifies, and formats.
+
+**Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()`. The handler then receives `ctx.fail(reason, msg?, data?)` keyed against the contract reason union — `ctx.fail('typo')` is a TypeScript error. The framework auto-populates `data.reason`, the linter enforces conformance, and the `recovery` string (≥5 words) is the source of truth for the recovery hint that flows to the wire. Spread `ctx.recoveryFor('reason')` into `data` to opt the contract recovery onto the wire payload.
 
 ```ts
-// 1. Plain Error — framework auto-classifies from message patterns
-throw new Error('Item not found');           // → NotFound
-throw new Error('Invalid query format');     // → ValidationError
+errors: [
+  { reason: 'candidate_not_found', code: JsonRpcErrorCode.NotFound,
+    when: 'Single-candidate lookup returned no record',
+    recovery: 'Verify the candidate_id (H/S/P + digits) or drop it and search by name.' },
+],
+async handler(input, ctx) {
+  if (!found) {
+    throw ctx.fail('candidate_not_found', `Candidate ${id} not found.`, {
+      candidate_id: id,
+      ...ctx.recoveryFor('candidate_not_found'),
+    });
+  }
+}
+```
 
-// 2. Error factories — explicit code, concise
-import { notFound, validationError, forbidden, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
-throw notFound('Item not found', { itemId });
-throw serviceUnavailable('API unavailable', { url }, { cause: err });
+**Declare contracts inline on each tool**, even when reasons look similar across tools — per-tool repetition is the intended cost of locality.
 
-// 3. McpError — full control over code and data
-import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
-throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
+**Fallback (no contract entry fits):** error factories or plain `Error`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely without contract entries.
+
+```ts
+import { notFound, validationError, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+throw validationError('Invalid query format', { field: 'query' });    // baseline — fine
+throw serviceUnavailable('API unavailable', { url }, { cause: err });
+throw new Error('Item not found');                                    // auto-classifies → NotFound
 ```
 
-Plain `Error` is fine for most cases. Use factories when the error code matters. See framework CLAUDE.md for the full auto-classification table and all available factories.
+Note: `invalidParams` is for malformed JSON-RPC params (rare post-Zod). For semantic post-shape validation, use `validationError`. See the framework `api-errors` skill for the full reference.
 
 ---
 
@@ -236,7 +269,7 @@ src/
 
 Skills are modular instructions in `skills/` at the project root. Read them directly when a task matches — e.g., `skills/add-tool/SKILL.md` when adding a tool.
 
-**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 `skills/` paths manually. After framework updates, re-copy to pick up changes.
+**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 `skills/` paths manually. After framework updates, run the `maintenance` skill — it re-syncs the agent directory automatically (Phase B).
 
 Available skills:
 
@@ -251,18 +284,25 @@ Available skills:
 | `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 |
+| `tool-defs-analysis` | Read-only audit of definition language across the surface (10 categories: voice, leaks, defaults, recovery, structure, …) |
+| `security-pass` | Audit server for MCP-flavored security gaps: output injection, scope blast radius, input sinks, tenant isolation |
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
-| `maintenance` | Sync skills and dependencies after updates |
+| `release-and-publish` | Post-wrapup ship workflow: verification gate, push commits/tags, publish to npm + MCP Registry + GHCR |
+| `maintenance` | Investigate changelogs, adopt upstream changes, sync skills and framework scripts |
+| `migrate-mcp-ts-template` | Migrate a legacy template fork to use `@cyanheads/mcp-ts-core` as a package dependency |
 | `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
 | `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
+| `api-canvas` | DataCanvas: register tabular data, run SQL, export, plus the `spillover()` helper for big result sets — Tier 3 opt-in |
 | `api-config` | AppConfig, parseConfig, env vars |
-| `api-context` | Context interface, logger, state, progress |
-| `api-errors` | McpError, JsonRpcErrorCode, error patterns |
+| `api-context` | Context interface, logger, state, progress, sessionId, recoveryFor |
+| `api-errors` | McpError, JsonRpcErrorCode, typed error contracts, factories |
+| `api-linter` | MCP definition lint rules reference — look here when devcheck flags `format-parity`, `schema-*`, `name-*`, `server-json-*`, etc. |
 | `api-services` | LLM, Speech, Graph services |
+| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-testing` | createMockContext, test patterns |
-| `api-utils` | Formatting, parsing, security, pagination, scheduling |
+| `api-utils` | Formatting, parsing, security, pagination, scheduling, telemetry helpers |
 | `api-workers` | Cloudflare Workers runtime |
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
@@ -281,16 +321,17 @@ When you complete a skill's checklist, check the boxes and add a completion time
 | `bun run format` | Auto-fix formatting |
 | `bun run lint:mcp` | Validate MCP tool/resource/prompt definitions |
 | `bun run test` | Run tests |
-| `bun run dev:stdio` | Dev mode (stdio) |
-| `bun run dev:http` | Dev mode (HTTP) |
+| `bun run start` | Production mode (transport from `MCP_TRANSPORT_TYPE`) |
 | `bun run start:stdio` | Production mode (stdio) |
 | `bun run start:http` | Production mode (HTTP) |
 
+For dev / smoke-testing, use `bun run rebuild && bun run start:stdio` (or `start:http`) — production-shape execution against the built `dist/`.
+
 ---
 
 ## Publishing
 
-After a version bump and final commit, publish to both npm and GHCR:
+Run the `release-and-publish` skill for the full flow (verification gate, push, npm + MCP Registry + GHCR). Reference commands:
 
 ```bash
 bun publish --access public
@@ -301,8 +342,6 @@ docker buildx build --platform linux/amd64,linux/arm64 \
   --push .
 ```
 
-Remind the user to run these after completing a release flow.
-
 ---
 
 ## Imports
@@ -320,12 +359,12 @@ import { getOpenFecService } from '@/services/openfec/openfec-service.js';
 
 ## Checklist
 
-- [ ] Zod schemas: all fields have `.describe()`, only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, etc.)
+- [ ] Zod schemas: all fields have `.describe()` (including nested object fields and array element types), only JSON-Schema-serializable types (no `z.custom()`, `z.date()`, `z.transform()`, `z.bigint()`, `z.symbol()`, `z.void()`, `z.map()`, `z.set()`, `z.function()`, `z.nan()`)
 - [ ] Optional nested objects: handler guards for empty inner values from form-based clients (`if (input.obj?.field && ...)`, not just `if (input.obj)`)
 - [ ] JSDoc `@fileoverview` + `@module` on every file
 - [ ] `ctx.log` for logging, `ctx.state` for storage
 - [ ] Handlers throw on failure — error factories or plain `Error`, no try/catch
-- [ ] `format()` renders all data the LLM needs — `content[]` is the only field most clients forward to the model
+- [ ] `format()` renders all data the LLM needs — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
 - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
 - [ ] Tests use `createMockContext()` from `@cyanheads/mcp-ts-core/testing`
 - [ ] `bun run devcheck` passes

package/README.md

@@ -6,9 +6,9 @@
 
 <div align="center">
 
-[![npm](https://img.shields.io/npm/v/@cyanheads/openfec-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openfec-mcp-server) [![Version](https://img.shields.io/badge/Version-0.4.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) 
+[![npm](https://img.shields.io/npm/v/@cyanheads/openfec-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openfec-mcp-server) [![Version](https://img.shields.io/badge/Version-0.4.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) 
 
-[![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-^1.2.0-f9f1e1.svg?style=flat-square)](https://bun.sh/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-^1.3.0-f9f1e1.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 

package/dist/mcp-server/resources/definitions/candidate.resource.d.ts

@@ -4,7 +4,13 @@
  * @module src/mcp-server/resources/definitions/candidate.resource
  */
 import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 export declare const candidateResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
     candidate_id: z.ZodString;
-}, z.core.$strip>, undefined>;
+}, z.core.$strip>, undefined, readonly [{
+    readonly reason: "candidate_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No candidate exists for the supplied candidate_id";
+    readonly recovery: "Verify the candidate_id format (H/S/P + digits) or look up the candidate by name via openfec_search_candidates.";
+}]>;
 //# sourceMappingURL=candidate.resource.d.ts.map

package/dist/mcp-server/resources/definitions/candidate.resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidate.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/candidate.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAIrD,eAAO,MAAM,iBAAiB;;6BAuB5B,CAAC"}
+{"version":3,"file":"candidate.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/candidate.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,iBAAiB;;;;;;;GAsC5B,CAAC"}

package/dist/mcp-server/resources/definitions/candidate.resource.js

@@ -4,6 +4,7 @@
  * @module src/mcp-server/resources/definitions/candidate.resource
  */
 import { resource, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { validateCandidateId } from '../../../mcp-server/tools/definitions/utils/id-validators.js';
 import { getOpenFecService } from '../../../services/openfec/openfec-service.js';
 export const candidateResource = resource('openfec://candidate/{candidate_id}', {
@@ -13,13 +14,25 @@ export const candidateResource = resource('openfec://candidate/{candidate_id}',
     params: z.object({
         candidate_id: z.string().describe('FEC candidate ID (e.g., P00003392, H2CO07170, S4AZ00345)'),
     }),
+    errors: [
+        {
+            reason: 'candidate_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No candidate exists for the supplied candidate_id',
+            recovery: 'Verify the candidate_id format (H/S/P + digits) or look up the candidate by name via openfec_search_candidates.',
+        },
+    ],
     async handler(params, ctx) {
         validateCandidateId(params.candidate_id);
         const fec = getOpenFecService();
         const candidateResult = await fec.getCandidate(params.candidate_id, ctx);
         const candidate = candidateResult.results[0];
-        if (!candidate)
-            throw new Error(`Candidate ${params.candidate_id} not found`);
+        if (!candidate) {
+            throw ctx.fail('candidate_not_found', `Candidate ${params.candidate_id} not found.`, {
+                candidate_id: params.candidate_id,
+                ...ctx.recoveryFor('candidate_not_found'),
+            });
+        }
         const totalsResult = await fec.getCandidateTotals({ candidate_id: params.candidate_id }, ctx);
         const totals = totalsResult.results[0];
         ctx.log.info('Candidate resource fetched', { candidate_id: params.candidate_id });

package/dist/mcp-server/resources/definitions/candidate.resource.js.map

@@ -1 +1 @@
-{"version":3,"file":"candidate.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/candidate.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,oCAAoC,EAAE;IAC9E,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EACT,uJAAuJ;IACzJ,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0DAA0D,CAAC;KAC9F,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,mBAAmB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAEzC,MAAM,GAAG,GAAG,iBAAiB,EAAE,CAAC;QAChC,MAAM,eAAe,GAAG,MAAM,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;QACzE,MAAM,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,MAAM,CAAC,YAAY,YAAY,CAAC,CAAC;QAE9E,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,kBAAkB,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,EAAE,GAAG,CAAC,CAAC;QAC9F,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAEvC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;QAClF,OAAO,EAAE,GAAG,SAAS,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;IAC7C,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"candidate.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/candidate.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,oCAAoC,EAAE;IAC9E,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EACT,uJAAuJ;IACzJ,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0DAA0D,CAAC;KAC9F,CAAC;IAEF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,qBAAqB;YAC7B,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,mDAAmD;YACzD,QAAQ,EACN,iHAAiH;SACpH;KACF;IAED,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,mBAAmB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAEzC,MAAM,GAAG,GAAG,iBAAiB,EAAE,CAAC;QAChC,MAAM,eAAe,GAAG,MAAM,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;QACzE,MAAM,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,GAAG,CAAC,IAAI,CAAC,qBAAqB,EAAE,aAAa,MAAM,CAAC,YAAY,aAAa,EAAE;gBACnF,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,GAAG,GAAG,CAAC,WAAW,CAAC,qBAAqB,CAAC;aAC1C,CAAC,CAAC;QACL,CAAC;QAED,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,kBAAkB,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,EAAE,GAAG,CAAC,CAAC;QAC9F,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAEvC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;QAClF,OAAO,EAAE,GAAG,SAAS,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;IAC7C,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/committee.resource.d.ts

@@ -4,7 +4,13 @@
  * @module src/mcp-server/resources/definitions/committee.resource
  */
 import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 export declare const committeeResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
     committee_id: z.ZodString;
-}, z.core.$strip>, undefined>;
+}, z.core.$strip>, undefined, readonly [{
+    readonly reason: "committee_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No committee exists for the supplied committee_id";
+    readonly recovery: "Verify the committee_id format (C + digits) or look up the committee by name via openfec_search_committees.";
+}]>;
 //# sourceMappingURL=committee.resource.d.ts.map

package/dist/mcp-server/resources/definitions/committee.resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"committee.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/committee.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAGrD,eAAO,MAAM,iBAAiB;;6BAkB5B,CAAC"}
+{"version":3,"file":"committee.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/committee.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,iBAAiB;;;;;;;GAmC5B,CAAC"}

package/dist/mcp-server/resources/definitions/committee.resource.js

@@ -4,6 +4,8 @@
  * @module src/mcp-server/resources/definitions/committee.resource
  */
 import { resource, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { validateCommitteeId } from '../../../mcp-server/tools/definitions/utils/id-validators.js';
 import { getOpenFecService } from '../../../services/openfec/openfec-service.js';
 export const committeeResource = resource('openfec://committee/{committee_id}', {
     name: 'FEC Committee Profile',
@@ -12,12 +14,25 @@ export const committeeResource = resource('openfec://committee/{committee_id}',
     params: z.object({
         committee_id: z.string().describe('FEC committee ID (e.g., C00358796)'),
     }),
+    errors: [
+        {
+            reason: 'committee_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No committee exists for the supplied committee_id',
+            recovery: 'Verify the committee_id format (C + digits) or look up the committee by name via openfec_search_committees.',
+        },
+    ],
     async handler(params, ctx) {
+        validateCommitteeId(params.committee_id);
         const fec = getOpenFecService();
         const result = await fec.getCommittee(params.committee_id, ctx);
         const committee = result.results[0];
-        if (!committee)
-            throw new Error(`Committee ${params.committee_id} not found`);
+        if (!committee) {
+            throw ctx.fail('committee_not_found', `Committee ${params.committee_id} not found.`, {
+                committee_id: params.committee_id,
+                ...ctx.recoveryFor('committee_not_found'),
+            });
+        }
         ctx.log.info('Committee resource fetched', { committee_id: params.committee_id });
         return committee;
     },

package/dist/mcp-server/resources/definitions/committee.resource.js.map

@@ -1 +1 @@
-{"version":3,"file":"committee.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/committee.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,oCAAoC,EAAE;IAC9E,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EACT,qJAAqJ;IACvJ,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;KACxE,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,MAAM,GAAG,GAAG,iBAAiB,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;QAChE,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,MAAM,CAAC,YAAY,YAAY,CAAC,CAAC;QAE9E,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;QAClF,OAAO,SAAS,CAAC;IACnB,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"committee.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/committee.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uDAAuD,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,QAAQ,CAAC,oCAAoC,EAAE;IAC9E,IAAI,EAAE,uBAAuB;IAC7B,WAAW,EACT,qJAAqJ;IACvJ,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oCAAoC,CAAC;KACxE,CAAC;IAEF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,qBAAqB;YAC7B,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,mDAAmD;YACzD,QAAQ,EACN,6GAA6G;SAChH;KACF;IAED,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,mBAAmB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAEzC,MAAM,GAAG,GAAG,iBAAiB,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;QAChE,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,GAAG,CAAC,IAAI,CAAC,qBAAqB,EAAE,aAAa,MAAM,CAAC,YAAY,aAAa,EAAE;gBACnF,YAAY,EAAE,MAAM,CAAC,YAAY;gBACjC,GAAG,GAAG,CAAC,WAAW,CAAC,qBAAqB,CAAC;aAC1C,CAAC,CAAC;QACL,CAAC;QAED,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,4BAA4B,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;QAClF,OAAO,SAAS,CAAC;IACnB,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/election.resource.d.ts

@@ -8,18 +8,18 @@ import { z } from '@cyanheads/mcp-ts-core';
 export declare const electionResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
     cycle: z.ZodString;
     office: z.ZodString;
-}, z.core.$strip>, undefined>;
+}, z.core.$strip>, undefined, undefined>;
 /** Senate races: openfec://election/2024/senate/AZ */
 export declare const electionStateResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
     cycle: z.ZodString;
     office: z.ZodString;
     state: z.ZodString;
-}, z.core.$strip>, undefined>;
+}, z.core.$strip>, undefined, undefined>;
 /** House races: openfec://election/2024/house/CA/12 */
 export declare const electionDistrictResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
     cycle: z.ZodString;
     office: z.ZodString;
     state: z.ZodString;
     district: z.ZodString;
-}, z.core.$strip>, undefined>;
+}, z.core.$strip>, undefined, undefined>;
 //# sourceMappingURL=election.resource.d.ts.map

package/dist/mcp-server/resources/definitions/election.resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"election.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/election.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAmCrD,yEAAyE;AACzE,eAAO,MAAM,gBAAgB;;;6BAU3B,CAAC;AAEH,sDAAsD;AACtD,eAAO,MAAM,qBAAqB;;;;6BAUhC,CAAC;AAEH,uDAAuD;AACvD,eAAO,MAAM,wBAAwB;;;;;6BAcpC,CAAC"}
+{"version":3,"file":"election.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/election.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAmCrD,yEAAyE;AACzE,eAAO,MAAM,gBAAgB;;;wCAU3B,CAAC;AAEH,sDAAsD;AACtD,eAAO,MAAM,qBAAqB;;;;wCAUhC,CAAC;AAEH,uDAAuD;AACvD,eAAO,MAAM,wBAAwB;;;;;wCAcpC,CAAC"}

package/dist/mcp-server/resources/definitions/index.d.ts

@@ -7,10 +7,20 @@ export { committeeResource } from './committee.resource.js';
 export { electionDistrictResource, electionResource, electionStateResource, } from './election.resource.js';
 export declare const allResourceDefinitions: (import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
     candidate_id: import("zod").ZodString;
-}, import("zod/v4/core").$strip>, undefined> | import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
+}, import("zod/v4/core").$strip>, undefined, readonly [{
+    readonly reason: "candidate_not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "No candidate exists for the supplied candidate_id";
+    readonly recovery: "Verify the candidate_id format (H/S/P + digits) or look up the candidate by name via openfec_search_candidates.";
+}]> | import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
     committee_id: import("zod").ZodString;
-}, import("zod/v4/core").$strip>, undefined> | import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
+}, import("zod/v4/core").$strip>, undefined, readonly [{
+    readonly reason: "committee_not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "No committee exists for the supplied committee_id";
+    readonly recovery: "Verify the committee_id format (C + digits) or look up the committee by name via openfec_search_committees.";
+}]> | import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
     cycle: import("zod").ZodString;
     office: import("zod").ZodString;
-}, import("zod/v4/core").$strip>, undefined>)[];
+}, import("zod/v4/core").$strip>, undefined, undefined>)[];
 //# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/resources/definitions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAUhC,eAAO,MAAM,sBAAsB;;;;;;;+CAMlC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAUhC,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;0DAMlC,CAAC"}

package/dist/mcp-server/tools/definitions/index.d.ts

@@ -41,7 +41,7 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
         per_page: import("zod").ZodNumber;
     }, import("zod/v4/core").$strip>;
     search_criteria: import("zod").ZodOptional<import("zod").ZodObject<{}, import("zod/v4/core").$loose>>;
-}, import("zod/v4/core").$strip>> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+}, import("zod/v4/core").$strip>, undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     mode: import("zod").ZodDefault<import("zod").ZodEnum<{
         summary: "summary";
         search: "search";
@@ -65,7 +65,27 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
         per_page: import("zod").ZodNumber;
     }, import("zod/v4/core").$strip>;
     search_criteria: import("zod").ZodOptional<import("zod").ZodObject<{}, import("zod/v4/core").$loose>>;
-}, import("zod/v4/core").$strip>> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "cycle_must_be_even";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Cycle is an odd year";
+    readonly recovery: "Federal election cycles are two-year periods ending in even years (e.g., 2024, 2026).";
+}, {
+    readonly reason: "missing_state_for_office";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Senate or House office without a state and without a zip";
+    readonly recovery: "Provide a two-letter state code (e.g., AZ) or a zip code to scope the senate or house race.";
+}, {
+    readonly reason: "missing_district_for_house";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "House office without a district number and without a zip";
+    readonly recovery: "Provide a two-digit district number (e.g., \"07\") or a zip code to identify the House race.";
+}, {
+    readonly reason: "summary_does_not_support_zip";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Summary mode invoked with a zip parameter";
+    readonly recovery: "Use mode \"search\" for ZIP-based lookups, or remove zip and use state and district for summary mode.";
+}]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     query: import("zod").ZodOptional<import("zod").ZodString>;
     candidate_id: import("zod").ZodOptional<import("zod").ZodString>;
     state: import("zod").ZodOptional<import("zod").ZodString>;
@@ -103,7 +123,12 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
         per_page: import("zod").ZodNumber;
     }, import("zod/v4/core").$strip>;
     search_criteria: import("zod").ZodOptional<import("zod").ZodObject<{}, import("zod/v4/core").$loose>>;
-}, import("zod/v4/core").$strip>> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "candidate_not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "Single-candidate lookup by candidate_id returned no record";
+    readonly recovery: "Verify the candidate_id format (H/S/P + digits) or drop it and search by name, state, or cycle.";
+}]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     query: import("zod").ZodOptional<import("zod").ZodString>;
     committee_id: import("zod").ZodOptional<import("zod").ZodString>;
     candidate_id: import("zod").ZodOptional<import("zod").ZodString>;
@@ -124,7 +149,12 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
         per_page: import("zod").ZodNumber;
     }, import("zod/v4/core").$strip>;
     search_criteria: import("zod").ZodOptional<import("zod").ZodObject<{}, import("zod/v4/core").$loose>>;
-}, import("zod/v4/core").$strip>> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "committee_not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "Single-committee lookup by committee_id returned no record";
+    readonly recovery: "Verify the committee_id format (C + digits) or drop it and search by name, candidate_id, or type.";
+}]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     mode: import("zod").ZodDefault<import("zod").ZodEnum<{
         by_size: "by_size";
         by_state: "by_state";
@@ -163,7 +193,17 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
         per_page: import("zod").ZodNumber;
     }, import("zod/v4/core").$strip>>;
     search_criteria: import("zod").ZodOptional<import("zod").ZodObject<{}, import("zod/v4/core").$loose>>;
-}, import("zod/v4/core").$strip>> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "itemized_requires_committee_id";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Itemized mode invoked without a committee_id";
+    readonly recovery: "Provide a committee_id, switch to a by_size or by_state aggregate mode with candidate_id, or look up the candidate's committee with openfec_search_committees.";
+}, {
+    readonly reason: "aggregate_requires_committee_id";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "by_employer or by_occupation aggregate without a committee_id";
+    readonly recovery: "These aggregates roll up to a single committee — provide a committee_id for the spending committee.";
+}]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     mode: import("zod").ZodDefault<import("zod").ZodEnum<{
         by_purpose: "by_purpose";
         by_recipient: "by_recipient";
@@ -199,7 +239,7 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
         per_page: import("zod").ZodNumber;
     }, import("zod/v4/core").$strip>>;
     search_criteria: import("zod").ZodOptional<import("zod").ZodObject<{}, import("zod/v4/core").$loose>>;
-}, import("zod/v4/core").$strip>> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+}, import("zod/v4/core").$strip>, undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     mode: import("zod").ZodDefault<import("zod").ZodEnum<{
         itemized: "itemized";
         by_candidate: "by_candidate";
@@ -243,7 +283,12 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
         per_page: import("zod").ZodNumber;
     }, import("zod/v4/core").$strip>>;
     search_criteria: import("zod").ZodOptional<import("zod").ZodObject<{}, import("zod/v4/core").$loose>>;
-}, import("zod/v4/core").$strip>> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "by_candidate_requires_candidate_id";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "by_candidate mode invoked without a candidate_id";
+    readonly recovery: "Find the candidate ID via openfec_search_candidates, then pass it here to see independent expenditures supporting or opposing that candidate.";
+}]> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     committee_id: import("zod").ZodOptional<import("zod").ZodString>;
     candidate_id: import("zod").ZodOptional<import("zod").ZodString>;
     filer_name: import("zod").ZodOptional<import("zod").ZodString>;
@@ -266,7 +311,7 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
         per_page: import("zod").ZodNumber;
     }, import("zod/v4/core").$strip>;
     search_criteria: import("zod").ZodOptional<import("zod").ZodObject<{}, import("zod/v4/core").$loose>>;
-}, import("zod/v4/core").$strip>> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+}, import("zod/v4/core").$strip>, undefined> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
     query: import("zod").ZodOptional<import("zod").ZodString>;
     type: import("zod").ZodOptional<import("zod").ZodEnum<{
         advisory_opinions: "advisory_opinions";
@@ -290,5 +335,10 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
     results: import("zod").ZodArray<import("zod").ZodObject<{}, import("zod/v4/core").$loose>>;
     total_count: import("zod").ZodNumber;
     search_criteria: import("zod").ZodOptional<import("zod").ZodObject<{}, import("zod/v4/core").$loose>>;
-}, import("zod/v4/core").$strip>>)[];
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "missing_filter";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
+    readonly when: "Called without query, type, or a specific identifier (ao_number / case_number)";
+    readonly recovery: "Provide at least a search query, document type, or specific identifier (ao_number, case_number) to scope the legal search.";
+}]>)[];
 //# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/tools/definitions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAYrD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oCAU9B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAYrD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAU9B,CAAC"}

package/dist/mcp-server/tools/definitions/lookup-calendar.tool.d.ts

@@ -34,5 +34,5 @@ export declare const lookupCalendar: import("@cyanheads/mcp-ts-core").ToolDefini
         per_page: z.ZodNumber;
     }, z.core.$strip>;
     search_criteria: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
-}, z.core.$strip>>;
+}, z.core.$strip>, undefined>;
 //# sourceMappingURL=lookup-calendar.tool.d.ts.map

package/dist/mcp-server/tools/definitions/lookup-calendar.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lookup-calendar.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/lookup-calendar.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAUjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAiJzB,CAAC"}
+{"version":3,"file":"lookup-calendar.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/lookup-calendar.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAUjD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAuJzB,CAAC"}

package/dist/mcp-server/tools/definitions/lookup-calendar.tool.js

@@ -46,7 +46,9 @@ export const lookupCalendar = tool('openfec_lookup_calendar', {
     }),
     output: z.object({
         results: z
-            .array(z.looseObject({}))
+            .array(z
+            .looseObject({})
+            .describe('A calendar record (event, filing deadline, or election date depending on mode).'))
             .describe('Calendar records — events, filing deadlines, or election dates depending on mode.'),
         pagination: z
             .object({