@mapomodule/mcp 0.0.0-stage → 1.0.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/README.md +509 -2
  2. package/bin/mapo-mcp.mjs +3 -0
  3. package/dist/build.d.mts +18 -0
  4. package/dist/build.d.ts +18 -0
  5. package/dist/build.mjs +351 -0
  6. package/dist/cli.d.mts +7 -0
  7. package/dist/cli.d.ts +7 -0
  8. package/dist/cli.mjs +274 -0
  9. package/dist/index.d.mts +68 -0
  10. package/dist/index.d.ts +68 -0
  11. package/dist/index.mjs +1 -0
  12. package/dist/knowledge/api.json +1 -0
  13. package/dist/knowledge/docs.json +1 -0
  14. package/dist/module.d.mts +16 -0
  15. package/dist/module.d.ts +16 -0
  16. package/dist/module.json +9 -0
  17. package/dist/module.mjs +124 -0
  18. package/dist/runtime/core/doctor.d.ts +0 -0
  19. package/dist/runtime/core/doctor.js +128 -0
  20. package/dist/runtime/core/endpoint.d.ts +0 -0
  21. package/dist/runtime/core/endpoint.js +8 -0
  22. package/dist/runtime/core/indexer.d.ts +0 -0
  23. package/dist/runtime/core/indexer.js +194 -0
  24. package/dist/runtime/core/instructions.d.ts +0 -0
  25. package/dist/runtime/core/instructions.js +10 -0
  26. package/dist/runtime/core/knowledge.d.ts +0 -0
  27. package/dist/runtime/core/knowledge.js +76 -0
  28. package/dist/runtime/core/openapi.d.ts +0 -0
  29. package/dist/runtime/core/openapi.js +229 -0
  30. package/dist/runtime/core/overview.d.ts +0 -0
  31. package/dist/runtime/core/overview.js +15 -0
  32. package/dist/runtime/core/prompts.d.ts +0 -0
  33. package/dist/runtime/core/prompts.js +108 -0
  34. package/dist/runtime/core/recipes.d.ts +0 -0
  35. package/dist/runtime/core/recipes.js +496 -0
  36. package/dist/runtime/core/resources.d.ts +0 -0
  37. package/dist/runtime/core/resources.js +92 -0
  38. package/dist/runtime/core/scaffold/fields.d.ts +0 -0
  39. package/dist/runtime/core/scaffold/fields.js +64 -0
  40. package/dist/runtime/core/scaffold/index.d.ts +0 -0
  41. package/dist/runtime/core/scaffold/index.js +74 -0
  42. package/dist/runtime/core/scaffold/templates.d.ts +0 -0
  43. package/dist/runtime/core/scaffold/templates.js +349 -0
  44. package/dist/runtime/core/schema-source.d.ts +0 -0
  45. package/dist/runtime/core/schema-source.js +70 -0
  46. package/dist/runtime/core/search.d.ts +0 -0
  47. package/dist/runtime/core/search.js +173 -0
  48. package/dist/runtime/core/tokenize.d.ts +0 -0
  49. package/dist/runtime/core/tokenize.js +96 -0
  50. package/dist/runtime/core/tool-spec.d.ts +0 -0
  51. package/dist/runtime/core/tool-spec.js +3 -0
  52. package/dist/runtime/core/tools/api.d.ts +0 -0
  53. package/dist/runtime/core/tools/api.js +192 -0
  54. package/dist/runtime/core/tools/app.d.ts +0 -0
  55. package/dist/runtime/core/tools/app.js +141 -0
  56. package/dist/runtime/core/tools/backend.d.ts +0 -0
  57. package/dist/runtime/core/tools/backend.js +143 -0
  58. package/dist/runtime/core/tools/docs.d.ts +0 -0
  59. package/dist/runtime/core/tools/docs.js +154 -0
  60. package/dist/runtime/core/tools/scaffold.d.ts +0 -0
  61. package/dist/runtime/core/tools/scaffold.js +127 -0
  62. package/dist/runtime/core/types.d.ts +0 -0
  63. package/dist/runtime/core/types.js +0 -0
  64. package/dist/runtime/core/write.d.ts +0 -0
  65. package/dist/runtime/core/write.js +53 -0
  66. package/dist/runtime/mcp/handlers/mapo/index.js +7 -0
  67. package/dist/runtime/mcp/handlers/mapo/prompts/crud-page.js +3 -0
  68. package/dist/runtime/mcp/handlers/mapo/prompts/custom-field.js +3 -0
  69. package/dist/runtime/mcp/handlers/mapo/prompts/debug-form.js +3 -0
  70. package/dist/runtime/mcp/handlers/mapo/prompts/migrate-v1.js +3 -0
  71. package/dist/runtime/mcp/handlers/mapo/prompts/theme.js +3 -0
  72. package/dist/runtime/mcp/handlers/mapo/resources/app-manifest.js +19 -0
  73. package/dist/runtime/mcp/handlers/mapo/resources/docs.js +34 -0
  74. package/dist/runtime/mcp/handlers/mapo/resources/fields.js +34 -0
  75. package/dist/runtime/mcp/handlers/mapo/resources/knowledge-index.js +22 -0
  76. package/dist/runtime/mcp/handlers/mapo/resources/overview.js +20 -0
  77. package/dist/runtime/mcp/handlers/mapo/tools/backend-schema.js +3 -0
  78. package/dist/runtime/mcp/handlers/mapo/tools/component-api.js +3 -0
  79. package/dist/runtime/mcp/handlers/mapo/tools/composable-api.js +3 -0
  80. package/dist/runtime/mcp/handlers/mapo/tools/doctor.js +3 -0
  81. package/dist/runtime/mcp/handlers/mapo/tools/get-doc.js +3 -0
  82. package/dist/runtime/mcp/handlers/mapo/tools/inspect-app.js +3 -0
  83. package/dist/runtime/mcp/handlers/mapo/tools/list-field-types.js +3 -0
  84. package/dist/runtime/mcp/handlers/mapo/tools/list-recipes.js +3 -0
  85. package/dist/runtime/mcp/handlers/mapo/tools/scaffold.js +3 -0
  86. package/dist/runtime/mcp/handlers/mapo/tools/search-docs.js +3 -0
  87. package/dist/runtime/nitro/context.d.ts +0 -0
  88. package/dist/runtime/nitro/context.js +21 -0
  89. package/dist/runtime/nitro/to-mcp-prompt.d.ts +0 -0
  90. package/dist/runtime/nitro/to-mcp-prompt.js +23 -0
  91. package/dist/runtime/nitro/to-mcp-tool.d.ts +0 -0
  92. package/dist/runtime/nitro/to-mcp-tool.js +28 -0
  93. package/dist/runtime/types/virtual-modules.d.ts +6 -0
  94. package/dist/types.d.mts +9 -0
  95. package/package.json +73 -4
  96. package/src/__tests__/cli.test.ts +137 -0
  97. package/src/__tests__/doctor.test.ts +145 -0
  98. package/src/__tests__/endpoint.test.ts +31 -0
  99. package/src/__tests__/fixtures/drf-schema.json +142 -0
  100. package/src/__tests__/fixtures.ts +198 -0
  101. package/src/__tests__/indexer.test.ts +114 -0
  102. package/src/__tests__/knowledge.test.ts +225 -0
  103. package/src/__tests__/openapi.test.ts +256 -0
  104. package/src/__tests__/overview.test.ts +105 -0
  105. package/src/__tests__/recipes.test.ts +55 -0
  106. package/src/__tests__/resources.test.ts +69 -0
  107. package/src/__tests__/scaffold.test.ts +153 -0
  108. package/src/__tests__/search.test.ts +105 -0
  109. package/src/__tests__/tools.test.ts +226 -0
  110. package/src/__tests__/write.test.ts +134 -0
  111. package/src/build/extract-components.ts +135 -0
  112. package/src/build/extract-composables.ts +125 -0
  113. package/src/build/extract-fields.ts +250 -0
  114. package/src/build/index.ts +103 -0
  115. package/src/cli.ts +375 -0
  116. package/src/index.ts +65 -0
  117. package/src/module.ts +213 -0
  118. package/src/runtime/core/doctor.ts +204 -0
  119. package/src/runtime/core/endpoint.ts +27 -0
  120. package/src/runtime/core/indexer.ts +285 -0
  121. package/src/runtime/core/instructions.ts +18 -0
  122. package/src/runtime/core/knowledge.ts +121 -0
  123. package/src/runtime/core/openapi.ts +417 -0
  124. package/src/runtime/core/overview.ts +44 -0
  125. package/src/runtime/core/prompts.ts +150 -0
  126. package/src/runtime/core/recipes.ts +574 -0
  127. package/src/runtime/core/resources.ts +150 -0
  128. package/src/runtime/core/scaffold/fields.ts +127 -0
  129. package/src/runtime/core/scaffold/index.ts +120 -0
  130. package/src/runtime/core/scaffold/templates.ts +394 -0
  131. package/src/runtime/core/schema-source.ts +123 -0
  132. package/src/runtime/core/search.ts +282 -0
  133. package/src/runtime/core/tokenize.ts +146 -0
  134. package/src/runtime/core/tool-spec.ts +74 -0
  135. package/src/runtime/core/tools/api.ts +300 -0
  136. package/src/runtime/core/tools/app.ts +201 -0
  137. package/src/runtime/core/tools/backend.ts +197 -0
  138. package/src/runtime/core/tools/docs.ts +218 -0
  139. package/src/runtime/core/tools/scaffold.ts +176 -0
  140. package/src/runtime/core/types.ts +133 -0
  141. package/src/runtime/core/write.ts +119 -0
  142. package/src/runtime/mcp/handlers/mapo/index.ts +16 -0
  143. package/src/runtime/mcp/handlers/mapo/prompts/crud-page.ts +4 -0
  144. package/src/runtime/mcp/handlers/mapo/prompts/custom-field.ts +4 -0
  145. package/src/runtime/mcp/handlers/mapo/prompts/debug-form.ts +4 -0
  146. package/src/runtime/mcp/handlers/mapo/prompts/migrate-v1.ts +4 -0
  147. package/src/runtime/mcp/handlers/mapo/prompts/theme.ts +4 -0
  148. package/src/runtime/mcp/handlers/mapo/resources/app-manifest.ts +28 -0
  149. package/src/runtime/mcp/handlers/mapo/resources/docs.ts +41 -0
  150. package/src/runtime/mcp/handlers/mapo/resources/fields.ts +37 -0
  151. package/src/runtime/mcp/handlers/mapo/resources/knowledge-index.ts +24 -0
  152. package/src/runtime/mcp/handlers/mapo/resources/overview.ts +22 -0
  153. package/src/runtime/mcp/handlers/mapo/tools/backend-schema.ts +4 -0
  154. package/src/runtime/mcp/handlers/mapo/tools/component-api.ts +4 -0
  155. package/src/runtime/mcp/handlers/mapo/tools/composable-api.ts +4 -0
  156. package/src/runtime/mcp/handlers/mapo/tools/doctor.ts +4 -0
  157. package/src/runtime/mcp/handlers/mapo/tools/get-doc.ts +4 -0
  158. package/src/runtime/mcp/handlers/mapo/tools/inspect-app.ts +4 -0
  159. package/src/runtime/mcp/handlers/mapo/tools/list-field-types.ts +4 -0
  160. package/src/runtime/mcp/handlers/mapo/tools/list-recipes.ts +4 -0
  161. package/src/runtime/mcp/handlers/mapo/tools/scaffold.ts +4 -0
  162. package/src/runtime/mcp/handlers/mapo/tools/search-docs.ts +4 -0
  163. package/src/runtime/nitro/context.ts +41 -0
  164. package/src/runtime/nitro/to-mcp-prompt.ts +30 -0
  165. package/src/runtime/nitro/to-mcp-tool.ts +35 -0
  166. package/src/runtime/types/virtual-modules.d.ts +6 -0
package/README.md CHANGED
@@ -1,3 +1,510 @@
1
- # Temporary Holding Version
1
+ # @mapomodule/mcp
2
2
 
3
- 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.
3
+ An [MCP](https://modelcontextprotocol.io) server that teaches AI assistants how to use **Mapo** —
4
+ the Nuxt 4 admin framework — inside your own project.
5
+
6
+ Without it, an assistant working in a Mapo app has nothing to go on: the documentation lives in a
7
+ private workspace package it never sees, component APIs are `.vue` files buried in `node_modules`,
8
+ and the app's real configuration (which field types are registered, which auth endpoints are set)
9
+ is only knowable from the running Nuxt instance. The predictable result is invented props,
10
+ invented field types, and Mapo v1 code in a v2 project.
11
+
12
+ This package gives the assistant the real thing: **grounded documentation search**, **curated
13
+ recipes**, and — when the dev server is running — **introspection of the actual app**.
14
+
15
+ Setting it up in an app: [How-to: set up your AI assistant](https://lotrekagency.github.io/mapo-new/howto/ai-assistant).
16
+ Reference on the docs site: [@mapomodule/mcp](https://lotrekagency.github.io/mapo-new/modules/mcp).
17
+
18
+ ---
19
+
20
+ ## Table of contents
21
+
22
+ - [How it works](#how-it-works)
23
+ - [Quick start](#quick-start)
24
+ - [Connecting your IDE](#connecting-your-ide)
25
+ - [Tools](#tools)
26
+ - [Prompts](#prompts)
27
+ - [Resources](#resources)
28
+ - [Recipes](#recipes)
29
+ - [Configuration](#configuration)
30
+ - [Security model](#security-model)
31
+ - [How the knowledge base is built](#how-the-knowledge-base-is-built)
32
+ - [Development](#development)
33
+ - [Troubleshooting](#troubleshooting)
34
+ - [Status](#status)
35
+
36
+ ---
37
+
38
+ ## How it works
39
+
40
+ The package ships **two ways to reach the same tools**:
41
+
42
+ ```
43
+ build time (this package) dev time (your app)
44
+ docs/**/*.md ────┐ ┌──────────────────────────────┐
45
+ uikit/form .vue ─┼─► src/build/* ────────────────────► │ @mapomodule/mcp (Nuxt module)│
46
+ descriptor.ts │ dist/knowledge/docs.json │ · installs mcp-toolkit │
47
+ module.ts ┘ /api.json │ · injects its definitions │
48
+ │ │ · POST /mcp/mapo │
49
+ ▼ └──────────────────────────────┘
50
+ src/runtime/core/*
51
+ (specs + search + recipes)
52
+ │
53
+ └───────────────────────► bin/mapo-mcp (stdio, no server needed)
54
+ ```
55
+
56
+ 1. **Nuxt module** — auto-installed by `mapomodule` in development. It registers
57
+ [`@nuxtjs/mcp-toolkit`](https://mcp-toolkit.nuxt.dev) and injects its own tools through the
58
+ toolkit's `mcp:definitions:paths` hook, as a **named handler**. Result: a dedicated endpoint at
59
+ `POST /mcp/mapo` that does not interfere with any MCP definitions your app itself may declare
60
+ (the toolkit's default `defaultHandlerStrategy: 'orphans'` keeps them separate).
61
+ 2. **stdio CLI** (`mapo-mcp`) — the same tools, spawned directly by the IDE. Works with the dev
62
+ server down, which is exactly when you are still deciding what to build; the two live tools are
63
+ forwarded to the app when it happens to be up.
64
+
65
+ Both adapters wrap a single set of tool specs in `src/runtime/core/tools/`, so behaviour never
66
+ diverges between the two transports.
67
+
68
+ ### Why a bundled knowledge base
69
+
70
+ Everything is extracted **at package build time** into `dist/knowledge/`: `docs.json` (heading-sized
71
+ chunks plus a BM25 inverted index) and `api.json` (components, field types and composables read from
72
+ the packages' sources). That means:
73
+
74
+ - it works offline, with no API keys and no embedding service;
75
+ - the knowledge always matches the installed version of Mapo, not whatever is on the website;
76
+ - answers are _sections_, not whole files — the assistant's context stays small;
77
+ - the API surface cannot drift from the code, because it _is_ the code.
78
+
79
+ ---
80
+
81
+ ## Quick start
82
+
83
+ The module is part of `mapomodule` and turns itself on in development:
84
+
85
+ ```ts
86
+ // nuxt.config.ts
87
+ export default defineNuxtConfig({
88
+ modules: ["@nuxt/ui", "mapomodule"],
89
+ mapo: {
90
+ // ...your usual Mapo config
91
+ // mcp: false, // ← opt out entirely
92
+ // mcp: { enabled: true } // ← force it on (also outside dev)
93
+ },
94
+ });
95
+ ```
96
+
97
+ Start the app and the endpoint is live:
98
+
99
+ ```bash
100
+ pnpm dev
101
+ curl -s -X POST http://localhost:3000/mcp/mapo \
102
+ -H 'content-type: application/json' \
103
+ -H 'accept: application/json, text/event-stream' \
104
+ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
105
+ ```
106
+
107
+ The endpoint sits under the app's `app.baseURL`, like every server route: an app served under
108
+ `/backoffice/` answers at `/backoffice/mcp/mapo`, and `/mcp/mapo` redirects to the app. The
109
+ `mapo:mcp` line of the startup log prints the full URL; behind a proxy, use the address you open
110
+ the app with (for example `http://localhost/backoffice/mcp/mapo`).
111
+
112
+ For the transport-independent variant, add the package explicitly — it ships as a dependency of
113
+ `mapomodule`, and package managers only expose the binaries of **direct** dependencies:
114
+
115
+ ```bash
116
+ pnpm add -D @mapomodule/mcp@next
117
+ npx mapo-mcp serve # MCP over stdio, no dev server required
118
+ ```
119
+
120
+ Mapo v2 is published on the `next` dist-tag while it is in beta. `mapo-mcp serve` accepts
121
+ `--app <url>` (the endpoint the live tools are forwarded to), `--root <dir>` (the project root for
122
+ scaffolding, by default the working directory) and `--knowledge <dir>` (a prebuilt knowledge base
123
+ instead of the bundled one).
124
+
125
+ ---
126
+
127
+ ## Connecting your IDE
128
+
129
+ All snippets assume `pnpm add -D @mapomodule/mcp@next` has been run in the app, so `npx` resolves
130
+ `mapo-mcp` from the local `node_modules/.bin`.
131
+
132
+ ### Claude Code (`.mcp.json` in the project root)
133
+
134
+ ```json
135
+ {
136
+ "mcpServers": {
137
+ "mapo": {
138
+ "command": "npx",
139
+ "args": ["mapo-mcp", "serve"]
140
+ }
141
+ }
142
+ }
143
+ ```
144
+
145
+ ### Cursor (`.cursor/mcp.json`) / Windsurf
146
+
147
+ ```json
148
+ {
149
+ "mcpServers": {
150
+ "mapo": { "command": "npx", "args": ["mapo-mcp", "serve"] }
151
+ }
152
+ }
153
+ ```
154
+
155
+ ### VS Code (`.vscode/mcp.json`)
156
+
157
+ ```json
158
+ {
159
+ "servers": {
160
+ "mapo": { "type": "stdio", "command": "npx", "args": ["mapo-mcp", "serve"] }
161
+ }
162
+ }
163
+ ```
164
+
165
+ ### HTTP instead of stdio
166
+
167
+ If your client speaks Streamable HTTP and you keep the dev server running, point it at
168
+ `http://localhost:3000/mcp/mapo` instead, or at the URL the startup log prints when the app runs
169
+ elsewhere. That variant additionally exposes the tools that need the live app. In Claude Code:
170
+
171
+ ```json
172
+ {
173
+ "mcpServers": {
174
+ "mapo": { "type": "http", "url": "http://localhost:3000/mcp/mapo" }
175
+ }
176
+ }
177
+ ```
178
+
179
+ > **stdio vs HTTP** — stdio always works and knows the docs; HTTP additionally knows _your_ app.
180
+ > Configuring both is a perfectly reasonable setup.
181
+
182
+ ---
183
+
184
+ ## Tools
185
+
186
+ Every tool is prefixed `mapo_` so it stays unambiguous when several MCP servers are connected. All
187
+ are annotated `readOnlyHint: true` except `mapo_scaffold`, which can create files and says so — no
188
+ tool is ever `destructiveHint`, because nothing here deletes or replaces without an explicit flag.
189
+
190
+ | Tool | What it does |
191
+ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
192
+ | `mapo_search_docs` | Ranked search over the Mapo docs. Returns the matching **sections** with their `path`, `#anchor`, matched symbols and an excerpt — plus the canonical recipe when the query matches a known task. Filters: `section` (`howto`, `guide`, `uikit`, `form`, `modules`, `migration`), `pkg` (`@mapomodule/form`, `uikit`, …), `limit`. |
193
+ | `mapo_get_doc` | Returns the exact markdown of a page, or of a single section via `heading` (accepts the heading text or its anchor). Reports the page's full heading list so the assistant can narrow down, and truncates at `maxChars`. |
194
+ | `mapo_list_recipes` | The curated task → documentation map. With no argument it opens with what Mapo is and lists everything Mapo does out of the box; with `task` it returns the canonical recipe for a goal. |
195
+ | `mapo_component_api` | Props, events, slots and exposed methods of a `Mapo*` component, **extracted from its source**: real types, defaults and JSDoc. Partial names resolve (`list` → `MapoList`); `include` narrows the answer to one section. |
196
+ | `mapo_list_field_types` | The form registry: every `type` a `FieldDescriptor` accepts, the component behind it, its `attrs` with types and descriptions, the registry-level default attrs, and a skeleton descriptor to copy. |
197
+ | `mapo_composable_api` | The auto-imported composables and stores (`useCrud`, `useMapoAuth`, `useMediaStore`, …) with their real signatures, grouped by package. |
198
+ | `mapo_inspect_app` | **Live.** How Mapo is set up in the running app: installed modules and versions, public Mapo configuration, registered field types, available components, routes and locales. |
199
+ | `mapo_doctor` | **Live.** Checks the running app for known misconfigurations (module order, missing login route, untouched auth endpoints, locales without catalogs, media endpoints) and returns each problem with its fix. |
200
+ | `mapo_scaffold` | Generates pages, forms, custom fields, a login page, a theme override, a backend proxy, menu and media pages in Mapo's own patterns. A dry run unless `write: true`. See [Scaffolding](#scaffolding). |
201
+ | `mapo_backend_schema` | Reads the backend's OpenAPI/DRF schema and turns a serializer into field descriptors, with choices, required and read-only flags and the endpoint of every relation. See [From the backend schema to a page](#from-the-backend-schema-to-a-page). |
202
+
203
+ Typical sequence an assistant follows:
204
+
205
+ ```
206
+ mapo_list_recipes({ task: "editors need to reorder navigation entries" })
207
+ → "Build a navigation menu editor" → howto/menu-manager.md
208
+ mapo_get_doc({ path: "howto/menu-manager.md" })
209
+ → writes code against the real API
210
+ mapo_component_api({ name: "MapoMenuManager" })
211
+ → props and slots as the component actually declares them
212
+ ```
213
+
214
+ **Why the API tools read source, not docs**: `docs/uikit/api.md` listed 11 props for `MapoDetail`
215
+ while the component declared 17. Prose drifts; source does not.
216
+
217
+ **The two live tools need the app.** Over HTTP they answer directly. Over stdio the CLI forwards
218
+ them to `http://localhost:3000/mcp/mapo` (override with `--app` or `MAPO_MCP_APP_URL` when the
219
+ app runs on another port, behind a proxy or under an `app.baseURL`), reconnecting on every call
220
+ because the dev server routinely starts after the editor. When it is down they explain how to
221
+ bring it up instead of guessing.
222
+
223
+ ### Scaffolding
224
+
225
+ `mapo_scaffold` is the only tool that can change the project, so its contract is deliberately
226
+ narrow:
227
+
228
+ - **Dry run by default.** It returns the files; nothing touches disk until `write: true`.
229
+ - **Field types are validated against the registry.** `fields: ["title:text", "body:wysiwyg"]`
230
+ fails with the list of real types rather than emitting a descriptor that renders nothing.
231
+ - **Writing is guarded** by [`write.ts`](src/runtime/core/write.ts): development only, paths
232
+ resolved and proven to stay inside the project root (symlinks followed), and an existing file is
233
+ never replaced without `overwrite: true`. Each file reports its own outcome instead of the batch
234
+ aborting halfway.
235
+ - The generated pages are modelled on the recipes in `docs/howto/` and on the pages that actually
236
+ run in `apps/example-e2e`, and are verified end to end: a scaffolded list page renders in the
237
+ example app unmodified.
238
+
239
+ After scaffolding new pages, **restart the dev server**: Nuxt hot-reloads `routes.mjs` but the
240
+ server-side router keeps the old table, so a brand-new route 404s until it restarts.
241
+
242
+ ### From the backend schema to a page
243
+
244
+ `mapo_backend_schema` closes the last gap: the assistant knows Mapo _and_ the API this project
245
+ talks to.
246
+
247
+ ```
248
+ mapo_backend_schema({ action: "list_models" }) # what the API exposes
249
+ mapo_backend_schema({ action: "describe_model", model: "Article" })
250
+ mapo_backend_schema({ action: "to_fields", model: "Article" })
251
+ ```
252
+
253
+ The mapping is deliberate rather than mechanical:
254
+
255
+ - `enum` → `select` with readable item labels; `format: date-time` → `datetime`; `binary` → `file`;
256
+ a short `maxLength` stays a `text`, a long one becomes a `textarea`.
257
+ - A nested component becomes `fks` and an array of components becomes `m2m` — **with the real
258
+ endpoint**, found by scanning `paths` for the collection route that serves that component
259
+ (`{count, results}` pagination and bare arrays both recognised).
260
+ - `readOnly` properties are skipped, and the tool says so; `includeReadOnly: true` keeps them as
261
+ readonly descriptors.
262
+ - Anything uncertain carries an inline comment (`// no list endpoint found for Editor`) instead of
263
+ a confident guess.
264
+ - A property whose mapping is not registered in _this_ app is skipped, not emitted.
265
+
266
+ The response ends with a ready-made `mapo_scaffold` payload, so schema → descriptors → page is
267
+ three calls.
268
+
269
+ The source is `mapo.mcp.backend.schemaUrl`, `$MAPO_BACKEND_SCHEMA_URL`, or the tool's `url`
270
+ argument — an http(s) URL **or a local file**, so a team can commit an exported schema and work
271
+ offline. drf-spectacular serves YAML by default: the tool detects it and tells you to add
272
+ `?format=json`.
273
+
274
+ ## Prompts
275
+
276
+ Slash-commands in clients that support MCP prompts. Each one names the tools to call and their
277
+ order, which is the part a model improvises worst:
278
+
279
+ | Prompt | Workflow |
280
+ | ------------------- | ---------------------------------------------------------------------------------- |
281
+ | `mapo-crud-page` | inspect the app → pick field types → scaffold list + detail → check component APIs |
282
+ | `mapo-custom-field` | check no built-in type fits → read the registry contract → scaffold → implement |
283
+ | `mapo-debug-form` | doctor → inspect registered types → compare `attrs` → search the docs |
284
+ | `mapo-migrate-v1` | read the migration page → verify every symbol against the installed source |
285
+ | `mapo-theme` | pick the lightest layer: tokens → scaffold override → slots → MapoOverride |
286
+
287
+ ## Resources
288
+
289
+ Attachable context, for clients that support MCP resources:
290
+
291
+ | URI | Contents |
292
+ | ------------------------ | ----------------------------------------------------------------------------------------- |
293
+ | `mapo://overview` | How Mapo fits together: the `guide/concepts.md` page, whole. |
294
+ | `mapo://knowledge/index` | Everything this server knows: recipes, doc pages, components, field types, composables. |
295
+ | `mapo://docs/{path}` | A full documentation page. Clients can list every page. |
296
+ | `mapo://fields/{type}` | The complete contract of one field type. Clients can list every type. |
297
+ | `mapo://app/manifest` | The running app's Mapo setup — HTTP transport only, since the CLI has no app to describe. |
298
+
299
+ ### Ranking, briefly
300
+
301
+ Plain BM25 over developer documentation has a known failure mode: prop tables win on term
302
+ frequency, so "register a custom field" returns the props of `MapoFormField` instead of the
303
+ registration recipe. The ranker therefore adds:
304
+
305
+ - **light stemming** so `paginate` / `paginated` / `pagination` collapse to one term;
306
+ - **page context** — a section gets a share of the score of its sibling sections, so a page that is
307
+ broadly about the topic beats an incidental mention elsewhere;
308
+ - **title/path affinity**, ignoring generic segments (`api`, `index`, `uikit`, …);
309
+ - **a reference penalty** on props/slots/emits tables, lifted when the query is explicitly about an
310
+ API surface ("what props does MapoDetail accept");
311
+ - **at most two sections per page**, so one page cannot fill the result list.
312
+
313
+ On top of that sits the recipe layer, which is the part that actually fixes _intent_.
314
+
315
+ ---
316
+
317
+ ## Recipes
318
+
319
+ [`src/runtime/core/recipes.ts`](src/runtime/core/recipes.ts) is a curated table mapping a task to
320
+ its canonical documentation page — the thing keyword search cannot infer. Each entry has an `id`, a
321
+ `task` phrased the way a developer would ask for it, `keywords`, the target `doc` (optionally a
322
+ `heading`), `seeAlso` links and a one-line `summary`.
323
+
324
+ **This is the file to update when a feature ships.** A test verifies that every `doc`, `heading` and
325
+ `seeAlso` in the table still exists in the generated knowledge base, so a renamed page fails CI
326
+ instead of silently sending assistants to a 404.
327
+
328
+ ---
329
+
330
+ ## Configuration
331
+
332
+ ```ts
333
+ mapo: {
334
+ mcp: {
335
+ enabled: true, // default: nuxt.options.dev
336
+ backend: {
337
+ schemaUrl: "http://localhost:8000/api/schema/?format=json",
338
+ tokenEnv: "MAPO_BACKEND_TOKEN", // env var name; the value is never echoed back
339
+ },
340
+ },
341
+ }
342
+ ```
343
+
344
+ | Option | Default | Description |
345
+ | ------------------- | ------------------------- | --------------------------------------------------------------------------------------- |
346
+ | `enabled` | `nuxt.options.dev` | Register the server. It is a development tool; production builds skip it unless forced. |
347
+ | `backend.schemaUrl` | `MAPO_BACKEND_SCHEMA_URL` | OpenAPI/DRF schema used by the backend tools. |
348
+ | `backend.tokenEnv` | `"MAPO_BACKEND_TOKEN"` | Name of the env var holding the schema bearer token. |
349
+
350
+ The route is fixed at `/mcp/mapo`, under the app's `app.baseURL`: the toolkit mounts named
351
+ handlers at `/mcp/<name>`, takes the name from the handler's directory, and its own `mcp.route`
352
+ option moves only its default handler. [`src/runtime/core/endpoint.ts`](src/runtime/core/endpoint.ts)
353
+ computes the URL the startup log prints.
354
+
355
+ The module can also be used standalone (`modules: ["@mapomodule/mcp"]`, config key `mapoMcp`) if you
356
+ are not installing the `mapomodule` meta-package.
357
+
358
+ ---
359
+
360
+ ## Security model
361
+
362
+ - **Development only by default.** The module returns early unless `enabled`, which defaults to
363
+ `nuxt.options.dev`, so the route does not exist in a production build unless you force it on.
364
+ - **No secrets in responses.** The app snapshot exposes public runtime config only; private keys
365
+ appear as key names, never values. Backend credentials are read from the environment and are never
366
+ included in tool output.
367
+ - **Read-only except scaffolding.** Every tool is annotated read-only except `mapo_scaffold`, whose
368
+ writing is opt-in (`write: true`), development-only, refuses to escape the project root and never
369
+ overwrites an existing file without `overwrite: true`.
370
+ - The toolkit's `security.allowedOrigins` default is left in place, so cross-site browser clients
371
+ must present an allowed `Origin`.
372
+
373
+ ---
374
+
375
+ ## How the knowledge base is built
376
+
377
+ ```bash
378
+ pnpm --filter @mapomodule/mcp build # module + CLI, then the knowledge index
379
+ pnpm --filter @mapomodule/mcp knowledge # index only
380
+ ```
381
+
382
+ [`scripts/build-knowledge.mjs`](scripts/build-knowledge.mjs) drives the generator in
383
+ [`src/build/`](src/build/), which produces two files.
384
+
385
+ **`docs.json`** — walks `docs/**/*.md` (skipping `roadmap/`, `contributing/`, `DECISIONS.md` and the
386
+ `AGENTS.md` / `CLAUDE.md` agent manuals, which are not app-building docs),
387
+ splits each page at its H2/H3 headings — ignoring headings inside fenced code blocks — and writes
388
+ every chunk plus the inverted index. Each chunk carries its path, section, package,
389
+ VitePress-compatible anchor, the symbols it mentions (`MapoList`, `useCrud`, field types) and
390
+ whether it is API reference.
391
+
392
+ **`api.json`** — reads the packages' sources:
393
+
394
+ | Extractor | Source | Produces |
395
+ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
396
+ | [`extract-components.ts`](src/build/extract-components.ts) | `uikit` + `form` `.vue` files, via `vue-component-meta` | props, events, slots, exposed, with resolved types, defaults and JSDoc |
397
+ | [`extract-fields.ts`](src/build/extract-fields.ts) | `registry/defaults.ts` (through jiti) + `types/descriptor.ts` (TypeScript compiler API) | every field `type`, its component, its `attrs`, and the shared descriptor properties |
398
+ | [`extract-composables.ts`](src/build/extract-composables.ts) | each module's `addImports([...])` calls | the auto-imported composables with their signatures |
399
+
400
+ Each extracted symbol is cross-linked back to the doc sections that document it.
401
+
402
+ Two deliberate choices: the generator reuses the **compiled** indexer (or the TypeScript source
403
+ through jiti in stub mode) rather than reimplementing tokenisation — index and query side must
404
+ produce identical tokens or recall silently degrades — and it lives in its own bundle entry so
405
+ `vue-component-meta`, `typescript` and `jiti` never reach the runtime.
406
+
407
+ Field types are extracted from the **declared** type text, not the checker's expansion: the latter
408
+ turns `DeepKeyOf<T>` into an unreadable wall of conditional types.
409
+
410
+ `MAPO_DOCS_ROOT` overrides the docs location; `MAPO_MCP_KNOWLEDGE_DIR` overrides where the runtime
411
+ looks for the generated files.
412
+
413
+ ---
414
+
415
+ ## Development
416
+
417
+ ```bash
418
+ pnpm --filter @mapomodule/mcp build
419
+ pnpm --filter @mapomodule/mcp test # unit + real-index regressions + stdio integration
420
+ pnpm --filter @mapomodule/mcp typecheck
421
+ ```
422
+
423
+ How to add a recipe, a prompt, a resource or a tool, and what to update when Mapo changes, is in
424
+ [Working on the MCP server](https://lotrekagency.github.io/mapo-new/contributing/mcp-server).
425
+ Verification across the monorepo is in
426
+ [Testing and verification](https://lotrekagency.github.io/mapo-new/contributing/testing).
427
+
428
+ What the server says about Mapo has two sources: the instructions in
429
+ [`src/runtime/core/instructions.ts`](src/runtime/core/instructions.ts), shared by both transports,
430
+ and the [Concepts](https://lotrekagency.github.io/mapo-new/guide/concepts) page, served as
431
+ `mapo://overview`.
432
+
433
+ Tools return markdown on purpose: assistants read it directly, and it costs fewer tokens than JSON
434
+ wrapped in prose.
435
+
436
+ ### Layout
437
+
438
+ ```
439
+ bin/mapo-mcp.mjs # the CLI entry point
440
+ scripts/
441
+ ├── build-knowledge.mjs # drives src/build → dist/knowledge/
442
+ └── clean-handler-dts.mjs # strips .d.ts files from the handler folder after the build
443
+ src/
444
+ ├── module.ts # Nuxt module: toolkit install, definition injection, app snapshot
445
+ ├── cli.ts # citty CLI → MCP over stdio
446
+ ├── index.ts # public types
447
+ ├── build/ # build-time only: docs indexing + source extraction
448
+ │ ├── index.ts # orchestrator → dist/knowledge/{docs,api}.json
449
+ │ ├── extract-components.ts # vue-component-meta
450
+ │ ├── extract-fields.ts # registry + descriptor interfaces
451
+ │ └── extract-composables.ts # addImports declarations
452
+ └── runtime/
453
+ ├── core/ # transport-agnostic: instructions, overview, knowledge loader,
454
+ │ # tokenizer, indexer, search, recipes, prompts, resources,
455
+ │ # doctor, openapi + schema source, endpoint URL, scaffold/,
456
+ │ # write guard, tool specs (tools/)
457
+ ├── nitro/ # server-side adapters
458
+ │ ├── context.ts # reads the build-time context virtual module
459
+ │ ├── to-mcp-tool.ts # spec → defineMcpTool
460
+ │ └── to-mcp-prompt.ts # spec → defineMcpPrompt
461
+ ├── mcp/handlers/mapo/ # the named handler with its tools, resources and prompts
462
+ └── types/ # virtual module declarations
463
+ ```
464
+
465
+ > `runtime/mcp/` must contain **nothing but** `handlers/`. The toolkit treats every top-level file
466
+ > of a scanned path as a handler definition, so a helper module placed there is loaded as a handler
467
+ > and breaks the Nitro build.
468
+
469
+ ---
470
+
471
+ ## Troubleshooting
472
+
473
+ **`POST /mcp/mapo` returns 404**
474
+ The module only registers in development. Check that the dev server is running, that
475
+ `mapo.mcp` is not `false`, and that the startup log contains the `mapo:mcp` line announcing the
476
+ endpoint.
477
+
478
+ **`POST /mcp/mapo` redirects, or the live tools say the app is not answering**
479
+ Clients follow the redirect as a GET and report `Method not allowed. Use POST for MCP requests.`
480
+ The app has an `app.baseURL` or runs behind a proxy, so the handler answers below the base URL.
481
+ Use the URL of the `mapo:mcp` startup line (for example `http://localhost/backoffice/mcp/mapo`)
482
+ as the HTTP `url`, or pass it to the stdio CLI with `--app` or `MAPO_MCP_APP_URL`.
483
+
484
+ **"Mapo knowledge base not found"**
485
+ The index was not generated. Run `pnpm --filter @mapomodule/mcp build`. Inside a consumer project
486
+ this cannot happen — the index ships in the published tarball.
487
+
488
+ **Search returns reference tables instead of a how-to**
489
+ Phrase the query as a task ("how do I …") rather than as a symbol; the ranker demotes prop tables
490
+ for task-shaped queries. If a task deserves a canonical answer, add it to `recipes.ts`.
491
+
492
+ **The assistant still invents props**
493
+ Make sure the client actually loaded the server (`tools/list` should show the `mapo_*` tools) and
494
+ that the handler `instructions` reached it — some clients ignore them, in which case a short project
495
+ rule ("always check Mapo docs with the mapo\_\* tools") does the job.
496
+
497
+ **A component is missing from `mapo_component_api`**
498
+ The build logs `skipped <Name>` when `vue-component-meta` cannot resolve a component. Only `Mapo*`
499
+ components under `src/runtime/components/` of `uikit` and `form` are extracted.
500
+
501
+ ---
502
+
503
+ ## Status
504
+
505
+ Shipped: documentation search with curated recipes, page retrieval, component/field/composable APIs
506
+ extracted from source, live app introspection and diagnostics, guarded scaffolding, backend schema
507
+ mapping, MCP resources and prompts, the dev-only Nuxt module with its namespaced handler, and the
508
+ stdio CLI with transparent forwarding of the live tools.
509
+
510
+ Planned: `mapo-mcp install` / Agent Skill / MCP App inspector.
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ // Thin shim so the published bin never depends on the bundler preserving a shebang.
3
+ import "../dist/cli.mjs";
@@ -0,0 +1,18 @@
1
+ import { DocsKnowledge, ApiKnowledge } from '../dist/runtime/core/types.js';
2
+
3
+ declare const DOCS_FILE = "docs.json";
4
+ declare const API_FILE = "api.json";
5
+ interface BuildKnowledgeOptions {
6
+ docsRoot: string;
7
+ repoRoot: string;
8
+ outDir: string;
9
+ }
10
+ interface BuildKnowledgeResult {
11
+ docs: DocsKnowledge;
12
+ api: ApiKnowledge;
13
+ }
14
+ /** Generates `docs.json` and `api.json` into `outDir`. */
15
+ declare function buildKnowledge({ docsRoot, repoRoot, outDir, }: BuildKnowledgeOptions): Promise<BuildKnowledgeResult>;
16
+
17
+ export { API_FILE, DOCS_FILE, buildKnowledge };
18
+ export type { BuildKnowledgeOptions, BuildKnowledgeResult };
@@ -0,0 +1,18 @@
1
+ import { DocsKnowledge, ApiKnowledge } from '../dist/runtime/core/types.js';
2
+
3
+ declare const DOCS_FILE = "docs.json";
4
+ declare const API_FILE = "api.json";
5
+ interface BuildKnowledgeOptions {
6
+ docsRoot: string;
7
+ repoRoot: string;
8
+ outDir: string;
9
+ }
10
+ interface BuildKnowledgeResult {
11
+ docs: DocsKnowledge;
12
+ api: ApiKnowledge;
13
+ }
14
+ /** Generates `docs.json` and `api.json` into `outDir`. */
15
+ declare function buildKnowledge({ docsRoot, repoRoot, outDir, }: BuildKnowledgeOptions): Promise<BuildKnowledgeResult>;
16
+
17
+ export { API_FILE, DOCS_FILE, buildKnowledge };
18
+ export type { BuildKnowledgeOptions, BuildKnowledgeResult };