@mapomodule/mcp 1.0.0-beta.2 → 1.0.0-experimental.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 (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 +411 -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 +640 -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 +408 -4
  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 +69 -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 +475 -0
  39. package/src/runtime/core/ai-setup/index.ts +29 -0
  40. package/src/runtime/core/ai-setup/plan.ts +706 -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 +429 -4
  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
@@ -0,0 +1,237 @@
1
+ export const AI_ROUNDS = {
2
+ 1: "What the AI is for",
3
+ 2: "Models, keys and people",
4
+ 3: "Tokens, forms and production"
5
+ };
6
+ export const AI_QUESTIONS = [
7
+ {
8
+ id: "task",
9
+ round: 1,
10
+ question: "What should the AI do for the operators?",
11
+ why: "It decides between Magic Fill, which works out of the box, and a page of the app that calls the gateway.",
12
+ fills: ["need", "wants"],
13
+ options: [
14
+ {
15
+ label: "Fill the record they are editing",
16
+ detail: "From a text or files, on every detail page: Magic Fill. The operator checks every value before saving.",
17
+ pass: 'wants: ["fill-record"]',
18
+ recommended: true
19
+ },
20
+ {
21
+ label: "Create several records from one source",
22
+ detail: 'A programme, a sheet: a page of the app calls `run` with `task: "extract"`. Mapo has no import page of its own yet.',
23
+ pass: 'wants: ["extract-records"]'
24
+ },
25
+ {
26
+ label: "Something else",
27
+ detail: "Write the need in `need`, and map it to the needs of the catalog (`wants`): the plan says what the module can and cannot do.",
28
+ pass: "need: <their words>"
29
+ }
30
+ ],
31
+ several: true
32
+ },
33
+ {
34
+ id: "sources",
35
+ round: 1,
36
+ question: "What do the operators start from?",
37
+ why: "The gateway reads text formats today; PDFs and images are not read yet.",
38
+ fills: ["wants", "ownFormat"],
39
+ options: [
40
+ {
41
+ label: "Texts, web pages, Markdown, CSV, Excel, JSON",
42
+ detail: "Mapo reads them all: pasted or attached in Magic Fill's panel.",
43
+ pass: 'wants: ["files"]',
44
+ recommended: true
45
+ },
46
+ {
47
+ label: "PDFs, scans or images",
48
+ detail: "Not yet in Mapo. A reader of the app can turn them into text meanwhile, with a library the app installs.",
49
+ pass: 'wants: ["pdf-images"]'
50
+ },
51
+ {
52
+ label: "A format of the app's own",
53
+ detail: "A calendar, an export: a reader of the app, in a Nitro plugin. Give its file extension.",
54
+ pass: 'wants: ["own-format"], ownFormat: "ics"'
55
+ }
56
+ ],
57
+ several: true
58
+ },
59
+ {
60
+ id: "data",
61
+ round: 1,
62
+ question: "May the records and their sources go to a cloud provider?",
63
+ why: "A cloud model sees what the operator sends; a model on the company's servers keeps it inside. Ask whoever answers for the data, not only the developer.",
64
+ fills: ["dataMayLeave"],
65
+ options: [
66
+ {
67
+ label: "Yes, to a provider we have a contract with",
68
+ detail: "OpenAI or Anthropic, with the region the contract gives.",
69
+ pass: "dataMayLeave: true"
70
+ },
71
+ {
72
+ label: "No, they stay on our servers",
73
+ detail: "Ollama, or a server that speaks OpenAI's API (LM Studio, vLLM, llama.cpp), at an address of the app's network. No key, no cost per token; the hardware decides the speed.",
74
+ pass: "dataMayLeave: false"
75
+ },
76
+ {
77
+ label: "Not sure yet",
78
+ detail: "Start with the mock in development, which sends nothing anywhere, and decide before production.",
79
+ pass: 'providers: ["mock"]'
80
+ }
81
+ ]
82
+ },
83
+ {
84
+ id: "providers",
85
+ round: 2,
86
+ question: "Which models?",
87
+ why: "Each provider is enabled in `mapo.ai.providers`; the operators pick among the models it lists, within what the admins give them.",
88
+ fills: ["providers"],
89
+ options: [
90
+ {
91
+ label: "OpenAI or Anthropic",
92
+ detail: "The best extraction; costs per token. Their efficient models are enough for most forms.",
93
+ pass: 'providers: ["openai"] or ["anthropic"], or both',
94
+ recommended: true
95
+ },
96
+ {
97
+ label: "Ollama or an OpenAI-compatible server",
98
+ detail: "Models on the company's servers: free per token, slower on modest hardware, weaker on large forms.",
99
+ pass: 'providers: ["ollama"] or ["openai-compatible"]'
100
+ },
101
+ {
102
+ label: "Another AI service",
103
+ detail: "A provider of the app's own, registered in a Nitro plugin.",
104
+ pass: 'providers: ["own"]'
105
+ }
106
+ ],
107
+ several: true
108
+ },
109
+ {
110
+ id: "keys",
111
+ round: 2,
112
+ question: "Who holds the keys, and who pays for the tokens?",
113
+ why: "A call uses the key nearest its user: their own token where allowed, else the admins' assignment to them, their group or everyone, else the project's key.",
114
+ fills: ["keys"],
115
+ options: [
116
+ {
117
+ label: "One project key",
118
+ detail: "In the server's environment, never in `nuxt.config.ts`. The simplest start: one bill.",
119
+ pass: 'keys: ["project"]',
120
+ recommended: true
121
+ },
122
+ {
123
+ label: "Keys per team, assigned by the AI's admins",
124
+ detail: "On the AI settings page, without a deploy: a key and the models for everyone, a group or a user.",
125
+ pass: 'keys: ["assigned"]'
126
+ },
127
+ {
128
+ label: "Each operator's own token",
129
+ detail: "Allowed by an assignment; each user saves theirs on the AI settings page and pays for their calls.",
130
+ pass: 'keys: ["personal"]'
131
+ }
132
+ ],
133
+ several: true
134
+ },
135
+ {
136
+ id: "people",
137
+ round: 2,
138
+ question: "Who may use the AI, and who administers it?",
139
+ why: "The gateway asks the backend who is signed in; a rule that cannot be read lets fewer users in, never more.",
140
+ fills: ["userGroups", "userPermissions", "allowedFlag", "adminGroups"],
141
+ options: [
142
+ {
143
+ label: "Every signed-in user; superusers administer",
144
+ detail: "The defaults: nothing to configure.",
145
+ pass: "",
146
+ recommended: true
147
+ },
148
+ {
149
+ label: "Some groups or permissions",
150
+ detail: "`mapo.ai.users` and `mapo.ai.admin`, by the groups or permissions the backend gives.",
151
+ pass: 'userGroups: ["editors"], adminGroups: ["ai-admins"]'
152
+ },
153
+ {
154
+ label: "A rule of the backend",
155
+ detail: "Such as internal accounts only: a field of the user the backend returns, checked by a `mapo-ai:user` hook.",
156
+ pass: 'allowedFlag: "is_internal"'
157
+ }
158
+ ],
159
+ several: true
160
+ },
161
+ {
162
+ id: "tokens",
163
+ round: 3,
164
+ question: "How do you keep the tokens and their cost in check?",
165
+ why: "Every call is audited with its tokens; a price per model turns them into money. The form's size, the source's length and the model decide what a call costs.",
166
+ fills: ["costs", "perUserPerMinute"],
167
+ options: [
168
+ {
169
+ label: "Watch the usage, with costs",
170
+ detail: "The usage by user, model and day on the AI settings page, in money once `mapo.ai.prices` prices the models.",
171
+ pass: "costs: true",
172
+ recommended: true
173
+ },
174
+ {
175
+ label: "Also cap the calls per user",
176
+ detail: "`mapo.ai.limits.perUserPerMinute`, 20 by default, counted by each server process.",
177
+ pass: "perUserPerMinute: 10"
178
+ },
179
+ {
180
+ label: "Tokens only",
181
+ detail: "The usage in tokens, without prices.",
182
+ pass: "costs: false"
183
+ }
184
+ ],
185
+ several: true
186
+ },
187
+ {
188
+ id: "forms",
189
+ round: 3,
190
+ question: "Where does Magic Fill show, and what must the AI never see?",
191
+ why: "Magic Fill is on every detail page by default. Fields named as secrets, read-only fields and media never reach the AI; others are kept out with `ai: { exclude: true }`. Rules the AI must always follow, such as the city or the tone, go in `instructions`.",
192
+ fills: ["magicFill", "instructions", "wants"],
193
+ options: [
194
+ {
195
+ label: "On every detail page",
196
+ detail: "Nothing to configure; a field's `ai` option keeps it out, guides the model or keeps a relation's names from the provider.",
197
+ pass: 'magicFill: "every-page"',
198
+ recommended: true
199
+ },
200
+ {
201
+ label: "Not on some pages",
202
+ detail: "`definePageMeta({ magicFill: false })` on those pages.",
203
+ pass: 'magicFill: "some-pages"'
204
+ },
205
+ {
206
+ label: "A panel of our own instead",
207
+ detail: "`mapo.ai.magicFill: false`, and `useMapoAiFill()` in a detail extension of the app.",
208
+ pass: 'magicFill: "own-panel"'
209
+ }
210
+ ]
211
+ },
212
+ {
213
+ id: "deploy",
214
+ round: 3,
215
+ question: "Where does the server run in production?",
216
+ why: "The keys, tokens, settings and audit are sealed in the Nitro storage `mapo-ai`: they need a place that lasts, shared by every instance, and the same secret everywhere.",
217
+ fills: ["deploy"],
218
+ options: [
219
+ {
220
+ label: "One Node server with a lasting disk",
221
+ detail: "The module's default: `.data/mapo-ai` on the server; a persistent volume in a container.",
222
+ pass: 'deploy: "single-node"',
223
+ recommended: true
224
+ },
225
+ {
226
+ label: "Several instances or containers",
227
+ detail: "One shared store, such as Redis, and the same secret on all of them.",
228
+ pass: 'deploy: "several-instances"'
229
+ },
230
+ {
231
+ label: "Serverless or edge",
232
+ detail: "A function's file system does not last: mount a driver, Redis on functions that run Node, one that works over HTTP (Upstash, Cloudflare KV) on an edge runtime.",
233
+ pass: 'deploy: "serverless"'
234
+ }
235
+ ]
236
+ }
237
+ ];
@@ -152,7 +152,7 @@ export function chunkMarkdown(path, markdown) {
152
152
  return chunks;
153
153
  }
154
154
  export function buildIndex(chunks) {
155
- const terms = {};
155
+ const postingsByTerm = /* @__PURE__ */ new Map();
156
156
  const lengths = [];
157
157
  chunks.forEach((chunk, chunkIndex) => {
158
158
  const counts = /* @__PURE__ */ new Map();
@@ -167,14 +167,21 @@ export function buildIndex(chunks) {
167
167
  add(chunk.tags.join(" "), BOOST.tags);
168
168
  let length = 0;
169
169
  for (const [term, frequency] of counts) {
170
- (terms[term] ??= []).push([chunkIndex, frequency]);
170
+ const postings = postingsByTerm.get(term) ?? [];
171
+ postings.push([chunkIndex, frequency]);
172
+ postingsByTerm.set(term, postings);
171
173
  length += frequency;
172
174
  }
173
175
  lengths.push(length);
174
176
  });
175
177
  const total = chunks.length;
176
178
  const avgLength = total ? lengths.reduce((a, b) => a + b, 0) / total : 0;
177
- return { terms, lengths, avgLength, total };
179
+ return {
180
+ terms: Object.fromEntries(postingsByTerm),
181
+ lengths,
182
+ avgLength,
183
+ total
184
+ };
178
185
  }
179
186
  export function buildDocsKnowledge(docsRoot) {
180
187
  const files = collectMarkdownFiles(docsRoot);
@@ -1,4 +1,4 @@
1
- export const MAPO_INSTRUCTIONS = `Mapo v2 is a Nuxt 4 admin framework (Vue 3, Nuxt UI v4, Pinia, @nuxtjs/i18n) for building backoffices on a REST API that follows Django REST Framework conventions. An app registers "@nuxt/ui" and then "mapomodule", and configures everything under the \`mapo\` key. The packages: @mapomodule/core ($mapoFetch, useCrud, useMapoAuth, the auth/permissions/roles middleware), store (Pinia stores), uikit (layouts, sidebar, MapoList, MapoDetail, media and menu managers, theming, MapoOverride), form (FieldDescriptor arrays rendered through a field registry, useMapoForm), i18n and utils. A page is declarative: definePageMeta (layout, middleware, label, icon, permissions) plus one Mapo component with props; the sidebar is built from route metadata. Mapo v2 is a rewrite of v1 (Nuxt 2, Vuex, Axios): v1 APIs do not exist here.
1
+ export const MAPO_INSTRUCTIONS = `Mapo v2 is a Nuxt 4 admin framework (Vue 3, Nuxt UI v4, Pinia, @nuxtjs/i18n) for building backoffices on a REST API that follows Django REST Framework conventions. An app registers "@nuxt/ui" and then "mapomodule", and configures everything under the \`mapo\` key. The packages: @mapomodule/core ($mapoFetch, useCrud, useMapoAuth, the auth/permissions/roles middleware), store (Pinia stores), uikit (layouts, sidebar, MapoList, MapoDetail, media and menu managers, theming, MapoOverride), form (FieldDescriptor arrays rendered through a field registry, useMapoForm), i18n and utils; ai is experimental, published on npm's \`experimental\` dist-tag only (\`pnpm add mapomodule@experimental\`), and opt-in with \`mapo.ai\` (AI-assisted data entry: today the AI gateway, for signed-in users only: \`status\`; \`read\`, which reads a file (text, Markdown, JSON, HTML, CSV, XLSX) into the text \`run\` takes, with readers the app can replace (registerMapoAiReader() in a Nitro plugin, the \`mapo-ai:read\` hook, \`mapo.ai.readers\` to turn a format off); and \`run\`, which asks a provider to fill a record or to extract the records of a source and answers one checked outcome per field; \`mapo.ai.providers\` enables the providers: Mapo's mock, \`openai\` and \`anthropic\` (OpenAI's and Anthropic's models, with the project's key in the environment: NUXT_MAPO_AI_PROVIDERS_OPENAI_API_KEY, NUXT_MAPO_AI_PROVIDERS_ANTHROPIC_API_KEY), \`ollama\` and \`openai-compatible\` (models on the app's own servers, at the \`baseURL\` the app sets, with their key in the environment), or one the app registers with registerMapoAiProvider() in a Nitro plugin; each call uses the key nearest the user: their own token where an admin allows it, a key the AI's admins assign to them, a group or everyone (/_mapo/ai/keys, which also narrows the models), or the project's, and \`status\` says the level, never the key; an AI settings page (/ai-settings, or <MapoAiSettings /> in a page of the app) lets each user pick their provider and model and check the connection, and the AI's admins assign keys and change how the AI works (instructions, verification rules, secret fields, prompt cache, Anthropic's fallbacks, models added where the app sets adminModels), and read the usage summed from the audit, with costs where mapo.ai.prices prices the models; \`mapo.ai.admin\` and \`mapo.ai.users\` say who administers and who may use the AI; its encrypted storage is sealed with the NUXT_MAPO_AI_SECRET environment variable, which \`run\` needs in production; Magic Fill is on every MapoDetail (a button in the sidebar card opens a panel: a text or files, the operator's instructions, "What I send to the AI" from \`run/preview\`, the model; a banner above the form follows the call, with Cancel, sums up the session (applied, kept, changed by the operator, waiting, already in the record), with Undo all, and previews the values that wait, to fill, to replace (before and after) or without proof, with a tick each (a list's items one by one, added after the record's own) and Apply selected, and takes the operator to each field that waits with Next to check), and \`mapo.ai.magicFill: false\` or definePageMeta({ magicFill: false }) turns it off; a field's descriptor guides the AI with \`ai\` (\`hint\`, \`exclude\`, and \`list: false\` to keep a relation's records from the provider), as \`x-mapo-ai\` does in a backend's schema; underneath, in a detail extension, useMapoAiFill() fills the form through \`run\`, looking up the related records the AI names with the operator's session (a short list to pick from, or a search by name), writing each value a quote verifies into an empty field and marking the others for the operator, in one session across answers that undo() or a save ends, and useMapoAiRead() sends a file to \`read\`). A page is declarative: definePageMeta (layout, middleware, label, icon, permissions) plus one Mapo component with props; the sidebar is built from route metadata. Mapo v2 is a rewrite of v1 (Nuxt 2, Vuex, Axios): v1 APIs do not exist here.
2
2
 
3
3
  Workflow:
4
4
  1. New to the project or the task? Read the overview: the mapo://overview resource, or mapo_get_doc({ path: "guide/concepts.md" }).
@@ -7,4 +7,5 @@ Workflow:
7
7
  4. Use mapo_search_docs for anything the recipes do not cover, then mapo_get_doc to read the exact section. Prefer these over recalling Mapo APIs from memory.
8
8
  5. Never invent component props, slots or field types: look them up with mapo_component_api, mapo_list_field_types and mapo_composable_api, which read the installed source.
9
9
  6. mapo_backend_schema maps the backend's OpenAPI schema to field descriptors, and mapo_scaffold generates pages, fields and overrides in Mapo's own patterns (a dry run unless asked to write).
10
- 7. Cite the doc path you relied on when you produce code.`;
10
+ 7. To turn on the AI module or Magic Fill, call mapo_ai_setup: it asks the developer what the AI is for, says what the module can and cannot do, and proposes the configuration, the keys and tokens, and the files.
11
+ 8. Cite the doc path you relied on when you produce code.`;
@@ -98,11 +98,35 @@ Pick the lightest layer that does the job, in this order:
98
98
 
99
99
  Say which layer you chose and why.`
100
100
  };
101
+ export const aiSetupPrompt = {
102
+ name: "mapo-ai-setup",
103
+ title: "Set up the AI and Magic Fill",
104
+ description: "Turn on @mapomodule/ai and Magic Fill: what it can do for a need, its configuration, the keys and the tokens.",
105
+ argsSchema: {
106
+ need: optional(
107
+ "What the AI should do, e.g. 'fill events from the press releases editors paste'"
108
+ )
109
+ },
110
+ render: ({
111
+ need
112
+ }) => `Help me turn on Mapo's AI module and Magic Fill in this project${need ? `, for this need: ${need}` : ""}.
113
+
114
+ Follow this order and do not skip a step:
115
+ 1. mapo_inspect_app \u2014 see whether @mapomodule/ai and @mapomodule/uikit are installed, and the order of the modules. If the dev server is not running, say so and go on.
116
+ 2. mapo_ai_setup with my need only \u2014 read its questions, and map my need to its \`wants\`.
117
+ 3. Ask me its questions one round at a time, at most three, the recommended answer first, and wait for my answers. Tell me plainly when the module cannot do something I need, and what it offers instead.
118
+ 4. mapo_ai_setup with my answers \u2014 show me whether the module can do it, the configuration, the keys and tokens, the files and the checks. Ask again what it lists under "Still to ask".
119
+ 5. Only after my OK: merge the \`mapo.ai\` block into nuxt.config.ts and create the plugins with mapo_ai_setup and \`write: true\`. Give me the environment variables' names: I set their values myself. Never write a key, a token or the secret in a file.
120
+ 6. Tell me how to check it, with the plan's "Check it" and mapo_doctor.
121
+
122
+ Cite the docs pages the plan points at, and read them with mapo_get_doc when you need more.`
123
+ };
101
124
  export const PROMPTS = [
102
125
  crudPagePrompt,
103
126
  customFieldPrompt,
104
127
  debugFormPrompt,
105
128
  migratePrompt,
106
- themePrompt
129
+ themePrompt,
130
+ aiSetupPrompt
107
131
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
108
132
  ];