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

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