@mapomodule/mcp 1.0.0-experimental.1 → 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.
package/dist/module.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@mapomodule/mcp",
3
3
  "configKey": "mapoMcp",
4
- "version": "1.0.0-experimental.1",
4
+ "version": "1.0.0-experimental.2",
5
5
  "builder": {
6
6
  "@nuxt/module-builder": "1.0.2",
7
7
  "unbuild": "unknown"
@@ -77,6 +77,7 @@ export const AI_TOPICS = [
77
77
  heading: "Related records"
78
78
  },
79
79
  fromRecipe("ai-read-files", "Sources"),
80
+ fromRecipe("ai-read-links", "Sources"),
80
81
  fromRecipe("ai-readers", "Sources"),
81
82
  fromRecipe("ai-providers", "Providers and models"),
82
83
  {
@@ -187,6 +188,8 @@ export const AI_NEED_IDS = [
187
188
  "fill-record",
188
189
  "extract-records",
189
190
  "files",
191
+ "links",
192
+ "web-search",
190
193
  "pdf-images",
191
194
  "own-format",
192
195
  "related-records",
@@ -234,6 +237,20 @@ export const AI_NEEDS = [
234
237
  how: "The gateway's `read` turns a file into text with Mapo's readers; Magic Fill's panel takes files, and `useMapoAiRead()` does it in a component of the app.",
235
238
  topics: ["ai-read-files"]
236
239
  },
240
+ {
241
+ id: "links",
242
+ need: "Start from the link of a web page",
243
+ verdict: "ready",
244
+ how: "The gateway's `read/link` fetches the page from the app's server, without the operator's session, and reads it as a file; links are on by default, and a guard refuses the server's own and private networks. Magic Fill's panel takes links, `useMapoAiRead().readLink()` does it in a component; `mapo.ai.web.allow` opens an intranet's hosts, `mapo.ai.readers.link: false` turns links off.",
245
+ topics: ["ai-read-links"]
246
+ },
247
+ {
248
+ id: "web-search",
249
+ need: "Search the web for the source",
250
+ verdict: "not-yet",
251
+ how: "Mapo does not search the web. The operator can give the link of each page instead (`read/link`), or the app can search in a page of its own and send the pages' links.",
252
+ topics: ["ai-read-links"]
253
+ },
237
254
  {
238
255
  id: "pdf-images",
239
256
  need: "Start from PDFs, scans or images",
@@ -71,6 +71,7 @@ const MAPO_EXTENSIONS = [
71
71
  "xlsx"
72
72
  ];
73
73
  const MAPO_READER_IDS = ["text", "markdown", "json", "html", "csv", "xlsx"];
74
+ const LINK_READER_ID = "link";
74
75
  function formatOf(answers) {
75
76
  const format = answers.ownFormat?.trim().replace(/^\./, "").toLowerCase();
76
77
  return format || void 0;
@@ -79,7 +80,8 @@ function isDraftable(format) {
79
80
  return EXTENSION.test(format) && !MAPO_EXTENSIONS.includes(format);
80
81
  }
81
82
  function readerIdOf(format) {
82
- const isId = /^[a-z]/.test(format) && !MAPO_READER_IDS.includes(format);
83
+ const isTaken = MAPO_READER_IDS.includes(format) || format === LINK_READER_ID;
84
+ const isId = /^[a-z]/.test(format) && !isTaken;
83
85
  return isId ? format : `format-${format}`;
84
86
  }
85
87
  function quoted(value) {
@@ -39,8 +39,8 @@ export const AI_QUESTIONS = [
39
39
  options: [
40
40
  {
41
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"]',
42
+ detail: "Mapo reads them all: pasted, attached or given as links in Magic Fill's panel.",
43
+ pass: 'wants: ["files", "links"]',
44
44
  recommended: true
45
45
  },
46
46
  {
@@ -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; 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.
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 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); \`read/link\`, which fetches the page of a link as a stranger would and reads it the same way, on by default (it refuses the server's own and private networks, and redirects there; \`mapo.ai.web\` opens or closes hosts, \`mapo.ai.readers.link: false\` turns links off, registerMapoAiFetcher() in a Nitro plugin fetches pages the app's own way); 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, files or links, 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\` and a link to \`read/link\`). 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" }).
@@ -695,11 +695,11 @@ export const RECIPES = [
695
695
  ],
696
696
  doc: "howto/magic-fill.md",
697
697
  seeAlso: ["modules/ai.md", "uikit/detail.md", "uikit/mapoverride.md"],
698
- summary: "Experimental: with mapo.ai and uikit, every MapoDetail gets Magic Fill: a button in the sidebar card opens a panel (a text or files read through read, the operator's instructions, What I send to the AI from run/preview, the provider and model, Extract), and a banner above the form follows the call, with Cancel, and sums up the session, with Undo all: a second extraction keeps the first one's marks, Keep or a change makes a value the operator's, and Save ends the session. Below the summary, the preview lists the values that wait, each with a tick: to fill (empty fields, ticked), to replace (shown before and after, never ticked from the start) and proposals without proof; Apply selected writes the ticked ones, the others keep waiting, and Ignore all ignores them. A value the record already holds is no replacement: the summary counts it. A list of items, as a repeater's, is chosen item by item, its verified items ticked from the start; the chosen items go after the record's own, never one it holds already. Related records show by their names: one found under another name waits unticked, and a record to pick inside an item gets its own mark once the item is in. definePageMeta({ magicFill: { evidence: false } }) asks the AI for no quotes on a page: every value then waits, marked. On a page with drafts, the session goes into MapoDetail's draft: after a reload, Restore brings back the marks with their quotes, the summary and Undo all, never the source. What I send to the AI shows every user of the AI the rules as the model reads them, the app's, the mapo-ai:prompt hooks' and the admins' included. Next to check, in the banner, takes the operator to each mark that waits, in the order of the form: the tab, group or list item that holds the field opens and the field takes the focus (revealField of the detail's context). The banner's errors say what to do: a key or a model taken away while the page was open (run answers data.reason) makes Magic Fill ask status again. Fields are prepared with their labels, help texts and ai on the descriptor: hint, exclude, and list: false for a relation whose names must not reach the provider. mapo.ai.magicFill: false, definePageMeta({ magicFill: false }) or MapoDetail's extensions prop turn it off; the components can be replaced with MapoOverride, and useMapoAiMagicFill(detail, { part }) gives their state and tells the other parts an override is there."
698
+ summary: "Experimental: with mapo.ai and uikit, every MapoDetail gets Magic Fill: a button in the sidebar card opens a panel (a text, files read through read or links read through read/link, the operator's instructions, What I send to the AI from run/preview, the provider and model, Extract), and a banner above the form follows the call, with Cancel, and sums up the session, with Undo all: a second extraction keeps the first one's marks, Keep or a change makes a value the operator's, and Save ends the session. Below the summary, the preview lists the values that wait, each with a tick: to fill (empty fields, ticked), to replace (shown before and after, never ticked from the start) and proposals without proof; Apply selected writes the ticked ones, the others keep waiting, and Ignore all ignores them. A value the record already holds is no replacement: the summary counts it. A list of items, as a repeater's, is chosen item by item, its verified items ticked from the start; the chosen items go after the record's own, never one it holds already. Related records show by their names: one found under another name waits unticked, and a record to pick inside an item gets its own mark once the item is in. definePageMeta({ magicFill: { evidence: false } }) asks the AI for no quotes on a page: every value then waits, marked. On a page with drafts, the session goes into MapoDetail's draft: after a reload, Restore brings back the marks with their quotes, the summary and Undo all, never the source. What I send to the AI shows every user of the AI the rules as the model reads them, the app's, the mapo-ai:prompt hooks' and the admins' included. Next to check, in the banner, takes the operator to each mark that waits, in the order of the form: the tab, group or list item that holds the field opens and the field takes the focus (revealField of the detail's context). The banner's errors say what to do: a key or a model taken away while the page was open (run answers data.reason) makes Magic Fill ask status again. Fields are prepared with their labels, help texts and ai on the descriptor: hint, exclude, and list: false for a relation whose names must not reach the provider. mapo.ai.magicFill: false, definePageMeta({ magicFill: false }) or MapoDetail's extensions prop turn it off; the components can be replaced with MapoOverride, and useMapoAiMagicFill(detail, { part }) gives their state and tells the other parts an override is there."
699
699
  },
700
700
  {
701
701
  id: "ai-read-files",
702
- task: "Give the AI a file, a web page, a CSV or an Excel sheet, instead of a pasted text",
702
+ task: "Give the AI a file instead of a pasted text: Markdown, a saved HTML page, a CSV or an Excel sheet",
703
703
  keywords: [
704
704
  "useMapoAiRead",
705
705
  "_mapo/ai/read",
@@ -715,7 +715,26 @@ export const RECIPES = [
715
715
  ],
716
716
  doc: "modules/ai.md",
717
717
  heading: "Read a file",
718
- summary: "Experimental: useMapoAiRead().read(file) posts one file to POST /_mapo/ai/read, which reads text, Markdown, JSON, HTML (into Markdown) and CSV or XLSX (each sheet whole, as a Markdown table) into the text parts run takes, without calling any AI; pass answer.parts to useMapoAiFill().fill(). The answer's status says when there are none: unsupported, empty, too-long (more than limits.maxSourceChars) or failed; files up to limits.maxFileBytes, 10 MB by default."
718
+ summary: "Experimental: useMapoAiRead().read(file) posts one file to POST /_mapo/ai/read, which reads text, Markdown, JSON, HTML (its main content into Markdown, under its title and address, with its JSON-LD and Open Graph data in a second part) and CSV or XLSX (each sheet whole, as a Markdown table) into the text parts run takes, without calling any AI; pass answer.parts to useMapoAiFill().fill(). The answer's status says when there are none: unsupported, empty, too-long (more than limits.maxSourceChars) or failed; files up to limits.maxFileBytes, 10 MB by default. A web page by its address, as a link: useMapoAiRead().readLink(url), recipe ai-read-links."
719
+ },
720
+ {
721
+ id: "ai-read-links",
722
+ task: "Give the AI a web page by its address, and keep the server's own network out of reach",
723
+ keywords: [
724
+ "url",
725
+ "web page",
726
+ "web address",
727
+ "page address",
728
+ "fetch a page",
729
+ "ssrf",
730
+ "private network",
731
+ "mapo.ai.web",
732
+ "registerMapoAiFetcher",
733
+ "experimental"
734
+ ],
735
+ doc: "modules/ai.md",
736
+ heading: "Read a web page",
737
+ summary: `Experimental: useMapoAiRead().readLink(url) posts { url } to POST /_mapo/ai/read/link, which fetches the page from the app's server as a stranger would (no cookie, no Authorization) and reads it with the reader of its format, as read reads a file; Magic Fill's panel has a field for links where status.links is true. Links are on by default; the guard refuses non-http(s) addresses, credentials, ports other than 80 and 443, the hosts of mapo.ai.web.deny, and any host that leads to the server itself, a private network or a cloud's metadata, checked by the connection's own lookup and again at each redirect (five at most). mapo.ai.web: { allow (hosts opened, "localhost:3000" for development), deny ("*" keeps every host out), userAgent, timeout (20 s) }; limits.linksPerUserPerMinute (20) and limits.maxFileBytes bound the pages; mapo.ai.readers.link: false or NUXT_MAPO_AI_READERS_LINK=false turns links off. The answer: read (with url), off, blocked (reason), unreachable (reason), http-error (httpStatus), too-large, or read's own. registerMapoAiFetcher({ fetch }) in a Nitro plugin replaces Mapo's fetcher, which runs on Node, and its guard of the network.`
719
738
  },
720
739
  {
721
740
  id: "ai-readers",
@@ -733,7 +752,7 @@ export const RECIPES = [
733
752
  ],
734
753
  doc: "modules/ai.md",
735
754
  heading: "Replace or add a reader",
736
- summary: "Experimental: in a Nitro plugin, registerMapoAiReader({ id, extensions, types?, read(file) }) puts the app's reader in place of Mapo's with the same id (text, markdown, json, html, csv, xlsx) or adds a format; the mapo-ai:read hook touches up the parts any reader read (context.parts), files only, never pasted text; mapo.ai.readers turns a reader off by id ({ xlsx: false }, or NUXT_MAPO_AI_READERS_XLSX=false)."
755
+ summary: "Experimental: in a Nitro plugin, registerMapoAiReader({ id, extensions, types?, read(file) }) puts the app's reader in place of Mapo's with the same id (text, markdown, json, html, csv, xlsx) or adds a format; the id link is taken, by links. The mapo-ai:read hook touches up the parts any reader read (context.parts), of files and of pages read from links (context.file.url), never pasted text; mapo.ai.readers turns a reader off by id ({ xlsx: false }, or NUXT_MAPO_AI_READERS_XLSX=false), and links with link: false."
737
756
  },
738
757
  {
739
758
  id: "ai-providers",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mapomodule/mcp",
3
- "version": "1.0.0-experimental.1",
3
+ "version": "1.0.0-experimental.2",
4
4
  "description": "Mapo MCP server: grounded docs, component and field APIs, live app introspection and scaffolding for AI assistants",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -87,6 +87,11 @@ describe("matchRecipes", () => {
87
87
  ["give the AI a csv spreadsheet instead of pasted text", "ai-read-files"],
88
88
  ["replace the reader of html files in the AI gateway", "ai-readers"],
89
89
  ["turn off xlsx files for the AI", "ai-readers"],
90
+ ["let the operator give the AI the link of a web page", "ai-read-links"],
91
+ [
92
+ "read a url server side without ssrf to private networks",
93
+ "ai-read-links",
94
+ ],
90
95
  ["assign a different openai key to the editors group", "ai-keys"],
91
96
  ["let an operator use their own personal token for the AI", "ai-keys"],
92
97
  ["add a settings page for the AI to my backoffice", "ai-settings"],
@@ -114,6 +119,17 @@ describe("matchRecipes", () => {
114
119
  expect(ids.length).toBeGreaterThan(1);
115
120
  });
116
121
 
122
+ it("keeps a question about linking records away from reading a web page", () => {
123
+ for (const query of [
124
+ "link an author to the article",
125
+ "link a record to another record",
126
+ "a field for a link",
127
+ ]) {
128
+ const ids = matchRecipes(query).map((recipe) => recipe.id);
129
+ expect(ids, query).not.toContain("ai-read-links");
130
+ }
131
+ });
132
+
117
133
  it("stays silent when the query is unrelated", () => {
118
134
  expect(matchRecipes("what is the weather today")).toEqual([]);
119
135
  });
@@ -111,6 +111,7 @@ export const AI_TOPICS: AiTopic[] = [
111
111
  heading: "Related records",
112
112
  },
113
113
  fromRecipe("ai-read-files", "Sources"),
114
+ fromRecipe("ai-read-links", "Sources"),
114
115
  fromRecipe("ai-readers", "Sources"),
115
116
  fromRecipe("ai-providers", "Providers and models"),
116
117
  {
@@ -230,6 +231,8 @@ export const AI_NEED_IDS = [
230
231
  "fill-record",
231
232
  "extract-records",
232
233
  "files",
234
+ "links",
235
+ "web-search",
233
236
  "pdf-images",
234
237
  "own-format",
235
238
  "related-records",
@@ -292,6 +295,20 @@ export const AI_NEEDS: AiNeed[] = [
292
295
  how: "The gateway's `read` turns a file into text with Mapo's readers; Magic Fill's panel takes files, and `useMapoAiRead()` does it in a component of the app.",
293
296
  topics: ["ai-read-files"],
294
297
  },
298
+ {
299
+ id: "links",
300
+ need: "Start from the link of a web page",
301
+ verdict: "ready",
302
+ how: "The gateway's `read/link` fetches the page from the app's server, without the operator's session, and reads it as a file; links are on by default, and a guard refuses the server's own and private networks. Magic Fill's panel takes links, `useMapoAiRead().readLink()` does it in a component; `mapo.ai.web.allow` opens an intranet's hosts, `mapo.ai.readers.link: false` turns links off.",
303
+ topics: ["ai-read-links"],
304
+ },
305
+ {
306
+ id: "web-search",
307
+ need: "Search the web for the source",
308
+ verdict: "not-yet",
309
+ how: "Mapo does not search the web. The operator can give the link of each page instead (`read/link`), or the app can search in a page of its own and send the pages' links.",
310
+ topics: ["ai-read-links"],
311
+ },
295
312
  {
296
313
  id: "pdf-images",
297
314
  need: "Start from PDFs, scans or images",
@@ -122,6 +122,8 @@ const MAPO_EXTENSIONS = [
122
122
  "xlsx",
123
123
  ];
124
124
  const MAPO_READER_IDS = ["text", "markdown", "json", "html", "csv", "xlsx"];
125
+ /** The id that turns links off: no reader may take it. */
126
+ const LINK_READER_ID = "link";
125
127
 
126
128
  /** The extension `ownFormat` names, lower case and without its dot. */
127
129
  function formatOf(answers: AiSetupAnswers): string | undefined {
@@ -136,10 +138,12 @@ function isDraftable(format: string): boolean {
136
138
 
137
139
  /**
138
140
  * The id of the app's reader: its extension, unless the extension does not
139
- * start with a letter, as an id must, or is the id of one of Mapo's readers.
141
+ * start with a letter, as an id must, or is the id of one of Mapo's readers,
142
+ * or `link`, which turns links off.
140
143
  */
141
144
  function readerIdOf(format: string): string {
142
- const isId = /^[a-z]/.test(format) && !MAPO_READER_IDS.includes(format);
145
+ const isTaken = MAPO_READER_IDS.includes(format) || format === LINK_READER_ID;
146
+ const isId = /^[a-z]/.test(format) && !isTaken;
143
147
  return isId ? format : `format-${format}`;
144
148
  }
145
149
 
@@ -74,8 +74,8 @@ export const AI_QUESTIONS: AiQuestion[] = [
74
74
  {
75
75
  label: "Texts, web pages, Markdown, CSV, Excel, JSON",
76
76
  detail:
77
- "Mapo reads them all: pasted or attached in Magic Fill's panel.",
78
- pass: 'wants: ["files"]',
77
+ "Mapo reads them all: pasted, attached or given as links in Magic Fill's panel.",
78
+ pass: 'wants: ["files", "links"]',
79
79
  recommended: true,
80
80
  },
81
81
  {
@@ -6,7 +6,7 @@
6
6
  *
7
7
  * Every `mapo_*` name below must be a real tool: a test checks it.
8
8
  */
9
- 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.
9
+ 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 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); \`read/link\`, which fetches the page of a link as a stranger would and reads it the same way, on by default (it refuses the server's own and private networks, and redirects there; \`mapo.ai.web\` opens or closes hosts, \`mapo.ai.readers.link: false\` turns links off, registerMapoAiFetcher() in a Nitro plugin fetches pages the app's own way); 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, files or links, 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\` and a link to \`read/link\`). 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.
10
10
 
11
11
  Workflow:
12
12
  1. New to the project or the task? Read the overview: the mapo://overview resource, or mapo_get_doc({ path: "guide/concepts.md" }).
@@ -760,11 +760,11 @@ export const RECIPES: Recipe[] = [
760
760
  doc: "howto/magic-fill.md",
761
761
  seeAlso: ["modules/ai.md", "uikit/detail.md", "uikit/mapoverride.md"],
762
762
  summary:
763
- "Experimental: with mapo.ai and uikit, every MapoDetail gets Magic Fill: a button in the sidebar card opens a panel (a text or files read through read, the operator's instructions, What I send to the AI from run/preview, the provider and model, Extract), and a banner above the form follows the call, with Cancel, and sums up the session, with Undo all: a second extraction keeps the first one's marks, Keep or a change makes a value the operator's, and Save ends the session. Below the summary, the preview lists the values that wait, each with a tick: to fill (empty fields, ticked), to replace (shown before and after, never ticked from the start) and proposals without proof; Apply selected writes the ticked ones, the others keep waiting, and Ignore all ignores them. A value the record already holds is no replacement: the summary counts it. A list of items, as a repeater's, is chosen item by item, its verified items ticked from the start; the chosen items go after the record's own, never one it holds already. Related records show by their names: one found under another name waits unticked, and a record to pick inside an item gets its own mark once the item is in. definePageMeta({ magicFill: { evidence: false } }) asks the AI for no quotes on a page: every value then waits, marked. On a page with drafts, the session goes into MapoDetail's draft: after a reload, Restore brings back the marks with their quotes, the summary and Undo all, never the source. What I send to the AI shows every user of the AI the rules as the model reads them, the app's, the mapo-ai:prompt hooks' and the admins' included. Next to check, in the banner, takes the operator to each mark that waits, in the order of the form: the tab, group or list item that holds the field opens and the field takes the focus (revealField of the detail's context). The banner's errors say what to do: a key or a model taken away while the page was open (run answers data.reason) makes Magic Fill ask status again. Fields are prepared with their labels, help texts and ai on the descriptor: hint, exclude, and list: false for a relation whose names must not reach the provider. mapo.ai.magicFill: false, definePageMeta({ magicFill: false }) or MapoDetail's extensions prop turn it off; the components can be replaced with MapoOverride, and useMapoAiMagicFill(detail, { part }) gives their state and tells the other parts an override is there.",
763
+ "Experimental: with mapo.ai and uikit, every MapoDetail gets Magic Fill: a button in the sidebar card opens a panel (a text, files read through read or links read through read/link, the operator's instructions, What I send to the AI from run/preview, the provider and model, Extract), and a banner above the form follows the call, with Cancel, and sums up the session, with Undo all: a second extraction keeps the first one's marks, Keep or a change makes a value the operator's, and Save ends the session. Below the summary, the preview lists the values that wait, each with a tick: to fill (empty fields, ticked), to replace (shown before and after, never ticked from the start) and proposals without proof; Apply selected writes the ticked ones, the others keep waiting, and Ignore all ignores them. A value the record already holds is no replacement: the summary counts it. A list of items, as a repeater's, is chosen item by item, its verified items ticked from the start; the chosen items go after the record's own, never one it holds already. Related records show by their names: one found under another name waits unticked, and a record to pick inside an item gets its own mark once the item is in. definePageMeta({ magicFill: { evidence: false } }) asks the AI for no quotes on a page: every value then waits, marked. On a page with drafts, the session goes into MapoDetail's draft: after a reload, Restore brings back the marks with their quotes, the summary and Undo all, never the source. What I send to the AI shows every user of the AI the rules as the model reads them, the app's, the mapo-ai:prompt hooks' and the admins' included. Next to check, in the banner, takes the operator to each mark that waits, in the order of the form: the tab, group or list item that holds the field opens and the field takes the focus (revealField of the detail's context). The banner's errors say what to do: a key or a model taken away while the page was open (run answers data.reason) makes Magic Fill ask status again. Fields are prepared with their labels, help texts and ai on the descriptor: hint, exclude, and list: false for a relation whose names must not reach the provider. mapo.ai.magicFill: false, definePageMeta({ magicFill: false }) or MapoDetail's extensions prop turn it off; the components can be replaced with MapoOverride, and useMapoAiMagicFill(detail, { part }) gives their state and tells the other parts an override is there.",
764
764
  },
765
765
  {
766
766
  id: "ai-read-files",
767
- task: "Give the AI a file, a web page, a CSV or an Excel sheet, instead of a pasted text",
767
+ task: "Give the AI a file instead of a pasted text: Markdown, a saved HTML page, a CSV or an Excel sheet",
768
768
  keywords: [
769
769
  "useMapoAiRead",
770
770
  "_mapo/ai/read",
@@ -781,7 +781,27 @@ export const RECIPES: Recipe[] = [
781
781
  doc: "modules/ai.md",
782
782
  heading: "Read a file",
783
783
  summary:
784
- "Experimental: useMapoAiRead().read(file) posts one file to POST /_mapo/ai/read, which reads text, Markdown, JSON, HTML (into Markdown) and CSV or XLSX (each sheet whole, as a Markdown table) into the text parts run takes, without calling any AI; pass answer.parts to useMapoAiFill().fill(). The answer's status says when there are none: unsupported, empty, too-long (more than limits.maxSourceChars) or failed; files up to limits.maxFileBytes, 10 MB by default.",
784
+ "Experimental: useMapoAiRead().read(file) posts one file to POST /_mapo/ai/read, which reads text, Markdown, JSON, HTML (its main content into Markdown, under its title and address, with its JSON-LD and Open Graph data in a second part) and CSV or XLSX (each sheet whole, as a Markdown table) into the text parts run takes, without calling any AI; pass answer.parts to useMapoAiFill().fill(). The answer's status says when there are none: unsupported, empty, too-long (more than limits.maxSourceChars) or failed; files up to limits.maxFileBytes, 10 MB by default. A web page by its address, as a link: useMapoAiRead().readLink(url), recipe ai-read-links.",
785
+ },
786
+ {
787
+ id: "ai-read-links",
788
+ task: "Give the AI a web page by its address, and keep the server's own network out of reach",
789
+ keywords: [
790
+ "url",
791
+ "web page",
792
+ "web address",
793
+ "page address",
794
+ "fetch a page",
795
+ "ssrf",
796
+ "private network",
797
+ "mapo.ai.web",
798
+ "registerMapoAiFetcher",
799
+ "experimental",
800
+ ],
801
+ doc: "modules/ai.md",
802
+ heading: "Read a web page",
803
+ summary:
804
+ "Experimental: useMapoAiRead().readLink(url) posts { url } to POST /_mapo/ai/read/link, which fetches the page from the app's server as a stranger would (no cookie, no Authorization) and reads it with the reader of its format, as read reads a file; Magic Fill's panel has a field for links where status.links is true. Links are on by default; the guard refuses non-http(s) addresses, credentials, ports other than 80 and 443, the hosts of mapo.ai.web.deny, and any host that leads to the server itself, a private network or a cloud's metadata, checked by the connection's own lookup and again at each redirect (five at most). mapo.ai.web: { allow (hosts opened, \"localhost:3000\" for development), deny (\"*\" keeps every host out), userAgent, timeout (20 s) }; limits.linksPerUserPerMinute (20) and limits.maxFileBytes bound the pages; mapo.ai.readers.link: false or NUXT_MAPO_AI_READERS_LINK=false turns links off. The answer: read (with url), off, blocked (reason), unreachable (reason), http-error (httpStatus), too-large, or read's own. registerMapoAiFetcher({ fetch }) in a Nitro plugin replaces Mapo's fetcher, which runs on Node, and its guard of the network.",
785
805
  },
786
806
  {
787
807
  id: "ai-readers",
@@ -800,7 +820,7 @@ export const RECIPES: Recipe[] = [
800
820
  doc: "modules/ai.md",
801
821
  heading: "Replace or add a reader",
802
822
  summary:
803
- "Experimental: in a Nitro plugin, registerMapoAiReader({ id, extensions, types?, read(file) }) puts the app's reader in place of Mapo's with the same id (text, markdown, json, html, csv, xlsx) or adds a format; the mapo-ai:read hook touches up the parts any reader read (context.parts), files only, never pasted text; mapo.ai.readers turns a reader off by id ({ xlsx: false }, or NUXT_MAPO_AI_READERS_XLSX=false).",
823
+ "Experimental: in a Nitro plugin, registerMapoAiReader({ id, extensions, types?, read(file) }) puts the app's reader in place of Mapo's with the same id (text, markdown, json, html, csv, xlsx) or adds a format; the id link is taken, by links. The mapo-ai:read hook touches up the parts any reader read (context.parts), of files and of pages read from links (context.file.url), never pasted text; mapo.ai.readers turns a reader off by id ({ xlsx: false }, or NUXT_MAPO_AI_READERS_XLSX=false), and links with link: false.",
804
824
  },
805
825
  {
806
826
  id: "ai-providers",