@mapomodule/mcp 1.0.0-beta.1 → 1.0.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +71 -41
  2. package/dist/cli.d.mts +1 -1
  3. package/dist/cli.d.ts +1 -1
  4. package/dist/cli.mjs +17 -6
  5. package/dist/knowledge/api.json +1 -1
  6. package/dist/knowledge/docs.json +1 -1
  7. package/dist/module.json +1 -1
  8. package/dist/module.mjs +5 -2
  9. package/dist/runtime/core/endpoint.d.ts +0 -0
  10. package/dist/runtime/core/endpoint.js +8 -0
  11. package/dist/runtime/core/indexer.js +2 -1
  12. package/dist/runtime/core/instructions.d.ts +0 -0
  13. package/dist/runtime/core/instructions.js +10 -0
  14. package/dist/runtime/core/overview.d.ts +0 -0
  15. package/dist/runtime/core/overview.js +15 -0
  16. package/dist/runtime/core/recipes.js +221 -3
  17. package/dist/runtime/core/resources.js +4 -0
  18. package/dist/runtime/core/tools/app.js +1 -1
  19. package/dist/runtime/core/tools/docs.js +6 -2
  20. package/dist/runtime/mcp/handlers/mapo/index.js +2 -8
  21. package/dist/runtime/mcp/handlers/mapo/resources/overview.js +20 -0
  22. package/package.json +1 -1
  23. package/src/__tests__/cli.test.ts +16 -0
  24. package/src/__tests__/endpoint.test.ts +31 -0
  25. package/src/__tests__/knowledge.test.ts +16 -0
  26. package/src/__tests__/overview.test.ts +105 -0
  27. package/src/__tests__/recipes.test.ts +13 -0
  28. package/src/cli.ts +22 -11
  29. package/src/module.ts +7 -8
  30. package/src/runtime/core/endpoint.ts +27 -0
  31. package/src/runtime/core/indexer.ts +10 -4
  32. package/src/runtime/core/instructions.ts +18 -0
  33. package/src/runtime/core/overview.ts +44 -0
  34. package/src/runtime/core/recipes.ts +233 -0
  35. package/src/runtime/core/resources.ts +6 -0
  36. package/src/runtime/core/tools/app.ts +4 -3
  37. package/src/runtime/core/tools/docs.ts +5 -2
  38. package/src/runtime/mcp/handlers/mapo/index.ts +2 -8
  39. package/src/runtime/mcp/handlers/mapo/resources/overview.ts +22 -0
@@ -21,6 +21,19 @@ 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
+ ["let editors choose a content block from a block picker", "block-editor"],
31
+ ["add my page to the sidebar with an icon", "sidebar-navigation"],
32
+ ["how to reorder sidebar/menu entries", "sidebar-navigation"],
33
+ ["change the branding of the login page", "login-page"],
34
+ ["TS2307 cannot find module mapomodule/types", "imports"],
35
+ ["connect claude code or copilot through mcp", "ai-assistant"],
36
+ ["set up the camomilla session cookie", "camomilla"],
24
37
  ])("maps %j to the %j recipe", (query, expectedId) => {
25
38
  expect(matchRecipes(query)[0]?.id).toBe(expectedId);
26
39
  });
package/src/cli.ts CHANGED
@@ -20,12 +20,16 @@ import {
20
20
  DOCS_URI_PREFIX,
21
21
  FIELD_URI_PREFIX,
22
22
  INDEX_URI,
23
+ OVERVIEW_URI,
23
24
  docResourceList,
24
25
  fieldResourceList,
25
26
  renderDocResource,
26
27
  renderFieldResource,
27
28
  renderKnowledgeIndex,
28
29
  } from "./runtime/core/resources.js";
30
+ import { mcpEndpointUrl } from "./runtime/core/endpoint.js";
31
+ import { MAPO_INSTRUCTIONS } from "./runtime/core/instructions.js";
32
+ import { renderOverview } from "./runtime/core/overview.js";
29
33
  import { apiTools } from "./runtime/core/tools/api.js";
30
34
  import { appTools } from "./runtime/core/tools/app.js";
31
35
  import { docsTools } from "./runtime/core/tools/docs.js";
@@ -55,7 +59,7 @@ function readVersion(): string {
55
59
  }
56
60
 
57
61
  /** Default endpoint of the Nuxt module, overridable with `--app`. */
58
- export const DEFAULT_APP_URL = "http://localhost:3000/mcp/mapo";
62
+ export const DEFAULT_APP_URL = mcpEndpointUrl("http://localhost:3000");
59
63
 
60
64
  /** All tools that run without the Nuxt dev server. */
61
65
  function staticTools(): AnyMapoToolSpec[] {
@@ -129,8 +133,10 @@ function createAppProxy(appUrl: string) {
129
133
  const message = error instanceof Error ? error.message : String(error);
130
134
  return (
131
135
  `\`${name}\` needs the running app, and ${appUrl} is not answering (${message}).\n\n` +
132
- "Start the dev server (`pnpm dev`) and call the tool again, or point the client " +
133
- "directly at the app endpoint. Documentation and API tools work without it."
136
+ "Start the dev server (`pnpm dev`) and call the tool again. If the app runs on another " +
137
+ "port, behind a proxy or under an `app.baseURL`, pass its endpoint with `--app` or " +
138
+ "`MAPO_MCP_APP_URL` (for example `http://localhost/backoffice/mcp/mapo`): the dev server " +
139
+ "prints it at startup. Documentation and API tools work without it."
134
140
  );
135
141
  }
136
142
  };
@@ -144,14 +150,7 @@ export async function createStdioServer(
144
150
  ): Promise<McpServer> {
145
151
  const server = new McpServer(
146
152
  { name: "mapo", version: readVersion() },
147
- {
148
- instructions:
149
- "Mapo admin framework (Nuxt 4). Start from mapo_list_recipes, then mapo_search_docs / " +
150
- "mapo_get_doc for how-to, and mapo_component_api / mapo_list_field_types / " +
151
- "mapo_composable_api for exact APIs — Mapo v2 differs substantially from v1, so never " +
152
- "recall its API from memory. mapo_inspect_app and mapo_doctor describe the project itself " +
153
- "and need its dev server running.",
154
- },
153
+ { instructions: MAPO_INSTRUCTIONS },
155
154
  );
156
155
 
157
156
  const context = createToolContext(knowledgeDir, rootDir, schemaUrl);
@@ -255,6 +254,18 @@ function registerResources(server: McpServer, context: MapoToolContext): void {
255
254
  markdown(uri, renderKnowledgeIndex(context.knowledge(), context.api())),
256
255
  );
257
256
 
257
+ server.registerResource(
258
+ "mapo-overview",
259
+ OVERVIEW_URI,
260
+ {
261
+ title: "Mapo overview",
262
+ description:
263
+ "How Mapo fits together: the packages, the backend contract, declarative pages, the form engine and the customization layers.",
264
+ mimeType: "text/markdown",
265
+ },
266
+ (uri) => markdown(uri, renderOverview(context.knowledge())),
267
+ );
268
+
258
269
  server.registerResource(
259
270
  "mapo-doc",
260
271
  new ResourceTemplate(`${DOCS_URI_PREFIX}{+path}`, {
package/src/module.ts CHANGED
@@ -10,6 +10,7 @@ import {
10
10
  } from "@nuxt/kit";
11
11
  import type { NuxtModule } from "@nuxt/schema";
12
12
  import type { MapoAppManifest, MapoMcpContext, MapoMcpOptions } from "./index";
13
+ import { mcpEndpointUrl } from "./runtime/core/endpoint";
13
14
 
14
15
  export type { MapoAppManifest, MapoMcpContext, MapoMcpOptions } from "./index";
15
16
 
@@ -30,13 +31,6 @@ interface ForeignModuleOptions {
30
31
  i18n?: { locales?: Array<string | { code: string }> };
31
32
  }
32
33
 
33
- /**
34
- * Directory name under `runtime/mcp/handlers/`, which the toolkit turns into
35
- * the handler name and the route segment. It is not configurable: folder
36
- * handlers always take their name from the directory.
37
- */
38
- const HANDLER_NAME = "mapo";
39
-
40
34
  /** Reads the field types extracted from the form registry at build time. */
41
35
  function readDefaultFieldTypes(knowledgeDir: string | null): string[] {
42
36
  if (!knowledgeDir) return [];
@@ -207,8 +201,13 @@ export default defineNuxtModule<MapoMcpOptions>({
207
201
  getContents: () => `export default ${JSON.stringify(buildContext())}`,
208
202
  });
209
203
 
204
+ // Nitro serves the handler under `app.baseURL`: print the URL it really
205
+ // answers on, which is what an HTTP client or `mapo-mcp serve --app` needs.
210
206
  log.info(
211
- `MCP server available at ${nuxt.options.devServer?.url ?? "http://localhost:3000"}/mcp/${HANDLER_NAME}`,
207
+ `MCP server available at ${mcpEndpointUrl(
208
+ nuxt.options.devServer?.url ?? "http://localhost:3000",
209
+ nuxt.options.app.baseURL,
210
+ )}`,
212
211
  );
213
212
  },
214
213
  }) satisfies NuxtModule<MapoMcpOptions>;
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Where the Mapo MCP handler answers.
3
+ *
4
+ * `@nuxtjs/mcp-toolkit` mounts named handlers at `/mcp/<name>` whatever its
5
+ * `mcp.route` option says, and Nitro serves every server route under the app's
6
+ * `app.baseURL`. An app served under `/backoffice/` therefore answers at
7
+ * `/backoffice/mcp/mapo`, and a request to `/mcp/mapo` misses it: the dev
8
+ * server answers with a redirect, which MCP clients follow as a GET.
9
+ */
10
+
11
+ /**
12
+ * Directory name under `runtime/mcp/handlers/`, which the toolkit turns into
13
+ * the handler name and the route segment. It is not configurable: folder
14
+ * handlers always take their name from the directory.
15
+ */
16
+ export const MCP_HANDLER_NAME = "mapo";
17
+
18
+ /** Path of the handler under an `app.baseURL` such as `/`, `/backoffice/` or `./`. */
19
+ export function mcpEndpointPath(baseURL = "/"): string {
20
+ const base = `/${baseURL.replace(/^\.?\/+/, "")}`.replace(/\/*$/, "/");
21
+ return `${base}mcp/${MCP_HANDLER_NAME}`;
22
+ }
23
+
24
+ /** Full URL of the handler on an origin such as `http://localhost:3000`. */
25
+ export function mcpEndpointUrl(origin: string, baseURL = "/"): string {
26
+ return `${origin.replace(/\/+$/, "")}${mcpEndpointPath(baseURL)}`;
27
+ }
@@ -17,20 +17,26 @@ export const KNOWLEDGE_VERSION = 1;
17
17
  /** Chunks larger than this are split further (H3, then paragraphs). */
18
18
  const MAX_CHUNK_CHARS = 3500;
19
19
 
20
- /** Directories under the docs root that are internal planning, not user docs. */
20
+ /**
21
+ * Directories under the docs root that are not app-building docs: internal
22
+ * planning, and `contributing/`, whose procedures for changing Mapo itself
23
+ * would otherwise compete with the answers for app developers.
24
+ */
21
25
  const EXCLUDED_DIRS = new Set([
22
26
  "node_modules",
23
27
  "roadmap",
28
+ "contributing",
24
29
  ".vitepress",
25
30
  "dist",
26
31
  ]);
27
32
 
28
33
  /**
29
34
  * Internal pages that are not user documentation. `DECISIONS.md` is an
30
- * Italian-language decision log for maintainers; surfacing it to assistants
31
- * only pollutes results.
35
+ * Italian-language decision log for maintainers, and `AGENTS.md` / `CLAUDE.md`
36
+ * are the manuals of the agents that edit the docs; surfacing them to
37
+ * assistants only pollutes results.
32
38
  */
33
- const EXCLUDED_FILES = new Set(["DECISIONS.md"]);
39
+ const EXCLUDED_FILES = new Set(["DECISIONS.md", "AGENTS.md", "CLAUDE.md"]);
34
40
 
35
41
  /** Field boosts baked into the term frequencies. */
36
42
  const BOOST = { heading: 3, title: 2, tags: 3, text: 1 } as const;
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Server instructions: what a client receives on `initialize`, and what most
3
+ * clients put in front of the model before any tool call. The Nuxt handler and
4
+ * the stdio CLI both use this text, so the two transports describe Mapo the
5
+ * same way. It stays short; the long form is the overview page (`overview.ts`).
6
+ *
7
+ * Every `mapo_*` name below must be a real tool: a test checks it.
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. 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
+
11
+ Workflow:
12
+ 1. New to the project or the task? Read the overview: the mapo://overview resource, or mapo_get_doc({ path: "guide/concepts.md" }).
13
+ 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.
14
+ 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.
15
+ 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.
16
+ 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.
17
+ 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).
18
+ 7. Cite the doc path you relied on when you produce code.`;
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Mapo's overview: the "Concepts" docs page, served whole as a resource and
3
+ * summarised at the top of `mapo_list_recipes`. The page is written once, for
4
+ * people and assistants alike; this module only selects from it, so the
5
+ * overview follows the docs on every knowledge build.
6
+ */
7
+ import { OVERVIEW_DOC, OVERVIEW_URI, renderDocResource } from "./resources.js";
8
+ import { getDoc } from "./search.js";
9
+ import type { DocsKnowledge } from "./types.js";
10
+
11
+ /** The section of the page that `mapo_list_recipes` opens with. */
12
+ const SUMMARY_HEADING = "What Mapo is";
13
+
14
+ /** The whole overview page, or a pointer to the docs when it is not indexed. */
15
+ export function renderOverview(knowledge: DocsKnowledge): string {
16
+ return (
17
+ renderDocResource(knowledge, OVERVIEW_DOC) ??
18
+ `The overview page \`${OVERVIEW_DOC}\` is not in this knowledge base. ` +
19
+ "Call mapo_list_recipes or mapo_search_docs instead."
20
+ );
21
+ }
22
+
23
+ /**
24
+ * The prose of the "What Mapo is" section, without its code samples, plus where
25
+ * to read the rest. Null when the page or the section is missing, so callers
26
+ * simply leave it out.
27
+ */
28
+ export function overviewSummary(knowledge: DocsKnowledge): string | null {
29
+ const doc = getDoc(knowledge, OVERVIEW_DOC, { heading: SUMMARY_HEADING });
30
+ if (!doc?.headings.includes(SUMMARY_HEADING)) return null;
31
+
32
+ const prose = doc.content
33
+ .replace(/^#+ .*\n+/, "")
34
+ .split(/\n```/)[0]!
35
+ .trim()
36
+ // The paragraph that introduces a code sample makes no sense without it.
37
+ .replace(/\n\n[^\n]*:$/, "");
38
+ if (!prose) return null;
39
+
40
+ return (
41
+ `${prose}\n\nFull overview: the \`${OVERVIEW_URI}\` resource, or ` +
42
+ `mapo_get_doc({ path: "${OVERVIEW_DOC}" }).`
43
+ );
44
+ }
@@ -24,6 +24,22 @@ export interface Recipe {
24
24
  }
25
25
 
26
26
  export const RECIPES: Recipe[] = [
27
+ {
28
+ id: "concepts",
29
+ task: "Understand how Mapo fits together",
30
+ keywords: [
31
+ "overview",
32
+ "architecture",
33
+ "packages",
34
+ "concepts",
35
+ "mental model",
36
+ "how it works",
37
+ ],
38
+ doc: "guide/concepts.md",
39
+ seeAlso: ["guide/architecture-flows.md", "guide/getting-started.md"],
40
+ summary:
41
+ "The packages, the backend contract, declarative pages, the form engine and the customization layers.",
42
+ },
27
43
  {
28
44
  id: "first-admin-page",
29
45
  task: "Create the first admin page",
@@ -35,6 +51,7 @@ export const RECIPES: Recipe[] = [
35
51
  "definePageMeta",
36
52
  "dashboard",
37
53
  "sidebar entry",
54
+ "install",
38
55
  ],
39
56
  doc: "howto/first-admin-page.md",
40
57
  seeAlso: ["guide/getting-started.md"],
@@ -115,6 +132,24 @@ export const RECIPES: Recipe[] = [
115
132
  summary:
116
133
  "Every built-in field type, the component behind it and its attrs.",
117
134
  },
135
+ {
136
+ id: "block-editor",
137
+ task: "Build a block editor with a block picker (repeater with templates)",
138
+ keywords: [
139
+ "block editor",
140
+ "block picker",
141
+ "repeater templates",
142
+ "page builder",
143
+ "RepeaterTemplate",
144
+ "picker",
145
+ "content blocks",
146
+ ],
147
+ doc: "howto/form-advanced.md",
148
+ heading: "Describe blocks and choose them in a picker",
149
+ seeAlso: ["uikit/form/api.md", "uikit/form/add-fields.md"],
150
+ summary:
151
+ "attrs.templates with label, icon, image and category, and attrs.picker (select or modal).",
152
+ },
118
153
  {
119
154
  id: "custom-field",
120
155
  task: "Create and register a custom field type",
@@ -253,6 +288,7 @@ export const RECIPES: Recipe[] = [
253
288
  "dark mode",
254
289
  "tokens",
255
290
  "design",
291
+ "primary color",
256
292
  ],
257
293
  doc: "howto/theming.md",
258
294
  seeAlso: ["uikit/theming.md"],
@@ -287,6 +323,9 @@ export const RECIPES: Recipe[] = [
287
323
  "proxy",
288
324
  "useCrud",
289
325
  "rest",
326
+ "fastapi",
327
+ "laravel",
328
+ "jwt",
290
329
  ],
291
330
  doc: "howto/backend-integration.md",
292
331
  seeAlso: ["modules/camomilla.md", "modules/api.md"],
@@ -300,6 +339,200 @@ export const RECIPES: Recipe[] = [
300
339
  doc: "migration/v1-to-v2.md",
301
340
  summary: "What changed between Mapo v1 and v2 and how to port each piece.",
302
341
  },
342
+ {
343
+ id: "conditional-fields",
344
+ task: "Show or hide form fields based on other values",
345
+ keywords: [
346
+ "visible",
347
+ "conditional",
348
+ "whenAny",
349
+ "matchesField",
350
+ "depends on",
351
+ "progressive disclosure",
352
+ ],
353
+ doc: "uikit/form/progressive-disclosure.md",
354
+ seeAlso: ["howto/form-advanced.md"],
355
+ summary:
356
+ "visible and show predicates built with the when/matchesField matcher helpers.",
357
+ },
358
+ {
359
+ id: "form-draft",
360
+ task: "Autosave form drafts",
361
+ keywords: ["draft", "autosave", "useFormDraft", "restore", "unsaved"],
362
+ doc: "uikit/form/draft.md",
363
+ seeAlso: ["howto/crud-detail.md"],
364
+ summary:
365
+ "useFormDraft keeps unsaved edits in localStorage and offers to restore them on the next visit.",
366
+ },
367
+ {
368
+ id: "schema-to-form",
369
+ task: "Generate form fields from a JSON Schema",
370
+ keywords: [
371
+ "json schema",
372
+ "useFormFromSchema",
373
+ "openapi",
374
+ "drf-spectacular",
375
+ "pydantic",
376
+ "serializer",
377
+ ],
378
+ doc: "uikit/form/schema-to-form.md",
379
+ seeAlso: ["howto/form-advanced.md"],
380
+ summary:
381
+ "useFormFromSchema turns a JSON Schema (DRF, Pydantic) into field descriptors you can extend.",
382
+ },
383
+ {
384
+ id: "form-slots",
385
+ task: "Customize how a form field renders with slots",
386
+ keywords: [
387
+ "field slot",
388
+ "hint",
389
+ "above",
390
+ "below",
391
+ "replace a field",
392
+ "group slot",
393
+ ],
394
+ doc: "uikit/form/slots.md",
395
+ summary:
396
+ "Per-field, per-group and global slots that wrap, extend or replace how fields render.",
397
+ },
398
+ {
399
+ id: "focus-mode",
400
+ task: "Focus mode for repeater items and long fields",
401
+ keywords: [
402
+ "focus mode",
403
+ "useFocusMode",
404
+ "fullscreen",
405
+ "field expand",
406
+ "MapoFocusPortal",
407
+ "breadcrumb",
408
+ ],
409
+ doc: "uikit/form/focus-mode.md",
410
+ seeAlso: ["uikit/form/field-expand.md"],
411
+ summary:
412
+ "Open a repeater item in a fullscreen view, or expand a single field in place.",
413
+ },
414
+ {
415
+ id: "sidebar-navigation",
416
+ task: "Build the sidebar navigation",
417
+ keywords: [
418
+ "sidebar",
419
+ "nested menu",
420
+ "parent",
421
+ "icon",
422
+ "label",
423
+ "sidebarFooter",
424
+ "sidebarOrder",
425
+ "reorder menu",
426
+ "route meta",
427
+ ],
428
+ doc: "uikit/sidebar.md",
429
+ seeAlso: ["howto/first-admin-page.md"],
430
+ summary:
431
+ "Route metadata builds the sidebar tree without menu config; use sidebarOrder to sort sibling entries.",
432
+ },
433
+ {
434
+ id: "login-page",
435
+ task: "Customize the login page",
436
+ keywords: [
437
+ "MapoLogin",
438
+ "sign in",
439
+ "login form",
440
+ "login redirect",
441
+ "branding",
442
+ ],
443
+ doc: "uikit/login.md",
444
+ seeAlso: ["howto/auth-permissions.md"],
445
+ summary:
446
+ "The built-in /login page: its slots, the redirect after login and error handling.",
447
+ },
448
+ {
449
+ id: "imports",
450
+ task: "Know what to import and from where",
451
+ keywords: [
452
+ "import",
453
+ "auto-import",
454
+ "import type",
455
+ "mapomodule/types",
456
+ "TS2307",
457
+ "cannot find module",
458
+ ],
459
+ doc: "guide/imports.md",
460
+ seeAlso: ["guide/known-limitations.md"],
461
+ summary:
462
+ "Composables and components are auto-imported, types come from mapomodule/types, utils are imported explicitly.",
463
+ },
464
+ {
465
+ id: "troubleshooting",
466
+ task: "Troubleshoot compatibility and version problems",
467
+ keywords: [
468
+ "module order",
469
+ "nuxt ui first",
470
+ "error",
471
+ "tested versions",
472
+ "peer dependencies",
473
+ "dedupe",
474
+ "duplicate vue",
475
+ ],
476
+ doc: "guide/compatibility.md",
477
+ seeAlso: ["guide/known-limitations.md"],
478
+ summary:
479
+ "Tested versions, what to declare in the app, module order and the common problems.",
480
+ },
481
+ {
482
+ id: "utils",
483
+ task: "Merge, diff and format with the utility helpers",
484
+ keywords: [
485
+ "deepMerge",
486
+ "objectDiff",
487
+ "slugify",
488
+ "formatDate",
489
+ "humanFileSize",
490
+ "normalizeEndpoint",
491
+ "debounce",
492
+ ],
493
+ doc: "modules/utils.md",
494
+ seeAlso: ["modules/api.md"],
495
+ summary:
496
+ "Typed helpers from @mapomodule/utils: merging, diffing, formatting, slugs and endpoints.",
497
+ },
498
+ {
499
+ id: "camomilla",
500
+ task: "Use the Camomilla CMS integration",
501
+ keywords: [
502
+ "camomilla",
503
+ "path rewrite",
504
+ "session cookie",
505
+ "django cms",
506
+ "media adapter",
507
+ ],
508
+ doc: "modules/camomilla.md",
509
+ seeAlso: ["howto/backend-integration.md"],
510
+ summary:
511
+ "The Camomilla integration: proxy options, path rewriting, the media adapter and session cookies.",
512
+ },
513
+ {
514
+ id: "ai-assistant",
515
+ task: "Set up an AI coding assistant",
516
+ keywords: ["mcp", "claude", "copilot", "cursor", "agent", "mapo-mcp"],
517
+ doc: "howto/ai-assistant.md",
518
+ seeAlso: ["modules/mcp.md"],
519
+ summary:
520
+ "Connect Claude Code, Copilot or Cursor to the Mapo MCP server over stdio or HTTP.",
521
+ },
522
+ {
523
+ id: "form-devtools",
524
+ task: "Inspect forms in Nuxt DevTools",
525
+ keywords: [
526
+ "devtools",
527
+ "debug form",
528
+ "registry warning",
529
+ "inspect",
530
+ "_mapo",
531
+ ],
532
+ doc: "uikit/form/devtools.md",
533
+ summary:
534
+ "The Mapo Forms tab: the module config and the live field registry your forms read.",
535
+ },
303
536
  ];
304
537
 
305
538
  export interface RecipeMatch extends Recipe {
@@ -13,6 +13,10 @@ export const DOCS_URI_PREFIX = "mapo://docs/";
13
13
  export const FIELD_URI_PREFIX = "mapo://fields/";
14
14
  export const INDEX_URI = "mapo://knowledge/index";
15
15
  export const MANIFEST_URI = "mapo://app/manifest";
16
+ export const OVERVIEW_URI = "mapo://overview";
17
+
18
+ /** The docs page that explains how Mapo fits together (see `overview.ts`). */
19
+ export const OVERVIEW_DOC = "guide/concepts.md";
16
20
 
17
21
  /** Everything the knowledge base contains, as a compact browsable map. */
18
22
  export function renderKnowledgeIndex(
@@ -43,6 +47,8 @@ export function renderKnowledgeIndex(
43
47
  "",
44
48
  `Generated ${knowledge.generatedAt}.`,
45
49
  "",
50
+ `Start with the overview: the \`${OVERVIEW_URI}\` resource (\`${OVERVIEW_DOC}\`).`,
51
+ "",
46
52
  "## Recipes",
47
53
  recipes,
48
54
  "",
@@ -20,9 +20,10 @@ const READ_ONLY = {
20
20
 
21
21
  const NO_APP =
22
22
  "This tool needs the running app and is only served over HTTP.\n\n" +
23
- "Start the dev server (`pnpm dev`) and point the client at " +
24
- "`http://localhost:3000/mcp/mapo`. The stdio server (`mapo-mcp serve`) knows the framework " +
25
- "and its documentation, but not the project using it.";
23
+ "Start the dev server (`pnpm dev`) and point the client at the URL it prints at startup: " +
24
+ "`http://localhost:3000/mcp/mapo` by default, under the app's `app.baseURL` when it has one. " +
25
+ "The stdio server (`mapo-mcp serve`) knows the framework and its documentation, but not the " +
26
+ "project using it.";
26
27
 
27
28
  type InspectSection =
28
29
  | "modules"
@@ -1,5 +1,6 @@
1
1
  /** Docs tools: grounded search, curated recipes and exact section retrieval. */
2
2
  import { z } from "zod";
3
+ import { overviewSummary } from "../overview.js";
3
4
  import { matchRecipes, RECIPES } from "../recipes.js";
4
5
  import { getDoc, searchDocs } from "../search.js";
5
6
  import { defineMapoTool } from "../tool-spec.js";
@@ -187,7 +188,7 @@ export const listRecipesTool = defineMapoTool({
187
188
  openWorldHint: false,
188
189
  },
189
190
  inputExamples: [{}, { task: "upload images and pick them in a form" }],
190
- run: (args: ListRecipesArgs) => {
191
+ run: (args: ListRecipesArgs, context: MapoToolContext) => {
191
192
  if (args.task) {
192
193
  const matches = matchRecipes(args.task, 3);
193
194
  if (!matches.length) {
@@ -199,11 +200,13 @@ export const listRecipesTool = defineMapoTool({
199
200
  return `${renderRecipes(matches)}Read the page with mapo_get_doc({ path }).`;
200
201
  }
201
202
 
203
+ // With no task the caller is surveying Mapo, so lead with what it is.
204
+ const summary = overviewSummary(context.knowledge());
202
205
  const lines = RECIPES.map(
203
206
  (recipe) =>
204
207
  `- **${recipe.task}** → \`${recipe.doc}\` — ${recipe.summary}`,
205
208
  );
206
- return `${RECIPES.length} Mapo recipes:\n\n${lines.join("\n")}\n\nRead one with mapo_get_doc({ path }).`;
209
+ return `${summary ? `${summary}\n\n` : ""}${RECIPES.length} Mapo recipes:\n\n${lines.join("\n")}\n\nRead one with mapo_get_doc({ path }).`;
207
210
  },
208
211
  });
209
212
 
@@ -1,4 +1,5 @@
1
1
  import { defineMcpHandler } from "@nuxtjs/mcp-toolkit/server";
2
+ import { MAPO_INSTRUCTIONS } from "../../../core/instructions.js";
2
3
 
3
4
  /**
4
5
  * Named handler → route `<mcp.route>/mapo` (default `/mcp/mapo`).
@@ -11,12 +12,5 @@ export default defineMcpHandler({
11
12
  name: "mapo",
12
13
  description:
13
14
  "Mapo admin framework: docs, component and field APIs, app introspection, scaffolding.",
14
- instructions: `This server exposes the Mapo admin framework (Nuxt 4 + Nuxt UI) to coding agents.
15
-
16
- Workflow:
17
- 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.
18
- 2. Start from mapo_list_recipes to find the canonical approach for the task — Mapo ships a lot out of the box, and the recipe names the page that documents it.
19
- 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.
20
- 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.
21
- 5. Cite the doc path you relied on when you produce code.`,
15
+ instructions: MAPO_INSTRUCTIONS,
22
16
  });
@@ -0,0 +1,22 @@
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
+
6
+ export default defineMcpResource({
7
+ name: "mapo-overview",
8
+ title: "Mapo overview",
9
+ description:
10
+ "How Mapo fits together: the packages, the backend contract, declarative pages, the form engine and the customization layers.",
11
+ uri: OVERVIEW_URI,
12
+ metadata: { mimeType: "text/markdown" },
13
+ handler: (uri: URL) => ({
14
+ contents: [
15
+ {
16
+ uri: uri.toString(),
17
+ mimeType: "text/markdown",
18
+ text: renderOverview(useDocsKnowledge()),
19
+ },
20
+ ],
21
+ }),
22
+ });