@mapomodule/mcp 1.0.0-beta.1 → 1.0.0-beta.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 +71 -41
- package/dist/cli.d.mts +1 -1
- package/dist/cli.d.ts +1 -1
- package/dist/cli.mjs +17 -6
- package/dist/knowledge/api.json +1 -1
- package/dist/knowledge/docs.json +1 -1
- package/dist/module.json +1 -1
- package/dist/module.mjs +5 -2
- package/dist/runtime/core/endpoint.d.ts +0 -0
- package/dist/runtime/core/endpoint.js +8 -0
- package/dist/runtime/core/indexer.js +2 -1
- package/dist/runtime/core/instructions.d.ts +0 -0
- package/dist/runtime/core/instructions.js +10 -0
- package/dist/runtime/core/overview.d.ts +0 -0
- package/dist/runtime/core/overview.js +15 -0
- package/dist/runtime/core/recipes.js +202 -3
- package/dist/runtime/core/resources.js +4 -0
- package/dist/runtime/core/tools/app.js +1 -1
- package/dist/runtime/core/tools/docs.js +6 -2
- package/dist/runtime/mcp/handlers/mapo/index.js +2 -8
- package/dist/runtime/mcp/handlers/mapo/resources/overview.js +20 -0
- package/package.json +1 -1
- package/src/__tests__/cli.test.ts +16 -0
- package/src/__tests__/endpoint.test.ts +31 -0
- package/src/__tests__/knowledge.test.ts +16 -0
- package/src/__tests__/overview.test.ts +105 -0
- package/src/__tests__/recipes.test.ts +11 -0
- package/src/cli.ts +22 -11
- package/src/module.ts +7 -8
- package/src/runtime/core/endpoint.ts +27 -0
- package/src/runtime/core/indexer.ts +10 -4
- package/src/runtime/core/instructions.ts +18 -0
- package/src/runtime/core/overview.ts +44 -0
- package/src/runtime/core/recipes.ts +213 -0
- package/src/runtime/core/resources.ts +6 -0
- package/src/runtime/core/tools/app.ts +4 -3
- package/src/runtime/core/tools/docs.ts +5 -2
- package/src/runtime/mcp/handlers/mapo/index.ts +2 -8
- package/src/runtime/mcp/handlers/mapo/resources/overview.ts +22 -0
package/dist/module.json
CHANGED
package/dist/module.mjs
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { existsSync, readFileSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
3
|
import { defineNuxtModule, logger, createResolver, hasNuxtModule, installModule, addServerTemplate } from '@nuxt/kit';
|
|
4
|
+
import { mcpEndpointUrl } from '../dist/runtime/core/endpoint.js';
|
|
4
5
|
|
|
5
|
-
const HANDLER_NAME = "mapo";
|
|
6
6
|
function readDefaultFieldTypes(knowledgeDir) {
|
|
7
7
|
if (!knowledgeDir) return [];
|
|
8
8
|
const file = join(knowledgeDir, "api.json");
|
|
@@ -113,7 +113,10 @@ const module$1 = defineNuxtModule({
|
|
|
113
113
|
getContents: () => `export default ${JSON.stringify(buildContext())}`
|
|
114
114
|
});
|
|
115
115
|
log.info(
|
|
116
|
-
`MCP server available at ${
|
|
116
|
+
`MCP server available at ${mcpEndpointUrl(
|
|
117
|
+
nuxt.options.devServer?.url ?? "http://localhost:3000",
|
|
118
|
+
nuxt.options.app.baseURL
|
|
119
|
+
)}`
|
|
117
120
|
);
|
|
118
121
|
}
|
|
119
122
|
});
|
|
File without changes
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export const MCP_HANDLER_NAME = "mapo";
|
|
2
|
+
export function mcpEndpointPath(baseURL = "/") {
|
|
3
|
+
const base = `/${baseURL.replace(/^\.?\/+/, "")}`.replace(/\/*$/, "/");
|
|
4
|
+
return `${base}mcp/${MCP_HANDLER_NAME}`;
|
|
5
|
+
}
|
|
6
|
+
export function mcpEndpointUrl(origin, baseURL = "/") {
|
|
7
|
+
return `${origin.replace(/\/+$/, "")}${mcpEndpointPath(baseURL)}`;
|
|
8
|
+
}
|
|
@@ -6,10 +6,11 @@ const MAX_CHUNK_CHARS = 3500;
|
|
|
6
6
|
const EXCLUDED_DIRS = /* @__PURE__ */ new Set([
|
|
7
7
|
"node_modules",
|
|
8
8
|
"roadmap",
|
|
9
|
+
"contributing",
|
|
9
10
|
".vitepress",
|
|
10
11
|
"dist"
|
|
11
12
|
]);
|
|
12
|
-
const EXCLUDED_FILES = /* @__PURE__ */ new Set(["DECISIONS.md"]);
|
|
13
|
+
const EXCLUDED_FILES = /* @__PURE__ */ new Set(["DECISIONS.md", "AGENTS.md", "CLAUDE.md"]);
|
|
13
14
|
const BOOST = { heading: 3, title: 2, tags: 3, text: 1 };
|
|
14
15
|
const PKG_BY_PREFIX = [
|
|
15
16
|
["uikit/form", "@mapomodule/form"],
|
|
File without changes
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
export const MAPO_INSTRUCTIONS = `Mapo v2 is a Nuxt 4 admin framework (Vue 3, Nuxt UI v4, Pinia, @nuxtjs/i18n) for building backoffices on a REST API that follows Django REST Framework conventions. An app registers "@nuxt/ui" and then "mapomodule", and configures everything under the \`mapo\` key. The packages: @mapomodule/core ($mapoFetch, useCrud, useMapoAuth, the auth/permissions/roles middleware), store (Pinia stores), uikit (layouts, sidebar, MapoList, MapoDetail, media and menu managers, theming, MapoOverride), form (FieldDescriptor arrays rendered through a field registry, useMapoForm), i18n and utils. A page is declarative: definePageMeta (layout, middleware, label, icon, permissions) plus one Mapo component with props; the sidebar is built from route metadata. Mapo v2 is a rewrite of v1 (Nuxt 2, Vuex, Axios): v1 APIs do not exist here.
|
|
2
|
+
|
|
3
|
+
Workflow:
|
|
4
|
+
1. New to the project or the task? Read the overview: the mapo://overview resource, or mapo_get_doc({ path: "guide/concepts.md" }).
|
|
5
|
+
2. Call mapo_inspect_app before writing code for this project: it reports the Mapo modules installed, the field types actually registered, the components available and the real configuration. mapo_doctor explains anything that looks misconfigured. Both need the app's dev server.
|
|
6
|
+
3. Start from mapo_list_recipes to find the canonical approach: Mapo ships a lot out of the box, and each recipe names the page that documents it.
|
|
7
|
+
4. Use mapo_search_docs for anything the recipes do not cover, then mapo_get_doc to read the exact section. Prefer these over recalling Mapo APIs from memory.
|
|
8
|
+
5. Never invent component props, slots or field types: look them up with mapo_component_api, mapo_list_field_types and mapo_composable_api, which read the installed source.
|
|
9
|
+
6. mapo_backend_schema maps the backend's OpenAPI schema to field descriptors, and mapo_scaffold generates pages, fields and overrides in Mapo's own patterns (a dry run unless asked to write).
|
|
10
|
+
7. Cite the doc path you relied on when you produce code.`;
|
|
File without changes
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { OVERVIEW_DOC, OVERVIEW_URI, renderDocResource } from "./resources.js";
|
|
2
|
+
import { getDoc } from "./search.js";
|
|
3
|
+
const SUMMARY_HEADING = "What Mapo is";
|
|
4
|
+
export function renderOverview(knowledge) {
|
|
5
|
+
return renderDocResource(knowledge, OVERVIEW_DOC) ?? `The overview page \`${OVERVIEW_DOC}\` is not in this knowledge base. Call mapo_list_recipes or mapo_search_docs instead.`;
|
|
6
|
+
}
|
|
7
|
+
export function overviewSummary(knowledge) {
|
|
8
|
+
const doc = getDoc(knowledge, OVERVIEW_DOC, { heading: SUMMARY_HEADING });
|
|
9
|
+
if (!doc?.headings.includes(SUMMARY_HEADING)) return null;
|
|
10
|
+
const prose = doc.content.replace(/^#+ .*\n+/, "").split(/\n```/)[0].trim().replace(/\n\n[^\n]*:$/, "");
|
|
11
|
+
if (!prose) return null;
|
|
12
|
+
return `${prose}
|
|
13
|
+
|
|
14
|
+
Full overview: the \`${OVERVIEW_URI}\` resource, or mapo_get_doc({ path: "${OVERVIEW_DOC}" }).`;
|
|
15
|
+
}
|
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
import { tokenize } from "./tokenize.js";
|
|
2
2
|
export const RECIPES = [
|
|
3
|
+
{
|
|
4
|
+
id: "concepts",
|
|
5
|
+
task: "Understand how Mapo fits together",
|
|
6
|
+
keywords: [
|
|
7
|
+
"overview",
|
|
8
|
+
"architecture",
|
|
9
|
+
"packages",
|
|
10
|
+
"concepts",
|
|
11
|
+
"mental model",
|
|
12
|
+
"how it works"
|
|
13
|
+
],
|
|
14
|
+
doc: "guide/concepts.md",
|
|
15
|
+
seeAlso: ["guide/architecture-flows.md", "guide/getting-started.md"],
|
|
16
|
+
summary: "The packages, the backend contract, declarative pages, the form engine and the customization layers."
|
|
17
|
+
},
|
|
3
18
|
{
|
|
4
19
|
id: "first-admin-page",
|
|
5
20
|
task: "Create the first admin page",
|
|
@@ -10,7 +25,8 @@ export const RECIPES = [
|
|
|
10
25
|
"layout",
|
|
11
26
|
"definePageMeta",
|
|
12
27
|
"dashboard",
|
|
13
|
-
"sidebar entry"
|
|
28
|
+
"sidebar entry",
|
|
29
|
+
"install"
|
|
14
30
|
],
|
|
15
31
|
doc: "howto/first-admin-page.md",
|
|
16
32
|
seeAlso: ["guide/getting-started.md"],
|
|
@@ -216,7 +232,8 @@ export const RECIPES = [
|
|
|
216
232
|
"colors",
|
|
217
233
|
"dark mode",
|
|
218
234
|
"tokens",
|
|
219
|
-
"design"
|
|
235
|
+
"design",
|
|
236
|
+
"primary color"
|
|
220
237
|
],
|
|
221
238
|
doc: "howto/theming.md",
|
|
222
239
|
seeAlso: ["uikit/theming.md"],
|
|
@@ -248,7 +265,10 @@ export const RECIPES = [
|
|
|
248
265
|
"drf",
|
|
249
266
|
"proxy",
|
|
250
267
|
"useCrud",
|
|
251
|
-
"rest"
|
|
268
|
+
"rest",
|
|
269
|
+
"fastapi",
|
|
270
|
+
"laravel",
|
|
271
|
+
"jwt"
|
|
252
272
|
],
|
|
253
273
|
doc: "howto/backend-integration.md",
|
|
254
274
|
seeAlso: ["modules/camomilla.md", "modules/api.md"],
|
|
@@ -260,6 +280,185 @@ export const RECIPES = [
|
|
|
260
280
|
keywords: ["v1", "upgrade", "legacy", "vuex", "axios", "breaking changes"],
|
|
261
281
|
doc: "migration/v1-to-v2.md",
|
|
262
282
|
summary: "What changed between Mapo v1 and v2 and how to port each piece."
|
|
283
|
+
},
|
|
284
|
+
{
|
|
285
|
+
id: "conditional-fields",
|
|
286
|
+
task: "Show or hide form fields based on other values",
|
|
287
|
+
keywords: [
|
|
288
|
+
"visible",
|
|
289
|
+
"conditional",
|
|
290
|
+
"whenAny",
|
|
291
|
+
"matchesField",
|
|
292
|
+
"depends on",
|
|
293
|
+
"progressive disclosure"
|
|
294
|
+
],
|
|
295
|
+
doc: "uikit/form/progressive-disclosure.md",
|
|
296
|
+
seeAlso: ["howto/form-advanced.md"],
|
|
297
|
+
summary: "visible and show predicates built with the when/matchesField matcher helpers."
|
|
298
|
+
},
|
|
299
|
+
{
|
|
300
|
+
id: "form-draft",
|
|
301
|
+
task: "Autosave form drafts",
|
|
302
|
+
keywords: ["draft", "autosave", "useFormDraft", "restore", "unsaved"],
|
|
303
|
+
doc: "uikit/form/draft.md",
|
|
304
|
+
seeAlso: ["howto/crud-detail.md"],
|
|
305
|
+
summary: "useFormDraft keeps unsaved edits in localStorage and offers to restore them on the next visit."
|
|
306
|
+
},
|
|
307
|
+
{
|
|
308
|
+
id: "schema-to-form",
|
|
309
|
+
task: "Generate form fields from a JSON Schema",
|
|
310
|
+
keywords: [
|
|
311
|
+
"json schema",
|
|
312
|
+
"useFormFromSchema",
|
|
313
|
+
"openapi",
|
|
314
|
+
"drf-spectacular",
|
|
315
|
+
"pydantic",
|
|
316
|
+
"serializer"
|
|
317
|
+
],
|
|
318
|
+
doc: "uikit/form/schema-to-form.md",
|
|
319
|
+
seeAlso: ["howto/form-advanced.md"],
|
|
320
|
+
summary: "useFormFromSchema turns a JSON Schema (DRF, Pydantic) into field descriptors you can extend."
|
|
321
|
+
},
|
|
322
|
+
{
|
|
323
|
+
id: "form-slots",
|
|
324
|
+
task: "Customize how a form field renders with slots",
|
|
325
|
+
keywords: [
|
|
326
|
+
"field slot",
|
|
327
|
+
"hint",
|
|
328
|
+
"above",
|
|
329
|
+
"below",
|
|
330
|
+
"replace a field",
|
|
331
|
+
"group slot"
|
|
332
|
+
],
|
|
333
|
+
doc: "uikit/form/slots.md",
|
|
334
|
+
summary: "Per-field, per-group and global slots that wrap, extend or replace how fields render."
|
|
335
|
+
},
|
|
336
|
+
{
|
|
337
|
+
id: "focus-mode",
|
|
338
|
+
task: "Focus mode for repeater items and long fields",
|
|
339
|
+
keywords: [
|
|
340
|
+
"focus mode",
|
|
341
|
+
"useFocusMode",
|
|
342
|
+
"fullscreen",
|
|
343
|
+
"field expand",
|
|
344
|
+
"MapoFocusPortal",
|
|
345
|
+
"breadcrumb"
|
|
346
|
+
],
|
|
347
|
+
doc: "uikit/form/focus-mode.md",
|
|
348
|
+
seeAlso: ["uikit/form/field-expand.md"],
|
|
349
|
+
summary: "Open a repeater item in a fullscreen view, or expand a single field in place."
|
|
350
|
+
},
|
|
351
|
+
{
|
|
352
|
+
id: "sidebar-navigation",
|
|
353
|
+
task: "Build the sidebar navigation",
|
|
354
|
+
keywords: [
|
|
355
|
+
"sidebar",
|
|
356
|
+
"nested menu",
|
|
357
|
+
"parent",
|
|
358
|
+
"icon",
|
|
359
|
+
"label",
|
|
360
|
+
"sidebarFooter",
|
|
361
|
+
"route meta"
|
|
362
|
+
],
|
|
363
|
+
doc: "uikit/sidebar.md",
|
|
364
|
+
seeAlso: ["howto/first-admin-page.md"],
|
|
365
|
+
summary: "Route metadata (label, icon, parent, sidebarFooter) builds the sidebar tree, with no menu config."
|
|
366
|
+
},
|
|
367
|
+
{
|
|
368
|
+
id: "login-page",
|
|
369
|
+
task: "Customize the login page",
|
|
370
|
+
keywords: [
|
|
371
|
+
"MapoLogin",
|
|
372
|
+
"sign in",
|
|
373
|
+
"login form",
|
|
374
|
+
"login redirect",
|
|
375
|
+
"branding"
|
|
376
|
+
],
|
|
377
|
+
doc: "uikit/login.md",
|
|
378
|
+
seeAlso: ["howto/auth-permissions.md"],
|
|
379
|
+
summary: "The built-in /login page: its slots, the redirect after login and error handling."
|
|
380
|
+
},
|
|
381
|
+
{
|
|
382
|
+
id: "imports",
|
|
383
|
+
task: "Know what to import and from where",
|
|
384
|
+
keywords: [
|
|
385
|
+
"import",
|
|
386
|
+
"auto-import",
|
|
387
|
+
"import type",
|
|
388
|
+
"mapomodule/types",
|
|
389
|
+
"TS2307",
|
|
390
|
+
"cannot find module"
|
|
391
|
+
],
|
|
392
|
+
doc: "guide/imports.md",
|
|
393
|
+
seeAlso: ["guide/known-limitations.md"],
|
|
394
|
+
summary: "Composables and components are auto-imported, types come from mapomodule/types, utils are imported explicitly."
|
|
395
|
+
},
|
|
396
|
+
{
|
|
397
|
+
id: "troubleshooting",
|
|
398
|
+
task: "Troubleshoot compatibility and version problems",
|
|
399
|
+
keywords: [
|
|
400
|
+
"module order",
|
|
401
|
+
"nuxt ui first",
|
|
402
|
+
"error",
|
|
403
|
+
"tested versions",
|
|
404
|
+
"peer dependencies",
|
|
405
|
+
"dedupe",
|
|
406
|
+
"duplicate vue"
|
|
407
|
+
],
|
|
408
|
+
doc: "guide/compatibility.md",
|
|
409
|
+
seeAlso: ["guide/known-limitations.md"],
|
|
410
|
+
summary: "Tested versions, what to declare in the app, module order and the common problems."
|
|
411
|
+
},
|
|
412
|
+
{
|
|
413
|
+
id: "utils",
|
|
414
|
+
task: "Merge, diff and format with the utility helpers",
|
|
415
|
+
keywords: [
|
|
416
|
+
"deepMerge",
|
|
417
|
+
"objectDiff",
|
|
418
|
+
"slugify",
|
|
419
|
+
"formatDate",
|
|
420
|
+
"humanFileSize",
|
|
421
|
+
"normalizeEndpoint",
|
|
422
|
+
"debounce"
|
|
423
|
+
],
|
|
424
|
+
doc: "modules/utils.md",
|
|
425
|
+
seeAlso: ["modules/api.md"],
|
|
426
|
+
summary: "Typed helpers from @mapomodule/utils: merging, diffing, formatting, slugs and endpoints."
|
|
427
|
+
},
|
|
428
|
+
{
|
|
429
|
+
id: "camomilla",
|
|
430
|
+
task: "Use the Camomilla CMS integration",
|
|
431
|
+
keywords: [
|
|
432
|
+
"camomilla",
|
|
433
|
+
"path rewrite",
|
|
434
|
+
"session cookie",
|
|
435
|
+
"django cms",
|
|
436
|
+
"media adapter"
|
|
437
|
+
],
|
|
438
|
+
doc: "modules/camomilla.md",
|
|
439
|
+
seeAlso: ["howto/backend-integration.md"],
|
|
440
|
+
summary: "The Camomilla integration: proxy options, path rewriting, the media adapter and session cookies."
|
|
441
|
+
},
|
|
442
|
+
{
|
|
443
|
+
id: "ai-assistant",
|
|
444
|
+
task: "Set up an AI coding assistant",
|
|
445
|
+
keywords: ["mcp", "claude", "copilot", "cursor", "agent", "mapo-mcp"],
|
|
446
|
+
doc: "howto/ai-assistant.md",
|
|
447
|
+
seeAlso: ["modules/mcp.md"],
|
|
448
|
+
summary: "Connect Claude Code, Copilot or Cursor to the Mapo MCP server over stdio or HTTP."
|
|
449
|
+
},
|
|
450
|
+
{
|
|
451
|
+
id: "form-devtools",
|
|
452
|
+
task: "Inspect forms in Nuxt DevTools",
|
|
453
|
+
keywords: [
|
|
454
|
+
"devtools",
|
|
455
|
+
"debug form",
|
|
456
|
+
"registry warning",
|
|
457
|
+
"inspect",
|
|
458
|
+
"_mapo"
|
|
459
|
+
],
|
|
460
|
+
doc: "uikit/form/devtools.md",
|
|
461
|
+
summary: "The Mapo Forms tab: the module config and the live field registry your forms read."
|
|
263
462
|
}
|
|
264
463
|
];
|
|
265
464
|
const TASK_WEIGHT = 1.5;
|
|
@@ -4,6 +4,8 @@ export const DOCS_URI_PREFIX = "mapo://docs/";
|
|
|
4
4
|
export const FIELD_URI_PREFIX = "mapo://fields/";
|
|
5
5
|
export const INDEX_URI = "mapo://knowledge/index";
|
|
6
6
|
export const MANIFEST_URI = "mapo://app/manifest";
|
|
7
|
+
export const OVERVIEW_URI = "mapo://overview";
|
|
8
|
+
export const OVERVIEW_DOC = "guide/concepts.md";
|
|
7
9
|
export function renderKnowledgeIndex(knowledge, api) {
|
|
8
10
|
const pages = listDocs(knowledge).map(
|
|
9
11
|
(doc) => `- \`${doc.path}\` \u2014 ${doc.title} (${doc.headings.length} sections)`
|
|
@@ -19,6 +21,8 @@ export function renderKnowledgeIndex(knowledge, api) {
|
|
|
19
21
|
"",
|
|
20
22
|
`Generated ${knowledge.generatedAt}.`,
|
|
21
23
|
"",
|
|
24
|
+
`Start with the overview: the \`${OVERVIEW_URI}\` resource (\`${OVERVIEW_DOC}\`).`,
|
|
25
|
+
"",
|
|
22
26
|
"## Recipes",
|
|
23
27
|
recipes,
|
|
24
28
|
"",
|
|
@@ -7,7 +7,7 @@ const READ_ONLY = {
|
|
|
7
7
|
idempotentHint: true,
|
|
8
8
|
openWorldHint: false
|
|
9
9
|
};
|
|
10
|
-
const NO_APP = "This tool needs the running app and is only served over HTTP.\n\nStart the dev server (`pnpm dev`) and point the client at `http://localhost:3000/mcp/mapo
|
|
10
|
+
const NO_APP = "This tool needs the running app and is only served over HTTP.\n\nStart the dev server (`pnpm dev`) and point the client at the URL it prints at startup: `http://localhost:3000/mcp/mapo` by default, under the app's `app.baseURL` when it has one. The stdio server (`mapo-mcp serve`) knows the framework and its documentation, but not the project using it.";
|
|
11
11
|
function renderModules(manifest) {
|
|
12
12
|
const installed = manifest.modules.map(
|
|
13
13
|
(module) => `- \`${module.name}\`${module.version ? ` @ ${module.version}` : ""}`
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { z } from "zod";
|
|
2
|
+
import { overviewSummary } from "../overview.js";
|
|
2
3
|
import { matchRecipes, RECIPES } from "../recipes.js";
|
|
3
4
|
import { getDoc, searchDocs } from "../search.js";
|
|
4
5
|
import { defineMapoTool } from "../tool-spec.js";
|
|
@@ -125,7 +126,7 @@ export const listRecipesTool = defineMapoTool({
|
|
|
125
126
|
openWorldHint: false
|
|
126
127
|
},
|
|
127
128
|
inputExamples: [{}, { task: "upload images and pick them in a form" }],
|
|
128
|
-
run: (args) => {
|
|
129
|
+
run: (args, context) => {
|
|
129
130
|
if (args.task) {
|
|
130
131
|
const matches = matchRecipes(args.task, 3);
|
|
131
132
|
if (!matches.length) {
|
|
@@ -133,10 +134,13 @@ export const listRecipesTool = defineMapoTool({
|
|
|
133
134
|
}
|
|
134
135
|
return `${renderRecipes(matches)}Read the page with mapo_get_doc({ path }).`;
|
|
135
136
|
}
|
|
137
|
+
const summary = overviewSummary(context.knowledge());
|
|
136
138
|
const lines = RECIPES.map(
|
|
137
139
|
(recipe) => `- **${recipe.task}** \u2192 \`${recipe.doc}\` \u2014 ${recipe.summary}`
|
|
138
140
|
);
|
|
139
|
-
return `${
|
|
141
|
+
return `${summary ? `${summary}
|
|
142
|
+
|
|
143
|
+
` : ""}${RECIPES.length} Mapo recipes:
|
|
140
144
|
|
|
141
145
|
${lines.join("\n")}
|
|
142
146
|
|
|
@@ -1,13 +1,7 @@
|
|
|
1
1
|
import { defineMcpHandler } from "@nuxtjs/mcp-toolkit/server";
|
|
2
|
+
import { MAPO_INSTRUCTIONS } from "../../../core/instructions.js";
|
|
2
3
|
export default defineMcpHandler({
|
|
3
4
|
name: "mapo",
|
|
4
5
|
description: "Mapo admin framework: docs, component and field APIs, app introspection, scaffolding.",
|
|
5
|
-
instructions:
|
|
6
|
-
|
|
7
|
-
Workflow:
|
|
8
|
-
1. Call mapo_inspect_app before writing code for this project: it reports the mapo modules installed, the field types actually registered, the components available and the real configuration. mapo_doctor explains anything that looks misconfigured.
|
|
9
|
-
2. Start from mapo_list_recipes to find the canonical approach for the task \u2014 Mapo ships a lot out of the box, and the recipe names the page that documents it.
|
|
10
|
-
3. Use mapo_search_docs for anything the recipes do not cover, then mapo_get_doc to read the exact section. Prefer these over recalling Mapo APIs from memory: Mapo v2 differs substantially from v1.
|
|
11
|
-
4. Never invent component props, slots or field types: look them up with mapo_component_api, mapo_list_field_types and mapo_composable_api, which read the installed source.
|
|
12
|
-
5. Cite the doc path you relied on when you produce code.`
|
|
6
|
+
instructions: MAPO_INSTRUCTIONS
|
|
13
7
|
});
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { defineMcpResource } from "@nuxtjs/mcp-toolkit/server";
|
|
2
|
+
import { renderOverview } from "../../../../core/overview.js";
|
|
3
|
+
import { OVERVIEW_URI } from "../../../../core/resources.js";
|
|
4
|
+
import { useDocsKnowledge } from "../../../../nitro/context.js";
|
|
5
|
+
export default defineMcpResource({
|
|
6
|
+
name: "mapo-overview",
|
|
7
|
+
title: "Mapo overview",
|
|
8
|
+
description: "How Mapo fits together: the packages, the backend contract, declarative pages, the form engine and the customization layers.",
|
|
9
|
+
uri: OVERVIEW_URI,
|
|
10
|
+
metadata: { mimeType: "text/markdown" },
|
|
11
|
+
handler: (uri) => ({
|
|
12
|
+
contents: [
|
|
13
|
+
{
|
|
14
|
+
uri: uri.toString(),
|
|
15
|
+
mimeType: "text/markdown",
|
|
16
|
+
text: renderOverview(useDocsKnowledge())
|
|
17
|
+
}
|
|
18
|
+
]
|
|
19
|
+
})
|
|
20
|
+
});
|
package/package.json
CHANGED
|
@@ -63,10 +63,26 @@ describeBuilt("mapo-mcp stdio server", () => {
|
|
|
63
63
|
const uris = resources.map((resource) => resource.uri);
|
|
64
64
|
|
|
65
65
|
expect(uris).toContain("mapo://knowledge/index");
|
|
66
|
+
expect(uris).toContain("mapo://overview");
|
|
66
67
|
expect(uris.some((uri) => uri.startsWith("mapo://docs/"))).toBe(true);
|
|
67
68
|
expect(uris.some((uri) => uri.startsWith("mapo://fields/"))).toBe(true);
|
|
68
69
|
});
|
|
69
70
|
|
|
71
|
+
it("sends the shared instructions on initialize", () => {
|
|
72
|
+
const instructions = client.getInstructions() ?? "";
|
|
73
|
+
|
|
74
|
+
expect(instructions).toContain("mapo_list_recipes");
|
|
75
|
+
expect(instructions).toContain("mapo://overview");
|
|
76
|
+
});
|
|
77
|
+
|
|
78
|
+
it("serves the overview page as a resource", async () => {
|
|
79
|
+
const result = await client.readResource({ uri: "mapo://overview" });
|
|
80
|
+
const content = result.contents[0] as TextResourceContent;
|
|
81
|
+
|
|
82
|
+
expect(content.mimeType).toBe("text/markdown");
|
|
83
|
+
expect(content.text).toContain("# Concepts");
|
|
84
|
+
});
|
|
85
|
+
|
|
70
86
|
it("reads a documentation page through its resource URI", async () => {
|
|
71
87
|
const result = await client.readResource({
|
|
72
88
|
uri: "mapo://docs/howto/crud-list.md",
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { describe, expect, it } from "vitest";
|
|
2
|
+
import { mcpEndpointPath, mcpEndpointUrl } from "../runtime/core/endpoint.js";
|
|
3
|
+
|
|
4
|
+
describe("mcpEndpointPath", () => {
|
|
5
|
+
it("is /mcp/mapo for an app served from the root", () => {
|
|
6
|
+
expect(mcpEndpointPath()).toBe("/mcp/mapo");
|
|
7
|
+
expect(mcpEndpointPath("/")).toBe("/mcp/mapo");
|
|
8
|
+
expect(mcpEndpointPath("./")).toBe("/mcp/mapo");
|
|
9
|
+
});
|
|
10
|
+
|
|
11
|
+
// Regression: the startup log used to print /mcp/mapo for an app under a
|
|
12
|
+
// base URL, where that path redirects and the handler answers below the base.
|
|
13
|
+
it("sits under app.baseURL, which Nitro puts in front of every server route", () => {
|
|
14
|
+
expect(mcpEndpointPath("/backoffice/")).toBe("/backoffice/mcp/mapo");
|
|
15
|
+
expect(mcpEndpointPath("/backoffice")).toBe("/backoffice/mcp/mapo");
|
|
16
|
+
expect(mcpEndpointPath("backoffice/admin/")).toBe(
|
|
17
|
+
"/backoffice/admin/mcp/mapo",
|
|
18
|
+
);
|
|
19
|
+
});
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
describe("mcpEndpointUrl", () => {
|
|
23
|
+
it("joins the origin and the path without doubling slashes", () => {
|
|
24
|
+
expect(mcpEndpointUrl("http://localhost:3000")).toBe(
|
|
25
|
+
"http://localhost:3000/mcp/mapo",
|
|
26
|
+
);
|
|
27
|
+
expect(mcpEndpointUrl("http://localhost:3000/", "/backoffice/")).toBe(
|
|
28
|
+
"http://localhost:3000/backoffice/mcp/mapo",
|
|
29
|
+
);
|
|
30
|
+
});
|
|
31
|
+
});
|
|
@@ -14,6 +14,7 @@ import {
|
|
|
14
14
|
loadDocsKnowledge,
|
|
15
15
|
resolveKnowledgeDir,
|
|
16
16
|
} from "../runtime/core/knowledge.js";
|
|
17
|
+
import { overviewSummary } from "../runtime/core/overview.js";
|
|
17
18
|
import { RECIPES } from "../runtime/core/recipes.js";
|
|
18
19
|
import { getDoc, searchDocs } from "../runtime/core/search.js";
|
|
19
20
|
|
|
@@ -40,6 +41,20 @@ describeBuilt("generated knowledge base", () => {
|
|
|
40
41
|
expect(roadmap).toEqual([]);
|
|
41
42
|
});
|
|
42
43
|
|
|
44
|
+
it("excludes the contributor docs and the agent manuals", () => {
|
|
45
|
+
const paths = [...new Set(knowledge.chunks.map((chunk) => chunk.path))];
|
|
46
|
+
expect(paths.filter((path) => path.startsWith("contributing/"))).toEqual(
|
|
47
|
+
[],
|
|
48
|
+
);
|
|
49
|
+
expect(
|
|
50
|
+
paths.filter((path) => /(^|\/)(AGENTS|CLAUDE)\.md$/.test(path)),
|
|
51
|
+
).toEqual([]);
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
it("indexes the overview the server opens with", () => {
|
|
55
|
+
expect(overviewSummary(knowledge)).toContain("Nuxt 4");
|
|
56
|
+
});
|
|
57
|
+
|
|
43
58
|
it.each([
|
|
44
59
|
["how do I build a paginated list of articles", "howto/crud-list.md"],
|
|
45
60
|
["add a new field type to the registry", "uikit/form/registry.md"],
|
|
@@ -47,6 +62,7 @@ describeBuilt("generated knowledge base", () => {
|
|
|
47
62
|
["protect a page with permissions", "howto/auth-permissions.md"],
|
|
48
63
|
["show a toast notification", "howto/feedback.md"],
|
|
49
64
|
["connect a django backend", "howto/backend-integration.md"],
|
|
65
|
+
["how do the packages fit together", "guide/concepts.md"],
|
|
50
66
|
])("ranks %j near the top of the results", (query, expectedPath) => {
|
|
51
67
|
const hits = searchDocs(knowledge, query, { limit: 3 });
|
|
52
68
|
expect(hits.map((hit) => hit.path)).toContain(expectedPath);
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
import { describe, expect, it } from "vitest";
|
|
2
|
+
import { MAPO_INSTRUCTIONS } from "../runtime/core/instructions.js";
|
|
3
|
+
import { overviewSummary, renderOverview } from "../runtime/core/overview.js";
|
|
4
|
+
import { OVERVIEW_DOC, OVERVIEW_URI } from "../runtime/core/resources.js";
|
|
5
|
+
import { apiTools } from "../runtime/core/tools/api.js";
|
|
6
|
+
import { appTools } from "../runtime/core/tools/app.js";
|
|
7
|
+
import { backendTools } from "../runtime/core/tools/backend.js";
|
|
8
|
+
import { docsTools, listRecipesTool } from "../runtime/core/tools/docs.js";
|
|
9
|
+
import { scaffoldTools } from "../runtime/core/tools/scaffold.js";
|
|
10
|
+
import { makeContext, makeKnowledge } from "./fixtures.js";
|
|
11
|
+
|
|
12
|
+
const CONCEPTS_DOC = `# Concepts
|
|
13
|
+
|
|
14
|
+
How Mapo fits together.
|
|
15
|
+
|
|
16
|
+
## What Mapo is
|
|
17
|
+
|
|
18
|
+
Mapo is a set of Nuxt 4 modules for building admin interfaces.
|
|
19
|
+
|
|
20
|
+
The stack is Nuxt 4, Vue 3 and Nuxt UI.
|
|
21
|
+
|
|
22
|
+
You install one meta-package next to Nuxt UI, in this order:
|
|
23
|
+
|
|
24
|
+
\`\`\`ts
|
|
25
|
+
export default defineNuxtConfig({ modules: ["@nuxt/ui", "mapomodule"] });
|
|
26
|
+
\`\`\`
|
|
27
|
+
|
|
28
|
+
## The packages
|
|
29
|
+
|
|
30
|
+
Each package has one role.
|
|
31
|
+
`;
|
|
32
|
+
|
|
33
|
+
const withConcepts = () => makeKnowledge({ [OVERVIEW_DOC]: CONCEPTS_DOC });
|
|
34
|
+
|
|
35
|
+
describe("renderOverview", () => {
|
|
36
|
+
it("serves the whole concepts page", () => {
|
|
37
|
+
const text = renderOverview(withConcepts());
|
|
38
|
+
expect(text).toContain("# Concepts");
|
|
39
|
+
expect(text).toContain("## The packages");
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
it("points at the other tools when the page is not indexed", () => {
|
|
43
|
+
const text = renderOverview(
|
|
44
|
+
makeKnowledge({ "howto/x.md": "# X\n\nText." }),
|
|
45
|
+
);
|
|
46
|
+
expect(text).toContain(OVERVIEW_DOC);
|
|
47
|
+
expect(text).toContain("mapo_list_recipes");
|
|
48
|
+
});
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
describe("overviewSummary", () => {
|
|
52
|
+
it("keeps the prose of the section and drops the code sample with its lead-in", () => {
|
|
53
|
+
const summary = overviewSummary(withConcepts())!;
|
|
54
|
+
expect(summary.startsWith("Mapo is a set of Nuxt 4 modules")).toBe(true);
|
|
55
|
+
expect(summary).toContain("The stack is");
|
|
56
|
+
expect(summary).not.toContain("defineNuxtConfig");
|
|
57
|
+
expect(summary).not.toContain("in this order");
|
|
58
|
+
expect(summary).toContain(OVERVIEW_URI);
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
it("is null when the page or the section is missing", () => {
|
|
62
|
+
const otherSection = makeKnowledge({
|
|
63
|
+
[OVERVIEW_DOC]: "# Concepts\n\n## Something else\n\nText.",
|
|
64
|
+
});
|
|
65
|
+
expect(overviewSummary(otherSection)).toBeNull();
|
|
66
|
+
expect(overviewSummary(makeKnowledge({}))).toBeNull();
|
|
67
|
+
});
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
describe("mapo_list_recipes without a task", () => {
|
|
71
|
+
it("opens with the overview when the concepts page is indexed", async () => {
|
|
72
|
+
const output = await listRecipesTool.run(
|
|
73
|
+
{},
|
|
74
|
+
makeContext({ [OVERVIEW_DOC]: CONCEPTS_DOC }),
|
|
75
|
+
);
|
|
76
|
+
expect(output.startsWith("Mapo is a set of Nuxt 4 modules")).toBe(true);
|
|
77
|
+
expect(output).toContain("Mapo recipes:");
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
it("lists the recipes alone when the page is missing", async () => {
|
|
81
|
+
const output = await listRecipesTool.run({}, makeContext());
|
|
82
|
+
expect(output).toMatch(/^\d+ Mapo recipes:/);
|
|
83
|
+
});
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
describe("server instructions", () => {
|
|
87
|
+
const toolNames = [
|
|
88
|
+
...docsTools,
|
|
89
|
+
...apiTools,
|
|
90
|
+
...appTools,
|
|
91
|
+
...scaffoldTools,
|
|
92
|
+
...backendTools,
|
|
93
|
+
].map((tool) => tool.name);
|
|
94
|
+
|
|
95
|
+
it("name only tools that exist", () => {
|
|
96
|
+
const named = MAPO_INSTRUCTIONS.match(/\bmapo_[a-z_]+/g) ?? [];
|
|
97
|
+
expect(named.length).toBeGreaterThan(5);
|
|
98
|
+
for (const name of named) expect(toolNames, name).toContain(name);
|
|
99
|
+
});
|
|
100
|
+
|
|
101
|
+
it("point at the overview", () => {
|
|
102
|
+
expect(MAPO_INSTRUCTIONS).toContain(OVERVIEW_URI);
|
|
103
|
+
expect(MAPO_INSTRUCTIONS).toContain(OVERVIEW_DOC);
|
|
104
|
+
});
|
|
105
|
+
});
|
|
@@ -21,6 +21,17 @@ describe("matchRecipes", () => {
|
|
|
21
21
|
["let editors reorder the navigation entries", "menu-manager"],
|
|
22
22
|
["port a v1 project to v2", "migration"],
|
|
23
23
|
["protect the dashboard route with permissions", "auth-permissions"],
|
|
24
|
+
["how do the packages fit together", "concepts"],
|
|
25
|
+
["show a field only when another field is checked", "conditional-fields"],
|
|
26
|
+
["autosave a draft while the user edits", "form-draft"],
|
|
27
|
+
["generate the fields from a json schema", "schema-to-form"],
|
|
28
|
+
["put a hint below one form field with a slot", "form-slots"],
|
|
29
|
+
["edit a repeater item fullscreen", "focus-mode"],
|
|
30
|
+
["add my page to the sidebar with an icon", "sidebar-navigation"],
|
|
31
|
+
["change the branding of the login page", "login-page"],
|
|
32
|
+
["TS2307 cannot find module mapomodule/types", "imports"],
|
|
33
|
+
["connect claude code or copilot through mcp", "ai-assistant"],
|
|
34
|
+
["set up the camomilla session cookie", "camomilla"],
|
|
24
35
|
])("maps %j to the %j recipe", (query, expectedId) => {
|
|
25
36
|
expect(matchRecipes(query)[0]?.id).toBe(expectedId);
|
|
26
37
|
});
|