@kywi-software/mcp 0.3.1 → 0.4.0

package/AGENT-PATTERNS.md

@@ -0,0 +1,294 @@
+# Kywi Patterns — building sites end users can maintain
+
+Guidance for agents building Kywi sites. These are opinions, not rules — a
+developer can overrule any of them — but they encode what Kywi is *for*: sites
+that get handed to non-developers who keep them alive without you. Follow them
+unless the project has a stated reason not to.
+
+## The core principle
+
+**If a non-developer might ever want to change it, model it in the CMS — don't
+hardcode it.** Every hardcoded testimonial array, pasted-in logo grid, or
+copy-edited JSX headline is a future support request. The test before writing
+any markup: *"When the site owner wants this different next month, do they
+edit content in the admin, or do they need a developer?"* If the answer is
+"developer," reach for one of the patterns below instead.
+
+Static code is for structure and brand chrome. Content — anything with words,
+images, prices, names, dates — belongs in Kywi.
+
+## Before you build: design the content model and get sign-off
+
+The most expensive failure in a CMS build is a poorly planned content model —
+types bolted on mid-build, collections discovered after their items were
+entered as free-form pages, taxonomy retrofitted onto a hundred nodes. Content
+entry is the costly part; planning is cheap. So **start every new site (or any
+significant new content area) by proposing the content model and getting the
+owner's sign-off before creating types or entering content.**
+
+Produce a short `CONTENT-MODEL.md` at the project root covering:
+
+- **Content inventory → types.** Every repeated shape, with its proposed type
+  (built-in page vs. custom), fields (name, field type, required), and
+  relationships. One table per type.
+- **Site tree sketch.** Top-level pages and a folder per collection (§1).
+- **Feeds.** Name, source type, taxonomy filter, sort/limit, and which pages
+  display each one.
+- **Taxonomy.** The category sets and expected tags (§3).
+- **Reusable components.** The sections that will appear on multiple pages (§4).
+- **Maintenance notes.** Who edits what; whether review workflow (§9), i18n
+  (§11), or scheduling (§10) apply.
+- **Open questions** for the owner.
+
+Present it, iterate, and get explicit approval — then build in playbook order.
+Keep the file updated as the model evolves; it's the site's living map.
+
+Proportionality applies (this is guidance, not law): a single-page brochure
+site needs a few sentences of confirmation, not a document. But anything
+involving custom types, collections, or more than a handful of pages deserves
+the full proposal — ten minutes of sign-off beats re-entering fifty nodes.
+
+## Quick decisions
+
+| You're about to… | Do this instead |
+|---|---|
+| Hardcode a list (testimonials, logos, posts, products, team) | Folder of nodes + a Feed + the Feed Display module (§1) |
+| Create one-off pages with identical field shapes | A custom content type + one node per item (§2) |
+| Filter/group content by topic, industry, audience | Categories & tags, queried by feeds (§3) |
+| Copy-paste a CTA/banner/snippet across pages | Save it as a reusable component (§4) |
+| Write page sections as JSX | Build them as layout sections/modules the owner can edit (§5) |
+| Hand-code a `<form>` | Build it in the Forms admin, place the Form module (§6) |
+| Drop images into `/public` | Upload to the Media library (§7) |
+| Build segment-specific or experimental UI unprompted | Ask the owner first — offer personalization/A-B with examples (§8) |
+| Let everyone publish straight to the live site | Configure groups + review workflow (§9) |
+| "Launch this next Tuesday" by deploying on Tuesday | Scheduled publishing / a changeset (§10) |
+
+---
+
+## 1. Collections: folders + feeds + Feed Display
+
+**The workhorse pattern.** Any repeating set of items that appears somewhere on
+the site — customer logos, testimonials, recent blog posts, products, portfolio
+pieces, team members, FAQs, press mentions — is a collection, and collections
+are never hardcoded.
+
+- **Structure:** a folder in the Site Tree per collection (`/testimonials`,
+  `/customers`, `/work`), one content node per item. Items that need their own
+  public page (blog posts, portfolio pieces) live at real paths; items that are
+  only ever displayed in aggregate (logos, quotes) still get nodes — their pages
+  just aren't linked.
+- **Query:** create a Feed (admin → Feeds): pick the content type, filter by
+  taxonomy, sort, and limit ("6 most recent posts", "testimonials tagged
+  `homepage`").
+- **Display:** place the **Feed Display** module wherever the collection should
+  render — home page hero strip, interior sidebars, a `/blog` index. One feed
+  can feed many pages.
+- **Why it wins:** the owner adds a testimonial by creating one node. Every
+  page showing that feed updates. No layout edits, no deploys.
+
+Advanced: product catalogs and portfolios are the same pattern with a richer
+custom type (§2) and taxonomy-driven feeds per category (§3). Multiple feeds
+over one collection give different slices (featured vs. all, per-category).
+
+## 2. Structured data: custom content types
+
+When several nodes share the same shape — recipes (ingredients, steps, prep
+time), team profiles (role, bio, headshot, links), products (price, SKU,
+gallery), case studies (client, industry, outcome) — define a **custom content
+type** so the shape is enforced and the data is queryable, instead of burying
+it in free-form body text.
+
+**Default: create types in the admin (Type Designer), not in kywi.config.ts.**
+Admin-created types are runtime-managed: the site owner can add a field next
+year ("dietary tags on recipes") without a developer or a migration. Reserve
+config-defined types (`contentTypes` in `kywi.config.ts`) for schema the
+*developer* must own — shapes that code depends on, reviewed in git, migrated
+by `kywi migrate`. When in doubt, admin-created.
+
+- Fields available include text, textarea, rich text, date, image, URL, email,
+  JSON, and relationship (with a target type — e.g. a recipe's `author` →
+  profile). Title can be made optional per type.
+- **Combine with §1:** the type gives you structure; a feed over the type gives
+  you the listing (`/recipes` index, an intranet's people directory); each
+  node's own page is the detail view. Listing + detail with zero custom code.
+- Don't shadow built-in fields (slug, body) with custom ones — Kywi will block
+  it; use the built-ins.
+
+## 3. Taxonomy: categories & tags
+
+Categories and tags are the cross-cutting organization layer over §1 and §2.
+Use **categories** for a site's stable sections (Recipes: Breakfast / Dinner /
+Dessert) and **tags** for freeform, evolving labels (gluten-free, quick,
+featured).
+
+- Feeds filter by taxonomy, so "show featured testimonials on the home page"
+  is: tag the nodes `featured`, point the feed at the tag. The owner curates
+  the home page by tagging — never by editing the page.
+- Prefer taxonomy-driven feeds over separate folders when items belong to
+  multiple groupings (a recipe is both `quick` and `vegetarian`; a folder can
+  only hold it once).
+
+## 4. Reusable components: edit once, propagate everywhere
+
+Anything designed once and used on multiple pages — CTA bands, promo banners,
+newsletter signup blocks, campaign snippets, "as seen in" strips — should be a
+**reusable component**, not copy-pasted sections.
+
+- In the layout editor, select the module and **Save as Component**; insert it
+  elsewhere from the component picker. Placed instances are **live
+  references**: editing the source component updates every page that uses it.
+- **Detach** an instance when a page genuinely needs a one-off variant — it
+  becomes an independent copy from that point on.
+- Rule of thumb: the second time you paste the same section, stop and make it
+  a component. The owner should be able to update the sitewide CTA in one
+  place, ten minutes before their webinar.
+
+## 5. Page layouts & modules — not hardcoded JSX
+
+Pages the owner should be able to restructure — landing pages, the home page,
+campaign pages — should be built **in the layout editor** (sections, columns,
+modules), rendered through Kywi's layout renderer. A scaffolded app already
+renders saved layouts on every content page; keep it that way.
+
+- The built-in module palette (hero, cards, CTA, testimonial, feed display,
+  pricing, FAQ, forms, comments, media…) covers most marketing-site needs.
+- Brand-specific blocks the palette lacks: build a **custom module** once
+  (`defineModule` in `kywi.config.ts` + a React component registered in the
+  host's module map — the scaffold's `lib/modules.tsx` shows the shape). The
+  developer owns the component; the owner places and configures instances.
+- Create **saved layouts** (Layouts admin) as page templates — "Landing page",
+  "Case study" — so new pages start from a consistent skeleton instead of a
+  blank canvas.
+- Hand-written JSX pages are fine for genuinely fixed chrome (a bespoke 404,
+  legal boilerplate shells) — but if marketing will ever want to swap a
+  headline, it's a layout page.
+
+## 6. Forms: always the Forms builder
+
+Never hand-code a `<form>`. Build forms in the Forms admin (fields, multi-step,
+success message, notification emails, optional reCAPTCHA via Settings →
+Security) and place them with the **Form / Form Embed** modules, which submit
+through Kywi's pipeline into admin → Submissions.
+
+- The owner edits fields, recipients, and the thank-you message without code.
+- Submissions are stored, browsable, and exportable — a hand-rolled form that
+  emails someone is data loss with extra steps.
+
+## 7. Media: the library, not /public
+
+All owner-managed imagery — logos, hero images, headshots, product shots —
+goes through the Media library (upload, alt text, automatic variants,
+on-demand resize). Reserve `/public` for build-time brand assets (favicon,
+font files) that only change when the code does.
+
+The difference matters at handover: the owner can swap a hero image in the
+library; they cannot ship a new `/public` file.
+
+## 8. Personalization & A/B testing — offer it, don't default to it
+
+Kywi ships a full personalization stack: **audiences** (rule-based, plus an
+optional self-identification widget), **page variants** targeted per audience,
+and **A/B experiments** with stable per-visitor assignment and recorded
+exposures. Most sites don't need it on day one — and unrequested
+personalization is complexity the owner didn't ask to maintain.
+
+**The agent's job is to surface the capability, not to assume it.** When
+scoping a build, ask the owner whether any of these fit, with examples:
+
+- *"Should returning visitors see a different home-page hero than first-timers
+  (e.g. 'Welcome back — pick up where you left off')?"*
+- *"Do you serve distinct segments (agencies vs. freelancers, industries,
+  regions) that should get tailored messaging on key pages?"*
+- *"Would you like visitors to self-identify (e.g. 'I'm a developer / I'm a
+  marketer') and see content ordered for them?"*
+- *"Is there a headline, CTA, or pricing presentation you'd like to A/B test
+  before committing?"*
+
+If yes, principles: personalize **sections and modules**, not whole sites; the
+default variant must stand alone (personalization is progressive enhancement);
+one experiment per conversion goal, and let it conclude before layering more.
+If no, skip it — the machinery is there when they grow into it.
+
+## 9. Editorial workflow: drafts, review, versions
+
+For any site with more than one author — or an owner who wants a safety net —
+configure the workflow rather than letting everything publish directly:
+
+- **Groups & permissions:** editors write (`draft → Submit for Review`),
+  a smaller group approves and publishes. Content-level permissions can gate
+  specific sections (e.g. only Legal edits `/legal/*`).
+- Published pages accept **pending revisions** — edits go through review while
+  the live page keeps serving — so review doesn't mean taking pages down.
+- Every save records a **version** with restore; approvers see field-level
+  diffs. Mention this at handover: "you can always roll back."
+
+Solo-owner sites can publish directly — but still enable it before the team
+grows past one.
+
+## 10. Scheduling & changesets
+
+- Content has schedule fields: publish at a future time, unpublish/expire
+  automatically. The background scheduler handles both — "post this Monday 9am"
+  is a field, not a calendar reminder.
+- **Changesets** batch related edits (a product launch touching six pages) and
+  publish them together, optionally on a schedule. Use one whenever a launch
+  spans multiple nodes — partial launches are worse than late ones.
+
+## 11. Multilingual sites
+
+If the owner needs more than one language, declare `locales` in
+`kywi.config.ts` up front — the scaffold routes locale prefixes (`/es/...`),
+falls back to the default locale, and emits hreflang alternates. Translations
+are per-node in the admin. Retrofitting i18n is far costlier than declaring it
+early, so ask at scoping time.
+
+## 12. SEO & the Agent Experience layer
+
+- Fill the **SEO tab** on every page that matters (meta title/description,
+  og:image); the scaffold maps it into the public head and emits JSON-LD.
+- The AX layer serves `llms.txt`, `llms-full.txt`, `sitemap.xml`, and
+  `robots.txt` at the site root out of the box — a Kywi site is legible to
+  agents and crawlers by default. Don't remove these routes; they're part of
+  the product's value.
+
+## Other capabilities worth knowing
+
+- **Comments:** a moderated Comments module (submissions land pending) for
+  blogs/community pages — ask the owner if discussion fits.
+- **Webhooks** (Web Services → Webhooks): notify external systems on content
+  events (rebuild a static mirror, ping Slack, sync a CRM) — signed, retried.
+- **API keys** with enforced scopes: hand a read-only key to a partner or a
+  frontend without exposing write access.
+
+## Build-order playbook (new site)
+
+0. **Propose the content model and get sign-off** ("Before you build", above)
+   — nothing else starts until the owner approves it.
+1. **Model first:** custom content types for every repeated shape (§2).
+2. **Structure:** site tree — pages, folders per collection (§1).
+3. **Taxonomy:** categories/tags the feeds will need (§3).
+4. **Media:** upload the brand's assets to the library (§7).
+5. **Templates:** saved layouts + reusable components for the recurring
+   sections (§4, §5); custom modules only where the palette falls short.
+6. **Wire collections:** feeds + Feed Display placements (§1).
+7. **Forms:** contact/newsletter/etc. in the builder (§6).
+8. **Workflow:** groups, permissions, review path (§9).
+9. **Ask about** personalization/A-B (§8), comments, webhooks, i18n (§11).
+10. **SEO pass** (§12), then hand over: show the owner where *their* edits
+    live — content nodes, feeds, components — and confirm nothing they'll want
+    to change requires you.
+
+## Anti-patterns (smells)
+
+- Creating types and entering content before the owner signed off on a
+  content model.
+- A hardcoded array of testimonials/logos/posts in a page component.
+- The same CTA JSX pasted on four pages.
+- A `<form>` that POSTs to a hand-rolled route (or nowhere).
+- Marketing imagery in `/public`.
+- A "blog" that is a folder of `.mdx` files the owner can't edit.
+- One-off content types created in config for shapes the owner will evolve.
+- Personalization built speculatively, with no owner request behind it.
+- Direct-publish-only workflow on a multi-author site.
+
+Every one of these has a section above. If you catch yourself mid-smell, refactor to the pattern before handover — it's minutes now, migrations later.

package/README.md

@@ -64,6 +64,17 @@ directly), `KYWI_API_URL` / `KYWI_MCP_DEV_KEY` (API mode), and
 `KYWI_MCP_MODE` (`filesystem` | `api` | `auto`, default `auto` — picks
 filesystem mode when `configPath` is writable, otherwise API mode).
 
+## Building patterns for agents
+
+Both servers register a `get_building_patterns` tool that returns
+[`AGENT-PATTERNS.md`](./AGENT-PATTERNS.md) — Kywi's official guidance for building
+sites end users can maintain (model content in the CMS instead of hardcoding it;
+use collections/feeds, custom types, the Forms builder, reusable components, and
+the layout editor). An agent should call it before authoring content or
+scaffolding a project. The doc is a verbatim copy of
+`docs/agents/AGENT-PATTERNS.md` in the monorepo, kept in sync by
+`scripts/sync-agent-patterns.mjs`.
+
 ## What's in the package
 
 - `.` — shared config types (`defineMcpConfig`, `McpConfig`).

package/dist/developer/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/developer/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAQtD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,CA6B9E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/developer/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAStD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,CA+B9E"}

package/dist/developer/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { createKywiSdk, KywiHttpClient } from '@kywi-software/sdk';
 import { detectMode } from './auto-detect.js';
+import { registerPatternsTool } from '../patterns.js';
 import { registerReadOnlyTools } from './tools/read-only.js';
 import { registerConfigMutationTools } from './tools/config-mutation.js';
 import { registerScaffoldingTools } from './tools/scaffolding.js';
@@ -10,6 +11,8 @@ export function createDeveloperMcpServer(config) {
     const server = new McpServer({ name: '@kywi-software/mcp/developer', version: '0.1.0' }, { capabilities: { tools: {} } });
     const mode = detectMode(config);
     const http = config.baseUrl ? new KywiHttpClient({ baseUrl: config.baseUrl, apiKey: config.apiKey }) : undefined;
+    // Kywi's building-patterns guide — available in every mode.
+    registerPatternsTool(server);
     registerReadOnlyTools(server, { mode, configPath: config.configPath, http });
     if (mode === 'filesystem' && config.configPath) {
         registerConfigMutationTools(server, { configPath: config.configPath });

package/dist/developer/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/developer/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAElE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAA;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAExE,MAAM,UAAU,wBAAwB,CAAC,MAA0B;IACjE,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,8BAA8B,EAAE,OAAO,EAAE,OAAO,EAAE,EAC1D,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAA;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;IAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAEhH,qBAAqB,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;IAE5E,IAAI,IAAI,KAAK,YAAY,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAC/C,2BAA2B,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAA;IACxE,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,aAAa,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;QAC7E,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;QAErC,IAAI,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1D,wBAAwB,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,CAAA;QAC5D,CAAC;IACH,CAAC;IAED,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,EAAE,CAAC;QAC3B,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACnC,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/developer/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAElE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAA;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAA;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAExE,MAAM,UAAU,wBAAwB,CAAC,MAA0B;IACjE,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,8BAA8B,EAAE,OAAO,EAAE,OAAO,EAAE,EAC1D,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAA;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAA;IAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAEhH,4DAA4D;IAC5D,oBAAoB,CAAC,MAAM,CAAC,CAAA;IAC5B,qBAAqB,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;IAE5E,IAAI,IAAI,KAAK,YAAY,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAC/C,2BAA2B,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CAAC,CAAA;IACxE,CAAC;IAED,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,aAAa,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;QAC7E,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;QAErC,IAAI,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1D,wBAAwB,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,CAAA;QAC5D,CAAC;IACH,CAAC;IAED,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,EAAE,CAAC;QAC3B,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACnC,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/patterns.d.ts

@@ -0,0 +1,13 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/** The building-patterns markdown, read once and cached. */
+export declare function readBuildingPatterns(): string;
+/** Tool handler: returns the raw building-patterns markdown as text. */
+export declare function handleGetBuildingPatterns(): {
+    content: [{
+        type: 'text';
+        text: string;
+    }];
+};
+/** Register the `get_building_patterns` tool on an MCP server. */
+export declare function registerPatternsTool(server: McpServer): void;
+//# sourceMappingURL=patterns.d.ts.map

package/dist/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../src/patterns.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AA0BxE,4DAA4D;AAC5D,wBAAgB,oBAAoB,IAAI,MAAM,CAK7C;AAED,wEAAwE;AACxE,wBAAgB,yBAAyB,IAAI;IAC3C,OAAO,EAAE,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC1C,CAEA;AAUD,kEAAkE;AAClE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAM5D"}

package/dist/patterns.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Exposes Kywi's building-patterns guide to agents over MCP.
+ *
+ * The MCP servers are tools-only (no MCP `resources`), so the guide is surfaced
+ * as a `get_building_patterns` tool that returns the markdown. Both the site and
+ * developer servers register it, so an agent authoring content or scaffolding a
+ * project encounters the same guidance.
+ *
+ * Asset resolution (dist-safe): the doc ships as `AGENT-PATTERNS.md` at the
+ * package root (in the package.json `files` array) and is read relative to THIS
+ * module's URL — NOT process.cwd(). `tsc` compiles src/patterns.ts → dist/patterns.js
+ * at the same depth, so `../AGENT-PATTERNS.md` resolves to the package root
+ * identically from src (tests), dist (published), and an installed
+ * node_modules/@kywi-software/mcp/. No copy-assets step is required because the
+ * doc lives at the package root rather than under src/ (unlike core's CSS, which
+ * sits beside the .ts that imports it and so needs copying into dist). The file
+ * is byte-identical to the repo canonical docs/agents/AGENT-PATTERNS.md, kept in
+ * sync by scripts/sync-agent-patterns.mjs (a drift test guards it).
+ */
+const PATTERNS_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', 'AGENT-PATTERNS.md');
+let cached;
+/** The building-patterns markdown, read once and cached. */
+export function readBuildingPatterns() {
+    if (cached === undefined) {
+        cached = readFileSync(PATTERNS_PATH, 'utf8');
+    }
+    return cached;
+}
+/** Tool handler: returns the raw building-patterns markdown as text. */
+export function handleGetBuildingPatterns() {
+    return { content: [{ type: 'text', text: readBuildingPatterns() }] };
+}
+const DESCRIPTION = "Kywi's official guidance for building sites end users can maintain: the patterns " +
+    'to follow when modeling content, collections, custom types, taxonomy, reusable ' +
+    'components, page layouts, forms, media, personalization, and editorial workflow. ' +
+    'Read this before authoring content or scaffolding a Kywi site — the core ' +
+    'principle is to model anything a non-developer might change in the CMS rather ' +
+    'than hardcoding it. Returns the full guide as markdown.';
+/** Register the `get_building_patterns` tool on an MCP server. */
+export function registerPatternsTool(server) {
+    server.registerTool('get_building_patterns', { description: DESCRIPTION, inputSchema: {} }, async () => handleGetBuildingPatterns());
+}
+//# sourceMappingURL=patterns.js.map

package/dist/patterns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.js","sourceRoot":"","sources":["../src/patterns.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAGxC;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,mBAAmB,CAAC,CAAA;AAE9F,IAAI,MAA0B,CAAA;AAE9B,4DAA4D;AAC5D,MAAM,UAAU,oBAAoB;IAClC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,GAAG,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,CAAA;IAC9C,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,yBAAyB;IAGvC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,oBAAoB,EAAE,EAAE,CAAC,EAAE,CAAA;AAC/E,CAAC;AAED,MAAM,WAAW,GACf,mFAAmF;IACnF,iFAAiF;IACjF,mFAAmF;IACnF,2EAA2E;IAC3E,gFAAgF;IAChF,yDAAyD,CAAA;AAE3D,kEAAkE;AAClE,MAAM,UAAU,oBAAoB,CAAC,MAAiB;IACpD,MAAM,CAAC,YAAY,CACjB,uBAAuB,EACvB,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,EAAE,EAAE,EAC7C,KAAK,IAAI,EAAE,CAAC,yBAAyB,EAAE,CACxC,CAAA;AACH,CAAC"}

package/dist/site/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AASjD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAwBpE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAUjD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CA0BpE"}

package/dist/site/server.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { createKywiSdk, KywiHttpClient } from '@kywi-software/sdk';
 import { textResult } from '../shared.js';
+import { registerPatternsTool } from '../patterns.js';
 import { registerContentTools } from './tools/content.js';
 import { registerLayoutTools } from './tools/layout.js';
 import { registerFeedTools } from './tools/feeds.js';
@@ -58,6 +59,8 @@ export function createSiteMcpServer(config) {
         baseUrl: config.baseUrl,
         apiKey: config.apiKey,
     });
+    // Kywi's building-patterns guide, so an authoring agent can consult it.
+    registerPatternsTool(server);
     registerContentTools(server, sdk, config.baseUrl, config.apiKey);
     registerLayoutTools(server, sdk);
     registerFeedTools(server, sdk);

package/dist/site/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kywi-software/mcp",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Model Context Protocol servers for Kywi CMS — a site server (content/nav/media over the REST API) and a developer server (kywi.config.ts scaffolding and mutation).",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -22,6 +22,7 @@
   },
   "files": [
     "dist",
+    "AGENT-PATTERNS.md",
     "README.md",
     "LICENSE"
   ],
@@ -46,7 +47,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.25.0",
-    "@kywi-software/sdk": "0.3.1"
+    "@kywi-software/sdk": "0.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",