socrata mcp server changelog

version

0.6.1 → 0.7.0

https://raw.githubusercontent.com/cyanheads/socrata-mcp-server/HEAD/AGENTS.md

− **Version:** 0.3.0− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.11`− **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0− **Zod:** ^4.6.5− import { validationError } from '@cyanheads/mcp-ts-core/errors';− import { DATASET_ID_PATTERN } from '@/services/socrata/types.js';−     datasetId: z.string().describe('Four-by-four dataset ID (e.g. kzjm-xkqj).'),−     if (!DATASET_ID_PATTERN.test(params.datasetId)) {−       throw validationError(`Invalid dataset ID format: "${params.datasetId}".`, { datasetId: params.datasetId });−     }− // src/config/server-config.ts — lazy-parsed, separate from framework config− `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`MY_API_KEY`) not the path (`apiKey`). Throws `ConfigurationError`, which the framework prints as a clean startup banner.−     server-config.ts                    # SOCRATA_APP_TOKEN, SOCRATA_DEFAULT_DOMAIN, SOCRATA_DATAFRAME_DROP_ENABLED (Zod schema)− 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 f− | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity (run by devcheck) |− `npm 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 − **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's bri+ **Version:** 0.6.1+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0+ **Zod:** ^4.6.7+ import { DatasetIdSchema } from '@/mcp-server/dataset-id-schema.js';+     // Four-by-four pattern in either letter case, lowercased before the handler sees it.+     datasetId: DatasetIdSchema.describe('Four-by-four dataset ID (e.g. kzjm-xkqj).'),+ // src/config/server-config.ts — parsed once in setup(), separate from framework config+ // src/index.ts — first in setup(), after createApp() has loaded `.env` and parsed its own config+ setup(core) {+   getServerConfig();+   initSocrataService();+ }+ `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`MY_API_KEY`) not the path (`apiKey`). Throws `ConfigurationError`, which `createApp()` prints as a clean startup banner when thrown during its setup — so nothing parses config at module import, where the same error exits on a raw stack trace. Reads that must happen earlier go through `server-config.ts` helpers that never parse: `activeServerConfig()` (the parsed config, or the schema defaults before `setup()`) b+     server-config.ts                    # SOCRATA_APP_TOKEN, SOCRATA_DEFAULT_DOMAIN, SOCRATA_DATAFRAME_DROP_ENABLED, SOCRATA_CLAMP_LIMITS (Zod schema; parsed in setup(), never at import)+ Two skill trees live at the project root, written for different readers:+ | 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 | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |+ 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.+ A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.+ | `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 |+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity, `.mcpbignore` coverage, plugin manifests, the published `skills/` tree (run by devcheck) |+ `npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`; source, tests, docs, caches, logs, agent docs, and plugin manifests require root-anchored exclusions. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips dependency-shipped agent docs, platform-specific native bindings, node-gyp build output beside a `binding.gyp`+ **Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewri+ - [ ] `plugin.json` + `mcp.json` populated — Agent Plugins 1.0.0 root pair from the templates, metadata from `package.json`; root `mcp.json` has `$schema`, `mcpServers`, a `type: "stdio"` entry keyed by the unscoped name, `npx -y <full package name>`, fixed `env` only. Keep both overlays: `.codex-plugin/plugin.json` keeps `"mcpServers": "./.codex-plugin/mcp.json"` so Codex ≥ 0.150.0 forwards the overlay's `env_vars` to the root server. `.mcpbignore` carries `/plugin.json` and `/mcp.json`

• + socrata-guide

env_vars

SOCRATA_APP_TOKEN, SOCRATA_DEFAULT_DOMAIN, SOCRATA_DATAFRAME_DROP_ENABLED, MCP_LOG_LEVEL → SOCRATA_APP_TOKEN, SOCRATA_DEFAULT_DOMAIN, SOCRATA_DATAFRAME_DROP_ENABLED, SOCRATA_CLAMP_LIMITS, MCP_LOG_LEVEL

version

0.5.1 → 0.6.1

version

0.4.0 → 0.5.1

version

0.3.0 → 0.4.0

https://raw.githubusercontent.com/cyanheads/socrata-mcp-server/HEAD/AGENTS.md

− **Version:** 0.2.1− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`− **MCP SDK:** `@modelcontextprotocol/server` ^2.0.0− | `ctx.log` | Request-scoped logger — `.debug()`, `.info()`, `.notice()`, `.warning()`, `.error()`. Auto-correlates requestId, traceId, tenantId. |− | `ctx.state` | Tenant-scoped KV — `.get(key)`, `.set(key, value, { ttl? })`, `.delete(key)`, `.list(prefix, { cursor, limit })`. Accepts any serializable value. |− | `ctx.requestInput` | Suspend and request missing elicitation, sampling, or roots input. Always `return ctx.requestInput(...)`. |− | `ctx.inputs` | Read responses supplied when the client retries a suspended request. |− | `ctx.requestId` | Unique request ID. |− | `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |− **Recommended: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` / `resource()` to receive `ctx.fail(reason, …)` typed against the reason union. TypeScript catches typos at compile time, `data.reason` is auto-populated for observability, linter enforces conformance against the handler body. `recovery` is required descriptive metadata for the agent's next move (≥ 5 words, lint-validated); for the wire `data.recovery.hint` (mirrored into `content[− throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });−     server-config.ts                    # SOCRATA_APP_TOKEN, SOCRATA_DEFAULT_DOMAIN (Zod schema)− | `api-mirror` | MirrorService: persistent self-refreshing local mirror (embedded SQLite + FTS5) of a bulk upstream dataset — Tier 3 opt-in |+ **Version:** 0.3.0+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.11`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0+   // format() populates content[] — the markdown twin of structuredContent.+   // Different clients read different surfaces (Claude Code → structuredContent,+   // Claude Desktop → content[]); both must carry the same data.+   // Enforced at lint time: every field in `output` must appear in the rendered text.+ ### Prompt+ ```ts+ import { prompt, z } from '@cyanheads/mcp-ts-core';+ export const exploreOpenData = prompt('explore_open_data', {+   description: 'Structured workflow for investigating a civic data question.',+   args: z.object({+     topic: z.string().describe('Civic data topic or question to investigate.'),+     portal: z.string().optional().describe('Target portal domain if known (e.g. data.seattle.gov).'),+   }),+   generate: (args) => [+     { role: 'user', content: { type: 'text', text: `I want to investigate: **${args.topic}**` } },+   ],+ });+ ```+ For env booleans use `z.stringbool()`, never `z.coerce.boolean()` — `Boolean("false")` is `true`, so a coerced flag can't be disabled through the environment. `z.stringbool()` parses `true/false/1/0/yes/no/on/off` and rejects anything else, so `=false` actually disables.+ ### Server identity and instructions+ `createApp()` accepts optional identity fields forwarded to the SDK's `initialize` response and the server manifest (`/.well-known/mcp.json`):+ ```ts+ await createApp({+   name: 'my-mcp-server',+   title: 'My Server',                         // human-readable display name+   websiteUrl: 'https://github.com/owner/repo', // canonical homepage URL+   description: 'One-line description.',        // wins over MCP_SERVER_DESCRIPTION+   icons: [{ src: 'https://example.com/icon.png', sizes: ['48x48'], mimeType: 'image/png' }],+   instructions: 'Use shortcut alpha for the most common case.', // session-level context+ });+ ```+ `instructions` is optional server-level orientation, sent on every `initialize` as session-level context. Use it for deployment guidance (connection aliases, regional notes, scope hints) instead of repeating the same context across tool descriptions. Client adoption is uneven, but there's no downside when set.+ ### Session posture and shutdown+ Two more `createApp()` options shape how the server runs rather than how it presents itself:+ ```ts+ await createApp({+   sessionMode: 'stateless',          // or { default: 'stateful', require: 'stateful' }

env_vars

SOCRATA_APP_TOKEN, SOCRATA_DEFAULT_DOMAIN, MCP_LOG_LEVEL → SOCRATA_APP_TOKEN, SOCRATA_DEFAULT_DOMAIN, SOCRATA_DATAFRAME_DROP_ENABLED, MCP_LOG_LEVEL

version

0.2.1 → 0.3.0