@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.
- package/README.md +26 -24
- package/dist/build.mjs +66 -4
- package/dist/cli.mjs +8 -1
- package/dist/knowledge/api.json +1 -1
- package/dist/knowledge/docs.json +1 -1
- package/dist/module.json +1 -1
- package/dist/runtime/core/ai-setup/catalog.d.ts +0 -0
- package/dist/runtime/core/ai-setup/catalog.js +428 -0
- package/dist/runtime/core/ai-setup/index.d.ts +0 -0
- package/dist/runtime/core/ai-setup/index.js +20 -0
- package/dist/runtime/core/ai-setup/plan.d.ts +0 -0
- package/dist/runtime/core/ai-setup/plan.js +642 -0
- package/dist/runtime/core/ai-setup/questions.d.ts +0 -0
- package/dist/runtime/core/ai-setup/questions.js +237 -0
- package/dist/runtime/core/indexer.js +10 -3
- package/dist/runtime/core/instructions.js +3 -2
- package/dist/runtime/core/prompts.js +25 -1
- package/dist/runtime/core/recipes.js +407 -3
- package/dist/runtime/core/search.js +2 -1
- package/dist/runtime/core/tools/ai.d.ts +0 -0
- package/dist/runtime/core/tools/ai.js +125 -0
- package/dist/runtime/core/tools/api.js +7 -1
- package/dist/runtime/mcp/handlers/mapo/prompts/ai-setup.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/ai-setup.js +3 -0
- package/package.json +1 -1
- package/src/__tests__/aiSetup.test.ts +330 -0
- package/src/__tests__/cli.test.ts +1 -0
- package/src/__tests__/composables.test.ts +95 -0
- package/src/__tests__/indexer.test.ts +19 -0
- package/src/__tests__/knowledge.test.ts +48 -0
- package/src/__tests__/overview.test.ts +11 -0
- package/src/__tests__/recipes.test.ts +83 -0
- package/src/__tests__/search.test.ts +16 -0
- package/src/__tests__/tools.test.ts +27 -1
- package/src/build/extract-components.ts +33 -5
- package/src/build/extract-composables.ts +65 -2
- package/src/cli.ts +8 -1
- package/src/runtime/core/ai-setup/catalog.ts +492 -0
- package/src/runtime/core/ai-setup/index.ts +29 -0
- package/src/runtime/core/ai-setup/plan.ts +710 -0
- package/src/runtime/core/ai-setup/questions.ts +290 -0
- package/src/runtime/core/indexer.ts +16 -4
- package/src/runtime/core/instructions.ts +3 -2
- package/src/runtime/core/prompts.ts +28 -0
- package/src/runtime/core/recipes.ts +428 -3
- package/src/runtime/core/search.ts +4 -1
- package/src/runtime/core/tools/ai.ts +209 -0
- package/src/runtime/core/tools/api.ts +8 -0
- package/src/runtime/mcp/handlers/mapo/prompts/ai-setup.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/ai-setup.ts +4 -0
|
@@ -67,6 +67,40 @@ export const RECIPES = [
|
|
|
67
67
|
seeAlso: ["uikit/detail.md", "uikit/form/index.md"],
|
|
68
68
|
summary: "MapoDetail wired to useCrud, with body/sidebar field descriptors and save flow."
|
|
69
69
|
},
|
|
70
|
+
{
|
|
71
|
+
id: "detail-context",
|
|
72
|
+
task: "Use the record and state of a detail page from a component inside it",
|
|
73
|
+
keywords: [
|
|
74
|
+
"useMapoDetail",
|
|
75
|
+
"detail context",
|
|
76
|
+
"inside MapoDetail",
|
|
77
|
+
"current record",
|
|
78
|
+
"record being edited",
|
|
79
|
+
"shared OPTIONS",
|
|
80
|
+
"state in the draft",
|
|
81
|
+
"draft part"
|
|
82
|
+
],
|
|
83
|
+
doc: "uikit/detail.md",
|
|
84
|
+
heading: "How to: read the detail from a component inside it",
|
|
85
|
+
seeAlso: ["uikit/form/annotations.md"],
|
|
86
|
+
summary: "useMapoDetail() gives a component inside MapoDetail the record, the fields rendered, languages, state, save(), onSaved(), an annotations channel and draft.part(), which keeps the component's own state in the page's draft, restored, discarded and cleared with the record's values."
|
|
87
|
+
},
|
|
88
|
+
{
|
|
89
|
+
id: "detail-extensions",
|
|
90
|
+
task: "Add an action or a section to every detail page",
|
|
91
|
+
keywords: [
|
|
92
|
+
"defineDetailExtension",
|
|
93
|
+
"detail extension",
|
|
94
|
+
"every detail page",
|
|
95
|
+
"action above save",
|
|
96
|
+
"MapoDetailExtensions",
|
|
97
|
+
"extensions prop"
|
|
98
|
+
],
|
|
99
|
+
doc: "uikit/detail.md",
|
|
100
|
+
heading: "How to: add an action to every detail page",
|
|
101
|
+
seeAlso: ["uikit/api.md"],
|
|
102
|
+
summary: "defineDetailExtension(), from a plugin, adds a component above Save or above the form of every MapoDetail; pages pick them with the extensions prop."
|
|
103
|
+
},
|
|
70
104
|
{
|
|
71
105
|
id: "standalone-form",
|
|
72
106
|
task: "Use the form engine outside a detail page",
|
|
@@ -316,10 +350,18 @@ export const RECIPES = [
|
|
|
316
350
|
{
|
|
317
351
|
id: "form-draft",
|
|
318
352
|
task: "Autosave form drafts",
|
|
319
|
-
keywords: [
|
|
353
|
+
keywords: [
|
|
354
|
+
"draft",
|
|
355
|
+
"autosave",
|
|
356
|
+
"useFormDraft",
|
|
357
|
+
"restore",
|
|
358
|
+
"unsaved",
|
|
359
|
+
"noDraft",
|
|
360
|
+
"saved draft"
|
|
361
|
+
],
|
|
320
362
|
doc: "uikit/form/draft.md",
|
|
321
|
-
seeAlso: ["howto/crud-detail.md"],
|
|
322
|
-
summary:
|
|
363
|
+
seeAlso: ["uikit/detail.md", "howto/crud-detail.md"],
|
|
364
|
+
summary: 'useFormDraft keeps unsaved edits in localStorage and offers to restore them on the next visit. MapoDetail does it with :draft="true", and useMapoForm with draftKey: per user, without the fields marked noDraft wherever their value is (every language, dotted keys, repeater items), new records included once they hold a value.'
|
|
323
365
|
},
|
|
324
366
|
{
|
|
325
367
|
id: "schema-to-form",
|
|
@@ -336,6 +378,57 @@ export const RECIPES = [
|
|
|
336
378
|
seeAlso: ["howto/form-advanced.md"],
|
|
337
379
|
summary: "useFormFromSchema turns a JSON Schema (DRF, Pydantic) into field descriptors you can extend."
|
|
338
380
|
},
|
|
381
|
+
{
|
|
382
|
+
id: "form-to-schema",
|
|
383
|
+
task: "Describe a form as JSON Schema",
|
|
384
|
+
keywords: [
|
|
385
|
+
"fieldsToJsonSchema",
|
|
386
|
+
"form to json schema",
|
|
387
|
+
"export the fields",
|
|
388
|
+
"serialize the form",
|
|
389
|
+
"round trip",
|
|
390
|
+
"x-mapo-field",
|
|
391
|
+
"x-mapo-attrs"
|
|
392
|
+
],
|
|
393
|
+
doc: "uikit/form/schema-to-form.md",
|
|
394
|
+
heading: "From form to JSON Schema",
|
|
395
|
+
seeAlso: ["uikit/form/custom-fields.md"],
|
|
396
|
+
summary: "fieldsToJsonSchema writes a form's descriptors as JSON Schema, and useFormFromSchema reads it back into the same descriptors."
|
|
397
|
+
},
|
|
398
|
+
{
|
|
399
|
+
id: "schema-sources",
|
|
400
|
+
task: "Build a form from DRF OPTIONS metadata or an OpenAPI document",
|
|
401
|
+
keywords: [
|
|
402
|
+
"drf metadata",
|
|
403
|
+
"options metadata",
|
|
404
|
+
"actions.POST",
|
|
405
|
+
"drfMetadataToJsonSchema",
|
|
406
|
+
"openApiToJsonSchema",
|
|
407
|
+
"metadataToJsonSchema",
|
|
408
|
+
"schemaFromMetadata",
|
|
409
|
+
"placeholder field"
|
|
410
|
+
],
|
|
411
|
+
doc: "uikit/form/schema-to-form.md",
|
|
412
|
+
heading: "From DRF metadata and OpenAPI",
|
|
413
|
+
seeAlso: ["uikit/detail.md"],
|
|
414
|
+
summary: "drfMetadataToJsonSchema and openApiToJsonSchema read what a DRF backend publishes as JSON Schema; MapoDetail derives its fields from the OPTIONS metadata."
|
|
415
|
+
},
|
|
416
|
+
{
|
|
417
|
+
id: "descriptor-extensions",
|
|
418
|
+
task: "Add typed properties of your own to field descriptors",
|
|
419
|
+
keywords: [
|
|
420
|
+
"FieldExtensions",
|
|
421
|
+
"extend the descriptor",
|
|
422
|
+
"declare module",
|
|
423
|
+
"module augmentation",
|
|
424
|
+
"custom descriptor property",
|
|
425
|
+
"typed property"
|
|
426
|
+
],
|
|
427
|
+
doc: "uikit/form/custom-fields.md",
|
|
428
|
+
heading: "Add your own descriptor properties",
|
|
429
|
+
seeAlso: ["uikit/form/schema-to-form.md"],
|
|
430
|
+
summary: "FieldExtensions adds typed properties of your own to every descriptor through module augmentation; the property option of fieldsToJsonSchema writes them into the schema."
|
|
431
|
+
},
|
|
339
432
|
{
|
|
340
433
|
id: "form-slots",
|
|
341
434
|
task: "Customize how a form field renders with slots",
|
|
@@ -365,6 +458,26 @@ export const RECIPES = [
|
|
|
365
458
|
seeAlso: ["uikit/form/field-expand.md"],
|
|
366
459
|
summary: "Open a repeater item in a fullscreen view, or expand a single field in place."
|
|
367
460
|
},
|
|
461
|
+
{
|
|
462
|
+
id: "field-annotations",
|
|
463
|
+
task: "Annotate the fields an assistant filled or that need a review",
|
|
464
|
+
keywords: [
|
|
465
|
+
"annotations",
|
|
466
|
+
"annotate",
|
|
467
|
+
"mark a field",
|
|
468
|
+
"field badge",
|
|
469
|
+
"tab count",
|
|
470
|
+
"suggested value",
|
|
471
|
+
"imported value",
|
|
472
|
+
"review note",
|
|
473
|
+
"outside the descriptor",
|
|
474
|
+
"MapoFormAnnotation",
|
|
475
|
+
"useFieldAnnotation"
|
|
476
|
+
],
|
|
477
|
+
doc: "uikit/form/annotations.md",
|
|
478
|
+
seeAlso: ["uikit/form/slots.md", "uikit/form/api.md"],
|
|
479
|
+
summary: "A reactive map keyed by value path on MapoForm, MapoDetail or useMapoForm: a mark with a popover next to the label and badges on tabs and repeater items, without remounting the fields."
|
|
480
|
+
},
|
|
368
481
|
{
|
|
369
482
|
id: "sidebar-navigation",
|
|
370
483
|
task: "Build the sidebar navigation",
|
|
@@ -478,6 +591,297 @@ export const RECIPES = [
|
|
|
478
591
|
],
|
|
479
592
|
doc: "uikit/form/devtools.md",
|
|
480
593
|
summary: "The Mapo Forms tab: the module config and the live field registry your forms read."
|
|
594
|
+
},
|
|
595
|
+
{
|
|
596
|
+
id: "ai-setup",
|
|
597
|
+
task: "Turn on the AI module and Magic Fill with a guided setup",
|
|
598
|
+
keywords: [
|
|
599
|
+
"set up the ai",
|
|
600
|
+
"configure the ai",
|
|
601
|
+
"enable the ai module",
|
|
602
|
+
"guided setup",
|
|
603
|
+
"what can the ai do",
|
|
604
|
+
"mapo_ai_setup",
|
|
605
|
+
"mapo-ai-setup",
|
|
606
|
+
"ai tokens",
|
|
607
|
+
"experimental"
|
|
608
|
+
],
|
|
609
|
+
doc: "modules/ai.md",
|
|
610
|
+
heading: "Enable the module",
|
|
611
|
+
seeAlso: ["modules/mcp.md", "howto/magic-fill.md"],
|
|
612
|
+
summary: "Experimental, on npm's experimental dist-tag only (pnpm add mapomodule@experimental): setting mapo.ai in nuxt.config.ts installs @mapomodule/ai, and a provider turns Magic Fill on in every MapoDetail. The mapo_ai_setup tool, or the mapo-ai-setup prompt, asks the developer what the AI is for, says what the module can and cannot do for it, and proposes the configuration, the environment variables (names only), the keys and tokens, and the server plugins."
|
|
613
|
+
},
|
|
614
|
+
{
|
|
615
|
+
id: "ai-run",
|
|
616
|
+
task: "Ask the AI to fill a record from a source",
|
|
617
|
+
keywords: [
|
|
618
|
+
"mapo.ai",
|
|
619
|
+
"language model",
|
|
620
|
+
"_mapo/ai/run",
|
|
621
|
+
"extract records",
|
|
622
|
+
"field outcomes",
|
|
623
|
+
"experimental"
|
|
624
|
+
],
|
|
625
|
+
doc: "modules/ai.md",
|
|
626
|
+
heading: "Ask the AI",
|
|
627
|
+
seeAlso: ["uikit/form/schema-to-form.md"],
|
|
628
|
+
summary: "Experimental, opt-in with mapo.ai: POST /_mapo/ai/run sends a record's backend schema and form fields with a source to an enabled provider and answers one checked outcome per field; useMapoAiFill() applies it to a detail form."
|
|
629
|
+
},
|
|
630
|
+
{
|
|
631
|
+
id: "ai-fill",
|
|
632
|
+
task: "Fill a detail form with the AI from a pasted text",
|
|
633
|
+
keywords: [
|
|
634
|
+
"useMapoAiFill",
|
|
635
|
+
"pasted text",
|
|
636
|
+
"fill the form",
|
|
637
|
+
"detail extension",
|
|
638
|
+
"verified values",
|
|
639
|
+
"undo",
|
|
640
|
+
"already holds",
|
|
641
|
+
"related records",
|
|
642
|
+
"relationChoices",
|
|
643
|
+
"experimental"
|
|
644
|
+
],
|
|
645
|
+
doc: "modules/ai.md",
|
|
646
|
+
heading: "Fill a detail form",
|
|
647
|
+
seeAlso: ["uikit/detail.md", "uikit/form/annotations.md"],
|
|
648
|
+
summary: "Experimental: in a detail extension, useMapoAiFill(detail), with the context of useMapoDetail(), sends the form's fields and the backend schema from OPTIONS with a source to run, writes each value a quote verifies into an empty field it shows and marks the others to apply, pick, set by hand or ignore, each mark with the words of the source that prove it; the mark of a replacement says what it replaces, and a value the field already holds is unchanged. Related records (fks and m2m fields with an endpoint) are looked up with the operator's session: the AI picks from the records of a relation that has 50 at most, or writes a name searched with ?search=; a record found with the AI's very name goes in as a verified value, one under another name waits with Apply, several are candidates to pick on the field's mark (choose()), and an m2m adds the records found after the field's own. The answers of a session add up: keep() or a change in the field makes a value the operator's, undo() puts back every answer's values, newest first, and a save of the record ends the session. snapshot() and resume() keep the session in a draft and take it back, read as outside data."
|
|
649
|
+
},
|
|
650
|
+
{
|
|
651
|
+
id: "ai-field-options",
|
|
652
|
+
task: "Guide the AI on one field, keep a field from it, or keep a relation's records from the provider",
|
|
653
|
+
keywords: [
|
|
654
|
+
"x-mapo-ai",
|
|
655
|
+
"ai.hint",
|
|
656
|
+
"hint",
|
|
657
|
+
"ai.exclude",
|
|
658
|
+
"list: false",
|
|
659
|
+
"keep a field from the ai",
|
|
660
|
+
"relation names",
|
|
661
|
+
"relationChoices",
|
|
662
|
+
"mapoAiFieldsSchema",
|
|
663
|
+
"privacy",
|
|
664
|
+
"experimental"
|
|
665
|
+
],
|
|
666
|
+
doc: "modules/ai.md",
|
|
667
|
+
heading: "Guide a field",
|
|
668
|
+
seeAlso: ["howto/magic-fill.md", "uikit/form/custom-fields.md"],
|
|
669
|
+
summary: "Experimental: with @mapomodule/ai installed, a field descriptor takes ai (declared on FieldExtensions): { hint } tells the model what to take and how, { exclude: true } keeps the field away from the AI, { list: false } keeps a relation's records from the provider (they are never listed, even when 50 or fewer; the AI writes the name it reads and Magic Fill searches it with ?search= after the answer). A backend's schema says the same with x-mapo-ai; what either side says holds, inside a repeater's items too, and the gateway leaves out the records of an unlisted relation even from a request that lists them. Magic Fill and useMapoAiFill() send them; a page that calls POST /_mapo/ai/run itself sends its fields with mapoAiFieldsSchema(fields), auto-imported, since fieldsToJsonSchema(fields) leaves them out."
|
|
670
|
+
},
|
|
671
|
+
{
|
|
672
|
+
id: "ai-magic-fill",
|
|
673
|
+
task: "Use Magic Fill, the AI panel of detail pages",
|
|
674
|
+
keywords: [
|
|
675
|
+
"magic fill",
|
|
676
|
+
"magicFill",
|
|
677
|
+
"disable",
|
|
678
|
+
"useMapoAiMagicFill",
|
|
679
|
+
"MapoAiMagicFillPanel",
|
|
680
|
+
"what i send to the ai",
|
|
681
|
+
"run/preview",
|
|
682
|
+
"cancel the call",
|
|
683
|
+
"undo all",
|
|
684
|
+
"proposals without proof",
|
|
685
|
+
"apply selected",
|
|
686
|
+
"before and after",
|
|
687
|
+
"items of a list",
|
|
688
|
+
"after a reload",
|
|
689
|
+
"related records",
|
|
690
|
+
"no quotes",
|
|
691
|
+
"evidence",
|
|
692
|
+
"next to check",
|
|
693
|
+
"magic fill error",
|
|
694
|
+
"experimental"
|
|
695
|
+
],
|
|
696
|
+
doc: "howto/magic-fill.md",
|
|
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, 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
|
+
},
|
|
700
|
+
{
|
|
701
|
+
id: "ai-read-files",
|
|
702
|
+
task: "Give the AI a file instead of a pasted text: Markdown, a saved HTML page, a CSV or an Excel sheet",
|
|
703
|
+
keywords: [
|
|
704
|
+
"useMapoAiRead",
|
|
705
|
+
"_mapo/ai/read",
|
|
706
|
+
"upload a file",
|
|
707
|
+
"file input",
|
|
708
|
+
"excel",
|
|
709
|
+
"xlsx",
|
|
710
|
+
"csv",
|
|
711
|
+
"spreadsheet",
|
|
712
|
+
"html page",
|
|
713
|
+
"markdown",
|
|
714
|
+
"experimental"
|
|
715
|
+
],
|
|
716
|
+
doc: "modules/ai.md",
|
|
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 (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.`
|
|
738
|
+
},
|
|
739
|
+
{
|
|
740
|
+
id: "ai-readers",
|
|
741
|
+
task: "Replace how the AI gateway reads a file format, add a format, or turn one off",
|
|
742
|
+
keywords: [
|
|
743
|
+
"registerMapoAiReader",
|
|
744
|
+
"mapo-ai:read",
|
|
745
|
+
"mapo.ai.readers",
|
|
746
|
+
"custom reader",
|
|
747
|
+
"reader",
|
|
748
|
+
"file format",
|
|
749
|
+
"turn off",
|
|
750
|
+
"redact",
|
|
751
|
+
"experimental"
|
|
752
|
+
],
|
|
753
|
+
doc: "modules/ai.md",
|
|
754
|
+
heading: "Replace or add a reader",
|
|
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."
|
|
756
|
+
},
|
|
757
|
+
{
|
|
758
|
+
id: "ai-providers",
|
|
759
|
+
task: "Add an AI provider, or answer with the mock",
|
|
760
|
+
keywords: [
|
|
761
|
+
"registerMapoAiProvider",
|
|
762
|
+
"MapoAiProviderError",
|
|
763
|
+
"registerMapoAiMockFixtures",
|
|
764
|
+
"mapo.ai.providers",
|
|
765
|
+
"mock provider",
|
|
766
|
+
"fixtures",
|
|
767
|
+
"llm"
|
|
768
|
+
],
|
|
769
|
+
doc: "modules/ai.md",
|
|
770
|
+
heading: "Providers",
|
|
771
|
+
seeAlso: ["modules/api.md"],
|
|
772
|
+
summary: "mapo.ai.providers enables what run may call: Mapo's mock, which answers without a network from fixtures or Label: value lines, Mapo's providers for OpenAI, Anthropic and local models, or a provider the app registers in a Nitro plugin with registerMapoAiProvider()."
|
|
773
|
+
},
|
|
774
|
+
{
|
|
775
|
+
id: "ai-keys",
|
|
776
|
+
task: "Assign AI provider keys and models to groups or users, or let operators use their own token",
|
|
777
|
+
keywords: [
|
|
778
|
+
"_mapo/ai/keys",
|
|
779
|
+
"_mapo/ai/token",
|
|
780
|
+
"assign a key",
|
|
781
|
+
"key per group",
|
|
782
|
+
"group",
|
|
783
|
+
"personal token",
|
|
784
|
+
"own token",
|
|
785
|
+
"key level",
|
|
786
|
+
"experimental"
|
|
787
|
+
],
|
|
788
|
+
doc: "modules/ai.md",
|
|
789
|
+
heading: "Keys",
|
|
790
|
+
summary: "Experimental: each call uses the key nearest the user: their own token where an admin's assignment allows it (PUT /_mapo/ai/token), else the first key up the admins' assignments (the user's, their groups' by the admins' order, everyone's: PUT /_mapo/ai/keys, PUT /_mapo/ai/keys/groups), else the project's in the environment. The nearest assignment also narrows the models; personal tokens are off unless allowed; status says the level and the last four characters, never the key; a provider with no key at any level answers 503."
|
|
791
|
+
},
|
|
792
|
+
{
|
|
793
|
+
id: "ai-settings",
|
|
794
|
+
task: "Give users and admins a page to choose AI providers and models, manage keys and check the connection",
|
|
795
|
+
keywords: [
|
|
796
|
+
"MapoAiSettings",
|
|
797
|
+
"ai-settings",
|
|
798
|
+
"mapo.ai.settings",
|
|
799
|
+
"settings page",
|
|
800
|
+
"usersApi",
|
|
801
|
+
"groupsApi",
|
|
802
|
+
"preference",
|
|
803
|
+
"check the connection",
|
|
804
|
+
"experimental"
|
|
805
|
+
],
|
|
806
|
+
doc: "modules/ai.md",
|
|
807
|
+
heading: "AI settings",
|
|
808
|
+
summary: "Experimental: the module adds an AI settings page at /ai-settings (mapo.ai.settings.path moves it, false leaves it out for <MapoAiSettings /> in a page of the app). Each user saves their provider and model (PUT /_mapo/ai/preferences), sees their key, saves their own token where allowed and checks the connection (POST /_mapo/ai/test, which lists the provider's models with their key, at no cost); admins assign keys, searching the backend's users and groups through mapo.ai.settings.usersApi and groupsApi."
|
|
809
|
+
},
|
|
810
|
+
{
|
|
811
|
+
id: "ai-admin-settings",
|
|
812
|
+
task: "Let the AI's admins change its instructions, verification rules, secret fields and models without a deploy",
|
|
813
|
+
keywords: [
|
|
814
|
+
"secretWords",
|
|
815
|
+
"adminModels",
|
|
816
|
+
"fallbacks",
|
|
817
|
+
"admin instructions",
|
|
818
|
+
"verification rules",
|
|
819
|
+
"secret field",
|
|
820
|
+
"add a model",
|
|
821
|
+
"how the AI works",
|
|
822
|
+
"experimental"
|
|
823
|
+
],
|
|
824
|
+
doc: "modules/ai.md",
|
|
825
|
+
heading: "How the AI works",
|
|
826
|
+
summary: "Experimental: on the AI settings page the AI's admins change how the AI works in the whole app (GET/PUT /_mapo/ai/settings, POST /_mapo/ai/settings/preview): their instructions (layer 3 of the prompt, after Mapo's and the app's; every user of the AI reads them in Magic Fill's What I send to the AI), the rules of verification over mapo.ai.verification, words that keep a field from the AI besides Mapo's and mapo.ai.secretWords, the prompt cache of openai and anthropic, Anthropic's fallbacks (off; on only where the app's anthropic.fallbacks leaves them on), and models they add where the app sets providers.<id>.adminModels: true, saved once the provider's server lists them. The app's options stay the defaults; changes are audited, and an unreadable record closes the AI with 503."
|
|
827
|
+
},
|
|
828
|
+
{
|
|
829
|
+
id: "ai-usage",
|
|
830
|
+
task: "See how much the AI is used and what it costs, by user, model and day",
|
|
831
|
+
keywords: [
|
|
832
|
+
"usage",
|
|
833
|
+
"tokens",
|
|
834
|
+
"cost",
|
|
835
|
+
"prices",
|
|
836
|
+
"mapo.ai.prices",
|
|
837
|
+
"audit",
|
|
838
|
+
"changes",
|
|
839
|
+
"experimental"
|
|
840
|
+
],
|
|
841
|
+
doc: "modules/ai.md",
|
|
842
|
+
heading: "Usage",
|
|
843
|
+
summary: "Experimental: the AI settings page shows the usage summed from the audit when it is read: the AI's admins see every user's calls of a period (GET /_mapo/ai/usage?days=, 1 to 3650, 30 unless set; the page offers 7, 30 and 90) by user, model and day, the latest 50 calls and the changes of keys and settings (GET /_mapo/ai/actions); each user their own (GET /_mapo/ai/usage/mine). Tokens always; a cost only for the models the app prices in mapo.ai.prices ({ currency, providers: { [provider]: { [model]: { input, output, cacheRead?, cacheWrite? } } } }, per million tokens): Mapo keeps no price list. Never what was sent."
|
|
844
|
+
},
|
|
845
|
+
{
|
|
846
|
+
id: "ai-cloud-models",
|
|
847
|
+
task: "Use OpenAI or Anthropic (Claude) models for the AI",
|
|
848
|
+
keywords: [
|
|
849
|
+
"openai",
|
|
850
|
+
"anthropic",
|
|
851
|
+
"claude",
|
|
852
|
+
"gpt",
|
|
853
|
+
"api key",
|
|
854
|
+
"prompt cache",
|
|
855
|
+
"promptCache",
|
|
856
|
+
"effort",
|
|
857
|
+
"reasoning",
|
|
858
|
+
"fallbacks",
|
|
859
|
+
"structured outputs"
|
|
860
|
+
],
|
|
861
|
+
doc: "modules/ai.md",
|
|
862
|
+
heading: "OpenAI",
|
|
863
|
+
summary: `Experimental: enable openai (Responses API, gpt-6.1-sol and gpt-6-luna unless models says otherwise) or anthropic (Messages API, claude-opus-5-5, claude-sonnet-5-5 and claude-haiku-5-5) in mapo.ai.providers, with the project's key in NUXT_MAPO_AI_PROVIDERS_OPENAI_API_KEY or NUXT_MAPO_AI_PROVIDERS_ANTHROPIC_API_KEY, never in the config (the AI's admins can assign their own over it); effort is "low" unless set, promptCache is off unless set, timeout 300 seconds; Anthropic retries a request its safety filters decline on a fallback model, which the answer's provider.model names.`
|
|
864
|
+
},
|
|
865
|
+
{
|
|
866
|
+
id: "ai-local-models",
|
|
867
|
+
task: "Use a local model, served by Ollama, LM Studio or vLLM, for the AI",
|
|
868
|
+
keywords: [
|
|
869
|
+
"ollama",
|
|
870
|
+
"local model",
|
|
871
|
+
"openai-compatible",
|
|
872
|
+
"lm studio",
|
|
873
|
+
"vllm",
|
|
874
|
+
"llama.cpp",
|
|
875
|
+
"self-hosted",
|
|
876
|
+
"server",
|
|
877
|
+
"api key",
|
|
878
|
+
"baseURL",
|
|
879
|
+
"contextTokens",
|
|
880
|
+
"num_ctx"
|
|
881
|
+
],
|
|
882
|
+
doc: "modules/ai.md",
|
|
883
|
+
heading: "Ollama",
|
|
884
|
+
summary: "Experimental: enable ollama (Ollama 0.40.13 or later, through its own API, http://localhost:11434 unless baseURL says otherwise) or openai-compatible (baseURL up to /v1, contextTokens when the server's list does not say the context) in mapo.ai.providers, with the models to allow; keys go in NUXT_MAPO_AI_PROVIDERS_OLLAMA_API_KEY or NUXT_MAPO_AI_PROVIDERS_OPENAI_COMPATIBLE_API_KEY; a prompt the model cannot read whole answers 413, a cut answer 502."
|
|
481
885
|
}
|
|
482
886
|
];
|
|
483
887
|
const TASK_WEIGHT = 1.5;
|
|
@@ -61,7 +61,8 @@ export function searchDocs(knowledge, query, options = {}) {
|
|
|
61
61
|
for (const term of queryTerms) {
|
|
62
62
|
if (seenTerms.has(term)) continue;
|
|
63
63
|
seenTerms.add(term);
|
|
64
|
-
const
|
|
64
|
+
const isIndexed = Object.hasOwn(index.terms, term);
|
|
65
|
+
const postings = isIndexed ? index.terms[term] : void 0;
|
|
65
66
|
if (!postings) continue;
|
|
66
67
|
const idf = Math.max(
|
|
67
68
|
0.05,
|
|
File without changes
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import {
|
|
3
|
+
AI_DEPLOY_CHOICES,
|
|
4
|
+
AI_KEY_CHOICES,
|
|
5
|
+
AI_MAGIC_FILL_CHOICES,
|
|
6
|
+
AI_NEED_IDS,
|
|
7
|
+
AI_PROVIDER_CHOICES,
|
|
8
|
+
aiSetupFiles,
|
|
9
|
+
hasAiAnswers,
|
|
10
|
+
renderAiSetupPlan,
|
|
11
|
+
renderAiSetupQuestions
|
|
12
|
+
} from "../ai-setup/index.js";
|
|
13
|
+
import { defineMapoTool } from "../tool-spec.js";
|
|
14
|
+
import { writeScaffold } from "../write.js";
|
|
15
|
+
function filesSection(files, args, context) {
|
|
16
|
+
if (!files.length) return "None: the answers need no server code of the app.";
|
|
17
|
+
if (!args.write) {
|
|
18
|
+
const blocks = files.map(
|
|
19
|
+
(file) => `### \`${file.path}\`
|
|
20
|
+
|
|
21
|
+
\`\`\`ts
|
|
22
|
+
${file.content}\`\`\``
|
|
23
|
+
);
|
|
24
|
+
return `${blocks.join("\n\n")}
|
|
25
|
+
|
|
26
|
+
Nothing was written. Call again with \`write: true\` to create these files.`;
|
|
27
|
+
}
|
|
28
|
+
const root = context.rootDir();
|
|
29
|
+
if (!root) {
|
|
30
|
+
return "Cannot write: the project root is unknown. Connect to the app's endpoint (`/mcp/mapo`), or run `mapo-mcp serve --root <path>`.";
|
|
31
|
+
}
|
|
32
|
+
const outcomes = writeScaffold(files, {
|
|
33
|
+
root,
|
|
34
|
+
overwrite: args.overwrite ?? false,
|
|
35
|
+
allowed: context.canWrite()
|
|
36
|
+
});
|
|
37
|
+
const lines = outcomes.map((outcome) => {
|
|
38
|
+
const icon = outcome.status === "written" ? "\u2714" : "\u2716";
|
|
39
|
+
const detail = outcome.reason ? `: ${outcome.reason}` : "";
|
|
40
|
+
return `- ${icon} \`${outcome.path}\` (${outcome.status})${detail}`;
|
|
41
|
+
});
|
|
42
|
+
return `Root: \`${root}\`
|
|
43
|
+
|
|
44
|
+
${lines.join("\n")}`;
|
|
45
|
+
}
|
|
46
|
+
export const aiSetupTool = defineMapoTool({
|
|
47
|
+
name: "mapo_ai_setup",
|
|
48
|
+
title: "Set up the AI and Magic Fill",
|
|
49
|
+
description: "Guide a developer through turning on @mapomodule/ai (experimental) and Magic Fill: without answers, the questions to ask them, in rounds, with every need the module can meet and everything it offers; with their answers, whether the module can do what they need, the `mapo.ai` configuration, the environment's 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 of the app and the checks. Shows the files unless `write: true`; never edits nuxt.config.ts, never writes a key.",
|
|
50
|
+
inputSchema: {
|
|
51
|
+
need: z.string().max(4e3).optional().describe("The developer's need, in their own words"),
|
|
52
|
+
wants: z.array(z.enum(AI_NEED_IDS)).optional().describe(
|
|
53
|
+
"The need mapped to the module's needs, such as `fill-record`, `extract-records`, `pdf-images`, `private-relations`, `team-keys`, `costs`: the questions list them all"
|
|
54
|
+
),
|
|
55
|
+
dataMayLeave: z.boolean().optional().describe(
|
|
56
|
+
"Whether the records and their sources may go to a cloud provider"
|
|
57
|
+
),
|
|
58
|
+
providers: z.array(z.enum(AI_PROVIDER_CHOICES)).optional().describe(
|
|
59
|
+
"The providers to enable; `own` is a provider of the app's own"
|
|
60
|
+
),
|
|
61
|
+
keys: z.array(z.enum(AI_KEY_CHOICES)).optional().describe(
|
|
62
|
+
"Where the keys come from: the project's (environment), the admins' assignments, users' own tokens"
|
|
63
|
+
),
|
|
64
|
+
userGroups: z.array(z.string()).optional().describe("The groups that may use the AI (`mapo.ai.users.groups`)"),
|
|
65
|
+
userPermissions: z.array(z.string()).optional().describe("The permissions that let a user use the AI"),
|
|
66
|
+
allowedFlag: z.string().max(64).optional().describe(
|
|
67
|
+
"A field of the user the backend returns that must be `true` for the AI, such as `is_internal`"
|
|
68
|
+
),
|
|
69
|
+
adminGroups: z.array(z.string()).optional().describe("The groups that administer the AI (`mapo.ai.admin.groups`)"),
|
|
70
|
+
costs: z.boolean().optional().describe("Whether the usage shows costs, with the models' prices"),
|
|
71
|
+
perUserPerMinute: z.number().int().min(1).max(1e3).optional().describe("The calls to `run` one user may make in a minute"),
|
|
72
|
+
magicFill: z.enum(AI_MAGIC_FILL_CHOICES).optional().describe("Where Magic Fill shows, or the app's own panel instead"),
|
|
73
|
+
instructions: z.string().max(2e3).optional().describe(
|
|
74
|
+
"Rules the AI follows in every prompt (`mapo.ai.instructions.all`)"
|
|
75
|
+
),
|
|
76
|
+
ownFormat: z.string().max(16).optional().describe(
|
|
77
|
+
"The extension of a file format the app reads itself, such as `ics`"
|
|
78
|
+
),
|
|
79
|
+
deploy: z.enum(AI_DEPLOY_CHOICES).optional().describe("Where the server runs in production"),
|
|
80
|
+
write: z.boolean().optional().describe(
|
|
81
|
+
"Create the plugin files instead of only showing them (development only)"
|
|
82
|
+
),
|
|
83
|
+
overwrite: z.boolean().optional().describe("Allow replacing files that already exist")
|
|
84
|
+
},
|
|
85
|
+
annotations: {
|
|
86
|
+
// Not read-only: with `write` it creates the plugins. Never destructive:
|
|
87
|
+
// an existing file is refused unless `overwrite` is set.
|
|
88
|
+
readOnlyHint: false,
|
|
89
|
+
destructiveHint: false,
|
|
90
|
+
idempotentHint: true,
|
|
91
|
+
openWorldHint: false
|
|
92
|
+
},
|
|
93
|
+
inputExamples: [
|
|
94
|
+
{ need: "Our editors paste press releases into the event form" },
|
|
95
|
+
{
|
|
96
|
+
need: "Editors fill articles from press releases; no data may leave the company",
|
|
97
|
+
wants: ["fill-record", "files", "local-only"],
|
|
98
|
+
dataMayLeave: false,
|
|
99
|
+
providers: ["ollama"],
|
|
100
|
+
keys: ["project"],
|
|
101
|
+
deploy: "single-node"
|
|
102
|
+
},
|
|
103
|
+
{
|
|
104
|
+
wants: ["fill-record", "team-keys", "costs"],
|
|
105
|
+
providers: ["openai"],
|
|
106
|
+
keys: ["project", "assigned"],
|
|
107
|
+
userGroups: ["editors"],
|
|
108
|
+
costs: true,
|
|
109
|
+
perUserPerMinute: 10,
|
|
110
|
+
deploy: "several-instances"
|
|
111
|
+
}
|
|
112
|
+
],
|
|
113
|
+
run: (args, context) => {
|
|
114
|
+
const manifest = context.manifest();
|
|
115
|
+
if (!hasAiAnswers(args)) {
|
|
116
|
+
const questions = renderAiSetupQuestions(args, manifest);
|
|
117
|
+
return args.write ? `Nothing was written: the answers decide which files the app needs.
|
|
118
|
+
|
|
119
|
+
${questions}` : questions;
|
|
120
|
+
}
|
|
121
|
+
const files = filesSection(aiSetupFiles(args), args, context);
|
|
122
|
+
return renderAiSetupPlan(args, manifest, files);
|
|
123
|
+
}
|
|
124
|
+
});
|
|
125
|
+
export const aiTools = [aiSetupTool];
|
|
@@ -39,6 +39,9 @@ function suggest(entries, name, limit = 8) {
|
|
|
39
39
|
|
|
40
40
|
Available: ${close.join(", ")}` : "";
|
|
41
41
|
}
|
|
42
|
+
const OPT_IN_PACKAGES = {
|
|
43
|
+
"@mapomodule/ai": "Experimental and opt-in: it exists only in an app that sets `mapo.ai` (the meta-module then installs `@mapomodule/ai`)."
|
|
44
|
+
};
|
|
42
45
|
function renderComponent(component, include) {
|
|
43
46
|
const wanted = include?.length ? new Set(include) : null;
|
|
44
47
|
const sections = [];
|
|
@@ -51,9 +54,12 @@ function renderComponent(component, include) {
|
|
|
51
54
|
if ((!wanted || wanted.has("exposed")) && component.exposed.length) {
|
|
52
55
|
sections.push(renderMembers("Exposed", component.exposed));
|
|
53
56
|
}
|
|
57
|
+
const optIn = OPT_IN_PACKAGES[component.pkg];
|
|
54
58
|
return `# ${component.name}
|
|
55
59
|
package: \`${component.pkg}\` \xB7 source: \`${component.file}\`
|
|
56
|
-
` + (
|
|
60
|
+
` + (optIn ? `
|
|
61
|
+
${optIn}
|
|
62
|
+
` : "") + (component.description ? `
|
|
57
63
|
${component.description}
|
|
58
64
|
` : "") + `
|
|
59
65
|
${sections.join("\n")}` + renderDocs(component.docs);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mapomodule/mcp",
|
|
3
|
-
"version": "1.0.0-
|
|
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",
|