@cyanheads/reliefweb-mcp-server 0.1.1 → 0.1.3

package/AGENTS.md

@@ -0,0 +1,395 @@
+# Developer Protocol
+
+**Server:** @cyanheads/reliefweb-mcp-server
+**Version:** 0.1.3
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.7`
+**Engines:** Bun ≥1.3.0, Node ≥24.0.0
+**MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
+**Zod:** ^4.4.3
+
+> **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.
+
+---
+
+## What's Next?
+
+When the user asks what's next or needs direction, suggest options based on the current project state. Common next steps:
+
+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-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 `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.
+
+---
+
+## 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.
+- **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.
+
+---
+
+## Patterns
+
+### Tool
+
+```ts
+import { tool, z } from '@cyanheads/mcp-ts-core';
+
+export const searchItems = tool('search_items', {
+  description: 'Search inventory items by query.',
+  annotations: { readOnlyHint: true },
+  input: z.object({
+    query: z.string().describe('Search terms'),
+    limit: z.number().default(10).describe('Max results'),
+  }),
+  output: z.object({
+    items: z.array(z.object({
+      id: z.string().describe('Item ID'),
+      name: z.string().describe('Item name'),
+    })).describe('Matching items'),
+  }),
+  auth: ['inventory:read'],
+
+  async handler(input, ctx) {
+    const items = await findItems(input.query, input.limit);
+    ctx.log.info('Search completed', { query: input.query, count: items.length });
+    return { items };
+  },
+
+  // 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.
+  format: (result) => [{
+    type: 'text',
+    text: result.items.map(i => `**${i.id}**: ${i.name}`).join('\n'),
+  }],
+});
+```
+
+### Resource
+
+```ts
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { notFound } from '@cyanheads/mcp-ts-core/errors';
+
+export const itemData = resource('inventory://{itemId}', {
+  description: 'Fetch an inventory item by ID.',
+  params: z.object({ itemId: z.string().describe('Item identifier') }),
+  auth: ['inventory:read'],
+  async handler(params, ctx) {
+    const item = await ctx.state.get(`item:${params.itemId}`);
+    if (!item) throw notFound(`Item ${params.itemId} not found`, { itemId: params.itemId });
+    return item;
+  },
+});
+```
+
+### Prompt
+
+```ts
+import { prompt, z } from '@cyanheads/mcp-ts-core';
+
+export const reviewCode = prompt('review_code', {
+  description: 'Review code for issues and best practices.',
+  args: z.object({
+    code: z.string().describe('Code to review'),
+    language: z.string().optional().describe('Programming language'),
+  }),
+  generate: (args) => [
+    { role: 'user', content: { type: 'text', text: `Review this ${args.language ?? ''} code:\n${args.code}` } },
+  ],
+});
+```
+
+### Server config
+
+```ts
+// src/config/server-config.ts — lazy-parsed, separate from framework config
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+
+const ServerConfigSchema = z.object({
+  apiKey: z.string().describe('External API key'),
+  maxResults: z.coerce.number().default(100),
+});
+
+let _config: z.infer<typeof ServerConfigSchema> | undefined;
+export function getServerConfig() {
+  _config ??= parseEnvConfig(ServerConfigSchema, {
+    apiKey: 'MY_API_KEY',
+    maxResults: 'MY_MAX_RESULTS',
+  });
+  return _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.
+
+---
+
+## Context
+
+Handlers receive a unified `ctx` object. Key properties:
+
+| Property | Description |
+|:---------|:------------|
+| `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.elicit` | Ask user for structured input. **Check for presence first:** `if (ctx.elicit) { ... }` |
+| `ctx.sample` | Request LLM completion from the client. **Check for presence first:** `if (ctx.sample) { ... }` |
+| `ctx.signal` | `AbortSignal` for cancellation. |
+| `ctx.progress` | Task progress (present when `task: true`) — `.setTotal(n)`, `.increment()`, `.update(message)`. |
+| `ctx.requestId` | Unique request ID. |
+| `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio. |
+
+---
+
+## Errors
+
+Handlers throw — the framework catches, classifies, and formats.
+
+**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[]` text), pass explicitly at the throw site when dynamic context matters: `ctx.fail('reason', msg, { recovery: { hint: '...' } })`. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring.
+
+```ts
+errors: [
+  { reason: 'no_match', code: JsonRpcErrorCode.NotFound,
+    when: 'No item matched the query',
+    recovery: 'Broaden the query or check the spelling and try again.' },
+],
+async handler(input, ctx) {
+  const item = await db.find(input.id);
+  if (!item) throw ctx.fail('no_match', `No item ${input.id}`);
+  return item;
+}
+```
+
+**Declare contracts inline on each tool.** The contract is part of the tool's public surface — one file should give the full picture. Don't extract a shared `errors[]` constant; per-tool repetition is the intended cost of locality.
+
+**Fallback (no contract entry fits):** throw via factories or plain `Error`.
+
+```ts
+// Error factories — explicit code
+import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+throw notFound('Item not found', { itemId });
+throw serviceUnavailable('API unavailable', { url }, { cause: err });
+
+// Plain Error — framework auto-classifies from message patterns
+throw new Error('Item not found');           // → NotFound
+throw new Error('Invalid query format');     // → ValidationError
+
+// McpError — when no factory exists for the code
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });
+```
+
+See framework CLAUDE.md and the `api-errors` skill for the full auto-classification table, all available factories, and the contract reference.
+
+---
+
+## Structure
+
+```text
+src/
+  index.ts                              # createApp() entry point
+  config/
+    server-config.ts                    # Server-specific env vars (Zod schema)
+  services/
+    [domain]/
+      [domain]-service.ts               # Domain service (init/accessor pattern)
+      types.ts                          # Domain types
+  mcp-server/
+    tools/definitions/
+      [tool-name].tool.ts               # Tool definitions
+    resources/definitions/
+      [resource-name].resource.ts       # Resource definitions
+    prompts/definitions/
+      [prompt-name].prompt.ts           # Prompt definitions
+```
+
+---
+
+## Naming
+
+| What | Convention | Example |
+|:-----|:-----------|:--------|
+| Files | kebab-case with suffix | `search-docs.tool.ts` |
+| Tool/resource/prompt names | snake_case | `search_docs` |
+| Directories | kebab-case | `src/services/doc-search/` |
+| Descriptions | Single string or template literal, no `+` concatenation | `'Search items by query and filter.'` |
+
+---
+
+## Skills
+
+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). Skills then load as context without referencing `skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
+
+Available skills:
+
+| Skill | Purpose |
+|:------|:--------|
+| `setup` | Post-init project orientation |
+| `design-mcp-server` | Design tool surface, resources, and services for a new server |
+| `add-tool` | Scaffold a new tool definition |
+| `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-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: voice, leaks, defaults, recovery hints, examples |
+| `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` | Investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest` |
+| `release-and-publish` | Ship a release: verification gate, push commits+tags, publish to npm / MCP Registry / GHCR / `.mcpb` bundle on GitHub Releases |
+| `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-linter` | Definition lint rules reference (`format-parity`, `schema-*`, `server-json-*`, …) |
+| `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, telemetry helpers |
+| `api-workers` | Cloudflare Workers runtime |
+| `report-issue-framework` | File bug/feature request against @cyanheads/mcp-ts-core |
+| `report-issue-local` | File bug/feature request against this server's repo |
+
+When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
+
+---
+
+## Commands
+
+| Command | Purpose |
+|:--------|:--------|
+| `bun run build` | Compile TypeScript |
+| `bun run rebuild` | Clean + build |
+| `bun run clean` | Remove build artifacts |
+| `bun run devcheck` | Lint + format + typecheck + security + packaging alignment |
+| `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — `bun update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
+| `bun run tree` | Generate directory structure doc |
+| `bun run format` | Auto-fix formatting |
+| `bun run test` | Run tests |
+| `bun run lint:mcp` | Validate MCP definitions against spec |
+| `bun run lint:packaging` | Validate env var alignment between `manifest.json` and `server.json` (skipped cleanly when `manifest.json` is absent) |
+| `bun run list-skills` | List skills in `skills/` with name + description |
+| `bun run start:stdio` | Production mode (stdio) |
+| `bun run start:http` | Production mode (HTTP) |
+| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
+| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
+| `bun run bundle` | Build and pack as `dist/reliefweb-mcp-server.mcpb` for one-click Claude Desktop install |
+
+---
+
+## Bundling
+
+`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+
+**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.
+
+**README install badges.** Drop these into the project README to give users one-click install paths. Fill in `<OWNER>` / `<REPO>` / `<PACKAGE_NAME>` and encode the per-server config. Cursor + VS Code badges assume the server is published to npm; Claude Desktop downloads the `.mcpb` directly so npm publishing isn't required.
+
+| Client | Mechanism |
+|:-------|:----------|
+| Claude Desktop | Browser downloads the `.mcpb` from the latest GitHub Release; OS file handler routes it to Claude Desktop, which opens the install dialog. No deep-link URL scheme yet — this is the canonical path. |
+| Cursor | Official `https://cursor.com/en/install-mcp` endpoint with base64 JSON config. |
+| VS Code / Insiders | Official `vscode:mcp/install?...` deep link, wrapped in `https://vscode.dev/redirect?url=` so GitHub-rendered markdown doesn't strip the non-HTTP scheme. |
+| Claude Code / Codex | CLI only (`claude mcp add` / `codex mcp add`); no URL scheme. |
+
+```markdown
+[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/<OWNER>/<REPO>/releases/latest/download/<PACKAGE_NAME>.mcpb)
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=<PACKAGE_NAME>&config=<BASE64_CONFIG>)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?<URLENCODED_JSON>)
+```
+
+Both install links route through HTTPS endpoints (`cursor.com/en/install-mcp` and `vscode.dev/redirect`) — GitHub-rendered markdown strips non-HTTP URL schemes from anchors, so a raw `cursor://` or `vscode:` link won't click through from github.com.
+
+Generate the encoded configs (replace `<PACKAGE_NAME>` and add env vars for any required API keys):
+
+```bash
+# Cursor: base64-encoded JSON. Split command/args, add env when keys are needed.
+echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"],"env":{"API_KEY":"your-api-key"}}' | base64
+# Without env (no required keys):
+echo -n '{"command":"npx","args":["-y","<PACKAGE_NAME>"]}' | base64
+
+# VS Code: URL-encoded JSON. Same shape plus a `name` field.
+node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"],env:{API_KEY:"your-api-key"}}))'
+# Without env:
+node -p 'encodeURIComponent(JSON.stringify({name:"<SHORT_NAME>",command:"npx",args:["-y","<PACKAGE_NAME>"]}))'
+```
+
+Both clients use the same `{command, args, env}` shape (matching `mcp.json` schema). VS Code adds a top-level `name` field. Omit `env` entirely when no API keys are needed — don't include empty objects or framework-only vars like `MCP_TRANSPORT_TYPE`.
+
+The Claude Desktop badge requires the bundle to ship with a stable filename — `bun run bundle` outputs `dist/<PACKAGE_NAME>.mcpb`, and `release-and-publish` attaches that file to the GitHub Release. `releases/latest/download/<PACKAGE_NAME>.mcpb` then redirects to the most recent release.
+
+---
+
+## Changelog
+
+Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `bun run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
+
+Each per-version file opens with YAML frontmatter:
+
+```markdown
+---
+summary: "One-line headline, ≤350 chars"  # required — powers the rollup index
+breaking: false                            # optional — true flags breaking changes
+security: false                            # optional — true flags security fixes
+---
+
+# 0.1.0 — YYYY-MM-DD
+...
+```
+
+`breaking: true` renders a `· ⚠️ Breaking` badge — use it when consumers must update code on upgrade (signature changes, removed APIs, config renames). `security: true` renders a `· 🛡️ Security` badge and pairs with a `## Security` body section. When both are set, badges render `· ⚠️ Breaking · 🛡️ Security`.
+
+**Section order** (Keep a Changelog): Added, Changed, Deprecated, Removed, Fixed, Security. Include only sections with entries — don't ship empty headers.
+
+**Tag annotations** render as GitHub Release bodies via `--notes-from-tag`. They must be structured markdown — never a flat comma-separated string. Subject omits the version number (GitHub prepends it). See `changelog/template.md` for the full format reference.
+
+---
+
+## Imports
+
+```ts
+// Framework — z is re-exported, no separate zod import needed
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+// Server's own code — via path alias
+import { getMyService } from '@/services/my-domain/my-service.js';
+```
+
+---
+
+## Checklist
+
+- [ ] Zod schemas: all fields have `.describe()`, 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)`). When regex/length constraints matter, use `z.union([z.literal(''), z.string().regex(...).describe(...)])` — literal variants are exempt from `describe-on-fields`.
+- [ ] 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 — different clients forward different surfaces (Claude Code → `structuredContent`, Claude Desktop → `content[]`); both must carry the same data
+- [ ] If wrapping external API: raw/domain/output schemas reviewed against real upstream sparsity/nullability before finalizing required vs optional fields
+- [ ] If wrapping external API: normalization and `format()` preserve uncertainty; do not fabricate facts from missing upstream data
+- [ ] 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`
+- [ ] `bun run devcheck` passes

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** @cyanheads/reliefweb-mcp-server
-**Version:** 0.1.1
+**Version:** 0.1.3
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.9.7`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0
@@ -251,22 +251,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: voice, leaks, defaults, recovery hints, examples |
 | `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` | Investigate changelogs, adopt upstream changes, sync skills to agent dirs |
-| `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 |
+| `maintenance` | Investigate changelogs, adopt upstream changes, and sync skills after `bun update --latest` |
+| `release-and-publish` | Ship a release: verification gate, push commits+tags, publish to npm / MCP Registry / GHCR / `.mcpb` bundle on GitHub Releases |
 | `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-linter` | Definition lint rules reference (`format-parity`, `schema-*`, `server-json-*`, …) |
 | `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, telemetry helpers |
-| `api-telemetry` | OTel catalog: spans, metrics, completion logs, env config, cardinality rules |
 | `api-workers` | Cloudflare Workers runtime |
+| `report-issue-framework` | File bug/feature request against @cyanheads/mcp-ts-core |
+| `report-issue-local` | File bug/feature request against this server's repo |
 
 When you complete a skill's checklist, check the boxes and add a completion timestamp at the end (e.g., `Completed: 2026-03-11`).
 
@@ -274,29 +277,30 @@ When you complete a skill's checklist, check the boxes and add a completion time
 
 ## Commands
 
-**Runtime:** Scripts use `tsx` — both `npm run <cmd>` and `bun run <cmd>` work. `bun` is slightly faster for script invocation but not required.
-
 | Command | Purpose |
 |:--------|:--------|
-| `npm run build` | Compile TypeScript |
-| `npm run rebuild` | Clean + build |
-| `npm run clean` | Remove build artifacts |
-| `npm run devcheck` | Lint + format + typecheck + security + changelog sync |
-| `bun run audit:refresh` | Delete `bun.lock`, reinstall, re-audit. Use when `devcheck` flags a transitive advisory — stale lockfile can mask already-patched deps. If advisory survives, it's real. |
-| `npm run tree` | Generate directory structure doc |
-| `npm run format` | Auto-fix formatting |
-| `npm test` | Run tests |
-| `npm run start:stdio` | Production mode (stdio) |
-| `npm run start:http` | Production mode (HTTP) |
-| `npm run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
-| `npm run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
-| `npm run bundle` | Build and pack as `.mcpb` for one-click Claude Desktop install |
+| `bun run build` | Compile TypeScript |
+| `bun run rebuild` | Clean + build |
+| `bun run clean` | Remove build artifacts |
+| `bun run devcheck` | Lint + format + typecheck + security + packaging alignment |
+| `bun run audit:refresh` | Delete `bun.lock`, reinstall, and re-run `bun audit`. Use when `devcheck` flags a transitive advisory — `bun update` is sticky on transitive resolutions, so the advisory may be a stale-lockfile false positive. If it survives the refresh, it's real. |
+| `bun run tree` | Generate directory structure doc |
+| `bun run format` | Auto-fix formatting |
+| `bun run test` | Run tests |
+| `bun run lint:mcp` | Validate MCP definitions against spec |
+| `bun run lint:packaging` | Validate env var alignment between `manifest.json` and `server.json` (skipped cleanly when `manifest.json` is absent) |
+| `bun run list-skills` | List skills in `skills/` with name + description |
+| `bun run start:stdio` | Production mode (stdio) |
+| `bun run start:http` | Production mode (HTTP) |
+| `bun run changelog:build` | Regenerate `CHANGELOG.md` from `changelog/*.md` |
+| `bun run changelog:check` | Verify `CHANGELOG.md` is in sync (used by devcheck) |
+| `bun run bundle` | Build and pack as `dist/reliefweb-mcp-server.mcpb` for one-click Claude Desktop install |
 
 ---
 
 ## Bundling
 
-`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
+`bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
 
 **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.
 
@@ -339,7 +343,7 @@ The Claude Desktop badge requires the bundle to ship with a stable filename —
 
 ## Changelog
 
-Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `npm run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `npm run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
+Directory-based, grouped by minor series via the `.x` semver-wildcard convention. Source of truth: `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.1.x/0.1.0.md`) — one file per release, shipped in the npm package. At release, author the per-version file with a concrete version and date, then run `bun run changelog:build` to regenerate the rollup. `changelog/template.md` is a **pristine format reference** — never edited or moved; read it for the frontmatter + section layout when scaffolding. `CHANGELOG.md` is a **navigation index** (header + link + summary per version), regenerated by `bun run changelog:build` — devcheck hard-fails on drift; never hand-edit it.
 
 Each per-version file opens with YAML frontmatter:
 
@@ -388,4 +392,4 @@ import { getMyService } from '@/services/my-domain/my-service.js';
 - [ ] 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`
-- [ ] `npm run devcheck` passes
+- [ ] `bun run devcheck` passes

package/Dockerfile

@@ -37,9 +37,10 @@ WORKDIR /usr/src/app
 ENV NODE_ENV=production
 
 # OCI image metadata (https://github.com/opencontainers/image-spec/blob/main/annotations.md)
-LABEL org.opencontainers.image.title="reliefweb-mcp-server"
-LABEL org.opencontainers.image.description=""
+LABEL org.opencontainers.image.title="@cyanheads/reliefweb-mcp-server"
+LABEL org.opencontainers.image.description="Search ReliefWeb humanitarian reports, disasters, jobs, and training from OCHA via MCP. STDIO or Streamable HTTP."
 LABEL org.opencontainers.image.licenses="Apache-2.0"
+LABEL org.opencontainers.image.source="https://github.com/cyanheads/reliefweb-mcp-server"
 
 # Copy dependency manifests
 COPY package.json bun.lock ./

package/README.md

@@ -1,13 +1,13 @@
 <div align="center">
   <h1>@cyanheads/reliefweb-mcp-server</h1>
-  <p><b>Search ReliefWeb humanitarian reports, disasters, jobs, training, and country profiles via MCP. STDIO or Streamable HTTP.</b>
+  <p><b>Search ReliefWeb humanitarian reports, disasters, jobs, and training from OCHA via MCP. STDIO or Streamable HTTP.</b>
   <div>9 Tools • 3 Resources • 1 Prompt</div>
   </p>
 </div>
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.1.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![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/reliefweb-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/reliefweb-mcp-server) [![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-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.1.3-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/reliefweb-mcp-server) [![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/reliefweb-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/reliefweb-mcp-server) [![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-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -175,7 +175,7 @@ Agent-friendly output:
 
 ### Prerequisites
 
-- [Bun v1.3.0](https://bun.sh/) or higher, or Node.js v24.0.0 or higher.
+- [Bun v1.3.2](https://bun.sh/) or higher.
 - A **pre-approved ReliefWeb appname** — register at [ReliefWeb API](https://reliefweb.int/help/api) and set `RELIEFWEB_APP_NAME`. The API has required pre-approved appnames since November 2025; requests without one are rejected.
 
 ### Self-Hosted / Local
@@ -245,8 +245,6 @@ cd reliefweb-mcp-server
 bun install
 ```
 
-4. **Copy `.env.example` to `.env` and set `RELIEFWEB_APP_NAME`.**
-
 ## Configuration
 
 All configuration is validated at startup via Zod schemas. Key environment variables:

package/changelog/0.1.x/0.1.2.md

@@ -0,0 +1,24 @@
+---
+summary: "Metadata alignment — package.json, Dockerfile, manifest.json, server.json, README, AGENTS.md, bunfig.toml"
+breaking: false
+security: false
+---
+
+# 0.1.2 — 2026-05-23
+
+Metadata-only patch: aligns all metadata files to the pubmed gold standard.
+
+## Added
+
+- `AGENTS.md` — agent protocol file for non-Claude Code consumers
+- `bunfig.toml` — Bun configuration file
+
+## Changed
+
+- `package.json` — description, scripts, and fields aligned to standard
+- `Dockerfile` — LABEL metadata updated
+- `manifest.json` — description and fields updated
+- `server.json` — description, runtimeHint, and env var entries updated
+- `README.md` — tagline and badges updated
+- `CLAUDE.md` — developer protocol updated
+- `docs/tree.md` — regenerated to reflect new files

package/changelog/0.1.x/0.1.3.md

@@ -0,0 +1,12 @@
+---
+summary: "Fix empty RELIEFWEB_APP_NAME validation and crisis_briefing country/disaster disambiguation"
+breaking: false
+security: false
+---
+
+# 0.1.3 — 2026-05-24
+
+## Fixed
+
+- **`RELIEFWEB_APP_NAME`** — changed `z.string()` to `z.string().min(1)` in `server-config.ts`; empty string now fails validation at startup rather than silently passing.
+- **`reliefweb_crisis_briefing` prompt** — added disambiguation logic for the jobs and training sections: when `target` is a disaster name or GLIDE number, `reliefweb_search_jobs` and `reliefweb_search_training` are called with `text=` instead of `country=` (the `country=` filter expects an ISO3 code; passing a disaster name returns no results).

package/dist/config/server-config.js

@@ -7,7 +7,7 @@
 import { z } from '@cyanheads/mcp-ts-core';
 import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
 const ServerConfigSchema = z.object({
-    appName: z.string().describe('Pre-approved appname for the ReliefWeb API v2.'),
+    appName: z.string().min(1).describe('Pre-approved appname for the ReliefWeb API v2.'),
 });
 let _config;
 export function getServerConfig() {

package/dist/config/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;CAC/E,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,OAAO,EAAE,oBAAoB;KAC9B,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,gDAAgD,CAAC;CACtF,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,OAAO,EAAE,oBAAoB;KAC9B,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/mcp-server/prompts/definitions/crisis-briefing.prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crisis-briefing.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/crisis-briefing.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,eAAO,MAAM,uBAAuB;;;;;;;kBAgElC,CAAC"}
+{"version":3,"file":"crisis-briefing.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/crisis-briefing.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,eAAO,MAAM,uBAAuB;;;;;;;kBAoElC,CAAC"}

package/dist/mcp-server/prompts/definitions/crisis-briefing.prompt.js

@@ -28,12 +28,16 @@ export const reliefwebCrisisBriefing = prompt('reliefweb_crisis_briefing', {
 - List active disasters with status, GLIDE number, and primary type.
 - List key appeals and response plans from the country/disaster profile.`;
         const jobsSection = `## Open Positions
-- Search for open humanitarian jobs with reliefweb_search_jobs filtered by country="${target}".
+- Determine whether "${target}" is a country/ISO3 code or a disaster name/GLIDE number.
+  - If it is a country or ISO3 code: call reliefweb_search_jobs with country="${target}".
+  - If it is a disaster name or GLIDE number: call reliefweb_search_jobs with text="${target}" (the country= filter expects an ISO3 code; passing a disaster name returns no results).
 - Group by organization and career category.
 - List title, organization, closing date, and URL for each position.
 - Note total count and any recurring roles (e.g., multiple UNHCR positions).`;
         const trainingSection = `## Training Opportunities
-- Search for upcoming training with reliefweb_search_training filtered by country or text.
+- Determine whether "${target}" is a country/ISO3 code or a disaster name/GLIDE number.
+  - If it is a country or ISO3 code: call reliefweb_search_training with country="${target}".
+  - If it is a disaster name or GLIDE number: call reliefweb_search_training with text="${target}".
 - List title, organizer, start date, format, and URL for each opportunity.`;
         let sections;
         if (focus === 'situation') {

package/dist/mcp-server/prompts/definitions/crisis-briefing.prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"crisis-briefing.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/crisis-briefing.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,2BAA2B,EAAE;IACzE,WAAW,EACT,yEAAyE;QACzE,+IAA+I;QAC/I,gDAAgD;QAChD,6HAA6H;IAC/H,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,mBAAmB,EAAE,CAAC;aACnB,MAAM,EAAE;aACR,QAAQ,CACP,+IAA+I,CAChJ;QACH,KAAK,EAAE,CAAC;aACL,IAAI,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;aACnC,QAAQ,EAAE;aACV,QAAQ,CACP,kNAAkN,CACnN;KACJ,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,CAAC;QAExC,MAAM,gBAAgB,GAAG;;6FAEgE,MAAM;;;;yEAI1B,CAAC;QAEtE,MAAM,WAAW,GAAG;sFAC8D,MAAM;;;6EAGf,CAAC;QAE1E,MAAM,eAAe,GAAG;;2EAE+C,CAAC;QAExE,IAAI,QAAgB,CAAC;QACrB,IAAI,KAAK,KAAK,WAAW,EAAE,CAAC;YAC1B,QAAQ,GAAG,gBAAgB,CAAC;QAC9B,CAAC;aAAM,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YAC5B,QAAQ,GAAG,GAAG,WAAW,OAAO,eAAe,EAAE,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,GAAG,gBAAgB,OAAO,WAAW,OAAO,eAAe,EAAE,CAAC;QAC3E,CAAC;QAED,MAAM,OAAO,GAAG,oDAAoD,MAAM;;;;EAI5E,QAAQ;;;;;;gCAMsB,CAAC;QAE7B,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IACtE,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"crisis-briefing.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/crisis-briefing.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,2BAA2B,EAAE;IACzE,WAAW,EACT,yEAAyE;QACzE,+IAA+I;QAC/I,gDAAgD;QAChD,6HAA6H;IAC/H,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,mBAAmB,EAAE,CAAC;aACnB,MAAM,EAAE;aACR,QAAQ,CACP,+IAA+I,CAChJ;QACH,KAAK,EAAE,CAAC;aACL,IAAI,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;aACnC,QAAQ,EAAE;aACV,QAAQ,CACP,kNAAkN,CACnN;KACJ,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,CAAC;QAExC,MAAM,gBAAgB,GAAG;;6FAEgE,MAAM;;;;yEAI1B,CAAC;QAEtE,MAAM,WAAW,GAAG;uBACD,MAAM;gFACmD,MAAM;sFACA,MAAM;;;6EAGf,CAAC;QAE1E,MAAM,eAAe,GAAG;uBACL,MAAM;oFACuD,MAAM;0FACA,MAAM;2EACrB,CAAC;QAExE,IAAI,QAAgB,CAAC;QACrB,IAAI,KAAK,KAAK,WAAW,EAAE,CAAC;YAC1B,QAAQ,GAAG,gBAAgB,CAAC;QAC9B,CAAC;aAAM,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YAC5B,QAAQ,GAAG,GAAG,WAAW,OAAO,eAAe,EAAE,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,GAAG,gBAAgB,OAAO,WAAW,OAAO,eAAe,EAAE,CAAC;QAC3E,CAAC;QAED,MAAM,OAAO,GAAG,oDAAoD,MAAM;;;;EAI5E,QAAQ;;;;;;gCAMsB,CAAC;QAE7B,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IACtE,CAAC;CACF,CAAC,CAAC"}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@cyanheads/reliefweb-mcp-server",
-  "version": "0.1.1",
-  "description": "MCP server for the ReliefWeb humanitarian data API — search reports, disasters, jobs, training, and country profiles.",
+  "version": "0.1.3",
+  "mcpName": "io.github.cyanheads/reliefweb-mcp-server",
+  "description": "Search ReliefWeb humanitarian reports, disasters, jobs, training, and country profiles via MCP. STDIO or Streamable HTTP.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,23 +20,23 @@
     "server.json"
   ],
   "scripts": {
-    "build": "tsx scripts/build.ts",
-    "rebuild": "tsx scripts/clean.ts && tsx scripts/build.ts",
-    "clean": "tsx scripts/clean.ts",
-    "devcheck": "tsx scripts/devcheck.ts",
+    "build": "bun run scripts/build.ts",
+    "rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts",
+    "clean": "bun run scripts/clean.ts",
+    "devcheck": "bun run scripts/devcheck.ts",
     "audit:refresh": "rm -f bun.lock && bun install && bun audit",
-    "tree": "tsx scripts/tree.ts",
-    "list-skills": "tsx scripts/list-skills.ts",
+    "tree": "bun run scripts/tree.ts",
+    "list-skills": "bun run scripts/list-skills.ts",
     "format": "biome check --write --unsafe .",
-    "lint:mcp": "tsx scripts/lint-mcp.ts",
-    "lint:packaging": "tsx scripts/lint-packaging.ts",
-    "bundle": "npm run build && npx -y @anthropic-ai/mcpb pack . dist/reliefweb-mcp-server.mcpb",
-    "changelog:build": "tsx scripts/build-changelog.ts",
-    "changelog:check": "tsx scripts/build-changelog.ts --check",
-    "test": "vitest run",
-    "start": "node dist/index.js",
-    "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
-    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
+    "lint:mcp": "bun run scripts/lint-mcp.ts",
+    "lint:packaging": "bun run scripts/lint-packaging.ts",
+    "bundle": "bun run build && npx -y @anthropic-ai/mcpb pack . dist/reliefweb-mcp-server.mcpb",
+    "changelog:build": "bun run scripts/build-changelog.ts",
+    "changelog:check": "bun run scripts/build-changelog.ts --check",
+    "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish",
+    "test": "bunx vitest run",
+    "start:stdio": "MCP_TRANSPORT_TYPE=stdio bun ./dist/index.js",
+    "start:http": "MCP_TRANSPORT_TYPE=http bun ./dist/index.js"
   },
   "keywords": [
     "mcp",
@@ -46,15 +47,34 @@
     "disasters",
     "humanitarian-aid",
     "ocha",
-    "crisis-data"
+    "crisis-data",
+    "typescript",
+    "bun",
+    "ai-agent"
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/cyanheads/reliefweb-mcp-server"
+    "url": "git+https://github.com/cyanheads/reliefweb-mcp-server.git"
   },
+  "bugs": {
+    "url": "https://github.com/cyanheads/reliefweb-mcp-server/issues"
+  },
+  "homepage": "https://github.com/cyanheads/reliefweb-mcp-server#readme",
+  "author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/reliefweb-mcp-server#readme)",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/cyanheads"
+    },
+    {
+      "type": "buy_me_a_coffee",
+      "url": "https://www.buymeacoffee.com/cyanheads"
+    }
+  ],
   "license": "Apache-2.0",
+  "packageManager": "bun@1.3.2",
   "engines": {
-    "bun": ">=1.3.0",
+    "bun": ">=1.3.2",
     "node": ">=24.0.0"
   },
   "publishConfig": {

package/server.json

@@ -1,19 +1,19 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
-  "name": "cyanheads/reliefweb-mcp-server",
-  "description": "ReliefWeb humanitarian data API — search reports, disasters, jobs, training, and country profiles.",
+  "name": "io.github.cyanheads/reliefweb-mcp-server",
+  "description": "Search ReliefWeb humanitarian reports, disasters, jobs, and training from OCHA.",
   "repository": {
     "url": "https://github.com/cyanheads/reliefweb-mcp-server",
     "source": "github"
   },
-  "version": "0.1.1",
+  "version": "0.1.3",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/reliefweb-mcp-server",
-      "runtimeHint": "node",
-      "version": "0.1.1",
+      "runtimeHint": "bun",
+      "version": "0.1.3",
       "packageArguments": [
         {
           "type": "positional",
@@ -47,8 +47,8 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cyanheads/reliefweb-mcp-server",
-      "runtimeHint": "node",
-      "version": "0.1.1",
+      "runtimeHint": "bun",
+      "version": "0.1.3",
       "packageArguments": [
         {
           "type": "positional",
@@ -87,6 +87,12 @@
           "isRequired": false,
           "default": "/mcp"
         },
+        {
+          "name": "MCP_PUBLIC_URL",
+          "description": "Public origin override for deployments behind a TLS-terminating reverse proxy (e.g. https://mcp.example.com).",
+          "format": "string",
+          "isRequired": false
+        },
         {
           "name": "MCP_AUTH_MODE",
           "description": "Authentication mode to use: 'none', 'jwt', or 'oauth'.",