@mapomodule/mcp 0.0.0-stage → 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.
Files changed (166) hide show
  1. package/README.md +509 -2
  2. package/bin/mapo-mcp.mjs +3 -0
  3. package/dist/build.d.mts +18 -0
  4. package/dist/build.d.ts +18 -0
  5. package/dist/build.mjs +351 -0
  6. package/dist/cli.d.mts +7 -0
  7. package/dist/cli.d.ts +7 -0
  8. package/dist/cli.mjs +274 -0
  9. package/dist/index.d.mts +68 -0
  10. package/dist/index.d.ts +68 -0
  11. package/dist/index.mjs +1 -0
  12. package/dist/knowledge/api.json +1 -0
  13. package/dist/knowledge/docs.json +1 -0
  14. package/dist/module.d.mts +16 -0
  15. package/dist/module.d.ts +16 -0
  16. package/dist/module.json +9 -0
  17. package/dist/module.mjs +124 -0
  18. package/dist/runtime/core/doctor.d.ts +0 -0
  19. package/dist/runtime/core/doctor.js +128 -0
  20. package/dist/runtime/core/endpoint.d.ts +0 -0
  21. package/dist/runtime/core/endpoint.js +8 -0
  22. package/dist/runtime/core/indexer.d.ts +0 -0
  23. package/dist/runtime/core/indexer.js +194 -0
  24. package/dist/runtime/core/instructions.d.ts +0 -0
  25. package/dist/runtime/core/instructions.js +10 -0
  26. package/dist/runtime/core/knowledge.d.ts +0 -0
  27. package/dist/runtime/core/knowledge.js +76 -0
  28. package/dist/runtime/core/openapi.d.ts +0 -0
  29. package/dist/runtime/core/openapi.js +229 -0
  30. package/dist/runtime/core/overview.d.ts +0 -0
  31. package/dist/runtime/core/overview.js +15 -0
  32. package/dist/runtime/core/prompts.d.ts +0 -0
  33. package/dist/runtime/core/prompts.js +108 -0
  34. package/dist/runtime/core/recipes.d.ts +0 -0
  35. package/dist/runtime/core/recipes.js +496 -0
  36. package/dist/runtime/core/resources.d.ts +0 -0
  37. package/dist/runtime/core/resources.js +92 -0
  38. package/dist/runtime/core/scaffold/fields.d.ts +0 -0
  39. package/dist/runtime/core/scaffold/fields.js +64 -0
  40. package/dist/runtime/core/scaffold/index.d.ts +0 -0
  41. package/dist/runtime/core/scaffold/index.js +74 -0
  42. package/dist/runtime/core/scaffold/templates.d.ts +0 -0
  43. package/dist/runtime/core/scaffold/templates.js +349 -0
  44. package/dist/runtime/core/schema-source.d.ts +0 -0
  45. package/dist/runtime/core/schema-source.js +70 -0
  46. package/dist/runtime/core/search.d.ts +0 -0
  47. package/dist/runtime/core/search.js +173 -0
  48. package/dist/runtime/core/tokenize.d.ts +0 -0
  49. package/dist/runtime/core/tokenize.js +96 -0
  50. package/dist/runtime/core/tool-spec.d.ts +0 -0
  51. package/dist/runtime/core/tool-spec.js +3 -0
  52. package/dist/runtime/core/tools/api.d.ts +0 -0
  53. package/dist/runtime/core/tools/api.js +192 -0
  54. package/dist/runtime/core/tools/app.d.ts +0 -0
  55. package/dist/runtime/core/tools/app.js +141 -0
  56. package/dist/runtime/core/tools/backend.d.ts +0 -0
  57. package/dist/runtime/core/tools/backend.js +143 -0
  58. package/dist/runtime/core/tools/docs.d.ts +0 -0
  59. package/dist/runtime/core/tools/docs.js +154 -0
  60. package/dist/runtime/core/tools/scaffold.d.ts +0 -0
  61. package/dist/runtime/core/tools/scaffold.js +127 -0
  62. package/dist/runtime/core/types.d.ts +0 -0
  63. package/dist/runtime/core/types.js +0 -0
  64. package/dist/runtime/core/write.d.ts +0 -0
  65. package/dist/runtime/core/write.js +53 -0
  66. package/dist/runtime/mcp/handlers/mapo/index.js +7 -0
  67. package/dist/runtime/mcp/handlers/mapo/prompts/crud-page.js +3 -0
  68. package/dist/runtime/mcp/handlers/mapo/prompts/custom-field.js +3 -0
  69. package/dist/runtime/mcp/handlers/mapo/prompts/debug-form.js +3 -0
  70. package/dist/runtime/mcp/handlers/mapo/prompts/migrate-v1.js +3 -0
  71. package/dist/runtime/mcp/handlers/mapo/prompts/theme.js +3 -0
  72. package/dist/runtime/mcp/handlers/mapo/resources/app-manifest.js +19 -0
  73. package/dist/runtime/mcp/handlers/mapo/resources/docs.js +34 -0
  74. package/dist/runtime/mcp/handlers/mapo/resources/fields.js +34 -0
  75. package/dist/runtime/mcp/handlers/mapo/resources/knowledge-index.js +22 -0
  76. package/dist/runtime/mcp/handlers/mapo/resources/overview.js +20 -0
  77. package/dist/runtime/mcp/handlers/mapo/tools/backend-schema.js +3 -0
  78. package/dist/runtime/mcp/handlers/mapo/tools/component-api.js +3 -0
  79. package/dist/runtime/mcp/handlers/mapo/tools/composable-api.js +3 -0
  80. package/dist/runtime/mcp/handlers/mapo/tools/doctor.js +3 -0
  81. package/dist/runtime/mcp/handlers/mapo/tools/get-doc.js +3 -0
  82. package/dist/runtime/mcp/handlers/mapo/tools/inspect-app.js +3 -0
  83. package/dist/runtime/mcp/handlers/mapo/tools/list-field-types.js +3 -0
  84. package/dist/runtime/mcp/handlers/mapo/tools/list-recipes.js +3 -0
  85. package/dist/runtime/mcp/handlers/mapo/tools/scaffold.js +3 -0
  86. package/dist/runtime/mcp/handlers/mapo/tools/search-docs.js +3 -0
  87. package/dist/runtime/nitro/context.d.ts +0 -0
  88. package/dist/runtime/nitro/context.js +21 -0
  89. package/dist/runtime/nitro/to-mcp-prompt.d.ts +0 -0
  90. package/dist/runtime/nitro/to-mcp-prompt.js +23 -0
  91. package/dist/runtime/nitro/to-mcp-tool.d.ts +0 -0
  92. package/dist/runtime/nitro/to-mcp-tool.js +28 -0
  93. package/dist/runtime/types/virtual-modules.d.ts +6 -0
  94. package/dist/types.d.mts +9 -0
  95. package/package.json +73 -4
  96. package/src/__tests__/cli.test.ts +137 -0
  97. package/src/__tests__/doctor.test.ts +145 -0
  98. package/src/__tests__/endpoint.test.ts +31 -0
  99. package/src/__tests__/fixtures/drf-schema.json +142 -0
  100. package/src/__tests__/fixtures.ts +198 -0
  101. package/src/__tests__/indexer.test.ts +114 -0
  102. package/src/__tests__/knowledge.test.ts +225 -0
  103. package/src/__tests__/openapi.test.ts +256 -0
  104. package/src/__tests__/overview.test.ts +105 -0
  105. package/src/__tests__/recipes.test.ts +55 -0
  106. package/src/__tests__/resources.test.ts +69 -0
  107. package/src/__tests__/scaffold.test.ts +153 -0
  108. package/src/__tests__/search.test.ts +105 -0
  109. package/src/__tests__/tools.test.ts +226 -0
  110. package/src/__tests__/write.test.ts +134 -0
  111. package/src/build/extract-components.ts +135 -0
  112. package/src/build/extract-composables.ts +125 -0
  113. package/src/build/extract-fields.ts +250 -0
  114. package/src/build/index.ts +103 -0
  115. package/src/cli.ts +375 -0
  116. package/src/index.ts +65 -0
  117. package/src/module.ts +213 -0
  118. package/src/runtime/core/doctor.ts +204 -0
  119. package/src/runtime/core/endpoint.ts +27 -0
  120. package/src/runtime/core/indexer.ts +285 -0
  121. package/src/runtime/core/instructions.ts +18 -0
  122. package/src/runtime/core/knowledge.ts +121 -0
  123. package/src/runtime/core/openapi.ts +417 -0
  124. package/src/runtime/core/overview.ts +44 -0
  125. package/src/runtime/core/prompts.ts +150 -0
  126. package/src/runtime/core/recipes.ts +574 -0
  127. package/src/runtime/core/resources.ts +150 -0
  128. package/src/runtime/core/scaffold/fields.ts +127 -0
  129. package/src/runtime/core/scaffold/index.ts +120 -0
  130. package/src/runtime/core/scaffold/templates.ts +394 -0
  131. package/src/runtime/core/schema-source.ts +123 -0
  132. package/src/runtime/core/search.ts +282 -0
  133. package/src/runtime/core/tokenize.ts +146 -0
  134. package/src/runtime/core/tool-spec.ts +74 -0
  135. package/src/runtime/core/tools/api.ts +300 -0
  136. package/src/runtime/core/tools/app.ts +201 -0
  137. package/src/runtime/core/tools/backend.ts +197 -0
  138. package/src/runtime/core/tools/docs.ts +218 -0
  139. package/src/runtime/core/tools/scaffold.ts +176 -0
  140. package/src/runtime/core/types.ts +133 -0
  141. package/src/runtime/core/write.ts +119 -0
  142. package/src/runtime/mcp/handlers/mapo/index.ts +16 -0
  143. package/src/runtime/mcp/handlers/mapo/prompts/crud-page.ts +4 -0
  144. package/src/runtime/mcp/handlers/mapo/prompts/custom-field.ts +4 -0
  145. package/src/runtime/mcp/handlers/mapo/prompts/debug-form.ts +4 -0
  146. package/src/runtime/mcp/handlers/mapo/prompts/migrate-v1.ts +4 -0
  147. package/src/runtime/mcp/handlers/mapo/prompts/theme.ts +4 -0
  148. package/src/runtime/mcp/handlers/mapo/resources/app-manifest.ts +28 -0
  149. package/src/runtime/mcp/handlers/mapo/resources/docs.ts +41 -0
  150. package/src/runtime/mcp/handlers/mapo/resources/fields.ts +37 -0
  151. package/src/runtime/mcp/handlers/mapo/resources/knowledge-index.ts +24 -0
  152. package/src/runtime/mcp/handlers/mapo/resources/overview.ts +22 -0
  153. package/src/runtime/mcp/handlers/mapo/tools/backend-schema.ts +4 -0
  154. package/src/runtime/mcp/handlers/mapo/tools/component-api.ts +4 -0
  155. package/src/runtime/mcp/handlers/mapo/tools/composable-api.ts +4 -0
  156. package/src/runtime/mcp/handlers/mapo/tools/doctor.ts +4 -0
  157. package/src/runtime/mcp/handlers/mapo/tools/get-doc.ts +4 -0
  158. package/src/runtime/mcp/handlers/mapo/tools/inspect-app.ts +4 -0
  159. package/src/runtime/mcp/handlers/mapo/tools/list-field-types.ts +4 -0
  160. package/src/runtime/mcp/handlers/mapo/tools/list-recipes.ts +4 -0
  161. package/src/runtime/mcp/handlers/mapo/tools/scaffold.ts +4 -0
  162. package/src/runtime/mcp/handlers/mapo/tools/search-docs.ts +4 -0
  163. package/src/runtime/nitro/context.ts +41 -0
  164. package/src/runtime/nitro/to-mcp-prompt.ts +30 -0
  165. package/src/runtime/nitro/to-mcp-tool.ts +35 -0
  166. package/src/runtime/types/virtual-modules.d.ts +6 -0
@@ -0,0 +1,16 @@
1
+ import { NuxtModule } from '@nuxt/schema';
2
+ import { MapoMcpOptions } from './index.mjs';
3
+ export { MapoAppManifest, MapoMcpContext } from './index.mjs';
4
+
5
+ /**
6
+ * Mapo MCP server — development-only.
7
+ *
8
+ * Registers a dedicated `@nuxtjs/mcp-toolkit` handler (default route `/mcp/mapo`)
9
+ * carrying Mapo's docs, API surface, app introspection and scaffolding tools.
10
+ * The definitions live inside this package and are injected through the
11
+ * toolkit's `mcp:definitions:paths` hook, so consuming apps write no MCP files
12
+ * and their own MCP definitions stay untouched.
13
+ */
14
+ declare const _default: NuxtModule<MapoMcpOptions, MapoMcpOptions, false>;
15
+
16
+ export { MapoMcpOptions, _default as default };
@@ -0,0 +1,16 @@
1
+ import { NuxtModule } from '@nuxt/schema';
2
+ import { MapoMcpOptions } from './index.js';
3
+ export { MapoAppManifest, MapoMcpContext } from './index.js';
4
+
5
+ /**
6
+ * Mapo MCP server — development-only.
7
+ *
8
+ * Registers a dedicated `@nuxtjs/mcp-toolkit` handler (default route `/mcp/mapo`)
9
+ * carrying Mapo's docs, API surface, app introspection and scaffolding tools.
10
+ * The definitions live inside this package and are injected through the
11
+ * toolkit's `mcp:definitions:paths` hook, so consuming apps write no MCP files
12
+ * and their own MCP definitions stay untouched.
13
+ */
14
+ declare const _default: NuxtModule<MapoMcpOptions, MapoMcpOptions, false>;
15
+
16
+ export { MapoMcpOptions, _default as default };
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "@mapomodule/mcp",
3
+ "configKey": "mapoMcp",
4
+ "version": "1.0.0-beta.2",
5
+ "builder": {
6
+ "@nuxt/module-builder": "1.0.2",
7
+ "unbuild": "unknown"
8
+ }
9
+ }
@@ -0,0 +1,124 @@
1
+ import { existsSync, readFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { defineNuxtModule, logger, createResolver, hasNuxtModule, installModule, addServerTemplate } from '@nuxt/kit';
4
+ import { mcpEndpointUrl } from '../dist/runtime/core/endpoint.js';
5
+
6
+ function readDefaultFieldTypes(knowledgeDir) {
7
+ if (!knowledgeDir) return [];
8
+ const file = join(knowledgeDir, "api.json");
9
+ if (!existsSync(file)) return [];
10
+ try {
11
+ const parsed = JSON.parse(readFileSync(file, "utf-8"));
12
+ return (parsed.fieldTypes ?? []).map((entry) => entry.type);
13
+ } catch {
14
+ return [];
15
+ }
16
+ }
17
+ const module$1 = defineNuxtModule({
18
+ meta: {
19
+ name: "@mapomodule/mcp",
20
+ configKey: "mapoMcp"
21
+ },
22
+ defaults: {},
23
+ async setup(options, nuxt) {
24
+ const log = logger.withTag("mapo:mcp");
25
+ const enabled = options.enabled ?? nuxt.options.dev;
26
+ if (!enabled) return;
27
+ const resolver = createResolver(import.meta.url);
28
+ const knowledgeDir = ["./knowledge", "../knowledge", "../dist/knowledge"].map((candidate) => resolver.resolve(candidate)).find((candidate) => existsSync(join(candidate, "docs.json")));
29
+ if (!knowledgeDir) {
30
+ log.warn(
31
+ "Knowledge base missing \u2014 docs tools will fail. Build it with `pnpm --filter @mapomodule/mcp build`."
32
+ );
33
+ }
34
+ if (!hasNuxtModule("@nuxtjs/mcp-toolkit")) {
35
+ await installModule(await resolver.resolvePath("@nuxtjs/mcp-toolkit"), {
36
+ name: "Mapo",
37
+ description: "Mapo admin framework: docs, APIs, app introspection and scaffolding."
38
+ });
39
+ }
40
+ const hook = nuxt.hook;
41
+ hook("mcp:definitions:paths", (paths) => {
42
+ paths.handlers.push(resolver.resolve("./runtime/mcp"));
43
+ });
44
+ const components = [];
45
+ const routes = [];
46
+ nuxt.hook("components:extend", (registered) => {
47
+ components.length = 0;
48
+ for (const component of registered) {
49
+ if (component.pascalName?.startsWith("Mapo"))
50
+ components.push(component.pascalName);
51
+ }
52
+ components.sort();
53
+ });
54
+ nuxt.hook("pages:extend", (pages) => {
55
+ routes.length = 0;
56
+ const walk = (list) => {
57
+ for (const page of list) {
58
+ routes.push({
59
+ path: page.path,
60
+ ...page.file ? { file: page.file } : {}
61
+ });
62
+ if (page.children?.length) walk(page.children);
63
+ }
64
+ };
65
+ walk(pages);
66
+ });
67
+ const buildContext = () => {
68
+ const publicConfig = nuxt.options.runtimeConfig.public;
69
+ const mapoConfig = Object.fromEntries(
70
+ Object.entries(publicConfig).filter(
71
+ ([key]) => key.toLowerCase().startsWith("mapo")
72
+ )
73
+ );
74
+ const options_ = nuxt.options;
75
+ const configuredTypes = Object.keys(
76
+ options_.mapoForm?.fields?.mapping ?? {}
77
+ );
78
+ const defaultTypes = readDefaultFieldTypes(knowledgeDir ?? null);
79
+ const manifest = {
80
+ rootDir: nuxt.options.rootDir,
81
+ dev: nuxt.options.dev,
82
+ modules: (nuxt.options._installedModules ?? []).map((installed) => ({
83
+ name: installed.meta?.name ?? "",
84
+ ...installed.meta?.version ? { version: installed.meta.version } : {}
85
+ })).filter((entry) => entry.name.includes("mapo")),
86
+ // Declaration order, not resolution order: `mapo_doctor` checks that
87
+ // `@nuxt/ui` is registered before `mapomodule`.
88
+ moduleOrder: (nuxt.options.modules ?? []).filter(
89
+ (entry) => typeof entry === "string"
90
+ ),
91
+ config: mapoConfig,
92
+ fieldTypes: [
93
+ ...defaultTypes.map((type) => ({ type, source: "default" })),
94
+ ...configuredTypes.filter((type) => !defaultTypes.includes(type)).map((type) => ({ type, source: "config" }))
95
+ ],
96
+ components: [...components],
97
+ routes: [...routes],
98
+ locales: (options_.i18n?.locales ?? []).map(
99
+ (locale) => typeof locale === "string" ? locale : locale.code
100
+ )
101
+ };
102
+ return {
103
+ knowledgeDir: knowledgeDir ?? null,
104
+ backend: {
105
+ schemaUrl: options.backend?.schemaUrl ?? process.env.MAPO_BACKEND_SCHEMA_URL ?? null,
106
+ tokenEnv: options.backend?.tokenEnv ?? "MAPO_BACKEND_TOKEN"
107
+ },
108
+ manifest
109
+ };
110
+ };
111
+ addServerTemplate({
112
+ filename: "#mapo-mcp/context.mjs",
113
+ getContents: () => `export default ${JSON.stringify(buildContext())}`
114
+ });
115
+ log.info(
116
+ `MCP server available at ${mcpEndpointUrl(
117
+ nuxt.options.devServer?.url ?? "http://localhost:3000",
118
+ nuxt.options.app.baseURL
119
+ )}`
120
+ );
121
+ }
122
+ });
123
+
124
+ export { module$1 as default };
File without changes
@@ -0,0 +1,128 @@
1
+ const AUTH_DEFAULTS = {
2
+ authLoginUrl: "/api/auth/login",
3
+ userInfoApi: "/api/profiles/me/",
4
+ logoutUrl: "/api/auth/logout",
5
+ loginUrl: "/login"
6
+ };
7
+ const MEDIA_ENDPOINT_DEFAULTS = {
8
+ media: "/api/media",
9
+ folders: "/api/media-folders"
10
+ };
11
+ const BUNDLED_LOCALES = /* @__PURE__ */ new Set(["en", "it"]);
12
+ const MEDIA_FIELD_TYPES = /* @__PURE__ */ new Set(["media", "media-m2m", "enhanced-media"]);
13
+ function section(manifest, key) {
14
+ const value = manifest.config[key];
15
+ return value && typeof value === "object" ? value : {};
16
+ }
17
+ export function runDoctor(manifest) {
18
+ const findings = [];
19
+ const core = section(manifest, "mapoCore");
20
+ const media = section(manifest, "mapoMedia");
21
+ const moduleNames = new Set(manifest.modules.map((module) => module.name));
22
+ const order = manifest.moduleOrder;
23
+ const uiIndex = order.indexOf("@nuxt/ui");
24
+ const mapoIndex = order.findIndex(
25
+ (name) => name === "mapomodule" || name.startsWith("@mapomodule/")
26
+ );
27
+ if (mapoIndex !== -1 && uiIndex === -1) {
28
+ findings.push({
29
+ rule: "nuxt-ui-missing",
30
+ severity: "error",
31
+ message: "`@nuxt/ui` is not declared in `modules[]`, but Mapo's UI layer requires it.",
32
+ fix: 'Add "@nuxt/ui" as the first entry of `modules[]`.',
33
+ doc: "guide/getting-started.md"
34
+ });
35
+ } else if (mapoIndex !== -1 && uiIndex > mapoIndex) {
36
+ findings.push({
37
+ rule: "nuxt-ui-order",
38
+ severity: "error",
39
+ message: `\`@nuxt/ui\` is declared after \`${order[mapoIndex]}\` in modules[]. Icons break during SSR when Nuxt UI is initialised after Mapo.`,
40
+ fix: 'Move "@nuxt/ui" before the Mapo entry in `modules[]`.',
41
+ doc: "guide/compatibility.md"
42
+ });
43
+ }
44
+ if (!moduleNames.has("@mapomodule/core")) {
45
+ findings.push({
46
+ rule: "core-missing",
47
+ severity: "error",
48
+ message: "`@mapomodule/core` is not installed \u2014 auth, `useCrud` and route middleware are unavailable.",
49
+ fix: 'Add "mapomodule" to `modules[]`.',
50
+ doc: "guide/getting-started.md"
51
+ });
52
+ }
53
+ const loginUrl = typeof core.loginUrl === "string" ? core.loginUrl : AUTH_DEFAULTS.loginUrl;
54
+ const hasLoginRoute = manifest.routes.some(
55
+ (route) => route.path === loginUrl
56
+ );
57
+ if (!hasLoginRoute && manifest.routes.length > 0) {
58
+ findings.push({
59
+ rule: "login-route-missing",
60
+ severity: "error",
61
+ message: `No page matches \`loginUrl\` (\`${loginUrl}\`); the auth middleware would redirect to a missing route.`,
62
+ fix: `Create \`pages${loginUrl}.vue\` rendering <MapoLogin /> with \`definePageMeta({ layout: false })\`, or change \`mapo.loginUrl\`.`,
63
+ doc: "howto/auth-permissions.md"
64
+ });
65
+ }
66
+ const authKeys = ["authLoginUrl", "userInfoApi", "logoutUrl"];
67
+ const allDefault = authKeys.every(
68
+ (key) => (core[key] ?? AUTH_DEFAULTS[key]) === AUTH_DEFAULTS[key]
69
+ );
70
+ if (allDefault) {
71
+ findings.push({
72
+ rule: "auth-endpoints-default",
73
+ severity: "info",
74
+ message: "Auth endpoints are still the Mapo defaults \u2014 fine for a mock backend, not for a real one.",
75
+ fix: "Set `mapo.authLoginUrl`, `mapo.userInfoApi` and `mapo.logoutUrl` to your backend routes.",
76
+ doc: "howto/backend-integration.md"
77
+ });
78
+ }
79
+ const adminRoutes = manifest.routes.filter(
80
+ (route) => route.path !== loginUrl
81
+ );
82
+ if (adminRoutes.length === 0) {
83
+ findings.push({
84
+ rule: "no-admin-pages",
85
+ severity: "warning",
86
+ message: "The app has no admin page yet (only the login route was found).",
87
+ fix: 'Create a page with `definePageMeta({ layout: "mapo-default", middleware: ["auth"] })`.',
88
+ doc: "howto/first-admin-page.md"
89
+ });
90
+ }
91
+ const uncovered = manifest.locales.filter(
92
+ (locale) => !BUNDLED_LOCALES.has(locale)
93
+ );
94
+ if (uncovered.length) {
95
+ findings.push({
96
+ rule: "locale-without-catalog",
97
+ severity: "warning",
98
+ message: `Mapo ships UI catalogs for en and it only; ${uncovered.join(", ")} will fall back for framework strings.`,
99
+ fix: "Add the missing `mapo.*` keys to your own `i18n/locales/<code>.json`.",
100
+ doc: "howto/i18n.md"
101
+ });
102
+ }
103
+ const usesMedia = manifest.fieldTypes.some(
104
+ (field) => MEDIA_FIELD_TYPES.has(field.type)
105
+ );
106
+ const endpoints = media.endpoints ?? {};
107
+ const mediaDefaults = (endpoints.media ?? MEDIA_ENDPOINT_DEFAULTS.media) === MEDIA_ENDPOINT_DEFAULTS.media && (endpoints.folders ?? MEDIA_ENDPOINT_DEFAULTS.folders) === MEDIA_ENDPOINT_DEFAULTS.folders;
108
+ if (usesMedia && mediaDefaults && !moduleNames.has("mapo-integrations-camomilla")) {
109
+ findings.push({
110
+ rule: "media-endpoints-default",
111
+ severity: "info",
112
+ message: `Media field types are registered but the media endpoints are still the defaults (\`${MEDIA_ENDPOINT_DEFAULTS.media}\`, \`${MEDIA_ENDPOINT_DEFAULTS.folders}\`) and no integration provides them.`,
113
+ fix: "Set `mapo.uikit.media.endpoints`, or install an integration that serves them.",
114
+ doc: "howto/media-manager.md"
115
+ });
116
+ }
117
+ const rank = {
118
+ error: 0,
119
+ warning: 1,
120
+ info: 2
121
+ };
122
+ return findings.sort((a, b) => rank[a.severity] - rank[b.severity]);
123
+ }
124
+ export const DOCTOR_BLIND_SPOTS = [
125
+ "field types registered at runtime by `defineFormField()` inside a plugin",
126
+ "`definePageMeta` values (layout, middleware, permissions) of your pages",
127
+ "anything that depends on a request, such as the logged-in user's permissions"
128
+ ];
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
+ }
File without changes
@@ -0,0 +1,194 @@
1
+ import { readdirSync, readFileSync, statSync } from "node:fs";
2
+ import { join, relative, sep } from "node:path";
3
+ import { tokenize } from "./tokenize.js";
4
+ export const KNOWLEDGE_VERSION = 1;
5
+ const MAX_CHUNK_CHARS = 3500;
6
+ const EXCLUDED_DIRS = /* @__PURE__ */ new Set([
7
+ "node_modules",
8
+ "roadmap",
9
+ "contributing",
10
+ ".vitepress",
11
+ "dist"
12
+ ]);
13
+ const EXCLUDED_FILES = /* @__PURE__ */ new Set(["DECISIONS.md", "AGENTS.md", "CLAUDE.md"]);
14
+ const BOOST = { heading: 3, title: 2, tags: 3, text: 1 };
15
+ const PKG_BY_PREFIX = [
16
+ ["uikit/form", "@mapomodule/form"],
17
+ ["uikit", "@mapomodule/uikit"],
18
+ ["modules/core", "@mapomodule/core"],
19
+ ["modules/store", "@mapomodule/store"],
20
+ ["modules/utils", "@mapomodule/utils"],
21
+ ["modules/i18n", "@mapomodule/i18n"],
22
+ ["modules/api", "@mapomodule/core"],
23
+ ["modules/camomilla", "mapo-integrations-camomilla"]
24
+ ];
25
+ const REFERENCE_PATH = /(?:^|\/)api\.md$/;
26
+ const REFERENCE_HEADING = /^(props|slots|emits|events|exposed|api)\b/i;
27
+ export function slugify(heading) {
28
+ return heading.toLowerCase().replace(/`/g, "").replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "-");
29
+ }
30
+ function toPosix(path) {
31
+ return sep === "/" ? path : path.split(sep).join("/");
32
+ }
33
+ export function collectMarkdownFiles(root) {
34
+ const files = [];
35
+ const walk = (dir) => {
36
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
37
+ if (entry.name.startsWith(".") && entry.name !== ".vitepress") continue;
38
+ const full = join(dir, entry.name);
39
+ if (entry.isDirectory()) {
40
+ if (EXCLUDED_DIRS.has(entry.name)) continue;
41
+ walk(full);
42
+ } else if (entry.isFile() && entry.name.endsWith(".md") && !EXCLUDED_FILES.has(entry.name)) {
43
+ files.push(full);
44
+ }
45
+ }
46
+ };
47
+ walk(root);
48
+ return files.sort();
49
+ }
50
+ export function extractTags(text) {
51
+ const tags = /* @__PURE__ */ new Set();
52
+ for (const match of text.matchAll(/\bMapo[A-Z][A-Za-z0-9]*/g))
53
+ tags.add(match[0]);
54
+ for (const match of text.matchAll(/\buse[A-Z][A-Za-z0-9]*/g))
55
+ tags.add(match[0]);
56
+ for (const match of text.matchAll(/\btype:\s*["']([a-z0-9-]+)["']/g)) {
57
+ if (match[1]) tags.add(match[1]);
58
+ }
59
+ return [...tags];
60
+ }
61
+ export function splitSections(markdown) {
62
+ const lines = markdown.replace(/\r\n/g, "\n").split("\n");
63
+ const sections = [];
64
+ let title = "";
65
+ let current = { heading: "", level: 1, lines: [] };
66
+ let fence = null;
67
+ for (const line of lines) {
68
+ const fenceMatch = /^\s*(```|~~~)/.exec(line);
69
+ if (fenceMatch) {
70
+ if (fence && line.trimStart().startsWith(fence)) fence = null;
71
+ else if (!fence) fence = fenceMatch[1];
72
+ current.lines.push(line);
73
+ continue;
74
+ }
75
+ if (!fence) {
76
+ const heading = /^(#{1,3})\s+(.*)$/.exec(line);
77
+ if (heading) {
78
+ const level = heading[1].length;
79
+ const text = heading[2].trim();
80
+ if (level === 1 && !title) {
81
+ title = text;
82
+ current.heading ||= text;
83
+ continue;
84
+ }
85
+ if (level >= 2) {
86
+ if (current.lines.some((l) => l.trim())) sections.push(current);
87
+ current = { heading: text, level, lines: [] };
88
+ continue;
89
+ }
90
+ }
91
+ }
92
+ current.lines.push(line);
93
+ }
94
+ if (current.lines.some((l) => l.trim())) sections.push(current);
95
+ return { title, sections };
96
+ }
97
+ function splitLongText(text) {
98
+ if (text.length <= MAX_CHUNK_CHARS) return [text];
99
+ const parts = [];
100
+ let buffer = "";
101
+ for (const paragraph of text.split(/\n{2,}/)) {
102
+ if (buffer && buffer.length + paragraph.length > MAX_CHUNK_CHARS) {
103
+ parts.push(buffer.trim());
104
+ buffer = "";
105
+ }
106
+ buffer += `${paragraph}
107
+
108
+ `;
109
+ }
110
+ if (buffer.trim()) parts.push(buffer.trim());
111
+ return parts;
112
+ }
113
+ export function chunkMarkdown(path, markdown) {
114
+ const posixPath = toPosix(path);
115
+ const segments = posixPath.split("/");
116
+ const section = segments.length > 1 ? segments[0] : "root";
117
+ const group = segments.length > 2 ? segments[1] : void 0;
118
+ const pkg = PKG_BY_PREFIX.find(
119
+ ([prefix]) => posixPath.startsWith(prefix)
120
+ )?.[1];
121
+ const { title, sections } = splitSections(markdown);
122
+ const docTitle = title || segments.at(-1).replace(/\.md$/, "");
123
+ const isReferencePage = REFERENCE_PATH.test(posixPath);
124
+ const chunks = [];
125
+ const seenAnchors = /* @__PURE__ */ new Map();
126
+ for (const rawSection of sections) {
127
+ const heading = rawSection.heading || docTitle;
128
+ const body = rawSection.lines.join("\n").trim();
129
+ if (!body) continue;
130
+ const parts = splitLongText(body);
131
+ parts.forEach((text, partIndex) => {
132
+ const baseAnchor = rawSection.heading ? slugify(rawSection.heading) : "";
133
+ const seen = seenAnchors.get(baseAnchor) ?? 0;
134
+ seenAnchors.set(baseAnchor, seen + 1);
135
+ const anchor = `${baseAnchor}${seen > 0 ? `-${seen}` : ""}`;
136
+ chunks.push({
137
+ id: `${posixPath}#${anchor}${partIndex > 0 ? `~${partIndex}` : ""}`,
138
+ path: posixPath,
139
+ section,
140
+ ...group ? { group } : {},
141
+ ...pkg ? { pkg } : {},
142
+ title: docTitle,
143
+ heading,
144
+ anchor,
145
+ level: rawSection.heading ? rawSection.level : 1,
146
+ ...isReferencePage || REFERENCE_HEADING.test(heading) ? { kind: "reference" } : {},
147
+ text,
148
+ tags: extractTags(text)
149
+ });
150
+ });
151
+ }
152
+ return chunks;
153
+ }
154
+ export function buildIndex(chunks) {
155
+ const terms = {};
156
+ const lengths = [];
157
+ chunks.forEach((chunk, chunkIndex) => {
158
+ const counts = /* @__PURE__ */ new Map();
159
+ const add = (input, boost) => {
160
+ for (const token of tokenize(input)) {
161
+ counts.set(token, (counts.get(token) ?? 0) + boost);
162
+ }
163
+ };
164
+ add(chunk.text, BOOST.text);
165
+ add(chunk.heading, BOOST.heading);
166
+ add(chunk.title, BOOST.title);
167
+ add(chunk.tags.join(" "), BOOST.tags);
168
+ let length = 0;
169
+ for (const [term, frequency] of counts) {
170
+ (terms[term] ??= []).push([chunkIndex, frequency]);
171
+ length += frequency;
172
+ }
173
+ lengths.push(length);
174
+ });
175
+ const total = chunks.length;
176
+ const avgLength = total ? lengths.reduce((a, b) => a + b, 0) / total : 0;
177
+ return { terms, lengths, avgLength, total };
178
+ }
179
+ export function buildDocsKnowledge(docsRoot) {
180
+ const files = collectMarkdownFiles(docsRoot);
181
+ const chunks = [];
182
+ for (const file of files) {
183
+ if (!statSync(file).isFile()) continue;
184
+ const markdown = readFileSync(file, "utf-8");
185
+ chunks.push(...chunkMarkdown(relative(docsRoot, file), markdown));
186
+ }
187
+ return {
188
+ version: KNOWLEDGE_VERSION,
189
+ generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
190
+ docsRoot: "docs",
191
+ chunks,
192
+ index: buildIndex(chunks)
193
+ };
194
+ }
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,76 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { dirname, join, resolve } from "node:path";
3
+ import { fileURLToPath } from "node:url";
4
+ import { KNOWLEDGE_VERSION } from "./indexer.js";
5
+ export const DOCS_KNOWLEDGE_FILE = "docs.json";
6
+ export const API_KNOWLEDGE_FILE = "api.json";
7
+ export const API_KNOWLEDGE_VERSION = 1;
8
+ const cache = /* @__PURE__ */ new Map();
9
+ const apiCache = /* @__PURE__ */ new Map();
10
+ const CANDIDATE_SUFFIXES = [
11
+ "knowledge",
12
+ "../knowledge",
13
+ "../../knowledge",
14
+ "../../../knowledge",
15
+ "../dist/knowledge",
16
+ "../../dist/knowledge",
17
+ "../../../dist/knowledge",
18
+ "../../../../dist/knowledge"
19
+ ];
20
+ export function resolveKnowledgeDir(fromUrl = import.meta.url) {
21
+ const override = process.env.MAPO_MCP_KNOWLEDGE_DIR;
22
+ if (override && existsSync(join(override, DOCS_KNOWLEDGE_FILE)))
23
+ return override;
24
+ const base = dirname(fileURLToPath(fromUrl));
25
+ for (const suffix of CANDIDATE_SUFFIXES) {
26
+ const candidate = resolve(base, suffix);
27
+ if (existsSync(join(candidate, DOCS_KNOWLEDGE_FILE))) return candidate;
28
+ }
29
+ return null;
30
+ }
31
+ export class KnowledgeNotBuiltError extends Error {
32
+ constructor(searchedFrom) {
33
+ super(
34
+ `Mapo knowledge base not found (looked around ${searchedFrom}). Build it with \`pnpm --filter @mapomodule/mcp knowledge\`.`
35
+ );
36
+ this.name = "KnowledgeNotBuiltError";
37
+ }
38
+ }
39
+ export function loadDocsKnowledge(dir) {
40
+ const directory = dir ?? resolveKnowledgeDir();
41
+ if (!directory)
42
+ throw new KnowledgeNotBuiltError(fileURLToPath(import.meta.url));
43
+ const cached = cache.get(directory);
44
+ if (cached) return cached;
45
+ const file = join(directory, DOCS_KNOWLEDGE_FILE);
46
+ if (!existsSync(file)) throw new KnowledgeNotBuiltError(directory);
47
+ const knowledge = JSON.parse(readFileSync(file, "utf-8"));
48
+ if (knowledge.version !== KNOWLEDGE_VERSION) {
49
+ throw new Error(
50
+ `Mapo knowledge base version mismatch: found ${knowledge.version}, expected ${KNOWLEDGE_VERSION}. Rebuild it.`
51
+ );
52
+ }
53
+ cache.set(directory, knowledge);
54
+ return knowledge;
55
+ }
56
+ export function loadApiKnowledge(dir) {
57
+ const directory = dir ?? resolveKnowledgeDir();
58
+ if (!directory)
59
+ throw new KnowledgeNotBuiltError(fileURLToPath(import.meta.url));
60
+ const cached = apiCache.get(directory);
61
+ if (cached) return cached;
62
+ const file = join(directory, API_KNOWLEDGE_FILE);
63
+ if (!existsSync(file)) throw new KnowledgeNotBuiltError(directory);
64
+ const api = JSON.parse(readFileSync(file, "utf-8"));
65
+ if (api.version !== API_KNOWLEDGE_VERSION) {
66
+ throw new Error(
67
+ `Mapo API surface version mismatch: found ${api.version}, expected ${API_KNOWLEDGE_VERSION}. Rebuild it.`
68
+ );
69
+ }
70
+ apiCache.set(directory, api);
71
+ return api;
72
+ }
73
+ export function clearKnowledgeCache() {
74
+ cache.clear();
75
+ apiCache.clear();
76
+ }
File without changes