@dockndevai/mcp-core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ankit Verma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,247 @@
+# Migrating a suite server onto `@dockndevai/mcp-core`
+
+This guide shows how an existing server replaces its local `security.ts`, `elicit.ts`, path
+canonicalization, config helpers, tool types, annotations, and server-assembly with `mcp-core`
+imports — **incrementally**, one server at a time, with no behaviour change.
+
+The golden rule is unchanged: **safe by default, least privilege, never leak secrets.** `mcp-core`
+owns the capability ranking, the guard flow, dry-run, elicitation, path safety, and the audit line.
+Your server keeps everything genuinely domain-specific.
+
+## What moves to mcp-core vs. what stays
+
+| Concern | Before (local file) | After |
+| --- | --- | --- |
+| Capability ranking + access-mode gating | `security.ts` | **mcp-core** `SecurityPolicy` |
+| Resource allowlist / protected / opt-in flags / dry-run / audit | `security.ts` | **mcp-core** `SecurityPolicy` + `guard()` |
+| Human-in-the-loop confirmation | `elicit.ts` | **mcp-core** `makeConfirmer` / `Confirmer` |
+| Path canonicalization (symlink-bypass fix) | `config.ts` `resolveRealPath` / `canonicalize` | **mcp-core** `resolveRealPath` / `canonicalize` / `resolvePath` |
+| Env parsing (`bool`/`csv`/`num`) | `config.ts` | **mcp-core** `envBool` / `envList` / `envNum` / `envEnum` |
+| Tool types + result helpers | `tools/types.ts` | **mcp-core** `ToolDef` / `BaseToolContext` / `jsonResult` / `textResult` / `imageResult` |
+| Annotations | `tools/annotations.ts` | **mcp-core** `annotationsFor` |
+| Tool registration + error wrapping | `server.ts` | **mcp-core** `buildServer` / `defaultErrorMapper` |
+| **Domain client** (SDK/REST wrapper) | `src/<domain>/client.ts` | **stays** — unchanged |
+| **Tool definitions** (the tools themselves) | `tools/{read,write,admin}.ts` | **stays** — re-pointed imports only |
+| **Env var names + defaults** (incl. full-control inversion, SAFE_PROTECTED) | `config.ts` | **stays** — `config.ts` now builds a `PolicyConfig` |
+| **Extra context** (e.g. laya-guard `GuardClient`) | `guard.ts`, context type | **stays** — add to your own `ToolContext` |
+| **Error subclasses** (e.g. `MacError`) + redaction | domain files | **stays** — pass a custom `mapError` |
+
+Net effect: `security.ts`, `elicit.ts`, `tools/types.ts`, and `tools/annotations.ts` are **deleted**;
+`config.ts` and `server.ts` shrink to domain wiring.
+
+## Step 1 — add the dependency
+
+```bash
+npm install @dockndevai/mcp-core
+```
+
+`@modelcontextprotocol/sdk` and `zod` are peer deps you already have.
+
+## Step 2 — delete `elicit.ts`, import from core
+
+`mcp-core`'s `elicit.ts` is byte-for-byte the suite's implementation. Delete the local file and:
+
+```diff
+- import { makeConfirmer, type Confirmer } from "./elicit.js";
++ import { makeConfirmer, type Confirmer } from "@dockndevai/mcp-core";
+```
+
+## Step 3 — move path canonicalization to core
+
+Delete the local `resolveRealPath` / `canonicalize` from `config.ts` and import them. `resolvePath`,
+`resolveRealPath` (sync) and `canonicalize` (async) all come from core and behave identically.
+
+```diff
+- import { resolveRealPath } from "../config.js";
++ import { resolveRealPath } from "@dockndevai/mcp-core";
+```
+
+## Step 4 — rewrite `config.ts` to build a `PolicyConfig`
+
+Keep your env-var names and defaults (including any full-control-by-default inversion and the
+`SAFE_PROTECTED` list). Replace the local `bool`/`csv`/`num` with core's `envBool`/`envList`/`envNum`,
+and emit a `PolicyConfig` instead of the old `SecurityConfig`.
+
+**Path-scoped server (mac-control / macos):**
+
+```ts
+import { type PolicyConfig, envBool, envEnum, envList, resolveRealPath } from "@dockndevai/mcp-core";
+
+export function loadPolicyConfig(): PolicyConfig {
+  const safeMode = envBool("MACCTL_SAFE_MODE", false);
+  const protectedRaw = envList("MACCTL_PROTECTED_PATHS");
+  return {
+    mode: envEnum("MACCTL_MODE", ["read-only", "read-write", "admin"] as const, safeMode ? "read-only" : "admin"),
+    auditTag: "mac-control",
+    dryRun: envBool("MACCTL_DRY_RUN", false),
+    auditLog: envBool("MACCTL_AUDIT_LOG", true),
+    resources: {
+      path: {
+        label: "path",
+        match: "prefix",
+        allowlist: envList("MACCTL_PATH_ALLOWLIST").map(resolveRealPath),
+        protected: (protectedRaw.length ? protectedRaw : safeMode ? SAFE_PROTECTED : []).map(resolveRealPath),
+        allowlistEnv: "MACCTL_PATH_ALLOWLIST",
+        protectedEnv: "MACCTL_PROTECTED_PATHS",
+      },
+      command: {
+        label: "program",
+        match: "exact",
+        allowlist: envList("MACCTL_COMMAND_ALLOWLIST"),
+        allowlistEnv: "MACCTL_COMMAND_ALLOWLIST",
+      },
+    },
+    flags: {
+      exec: { enabled: envBool("MACCTL_ALLOW_EXEC", !safeMode), env: "MACCTL_ALLOW_EXEC", describe: "runs arbitrary code or kills a process" },
+      delete: { enabled: envBool("MACCTL_ALLOW_DELETE", !safeMode), env: "MACCTL_ALLOW_DELETE" },
+      input: { enabled: envBool("MACCTL_ALLOW_INPUT", !safeMode), env: "MACCTL_ALLOW_INPUT", describe: "injects GUI input" },
+    },
+  };
+}
+```
+
+**REST name-scoped server (debezium):**
+
+```ts
+import { type PolicyConfig, envBool, envEnum, envList } from "@dockndevai/mcp-core";
+
+export function loadPolicyConfig(): PolicyConfig {
+  return {
+    mode: envEnum("DEBEZIUM_MODE", ["read-only", "read-write", "admin"] as const, "read-only"),
+    auditTag: "debezium-mcp",
+    dryRun: envBool("DEBEZIUM_DRY_RUN"),
+    auditLog: envBool("DEBEZIUM_AUDIT_LOG", true),
+    resources: {
+      connector: {
+        label: "connector",
+        match: "exact",
+        allowlist: envList("DEBEZIUM_CONNECTOR_ALLOWLIST"),
+        protected: envList("DEBEZIUM_PROTECTED_CONNECTORS"),
+        allowlistEnv: "DEBEZIUM_CONNECTOR_ALLOWLIST",
+        protectedEnv: "DEBEZIUM_PROTECTED_CONNECTORS",
+      },
+    },
+    flags: { delete: { enabled: envBool("DEBEZIUM_ALLOW_DELETE"), env: "DEBEZIUM_ALLOW_DELETE" } },
+    destructiveFlag: "delete",   // preserves the `destructive && !allowDelete` shape
+  };
+}
+```
+
+## Step 5 — update `guard()` call sites in the tools
+
+The guard context changes from flat fields to the `resources` / `requires` / `bypasses` shape. The
+semantics are identical.
+
+**Path-scoped:**
+
+```diff
+- policy.guard({ tool: "read_file", capability: "read", path: abs });
++ policy.guard({ tool: "read_file", capability: "read", resources: { path: { value: abs } } });
+
+- policy.guard({ tool: "write_file", capability: "write", path: abs, pathMutation: true });
++ policy.guard({ tool: "write_file", capability: "write", resources: { path: { value: abs, mutation: true } } });
+
+- policy.guard({ tool: "run_command", capability: "admin", command: basename(cmd),
+-                shellEscape: isShellEscape(cmd, argv), requiresExec: true, destructive: true });
++ policy.guard({ tool: "run_command", capability: "admin",
++                resources: { command: { value: basename(cmd) } },
++                bypasses: ["command"],          // only matters when the command allowlist is set
++                requires: ["exec"], destructive: true });
+
+- policy.guard({ tool: "delete_path", capability: "admin", requiresDelete: true, destructive: true, path: abs, pathMutation: true });
++ policy.guard({ tool: "delete_path", capability: "admin", requires: ["delete"], destructive: true,
++                resources: { path: { value: abs, mutation: true } } });
+
+- policy.guard({ tool: "type_text", capability: "admin", requiresInput: true });
++ policy.guard({ tool: "type_text", capability: "admin", requires: ["input"] });
+```
+
+`bypasses: ["command"]` replaces the `shellEscape` boolean: pass it when the op (a shell `-c`) could
+run outside the named allowlist; core refuses it only while that rule's allowlist is non-empty.
+
+**REST name-scoped:** the old code refused mutation of a protected connector when
+`capability !== "read"`. Express that as `mutation`:
+
+```diff
+- policy.guard({ tool: "delete_connector", capability: "admin", connector: name, destructive: true });
++ policy.guard({ tool: "delete_connector", capability: "admin", destructive: true,
++                resources: { connector: { value: name, mutation: true } } });
+
+- policy.guard({ tool: "get_connector", capability: "read", connector: name });
++ policy.guard({ tool: "get_connector", capability: "read", resources: { connector: { value: name } } });
+```
+
+Also replace helper calls: `policy.isPathAllowed(p)` → `policy.isResourceAllowed("path", p)`,
+`policy.isPathProtected(p)` → `policy.isResourceProtected("path", p)`,
+`policy.isCommandAllowed(c)` → `policy.isResourceAllowed("command", c)`.
+
+## Step 6 — tool types, results, annotations
+
+Delete `tools/types.ts` and `tools/annotations.ts`. In your tool files:
+
+```diff
+- import { type ToolDef, jsonResult, textResult, imageResult } from "./types.js";
++ import { type ToolDef, jsonResult, textResult, imageResult } from "@dockndevai/mcp-core";
+```
+
+Define your own context by extending `BaseToolContext` (this is where extra context such as the
+laya-guard `GuardClient` stays):
+
+```ts
+import type { BaseToolContext } from "@dockndevai/mcp-core";
+import type { MacClient } from "../mac/client.js";
+import type { GuardClient } from "../guard.js";
+
+export interface ToolContext extends BaseToolContext {
+  client: MacClient;
+  guard: GuardClient;   // domain-specific — stays
+}
+```
+
+Tool definitions become `ToolDef<ToolContext>`. Keep the `capability` tag honest and set
+`destructive` where it applied. Use `enabledWhen: (p) => p.isFlagEnabled("exec")` to keep the most
+dangerous tools unregistered until their flag is on (replacing any manual filtering in `server.ts`).
+
+## Step 7 — rewrite `server.ts` with `buildServer`
+
+```ts
+import { buildServer, makeConfirmer, defaultErrorMapper, type ToolResult } from "@dockndevai/mcp-core";
+import { MacError } from "./mac/client.js";
+
+export function build() {
+  const policy = new SecurityPolicy(loadPolicyConfig());
+  const client = new MacClient(loadLimits());
+  const guard = new GuardClient(loadGuardConfig());
+  const context = { policy, client, guard } as ToolContext;  // confirm set below
+
+  const built = buildServer<ToolContext>({
+    name: "mac-control",
+    version: "0.4.0",
+    tools: [...readTools, ...writeTools, ...adminTools],
+    context,
+    mapError,   // keep domain error handling (e.g. MacError) — see below
+  });
+  context.confirm = makeConfirmer(built.server);
+  return built;
+}
+
+// Keep domain-specific error mapping (and redaction) by wrapping the default.
+function mapError(err: unknown): ToolResult {
+  if (err instanceof MacError) return { content: [{ type: "text", text: err.message }], isError: true };
+  return defaultErrorMapper(err);
+}
+```
+
+## Step 8 — port the tests, verify
+
+Point the server's `test/security.test.ts` at the new `PolicyConfig` shape (mcp-core already carries
+the exhaustive guard/elicit/path-canonicalization tests, so the server's own suite can shrink to
+domain wiring smoke tests — mirroring the generated scaffold's `test/security.test.ts`). Then:
+
+```bash
+npm run typecheck && npm test && npm run build
+npm audit   # expect 0 vulnerabilities
+```
+
+Nothing about the operator-facing env vars, defaults, or guarantees changes — only where the code
+lives. Bump the server's version, keep `server.json` in sync, and cut a release as usual.

package/README.md

@@ -1,3 +1,159 @@
-# Temporary Holding Version
+# @dockndevai/mcp-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared **governance library** for the [dockndevai](https://github.com/dockndevai) MCP server suite. It is the single audited implementation of the suite's safe-by-default security model, extracted so every server imports it instead of each carrying a near-identical copy.
+
+> This is a **library**, not an MCP server. It has no `server.json`, no `mcpName`, and is not listed in any MCP registry. Node >= 22, ESM, TypeScript types included.
+
+## Why
+
+Every server in the suite shares one philosophy — **safe by default, least privilege, never leak secrets** — and had near-identical `security.ts`, `elicit.ts`, path canonicalization, and config helpers. Divergence is a security risk: a fix to the symlink allowlist-bypass or the guard flow had to be applied N times. `mcp-core` makes it one audited, unit-tested implementation. Domains supply only what is genuinely domain-specific (the resource label, which gates apply, the client); core owns the capability ranking, the guard flow, dry-run, elicitation, path safety, and the JSON audit line.
+
+## Install
+
+```bash
+npm install @dockndevai/mcp-core
+# peers (your server already depends on these):
+npm install @modelcontextprotocol/sdk zod
+```
+
+## The model in one minute
+
+- **Capabilities** — every tool is `read` | `write` | `admin`.
+- **Access modes** — `read-only` (0) → `read-write` (1) → `admin` (2). A tool is registered only when its capability rank ≤ the mode rank, so over-privileged tools are never advertised.
+- **Resources** — a named, scoped domain (a filesystem `path`, a Kafka `connector`, a `realm`, a `topic`, a `command`…). Each has an **allowlist** (empty = all) and a **protected** list (readable forever, never mutable), matched either by `prefix` (segment-aware, for hierarchical paths) or `exact` (for flat names).
+- **Opt-in flags** — high-impact powers (exec, delete, input…) each need a second explicit flag on top of the mode.
+- **Dry-run** — mutating ops can be validated + audited without executing.
+- **Audit** — every decision emits one JSON line to **stderr** (never stdout — stdout belongs to the MCP transport).
+
+## API overview
+
+```ts
+import {
+  // policy engine
+  SecurityPolicy, PolicyError,
+  type Capability, type AccessMode, type PolicyConfig, type ResourceRule, type FlagRule, type GuardContext,
+  isUnder,
+  // human-in-the-loop confirmation
+  makeConfirmer, type Confirmer, type ConfirmRequest, type ConfirmOutcome,
+  // path safety (the audited symlink-bypass fix)
+  resolvePath, resolveRealPath, canonicalize,
+  // env parsing
+  envBool, envList, envCsv, envNum, envEnum,
+  // tool types + result helpers
+  type ToolDef, type BaseToolContext, type ToolResult, type ContentBlock,
+  jsonResult, textResult, imageResult,
+  // annotations + server assembly
+  annotationsFor, type ToolAnnotations,
+  buildServer, defaultErrorMapper, type BuildServerOptions,
+} from "@dockndevai/mcp-core";
+```
+
+### `SecurityPolicy`
+
+```ts
+const policy = new SecurityPolicy({
+  mode: "read-only",
+  auditTag: "my-server",          // the "audit" field of each JSON audit line
+  dryRun: false,
+  auditLog: true,
+  resources: {
+    path: {                        // key referenced from guard() contexts
+      label: "path",
+      match: "prefix",             // "prefix" (isUnder) | "exact"
+      allowlist: ["/work"],        // empty = all allowed
+      protected: ["/work/.secrets"],
+      allowlistEnv: "MYSRV_PATH_ALLOWLIST",   // surfaced in denial messages
+      protectedEnv: "MYSRV_PROTECTED_PATHS",
+    },
+  },
+  flags: {
+    exec: { enabled: false, env: "MYSRV_ALLOW_EXEC", describe: "runs arbitrary code" },
+    delete: { enabled: false, env: "MYSRV_ALLOW_DELETE" },
+  },
+  destructiveFlag: "delete",       // optional: a `destructive` op also requires this flag
+});
+
+policy.isCapabilityEnabled("write");            // mode gate (use when registering)
+policy.isFlagEnabled("exec");                   // flag state (use in enabledWhen)
+policy.isResourceAllowed("path", "/work/a");    // allowlist check
+policy.isResourceProtected("path", "/work/x");  // protected check
+```
+
+### `guard(ctx)` — call first in every handler
+
+```ts
+const { dryRun } = policy.guard({
+  tool: "write_file",
+  capability: "write",
+  resources: { path: { value: abs, mutation: true } }, // mutation => protected refused
+  requires: ["exec"],       // opt-in flags that must be enabled
+  bypasses: ["command"],    // rule names whose allowlist this op could evade (e.g. shell -c)
+  destructive: false,       // records in audit; gates destructiveFlag
+});
+if (dryRun) return textResult("[dry-run] Would …");
+```
+
+`guard()` throws `PolicyError` on any denial (capability, flag, bypass, allowlist, protected) and emits the matching audit line. It returns `{ dryRun }` — `true` only for mutating ops when `dryRun` is configured, never for reads.
+
+### Path safety — `resolveRealPath` / `canonicalize`
+
+The audited fix for the symlink allowlist-bypass: a symlink planted inside an allowlisted directory (or pointing at a protected one) must resolve to its **real** target before `guard()` sees it, because `fs` follows symlinks. Always guard on the canonical value and perform the op on it.
+
+```ts
+const abs = resolveRealPath(args.path);  // sync: ~-expand + realpath, parent-dir fallback for new leaves
+policy.guard({ tool, capability: "read", resources: { path: { value: abs } } });
+// or, async, when you resolvePath first:
+const canon = await canonicalize(resolvePath(args.path));
+```
+
+### `makeConfirmer(server)` — human-in-the-loop
+
+Returns a `Confirmer`. When the client advertises elicitation, destructive tools pause for the **human** to approve the exact action; when it can't (or elicitation fails), it falls back to `{ approved: true }` — the policy gate was the real control, so this only ever adds a checkpoint, never removes one.
+
+### `buildServer(opts)` — register the enabled tools
+
+```ts
+const ctx: MyCtx = { policy, client, confirm: undefined as never };
+const { server, enabled } = buildServer<MyCtx>({
+  name: "my-server",
+  version: "0.1.0",
+  tools: [...readTools, ...writeTools, ...adminTools],
+  context: ctx,
+});
+ctx.confirm = makeConfirmer(server);   // confirmer needs the server
+```
+
+A tool is registered only when `policy.isCapabilityEnabled(tool.capability)` **and** its optional `enabledWhen(policy)` passes (use it to keep the most dangerous tools hidden until an opt-in flag is on). Handlers are wrapped so thrown errors (including `PolicyError`) become a clean `isError` result via `defaultErrorMapper` (override with `mapError`).
+
+## Scaffold a new server — `create-mcp-server`
+
+A generator ships with the package. It copies a minimal, working server built on `mcp-core` (config + security wiring + server + index + one read/write/admin tool each + a test) and substitutes the name/resource.
+
+```bash
+npm create @dockndevai/mcp-server -- mcp-widget --resource widget
+# or, once installed:
+npx create-mcp-server mcp-widget --resource widget --dir ./mcp-widget
+```
+
+| Arg | Meaning |
+| --- | --- |
+| `<name>` | Server name, e.g. `mcp-widget` (an `mcp-` prefix is added if missing). |
+| `--resource <label>` | The resource the server scopes (singular), e.g. `widget`. Default `item`. |
+| `--dir <path>` | Target directory. Default `./<name>`. |
+
+It derives the package name (`@dockndevai/<name>`), the env prefix (`WIDGET_`), and the tool names (`get_widget`, `update_widget`, `delete_widget`). Then:
+
+```bash
+cd mcp-widget && npm install
+npm run typecheck && npm test && npm run build
+```
+
+Replace the in-memory stub in `src/client.ts` with your backend, adjust the resource rule in `src/security.ts`, and flesh out the tools. The governance primitives stay in `mcp-core` — never reimplement them.
+
+## Migrating an existing server
+
+See [MIGRATION.md](./MIGRATION.md) for the step-by-step: how a server replaces its local `security.ts` / `elicit.ts` / `canonicalize` / config helpers with `mcp-core` imports, and what stays domain-specific. Adoption is incremental — one server at a time, no big-bang.
+
+## License
+
+MIT

package/bin/create-mcp-server.mjs

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/**
+ * create-mcp-server — scaffold a new dockndevai MCP server on top of @dockndevai/mcp-core.
+ *
+ * Usage:
+ *   npx @dockndevai/create-mcp-server <name> [--resource <label>] [--dir <path>]
+ *   npm create @dockndevai/mcp-server -- <name> --resource widget
+ *
+ *   <name>        Server name, e.g. "mcp-widget" (an "mcp-" prefix is added if missing).
+ *   --resource    The resource the server scopes (singular), e.g. "widget". Default: "item".
+ *   --dir         Target directory. Default: ./<name>.
+ *
+ * It copies scaffold/template, substitutes the placeholder tokens, and renames the dotfile
+ * templates (gitignore -> .gitignore, env.example -> .env.example). It does NOT run npm install.
+ */
+import { cp, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE = path.join(HERE, "..", "scaffold", "template");
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--resource" || a === "-r") args.resource = argv[++i];
+    else if (a === "--dir" || a === "-d") args.dir = argv[++i];
+    else if (a === "--help" || a === "-h") args.help = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+function usage() {
+  console.log(
+    `create-mcp-server <name> [--resource <label>] [--dir <path>]\n\n` +
+      `  <name>      Server name, e.g. "mcp-widget" (an "mcp-" prefix is added if missing).\n` +
+      `  --resource  Resource the server scopes (singular), e.g. "widget". Default: "item".\n` +
+      `  --dir       Target directory. Default: ./<name>.`,
+  );
+}
+
+function pascal(s) {
+  return s
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1).toLowerCase())
+    .join("");
+}
+
+function sanitizeResource(r) {
+  // Keep it a safe JS identifier fragment (used in tool names like get_<resource>).
+  const clean = r.toLowerCase().replace(/[^a-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+  return clean || "item";
+}
+
+async function walk(dir) {
+  const out = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await walk(full)));
+    else out.push(full);
+  }
+  return out;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help || args._.length === 0) {
+    usage();
+    process.exit(args.help ? 0 : 1);
+  }
+
+  let name = args._[0].trim();
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    console.error(`Error: name "${name}" must be lowercase letters, digits and hyphens only.`);
+    process.exit(1);
+  }
+  if (!name.startsWith("mcp-")) name = `mcp-${name}`;
+
+  const resource = sanitizeResource(args.resource ?? "item");
+  const envBase = name.replace(/^mcp-/, "");
+  const tokens = {
+    __PKG_NAME__: `@dockndevai/${name}`,
+    __SERVER_NAME__: name,
+    __ENV_PREFIX__: envBase.toUpperCase().replace(/[^A-Z0-9]+/g, "_"),
+    __SERVER_PASCAL__: pascal(envBase),
+    __RESOURCE__: resource,
+  };
+
+  const target = path.resolve(args.dir ?? name);
+  if (existsSync(target) && (await readdir(target)).length > 0) {
+    console.error(`Error: target directory "${target}" exists and is not empty.`);
+    process.exit(1);
+  }
+
+  if (!existsSync(TEMPLATE)) {
+    console.error(`Error: template not found at ${TEMPLATE}. Is the package installed correctly?`);
+    process.exit(1);
+  }
+
+  // Copy the whole template, then substitute tokens in every file, then rename dotfiles.
+  await mkdir(target, { recursive: true });
+  await cp(TEMPLATE, target, { recursive: true });
+
+  const files = await walk(target);
+  for (const file of files) {
+    const raw = await readFile(file, "utf8");
+    let replaced = raw;
+    for (const [tok, val] of Object.entries(tokens)) replaced = replaced.split(tok).join(val);
+    if (replaced !== raw) await writeFile(file, replaced, "utf8");
+  }
+
+  // Template dotfiles are shipped without a leading dot so npm doesn't strip them on publish.
+  const renames = [
+    ["gitignore", ".gitignore"],
+    ["env.example", ".env.example"],
+  ];
+  for (const [from, to] of renames) {
+    const src = path.join(target, from);
+    if (existsSync(src)) await rename(src, path.join(target, to));
+  }
+
+  console.log(`\nScaffolded ${tokens.__PKG_NAME__} in ${target}\n`);
+  console.log(`  resource: ${resource}    env prefix: ${tokens.__ENV_PREFIX__}_\n`);
+  console.log(`Next steps:`);
+  console.log(`  cd ${path.relative(process.cwd(), target) || "."}`);
+  console.log(`  npm install`);
+  console.log(`  npm run typecheck && npm test && npm run build`);
+  console.log(`\nThen wire src/client.ts to your backend and flesh out the tools. See the README.\n`);
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.stack : String(err));
+  process.exit(1);
+});

package/dist/annotations.d.ts

@@ -0,0 +1,25 @@
+import type { BaseToolContext, ToolDef } from "./tools.js";
+/**
+ * MCP tool annotations — machine-readable behaviour hints the host reads to decide what to
+ * auto-approve versus prompt on. See https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations
+ */
+export interface ToolAnnotations {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/**
+ * Derive annotations from a tool's declared capability, so the safe-by-default access model is
+ * exposed to the host rather than hidden in the description.
+ *
+ * - `read`  ⇒ read-only, non-destructive, idempotent.
+ * - `write` ⇒ mutating; non-destructive unless the tool sets `destructive`.
+ * - `admin` ⇒ mutating and destructive (data loss possible) unless the tool overrides it.
+ *
+ * `openWorldHint` defaults to true (these servers act on live external systems); pass `false` for a
+ * server whose effects are fully local and closed.
+ */
+export declare function annotationsFor(tool: ToolDef<BaseToolContext>, openWorld?: boolean): ToolAnnotations;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,eAAe,CAAC,EAAE,SAAS,UAAO,GAAG,eAAe,CAUhG"}

package/dist/annotations.js

@@ -0,0 +1,23 @@
+/**
+ * Derive annotations from a tool's declared capability, so the safe-by-default access model is
+ * exposed to the host rather than hidden in the description.
+ *
+ * - `read`  ⇒ read-only, non-destructive, idempotent.
+ * - `write` ⇒ mutating; non-destructive unless the tool sets `destructive`.
+ * - `admin` ⇒ mutating and destructive (data loss possible) unless the tool overrides it.
+ *
+ * `openWorldHint` defaults to true (these servers act on live external systems); pass `false` for a
+ * server whose effects are fully local and closed.
+ */
+export function annotationsFor(tool, openWorld = true) {
+    const readOnly = tool.capability === "read";
+    const destructive = tool.destructive ?? tool.capability === "admin";
+    return {
+        title: tool.config.title,
+        readOnlyHint: readOnly,
+        destructiveHint: readOnly ? false : destructive,
+        idempotentHint: tool.idempotent ?? readOnly,
+        openWorldHint: openWorld,
+    };
+}
+//# sourceMappingURL=annotations.js.map

package/dist/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,IAA8B,EAAE,SAAS,GAAG,IAAI;IAC7E,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,KAAK,MAAM,CAAC;IAC5C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,UAAU,KAAK,OAAO,CAAC;IACpE,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;QACxB,YAAY,EAAE,QAAQ;QACtB,eAAe,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW;QAC/C,cAAc,EAAE,IAAI,CAAC,UAAU,IAAI,QAAQ;QAC3C,aAAa,EAAE,SAAS;KACzB,CAAC;AACJ,CAAC"}

package/dist/elicit.d.ts

@@ -0,0 +1,37 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Human-in-the-loop confirmation for destructive operations, via MCP elicitation.
+ *
+ * When the connected client advertises the elicitation capability, a destructive tool
+ * pauses and asks the **human** to approve the exact action — the model cannot approve
+ * on the user's behalf, which is the whole point (a model can trivially echo a
+ * confirmation string; it cannot check a box a human is shown).
+ *
+ * When the client does NOT support elicitation, or the elicitation round-trip fails,
+ * the call falls back to the policy gate that already permitted it (admin mode + the
+ * `*_ALLOW_DELETE` flag). So enabling this is never *more* permissive than before — it
+ * only adds a human checkpoint where one is possible.
+ */
+export interface ConfirmRequest {
+    /** Short verb phrase naming the action, e.g. "delete dashboard". */
+    action: string;
+    /** The exact resource affected (uid, name, id …) — shown to the human. */
+    target: string;
+    /** Extra context lines shown under the prompt. */
+    details?: Record<string, string | number | boolean | undefined>;
+}
+export type ConfirmOutcome = {
+    approved: true;
+    interactive: boolean;
+} | {
+    approved: false;
+    reason: string;
+};
+export interface Confirmer {
+    /** Whether the connected client can prompt the human at all. */
+    available(): boolean;
+    /** Ask the human to approve a destructive action. */
+    confirm(req: ConfirmRequest): Promise<ConfirmOutcome>;
+}
+export declare function makeConfirmer(server: McpServer): Confirmer;
+//# sourceMappingURL=elicit.d.ts.map

package/dist/elicit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elicit.d.ts","sourceRoot":"","sources":["../src/elicit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;CACjE;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,GACxC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,MAAM,WAAW,SAAS;IACxB,gEAAgE;IAChE,SAAS,IAAI,OAAO,CAAC;IACrB,qDAAqD;IACrD,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACvD;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CA4C1D"}