@kywi-software/mcp

Two Model Context Protocol servers for Kywi CMS, so an AI agent can author content or scaffold a project over stdio:

• kywi-mcp-site — content-authoring tools (content, layout, media, search, users, feeds, webhooks) against a running Kywi site's REST API. Built on @kywi-software/sdk.
• kywi-mcp-dev — project scaffolding and config tools: read/mutate a local kywi.config.ts (content types, sites, themes), or drive the same operations over the REST API.

See the root README for how this fits into the rest of Kywi.

Install

npm install -g @kywi-software/mcp
# or: npx @kywi-software/mcp

Usage

Both binaries speak MCP over stdio — wire them into an MCP-capable client (e.g. Claude Code, Claude Desktop) via its server config.

kywi-mcp-site

{
  "mcpServers": {
    "kywi-site": {
      "command": "kywi-mcp-site",
      "env": {
        "KYWI_API_URL": "https://your-site.example.com/api/v1",
        "KYWI_MCP_API_KEY": "kywi_xxxxxxxx"
      }
    }
  }
}

KYWI_API_URL defaults to http://localhost:3000/api/v1 if unset.

kywi-mcp-dev

{
  "mcpServers": {
    "kywi-dev": {
      "command": "kywi-mcp-dev",
      "env": {
        "KYWI_CONFIG_PATH": "/path/to/project/kywi.config.ts"
      }
    }
  }
}

Env vars: KYWI_CONFIG_PATH (filesystem mode — read/mutate kywi.config.ts 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).

Tool contracts worth knowing before you call them

Three behaviours account for most of the surprises when an agent drives a real site. They are documented in the tool descriptions too, but here in one place:

Every list_* result carries total and hasMore. list_content (and the per-type list_<type> tools) page: the default page size is 10 and the server caps limit at 100. hasMore: true means you are holding a truncated answer and must ask for the next page — the tempting shortcut, limit: 1000, is silently clamped to 100 and fails again at the 101st row. The unpaged lists (list_media with no limit, list_feeds, list_menus, list_components, list_users) return everything and report hasMore: false.

Check for existence with a filter, not by paging. list_content accepts slug and path for exact matches, so "does /resources already exist?" is one call whose total is the answer. Paging until you happen to see it is how a build creates a second published copy of a page it already had.

Omitted module props take the module's default; '' stays blank. add_module fills in every prop you leave out with the defaultValue the module declares, so a module placed with no props still renders. Writing a prop as an empty string means "blank on purpose" and is preserved. Call list_module_types to see each prop's default. Defaults are applied to modules a write ADDS, so re-saving a page never puts back a prop that was deliberately left off an existing module.

upload_media sends the file as the raw request body with its name in x-filename and its type in Content-Type — so filename must carry a real extension (hero.png, not hero), and it must agree with mimeType: the server gates uploads on both. The name is reduced to a plain basename on the way (path segments stripped, anything outside [A-Za-z0-9._-] replaced with _), so pass a bare file name and read the stored filename back off the result rather than assuming it. alt and caption are stored as the file's metadata after the upload.

list_media returns the whole library when you omit limit; page is only meaningful alongside a limit, and sending it alone is an error rather than a silent first page.

Building patterns for agents

Both servers register a get_building_patterns tool that returns 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).
• ./site — createSiteMcpServer, the site server's tool implementations (packages/mcp/src/site/tools/*.ts).
• ./developer — createDeveloperMcpServer, the developer server's tool implementations (packages/mcp/src/developer/tools/*.ts), including filesystem config mutation and content-type scaffolding.

packages/mcp/src/config.ts and the tools/ directories are the source of truth for exact tool names and schemas.