@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.
- 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 +411 -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 +640 -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 +408 -4
- 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 +69 -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 +475 -0
- package/src/runtime/core/ai-setup/index.ts +29 -0
- package/src/runtime/core/ai-setup/plan.ts +706 -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 +429 -4
- 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
package/README.md
CHANGED
|
@@ -184,21 +184,22 @@ elsewhere. That variant additionally exposes the tools that need the live app. I
|
|
|
184
184
|
## Tools
|
|
185
185
|
|
|
186
186
|
Every tool is prefixed `mapo_` so it stays unambiguous when several MCP servers are connected. All
|
|
187
|
-
are annotated `readOnlyHint: true` except `mapo_scaffold`, which can create files and
|
|
187
|
+
are annotated `readOnlyHint: true` except `mapo_scaffold` and `mapo_ai_setup`, which can create files and say so — no
|
|
188
188
|
tool is ever `destructiveHint`, because nothing here deletes or replaces without an explicit flag.
|
|
189
189
|
|
|
190
|
-
| Tool | What it does
|
|
191
|
-
| ----------------------- |
|
|
192
|
-
| `mapo_search_docs` | Ranked search over the Mapo docs. Returns the matching **sections** with their `path`, `#anchor`, matched symbols and an excerpt — plus the canonical recipe when the query matches a known task. Filters: `section` (`howto`, `guide`, `uikit`, `form`, `modules`, `migration`), `pkg` (`@mapomodule/form`, `uikit`, …), `limit`.
|
|
193
|
-
| `mapo_get_doc` | Returns the exact markdown of a page, or of a single section via `heading` (accepts the heading text or its anchor). Reports the page's full heading list so the assistant can narrow down, and truncates at `maxChars`.
|
|
194
|
-
| `mapo_list_recipes` | The curated task → documentation map. With no argument it opens with what Mapo is and lists everything Mapo does out of the box; with `task` it returns the canonical recipe for a goal.
|
|
195
|
-
| `mapo_component_api` | Props, events, slots and exposed methods of a `Mapo*` component, **extracted from its source**: real types, defaults and JSDoc. Partial names resolve (`list` → `MapoList`); `include` narrows the answer to one section.
|
|
196
|
-
| `mapo_list_field_types` | The form registry: every `type` a `FieldDescriptor` accepts, the component behind it, its `attrs` with types and descriptions, the registry-level default attrs, and a skeleton descriptor to copy.
|
|
197
|
-
| `mapo_composable_api` | The auto-imported composables and stores (`useCrud`, `useMapoAuth`, `useMediaStore`, …) with their real signatures, grouped by package.
|
|
198
|
-
| `mapo_inspect_app` | **Live.** How Mapo is set up in the running app: installed modules and versions, public Mapo configuration, registered field types, available components, routes and locales.
|
|
199
|
-
| `mapo_doctor` | **Live.** Checks the running app for known misconfigurations (module order, missing login route, untouched auth endpoints, locales without catalogs, media endpoints) and returns each problem with its fix.
|
|
200
|
-
| `mapo_scaffold` | Generates pages, forms, custom fields, a login page, a theme override, a backend proxy, menu and media pages in Mapo's own patterns. A dry run unless `write: true`. See [Scaffolding](#scaffolding).
|
|
201
|
-
| `mapo_backend_schema` | Reads the backend's OpenAPI/DRF schema and turns a serializer into field descriptors, with choices, required and read-only flags and the endpoint of every relation. See [From the backend schema to a page](#from-the-backend-schema-to-a-page).
|
|
190
|
+
| Tool | What it does |
|
|
191
|
+
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
192
|
+
| `mapo_search_docs` | Ranked search over the Mapo docs. Returns the matching **sections** with their `path`, `#anchor`, matched symbols and an excerpt — plus the canonical recipe when the query matches a known task. Filters: `section` (`howto`, `guide`, `uikit`, `form`, `modules`, `migration`), `pkg` (`@mapomodule/form`, `uikit`, …), `limit`. |
|
|
193
|
+
| `mapo_get_doc` | Returns the exact markdown of a page, or of a single section via `heading` (accepts the heading text or its anchor). Reports the page's full heading list so the assistant can narrow down, and truncates at `maxChars`. |
|
|
194
|
+
| `mapo_list_recipes` | The curated task → documentation map. With no argument it opens with what Mapo is and lists everything Mapo does out of the box; with `task` it returns the canonical recipe for a goal. |
|
|
195
|
+
| `mapo_component_api` | Props, events, slots and exposed methods of a `Mapo*` component, **extracted from its source**: real types, defaults and JSDoc. Partial names resolve (`list` → `MapoList`); `include` narrows the answer to one section. |
|
|
196
|
+
| `mapo_list_field_types` | The form registry: every `type` a `FieldDescriptor` accepts, the component behind it, its `attrs` with types and descriptions, the registry-level default attrs, and a skeleton descriptor to copy. |
|
|
197
|
+
| `mapo_composable_api` | The auto-imported composables and stores (`useCrud`, `useMapoAuth`, `useMediaStore`, …) with their real signatures, grouped by package. |
|
|
198
|
+
| `mapo_inspect_app` | **Live.** How Mapo is set up in the running app: installed modules and versions, public Mapo configuration, registered field types, available components, routes and locales. |
|
|
199
|
+
| `mapo_doctor` | **Live.** Checks the running app for known misconfigurations (module order, missing login route, untouched auth endpoints, locales without catalogs, media endpoints) and returns each problem with its fix. |
|
|
200
|
+
| `mapo_scaffold` | Generates pages, forms, custom fields, a login page, a theme override, a backend proxy, menu and media pages in Mapo's own patterns. A dry run unless `write: true`. See [Scaffolding](#scaffolding). |
|
|
201
|
+
| `mapo_backend_schema` | Reads the backend's OpenAPI/DRF schema and turns a serializer into field descriptors, with choices, required and read-only flags and the endpoint of every relation. See [From the backend schema to a page](#from-the-backend-schema-to-a-page). |
|
|
202
|
+
| `mapo_ai_setup` | Guides turning on `@mapomodule/ai` and Magic Fill. With no answers it returns the questions to ask the developer, in rounds, every need the module can meet and everything it offers; with the answers, whether the module can do what they need, the `mapo.ai` configuration, the environment variables (names only), where each call's key comes from and how to keep the tokens and their cost in check, the forms' options, the server plugins and the checks. A dry run unless `write: true`; never edits `nuxt.config.ts`, never writes a key. |
|
|
202
203
|
|
|
203
204
|
Typical sequence an assistant follows:
|
|
204
205
|
|
|
@@ -222,8 +223,8 @@ bring it up instead of guessing.
|
|
|
222
223
|
|
|
223
224
|
### Scaffolding
|
|
224
225
|
|
|
225
|
-
`mapo_scaffold`
|
|
226
|
-
narrow:
|
|
226
|
+
`mapo_scaffold` can change the project, as `mapo_ai_setup` can for the AI's server plugins through the same
|
|
227
|
+
guard, so its contract is deliberately narrow:
|
|
227
228
|
|
|
228
229
|
- **Dry run by default.** It returns the files; nothing touches disk until `write: true`.
|
|
229
230
|
- **Field types are validated against the registry.** `fields: ["title:text", "body:wysiwyg"]`
|
|
@@ -276,13 +277,14 @@ offline. drf-spectacular serves YAML by default: the tool detects it and tells y
|
|
|
276
277
|
Slash-commands in clients that support MCP prompts. Each one names the tools to call and their
|
|
277
278
|
order, which is the part a model improvises worst:
|
|
278
279
|
|
|
279
|
-
| Prompt | Workflow
|
|
280
|
-
| ------------------- |
|
|
281
|
-
| `mapo-crud-page` | inspect the app → pick field types → scaffold list + detail → check component APIs
|
|
282
|
-
| `mapo-custom-field` | check no built-in type fits → read the registry contract → scaffold → implement
|
|
283
|
-
| `mapo-debug-form` | doctor → inspect registered types → compare `attrs` → search the docs
|
|
284
|
-
| `mapo-migrate-v1` | read the migration page → verify every symbol against the installed source
|
|
285
|
-
| `mapo-theme` | pick the lightest layer: tokens → scaffold override → slots → MapoOverride
|
|
280
|
+
| Prompt | Workflow |
|
|
281
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
282
|
+
| `mapo-crud-page` | inspect the app → pick field types → scaffold list + detail → check component APIs |
|
|
283
|
+
| `mapo-custom-field` | check no built-in type fits → read the registry contract → scaffold → implement |
|
|
284
|
+
| `mapo-debug-form` | doctor → inspect registered types → compare `attrs` → search the docs |
|
|
285
|
+
| `mapo-migrate-v1` | read the migration page → verify every symbol against the installed source |
|
|
286
|
+
| `mapo-theme` | pick the lightest layer: tokens → scaffold override → slots → MapoOverride |
|
|
287
|
+
| `mapo-ai-setup` | inspect the app → ask what the AI is for, in rounds → say what the module can do → plan → write the plugins after the OK |
|
|
286
288
|
|
|
287
289
|
## Resources
|
|
288
290
|
|
|
@@ -364,7 +366,7 @@ are not installing the `mapomodule` meta-package.
|
|
|
364
366
|
- **No secrets in responses.** The app snapshot exposes public runtime config only; private keys
|
|
365
367
|
appear as key names, never values. Backend credentials are read from the environment and are never
|
|
366
368
|
included in tool output.
|
|
367
|
-
- **Read-only except scaffolding.** Every tool is annotated read-only except `mapo_scaffold`, whose
|
|
369
|
+
- **Read-only except scaffolding.** Every tool is annotated read-only except `mapo_scaffold` and `mapo_ai_setup`, whose
|
|
368
370
|
writing is opt-in (`write: true`), development-only, refuses to escape the project root and never
|
|
369
371
|
overwrites an existing file without `overwrite: true`.
|
|
370
372
|
- The toolkit's `security.allowedOrigins` default is left in place, so cross-site browser clients
|
|
@@ -496,7 +498,7 @@ rule ("always check Mapo docs with the mapo\_\* tools") does the job.
|
|
|
496
498
|
|
|
497
499
|
**A component is missing from `mapo_component_api`**
|
|
498
500
|
The build logs `skipped <Name>` when `vue-component-meta` cannot resolve a component. Only `Mapo*`
|
|
499
|
-
components under `src/runtime/components/` of `uikit` and `form` are extracted.
|
|
501
|
+
components under `src/runtime/components/` of `uikit` and `form` are extracted, and the ones `@mapomodule/ai` registers for apps (its settings page and Magic Fill's parts).
|
|
500
502
|
|
|
501
503
|
---
|
|
502
504
|
|
package/dist/build.mjs
CHANGED
|
@@ -8,7 +8,18 @@ import { pathToFileURL } from 'node:url';
|
|
|
8
8
|
|
|
9
9
|
const COMPONENT_PACKAGES = [
|
|
10
10
|
{ pkg: "@mapomodule/uikit", dir: "packages/@mapomodule/uikit" },
|
|
11
|
-
{ pkg: "@mapomodule/form", dir: "packages/@mapomodule/form" }
|
|
11
|
+
{ pkg: "@mapomodule/form", dir: "packages/@mapomodule/form" },
|
|
12
|
+
{
|
|
13
|
+
pkg: "@mapomodule/ai",
|
|
14
|
+
dir: "packages/@mapomodule/ai",
|
|
15
|
+
only: [
|
|
16
|
+
"MapoAiSettings",
|
|
17
|
+
"MapoAiMagicFillAction",
|
|
18
|
+
"MapoAiMagicFillBanner",
|
|
19
|
+
"MapoAiMagicFillPanel",
|
|
20
|
+
"MapoAiMagicFillPreview"
|
|
21
|
+
]
|
|
22
|
+
}
|
|
12
23
|
];
|
|
13
24
|
const MAX_TYPE_LENGTH$1 = 160;
|
|
14
25
|
function shortenType(type) {
|
|
@@ -44,12 +55,15 @@ function toMembers(entries, withType = true) {
|
|
|
44
55
|
}
|
|
45
56
|
function extractComponents(repoRoot, docsFor) {
|
|
46
57
|
const components = [];
|
|
47
|
-
for (const { pkg, dir } of COMPONENT_PACKAGES) {
|
|
58
|
+
for (const { pkg, dir, only } of COMPONENT_PACKAGES) {
|
|
48
59
|
const packageRoot = join(repoRoot, dir);
|
|
49
60
|
const tsconfig = join(packageRoot, "tsconfig.json");
|
|
50
61
|
const componentsRoot = join(packageRoot, "src", "runtime", "components");
|
|
62
|
+
const isListed = (file) => !only || only.includes(
|
|
63
|
+
file.split("/").pop().replace(/\.vue$/, "")
|
|
64
|
+
);
|
|
51
65
|
const files = collectVueFiles(componentsRoot).filter(
|
|
52
|
-
(file) => /\/Mapo[A-Z][^/]*\.vue$/.test(file)
|
|
66
|
+
(file) => /\/Mapo[A-Z][^/]*\.vue$/.test(file) && isListed(file)
|
|
53
67
|
);
|
|
54
68
|
if (!files.length || !existsSync(tsconfig)) continue;
|
|
55
69
|
const checker = createChecker(tsconfig, {
|
|
@@ -90,6 +104,51 @@ function shorten$1(value) {
|
|
|
90
104
|
const collapsed = value.replace(/\s+/g, " ").trim();
|
|
91
105
|
return collapsed.length > MAX_SIGNATURE_LENGTH ? `${collapsed.slice(0, MAX_SIGNATURE_LENGTH)}\u2026` : collapsed;
|
|
92
106
|
}
|
|
107
|
+
function addImportsArguments(source) {
|
|
108
|
+
const calls = [];
|
|
109
|
+
for (const match of source.matchAll(/\baddImports\s*\(/g)) {
|
|
110
|
+
const start = (match.index ?? 0) + match[0].length;
|
|
111
|
+
calls.push(source.slice(start, closingParenthesis(source, start)));
|
|
112
|
+
}
|
|
113
|
+
return calls;
|
|
114
|
+
}
|
|
115
|
+
function closingParenthesis(source, from) {
|
|
116
|
+
let depth = 1;
|
|
117
|
+
let at = from;
|
|
118
|
+
while (at < source.length) {
|
|
119
|
+
const char = source[at];
|
|
120
|
+
const next = source[at + 1];
|
|
121
|
+
if (char === '"' || char === "'" || char === "`") {
|
|
122
|
+
at = afterString(source, at, char);
|
|
123
|
+
continue;
|
|
124
|
+
}
|
|
125
|
+
if (char === "/" && next === "/") {
|
|
126
|
+
const end = source.indexOf("\n", at);
|
|
127
|
+
at = end === -1 ? source.length : end;
|
|
128
|
+
continue;
|
|
129
|
+
}
|
|
130
|
+
if (char === "/" && next === "*") {
|
|
131
|
+
const end = source.indexOf("*/", at + 2);
|
|
132
|
+
at = end === -1 ? source.length : end + 2;
|
|
133
|
+
continue;
|
|
134
|
+
}
|
|
135
|
+
if (char === "(") depth++;
|
|
136
|
+
if (char === ")") depth--;
|
|
137
|
+
if (depth === 0) return at;
|
|
138
|
+
at++;
|
|
139
|
+
}
|
|
140
|
+
return source.length;
|
|
141
|
+
}
|
|
142
|
+
function afterString(source, at, quote) {
|
|
143
|
+
let index = at + 1;
|
|
144
|
+
while (index < source.length) {
|
|
145
|
+
const char = source[index];
|
|
146
|
+
if (char === "\\") index += 2;
|
|
147
|
+
else if (char === quote) return index + 1;
|
|
148
|
+
else index++;
|
|
149
|
+
}
|
|
150
|
+
return source.length;
|
|
151
|
+
}
|
|
93
152
|
function collectCandidates(repoRoot) {
|
|
94
153
|
const packagesDir = join(repoRoot, PACKAGES_ROOT);
|
|
95
154
|
if (!existsSync(packagesDir)) return [];
|
|
@@ -100,7 +159,10 @@ function collectCandidates(repoRoot) {
|
|
|
100
159
|
if (!existsSync(moduleFile)) continue;
|
|
101
160
|
const source = readFileSync(moduleFile, "utf-8");
|
|
102
161
|
const packageRoot = join(packagesDir, entry.name);
|
|
103
|
-
|
|
162
|
+
const entries = addImportsArguments(source).flatMap((call) => [
|
|
163
|
+
...call.matchAll(ADD_IMPORT_ENTRY)
|
|
164
|
+
]);
|
|
165
|
+
for (const match of entries) {
|
|
104
166
|
const [, name, from] = match;
|
|
105
167
|
if (!name || !from) continue;
|
|
106
168
|
const base = join(packageRoot, "src", from.replace(/^\.\//, ""));
|
package/dist/cli.mjs
CHANGED
|
@@ -13,6 +13,7 @@ import { appTools } from '../dist/runtime/core/tools/app.js';
|
|
|
13
13
|
import { docsTools } from '../dist/runtime/core/tools/docs.js';
|
|
14
14
|
import { scaffoldTools } from '../dist/runtime/core/tools/scaffold.js';
|
|
15
15
|
import { backendTools } from '../dist/runtime/core/tools/backend.js';
|
|
16
|
+
import { aiTools } from '../dist/runtime/core/tools/ai.js';
|
|
16
17
|
import { PROMPTS } from '../dist/runtime/core/prompts.js';
|
|
17
18
|
import { resolveKnowledgeDir, loadApiKnowledge, loadDocsKnowledge } from '../dist/runtime/core/knowledge.js';
|
|
18
19
|
|
|
@@ -28,7 +29,13 @@ function readVersion() {
|
|
|
28
29
|
}
|
|
29
30
|
const DEFAULT_APP_URL = mcpEndpointUrl("http://localhost:3000");
|
|
30
31
|
function staticTools() {
|
|
31
|
-
return [
|
|
32
|
+
return [
|
|
33
|
+
...docsTools,
|
|
34
|
+
...apiTools,
|
|
35
|
+
...scaffoldTools,
|
|
36
|
+
...backendTools,
|
|
37
|
+
...aiTools
|
|
38
|
+
];
|
|
32
39
|
}
|
|
33
40
|
function createToolContext(knowledgeDir, rootDir, schemaUrl = null) {
|
|
34
41
|
let docs = null;
|