ADR-0023: docs-mcp ships as a publishable npm package with docs bundled at build time
- Status: Proposed
- Date: 2026-08-19
- Deciders: @VicenzoMF
Context
ADR-0022 decided how the docs-search MCP server searches (lexical, not vector RAG) but not how it reaches a consumer. As built, main.ts resolved docs/ via a path relative to its own location in the monorepo (../../../docs) — correct for running the server from inside this checkout (dogfooding, TODO-POC-SPEC.md), but useless for an app scaffolded by kata init on someone else's machine: there is no Kata monorepo checkout next to it to read docs/ from.
kata init today is purely flag-driven (--minimal, --force, --cwd, --help) — no interactive prompt library exists anywhere in the repo. Adding a full interactive "seletor" would be a first-of-its-kind UX shift and risks breaking any script/CI that already calls kata init non-interactively; nothing in the codebase asked for that yet, so it's out of scope here.
Decision
We will:
Bundle the docs into
@kata/docs-mcpat build time.scripts/copy-docs.mjscopiesdocs/{guide,cookbook,reference,adr}/**/*.mdintopackages/docs-mcp/data/docs/before bothstart(dev) andbuild.main.tsresolvesdocsRootas../data/docsrelative to itself — a sibling ofsrc/in dev and ofdist/once built, so the same relative path works whether the server runs viatsx src/main.tsor as the publisheddist/main.js.data/is generated and already gitignored (present in the root.gitignoresince the repo's first commit).Make
@kata/docs-mcpgenuinely publishable, mirroringkatajs's existing (unpublished-but-ready) shape: noprivatefield,binpointing atdist/main.js,files: [dist, data, README.md],publishConfig.access: public, atsupbuild (baretscwould emit extensionless imports Node's ESM loader can't resolve — same reasoning aspackages/kata/tsup.config.ts). The actualnpm publishremains a manual step for the repo owner, same askatajsitself.Add
kata init --with-docs-mcp— a flag, not a prompt, consistent with the CLI's existing non-interactive design. It writes.mcp.json:json{ "mcpServers": { "kata-docs": { "command": "npx", "args": ["-y", "@kata/docs-mcp"] } } }onlyIfAbsent, like the other generated manifests — a real project's.mcp.jsonmay already register other servers. The CLI's next-steps output warns that this requires@kata/docs-mcpto actually be published first.
Alternatives considered
A — Interactive prompt ("seletor") in kata init
Rejected for now. No prompt library exists in the repo; introducing one is a larger UX decision (backward compatibility for scripted/CI invocations of kata init, a new dependency) than this feature justifies on its own. A flag achieves the same opt-in outcome without it. Revisit if kata init grows enough optional features that flags stop scaling.
B — Host docs-mcp as a remote/hosted service
Rejected. Contradicts ADR-0022's "local first" decision outright — a hosted server is a different trust and latency model, not a distribution detail.
C — Keep docs-mcp monorepo-internal only, don't wire kata init at all
Rejected as the long-term answer, though it was the state before this ADR. Kata's core thesis is being developed with AI assistance at low adoption ([[kata-framework]]) — leaving the docs-search tool undiscoverable by generated apps directly undercuts that thesis. Kept as the fallback if npm publishing turns out to be blocked for some reason.
Consequences
Positive
@kata/docs-mcpworks identically in dev (tsx) and once published (npx @kata/docs-mcp) — verified by running the compileddist/main.jsstandalone via plainnode, no tsx/TypeScript required.kata init --with-docs-mcpcosts nothing to users who don't pass it — purely additive,onlyIfAbsent.- No new runtime dependency in the framework itself — this only touches the CLI's generator layer and a sibling tooling package.
Negative / costs
- The bundled
data/docssnapshot is frozen at whatever version of@kata/docs-mcpa consumer'snpxresolves — republishing is required to pick up doc changes. Acceptable: this is normal for any versioned package. .mcp.jsonwritten by--with-docs-mcpis inert until@kata/docs-mcpis actually published — a real, current gap this ADR does not close by itself.
Follow-ups
- Actually
npm publish @kata/docs-mcp(manual, repo owner) — until then--with-docs-mcpships forward-looking config only. - Consider whether
@kata/docs-mcpshould instead ship insidekatajsitself (a subpath export) rather than as a separate package, once real usage data exists.
Companion rules
None. This ADR governs CLI scaffolding output and external tooling packaging, not application code inside generated Kata projects — no archgate rule applies.
Numbering note: confirmed against origin/main on 2026-08-19 — max ADR on origin/main is 0021; this session's own ADR-0022 (docs-mcp lexical search) is only in open PR #225, not yet merged. 0023 is the real next number given that PR merges first; a same-branch-name PR (#224) already merged once mid-session without conflict (see [[kata-adr-numbering-collision]]), so reconfirm against origin/main right before applying regardless of this note.