@mapomodule/mcp 1.0.0-beta.3 → 1.0.0-experimental.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 (50) hide show
  1. package/README.md +26 -24
  2. package/dist/build.mjs +66 -4
  3. package/dist/cli.mjs +8 -1
  4. package/dist/knowledge/api.json +1 -1
  5. package/dist/knowledge/docs.json +1 -1
  6. package/dist/module.json +1 -1
  7. package/dist/runtime/core/ai-setup/catalog.d.ts +0 -0
  8. package/dist/runtime/core/ai-setup/catalog.js +428 -0
  9. package/dist/runtime/core/ai-setup/index.d.ts +0 -0
  10. package/dist/runtime/core/ai-setup/index.js +20 -0
  11. package/dist/runtime/core/ai-setup/plan.d.ts +0 -0
  12. package/dist/runtime/core/ai-setup/plan.js +642 -0
  13. package/dist/runtime/core/ai-setup/questions.d.ts +0 -0
  14. package/dist/runtime/core/ai-setup/questions.js +237 -0
  15. package/dist/runtime/core/indexer.js +10 -3
  16. package/dist/runtime/core/instructions.js +3 -2
  17. package/dist/runtime/core/prompts.js +25 -1
  18. package/dist/runtime/core/recipes.js +407 -3
  19. package/dist/runtime/core/search.js +2 -1
  20. package/dist/runtime/core/tools/ai.d.ts +0 -0
  21. package/dist/runtime/core/tools/ai.js +125 -0
  22. package/dist/runtime/core/tools/api.js +7 -1
  23. package/dist/runtime/mcp/handlers/mapo/prompts/ai-setup.js +3 -0
  24. package/dist/runtime/mcp/handlers/mapo/tools/ai-setup.js +3 -0
  25. package/package.json +1 -1
  26. package/src/__tests__/aiSetup.test.ts +330 -0
  27. package/src/__tests__/cli.test.ts +1 -0
  28. package/src/__tests__/composables.test.ts +95 -0
  29. package/src/__tests__/indexer.test.ts +19 -0
  30. package/src/__tests__/knowledge.test.ts +48 -0
  31. package/src/__tests__/overview.test.ts +11 -0
  32. package/src/__tests__/recipes.test.ts +83 -0
  33. package/src/__tests__/search.test.ts +16 -0
  34. package/src/__tests__/tools.test.ts +27 -1
  35. package/src/build/extract-components.ts +33 -5
  36. package/src/build/extract-composables.ts +65 -2
  37. package/src/cli.ts +8 -1
  38. package/src/runtime/core/ai-setup/catalog.ts +492 -0
  39. package/src/runtime/core/ai-setup/index.ts +29 -0
  40. package/src/runtime/core/ai-setup/plan.ts +710 -0
  41. package/src/runtime/core/ai-setup/questions.ts +290 -0
  42. package/src/runtime/core/indexer.ts +16 -4
  43. package/src/runtime/core/instructions.ts +3 -2
  44. package/src/runtime/core/prompts.ts +28 -0
  45. package/src/runtime/core/recipes.ts +428 -3
  46. package/src/runtime/core/search.ts +4 -1
  47. package/src/runtime/core/tools/ai.ts +209 -0
  48. package/src/runtime/core/tools/api.ts +8 -0
  49. package/src/runtime/mcp/handlers/mapo/prompts/ai-setup.ts +4 -0
  50. package/src/runtime/mcp/handlers/mapo/tools/ai-setup.ts +4 -0
package/README.md CHANGED
@@ -184,21 +184,22 @@ elsewhere. That variant additionally exposes the tools that need the live app. I
184
184
  ## Tools
185
185
 
186
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
187
+ are annotated `readOnlyHint: true` except `mapo_scaffold` and `mapo_ai_setup`, which can create files and say so — no
188
188
  tool is ever `destructiveHint`, because nothing here deletes or replaces without an explicit flag.
189
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). |
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
+ | `mapo_ai_setup` | Guides turning on `@mapomodule/ai` and Magic Fill. With no answers it returns the questions to ask the developer, in rounds, every need the module can meet and everything it offers; with the answers, whether the module can do what they need, the `mapo.ai` configuration, the environment variables (names only), where each call's key comes from and how to keep the tokens and their cost in check, the forms' options, the server plugins and the checks. A dry run unless `write: true`; never edits `nuxt.config.ts`, never writes a key. |
202
203
 
203
204
  Typical sequence an assistant follows:
204
205
 
@@ -222,8 +223,8 @@ bring it up instead of guessing.
222
223
 
223
224
  ### Scaffolding
224
225
 
225
- `mapo_scaffold` is the only tool that can change the project, so its contract is deliberately
226
- narrow:
226
+ `mapo_scaffold` can change the project, as `mapo_ai_setup` can for the AI's server plugins through the same
227
+ guard, so its contract is deliberately narrow:
227
228
 
228
229
  - **Dry run by default.** It returns the files; nothing touches disk until `write: true`.
229
230
  - **Field types are validated against the registry.** `fields: ["title:text", "body:wysiwyg"]`
@@ -276,13 +277,14 @@ offline. drf-spectacular serves YAML by default: the tool detects it and tells y
276
277
  Slash-commands in clients that support MCP prompts. Each one names the tools to call and their
277
278
  order, which is the part a model improvises worst:
278
279
 
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 |
280
+ | Prompt | Workflow |
281
+ | ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
282
+ | `mapo-crud-page` | inspect the app → pick field types → scaffold list + detail → check component APIs |
283
+ | `mapo-custom-field` | check no built-in type fits → read the registry contract → scaffold → implement |
284
+ | `mapo-debug-form` | doctor → inspect registered types → compare `attrs` → search the docs |
285
+ | `mapo-migrate-v1` | read the migration page → verify every symbol against the installed source |
286
+ | `mapo-theme` | pick the lightest layer: tokens → scaffold override → slots → MapoOverride |
287
+ | `mapo-ai-setup` | inspect the app → ask what the AI is for, in rounds → say what the module can do → plan → write the plugins after the OK |
286
288
 
287
289
  ## Resources
288
290
 
@@ -364,7 +366,7 @@ are not installing the `mapomodule` meta-package.
364
366
  - **No secrets in responses.** The app snapshot exposes public runtime config only; private keys
365
367
  appear as key names, never values. Backend credentials are read from the environment and are never
366
368
  included in tool output.
367
- - **Read-only except scaffolding.** Every tool is annotated read-only except `mapo_scaffold`, whose
369
+ - **Read-only except scaffolding.** Every tool is annotated read-only except `mapo_scaffold` and `mapo_ai_setup`, whose
368
370
  writing is opt-in (`write: true`), development-only, refuses to escape the project root and never
369
371
  overwrites an existing file without `overwrite: true`.
370
372
  - The toolkit's `security.allowedOrigins` default is left in place, so cross-site browser clients
@@ -496,7 +498,7 @@ rule ("always check Mapo docs with the mapo\_\* tools") does the job.
496
498
 
497
499
  **A component is missing from `mapo_component_api`**
498
500
  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.
501
+ components under `src/runtime/components/` of `uikit` and `form` are extracted, and the ones `@mapomodule/ai` registers for apps (its settings page and Magic Fill's parts).
500
502
 
501
503
  ---
502
504
 
package/dist/build.mjs CHANGED
@@ -8,7 +8,18 @@ import { pathToFileURL } from 'node:url';
8
8
 
9
9
  const COMPONENT_PACKAGES = [
10
10
  { pkg: "@mapomodule/uikit", dir: "packages/@mapomodule/uikit" },
11
- { pkg: "@mapomodule/form", dir: "packages/@mapomodule/form" }
11
+ { pkg: "@mapomodule/form", dir: "packages/@mapomodule/form" },
12
+ {
13
+ pkg: "@mapomodule/ai",
14
+ dir: "packages/@mapomodule/ai",
15
+ only: [
16
+ "MapoAiSettings",
17
+ "MapoAiMagicFillAction",
18
+ "MapoAiMagicFillBanner",
19
+ "MapoAiMagicFillPanel",
20
+ "MapoAiMagicFillPreview"
21
+ ]
22
+ }
12
23
  ];
13
24
  const MAX_TYPE_LENGTH$1 = 160;
14
25
  function shortenType(type) {
@@ -44,12 +55,15 @@ function toMembers(entries, withType = true) {
44
55
  }
45
56
  function extractComponents(repoRoot, docsFor) {
46
57
  const components = [];
47
- for (const { pkg, dir } of COMPONENT_PACKAGES) {
58
+ for (const { pkg, dir, only } of COMPONENT_PACKAGES) {
48
59
  const packageRoot = join(repoRoot, dir);
49
60
  const tsconfig = join(packageRoot, "tsconfig.json");
50
61
  const componentsRoot = join(packageRoot, "src", "runtime", "components");
62
+ const isListed = (file) => !only || only.includes(
63
+ file.split("/").pop().replace(/\.vue$/, "")
64
+ );
51
65
  const files = collectVueFiles(componentsRoot).filter(
52
- (file) => /\/Mapo[A-Z][^/]*\.vue$/.test(file)
66
+ (file) => /\/Mapo[A-Z][^/]*\.vue$/.test(file) && isListed(file)
53
67
  );
54
68
  if (!files.length || !existsSync(tsconfig)) continue;
55
69
  const checker = createChecker(tsconfig, {
@@ -90,6 +104,51 @@ function shorten$1(value) {
90
104
  const collapsed = value.replace(/\s+/g, " ").trim();
91
105
  return collapsed.length > MAX_SIGNATURE_LENGTH ? `${collapsed.slice(0, MAX_SIGNATURE_LENGTH)}\u2026` : collapsed;
92
106
  }
107
+ function addImportsArguments(source) {
108
+ const calls = [];
109
+ for (const match of source.matchAll(/\baddImports\s*\(/g)) {
110
+ const start = (match.index ?? 0) + match[0].length;
111
+ calls.push(source.slice(start, closingParenthesis(source, start)));
112
+ }
113
+ return calls;
114
+ }
115
+ function closingParenthesis(source, from) {
116
+ let depth = 1;
117
+ let at = from;
118
+ while (at < source.length) {
119
+ const char = source[at];
120
+ const next = source[at + 1];
121
+ if (char === '"' || char === "'" || char === "`") {
122
+ at = afterString(source, at, char);
123
+ continue;
124
+ }
125
+ if (char === "/" && next === "/") {
126
+ const end = source.indexOf("\n", at);
127
+ at = end === -1 ? source.length : end;
128
+ continue;
129
+ }
130
+ if (char === "/" && next === "*") {
131
+ const end = source.indexOf("*/", at + 2);
132
+ at = end === -1 ? source.length : end + 2;
133
+ continue;
134
+ }
135
+ if (char === "(") depth++;
136
+ if (char === ")") depth--;
137
+ if (depth === 0) return at;
138
+ at++;
139
+ }
140
+ return source.length;
141
+ }
142
+ function afterString(source, at, quote) {
143
+ let index = at + 1;
144
+ while (index < source.length) {
145
+ const char = source[index];
146
+ if (char === "\\") index += 2;
147
+ else if (char === quote) return index + 1;
148
+ else index++;
149
+ }
150
+ return source.length;
151
+ }
93
152
  function collectCandidates(repoRoot) {
94
153
  const packagesDir = join(repoRoot, PACKAGES_ROOT);
95
154
  if (!existsSync(packagesDir)) return [];
@@ -100,7 +159,10 @@ function collectCandidates(repoRoot) {
100
159
  if (!existsSync(moduleFile)) continue;
101
160
  const source = readFileSync(moduleFile, "utf-8");
102
161
  const packageRoot = join(packagesDir, entry.name);
103
- for (const match of source.matchAll(ADD_IMPORT_ENTRY)) {
162
+ const entries = addImportsArguments(source).flatMap((call) => [
163
+ ...call.matchAll(ADD_IMPORT_ENTRY)
164
+ ]);
165
+ for (const match of entries) {
104
166
  const [, name, from] = match;
105
167
  if (!name || !from) continue;
106
168
  const base = join(packageRoot, "src", from.replace(/^\.\//, ""));
package/dist/cli.mjs CHANGED
@@ -13,6 +13,7 @@ import { appTools } from '../dist/runtime/core/tools/app.js';
13
13
  import { docsTools } from '../dist/runtime/core/tools/docs.js';
14
14
  import { scaffoldTools } from '../dist/runtime/core/tools/scaffold.js';
15
15
  import { backendTools } from '../dist/runtime/core/tools/backend.js';
16
+ import { aiTools } from '../dist/runtime/core/tools/ai.js';
16
17
  import { PROMPTS } from '../dist/runtime/core/prompts.js';
17
18
  import { resolveKnowledgeDir, loadApiKnowledge, loadDocsKnowledge } from '../dist/runtime/core/knowledge.js';
18
19
 
@@ -28,7 +29,13 @@ function readVersion() {
28
29
  }
29
30
  const DEFAULT_APP_URL = mcpEndpointUrl("http://localhost:3000");
30
31
  function staticTools() {
31
- return [...docsTools, ...apiTools, ...scaffoldTools, ...backendTools];
32
+ return [
33
+ ...docsTools,
34
+ ...apiTools,
35
+ ...scaffoldTools,
36
+ ...backendTools,
37
+ ...aiTools
38
+ ];
32
39
  }
33
40
  function createToolContext(knowledgeDir, rootDir, schemaUrl = null) {
34
41
  let docs = null;