@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,154 @@
1
+ import { z } from "zod";
2
+ import { overviewSummary } from "../overview.js";
3
+ import { matchRecipes, RECIPES } from "../recipes.js";
4
+ import { getDoc, searchDocs } from "../search.js";
5
+ import { defineMapoTool } from "../tool-spec.js";
6
+ function renderRecipes(recipes) {
7
+ if (!recipes.length) return "";
8
+ const lines = recipes.map((recipe) => {
9
+ const section = recipe.heading ? ` (section "${recipe.heading}")` : "";
10
+ const seeAlso = recipe.seeAlso?.length ? `
11
+ see also: ${recipe.seeAlso.join(", ")}` : "";
12
+ return `- **${recipe.task}** \u2192 \`${recipe.doc}\`${section}
13
+ ${recipe.summary}${seeAlso}`;
14
+ });
15
+ return `## Canonical recipe${recipes.length > 1 ? "s" : ""} for this task
16
+ ${lines.join("\n")}
17
+
18
+ `;
19
+ }
20
+ const SECTIONS = [
21
+ "howto",
22
+ "guide",
23
+ "uikit",
24
+ "form",
25
+ "modules",
26
+ "migration"
27
+ ];
28
+ export const searchDocsTool = defineMapoTool({
29
+ name: "mapo_search_docs",
30
+ title: "Search Mapo documentation",
31
+ description: "Search the official Mapo documentation and return the most relevant sections (never whole files). Use this before writing any Mapo code; follow up with mapo_get_doc to read a full section.",
32
+ inputSchema: {
33
+ query: z.string().describe(
34
+ "Natural-language question or keywords, e.g. 'paginated list with filters'"
35
+ ),
36
+ section: z.enum(SECTIONS).optional().describe("Restrict to one docs area"),
37
+ pkg: z.string().optional().describe("Restrict to a package, e.g. '@mapomodule/form' or 'uikit'"),
38
+ limit: z.number().int().min(1).max(20).optional().describe("Number of sections to return (default 5)")
39
+ },
40
+ annotations: {
41
+ readOnlyHint: true,
42
+ destructiveHint: false,
43
+ idempotentHint: true,
44
+ openWorldHint: false
45
+ },
46
+ inputExamples: [
47
+ { query: "CRUD list with filters and bulk actions" },
48
+ { query: "custom form field registration", section: "form" }
49
+ ],
50
+ run: (args, context) => {
51
+ const hits = searchDocs(context.knowledge(), args.query, {
52
+ ...args.section ? { section: args.section } : {},
53
+ ...args.pkg ? { pkg: args.pkg } : {},
54
+ ...args.limit ? { limit: args.limit } : {}
55
+ });
56
+ const recipes = renderRecipes(matchRecipes(args.query));
57
+ if (!hits.length) {
58
+ return recipes ? `${recipes}No section matched the keywords, but the recipe above covers this task.` : `No documentation section matched "${args.query}". Try fewer or more general keywords, or drop the section filter.`;
59
+ }
60
+ const body = hits.map(
61
+ (hit, position) => `### ${position + 1}. ${hit.title} \u2014 ${hit.heading}
62
+ path: \`${hit.path}\`${hit.anchor ? ` \xB7 anchor: \`#${hit.anchor}\`` : ""} \xB7 score: ${hit.score}
63
+ ` + (hit.tags.length ? `symbols: ${hit.tags.join(", ")}
64
+ ` : "") + `
65
+ ${hit.snippet}
66
+ `
67
+ ).join("\n---\n\n");
68
+ return `${recipes}${hits.length} matching section(s) for "${args.query}":
69
+
70
+ ${body}
71
+ ---
72
+ Read a full section with mapo_get_doc({ path, heading }).`;
73
+ }
74
+ });
75
+ export const getDocTool = defineMapoTool({
76
+ name: "mapo_get_doc",
77
+ title: "Read a Mapo documentation page",
78
+ description: "Return the exact markdown of a documentation page, or of one of its sections when `heading` is given. Paths come from mapo_search_docs (e.g. 'howto/crud-list.md').",
79
+ inputSchema: {
80
+ path: z.string().describe(
81
+ "Doc path relative to the docs root, e.g. 'howto/crud-detail.md'"
82
+ ),
83
+ heading: z.string().optional().describe(
84
+ "Section heading or anchor to return instead of the whole page"
85
+ ),
86
+ maxChars: z.number().int().min(500).max(4e4).optional().describe("Truncation limit (default 8000)")
87
+ },
88
+ annotations: {
89
+ readOnlyHint: true,
90
+ destructiveHint: false,
91
+ idempotentHint: true,
92
+ openWorldHint: false
93
+ },
94
+ inputExamples: [
95
+ { path: "howto/crud-list.md" },
96
+ { path: "uikit/form/validation.md", heading: "Async validation" }
97
+ ],
98
+ run: (args, context) => {
99
+ const doc = getDoc(context.knowledge(), args.path, {
100
+ ...args.heading ? { heading: args.heading } : {},
101
+ ...args.maxChars ? { maxChars: args.maxChars } : {}
102
+ });
103
+ if (!doc) {
104
+ return `No such documentation page: "${args.path}". Use mapo_search_docs to find the correct path.`;
105
+ }
106
+ return `# ${doc.title}
107
+ source: \`${doc.path}\`
108
+ sections: ${doc.headings.join(" \xB7 ") || "(none)"}
109
+
110
+ ${doc.content}`;
111
+ }
112
+ });
113
+ export const listRecipesTool = defineMapoTool({
114
+ name: "mapo_list_recipes",
115
+ title: "List Mapo task recipes",
116
+ description: "List the canonical Mapo recipes (task \u2192 documentation page). Call this to discover what Mapo can do out of the box before designing a solution, or pass `task` to find the recipe for a goal.",
117
+ inputSchema: {
118
+ task: z.string().optional().describe(
119
+ "Goal in plain words, e.g. 'let editors reorder navigation entries'"
120
+ )
121
+ },
122
+ annotations: {
123
+ readOnlyHint: true,
124
+ destructiveHint: false,
125
+ idempotentHint: true,
126
+ openWorldHint: false
127
+ },
128
+ inputExamples: [{}, { task: "upload images and pick them in a form" }],
129
+ run: (args, context) => {
130
+ if (args.task) {
131
+ const matches = matchRecipes(args.task, 3);
132
+ if (!matches.length) {
133
+ return `No curated recipe matches "${args.task}". Fall back to mapo_search_docs, or call mapo_list_recipes with no argument to see every recipe.`;
134
+ }
135
+ return `${renderRecipes(matches)}Read the page with mapo_get_doc({ path }).`;
136
+ }
137
+ const summary = overviewSummary(context.knowledge());
138
+ const lines = RECIPES.map(
139
+ (recipe) => `- **${recipe.task}** \u2192 \`${recipe.doc}\` \u2014 ${recipe.summary}`
140
+ );
141
+ return `${summary ? `${summary}
142
+
143
+ ` : ""}${RECIPES.length} Mapo recipes:
144
+
145
+ ${lines.join("\n")}
146
+
147
+ Read one with mapo_get_doc({ path }).`;
148
+ }
149
+ });
150
+ export const docsTools = [
151
+ searchDocsTool,
152
+ getDocTool,
153
+ listRecipesTool
154
+ ];
File without changes
@@ -0,0 +1,127 @@
1
+ import { z } from "zod";
2
+ import {
3
+ SCAFFOLD_DESCRIPTIONS,
4
+ SCAFFOLD_KINDS,
5
+ UnknownFieldTypeError,
6
+ scaffold
7
+ } from "../scaffold/index.js";
8
+ import { defineMapoTool } from "../tool-spec.js";
9
+ import { writeScaffold } from "../write.js";
10
+ function languageOf(path) {
11
+ if (path.endsWith(".vue")) return "vue";
12
+ if (path.endsWith(".ts")) return "ts";
13
+ if (path.endsWith(".css")) return "css";
14
+ return "";
15
+ }
16
+ const KIND_LIST = SCAFFOLD_KINDS.map(
17
+ (kind) => `\`${kind}\` (${SCAFFOLD_DESCRIPTIONS[kind]})`
18
+ ).join(", ");
19
+ export const scaffoldTool = defineMapoTool({
20
+ name: "mapo_scaffold",
21
+ title: "Scaffold Mapo code",
22
+ description: `Generate Mapo code that follows the framework's canonical patterns: list and detail pages, standalone forms, custom field types, login page, theming, backend proxy, menu and media pages. Returns the files for review; pass \`write: true\` to create them in the project. Kinds: ${KIND_LIST}.`,
23
+ inputSchema: {
24
+ kind: z.enum(SCAFFOLD_KINDS).describe("What to generate"),
25
+ name: z.string().optional().describe(
26
+ "Resource name, e.g. 'articles' \u2014 or the type name for custom-field"
27
+ ),
28
+ endpoint: z.string().optional().describe("REST endpoint (default `/api/<name>`)"),
29
+ route: z.string().optional().describe("Route base (default `/<name>`)"),
30
+ fields: z.array(z.string()).optional().describe(
31
+ "Field specs `key[:type[:label]]`, e.g. ['title:text:Title', 'body:editor']"
32
+ ),
33
+ write: z.boolean().optional().describe(
34
+ "Create the files instead of only showing them (development only)"
35
+ ),
36
+ overwrite: z.boolean().optional().describe("Allow replacing files that already exist")
37
+ },
38
+ annotations: {
39
+ // Not read-only: with `write` it creates files. Never destructive: existing
40
+ // files are refused unless `overwrite` is set.
41
+ readOnlyHint: false,
42
+ destructiveHint: false,
43
+ idempotentHint: true,
44
+ openWorldHint: false
45
+ },
46
+ inputExamples: [
47
+ {
48
+ kind: "list-page",
49
+ name: "articles",
50
+ fields: ["title:text:Title", "status:select:Status"]
51
+ },
52
+ {
53
+ kind: "detail-page",
54
+ name: "articles",
55
+ fields: ["title:text", "body:editor"],
56
+ write: true
57
+ },
58
+ { kind: "custom-field", name: "star-rating" }
59
+ ],
60
+ run: (args, context) => {
61
+ let result;
62
+ try {
63
+ result = scaffold({
64
+ kind: args.kind,
65
+ ...args.name ? { name: args.name } : {},
66
+ ...args.endpoint ? { endpoint: args.endpoint } : {},
67
+ ...args.route ? { route: args.route } : {},
68
+ ...args.fields ? { fields: args.fields } : {},
69
+ api: context.api()
70
+ });
71
+ } catch (error) {
72
+ if (error instanceof UnknownFieldTypeError) return error.message;
73
+ throw error;
74
+ }
75
+ const notes = result.notes.map((note) => `- ${note}`).join("\n");
76
+ const docs = result.docs.map((doc) => `\`${doc}\``).join(", ");
77
+ if (!args.write) {
78
+ const blocks = result.files.map(
79
+ (file) => `### \`${file.path}\`
80
+
81
+ \`\`\`${languageOf(file.path)}
82
+ ${file.content}\`\`\``
83
+ ).join("\n\n");
84
+ return `# ${SCAFFOLD_DESCRIPTIONS[args.kind]}
85
+
86
+ ${blocks}
87
+
88
+ ## Notes
89
+ ${notes}
90
+
91
+ Docs: ${docs}
92
+
93
+ Nothing was written. Call again with \`write: true\` to create these files.`;
94
+ }
95
+ const root = context.rootDir();
96
+ if (!root) {
97
+ return "Cannot write: the project root is unknown.\n\nConnect to the app's endpoint (`/mcp/mapo`) so the server knows where the project is, or run `mapo-mcp serve --root <path>`. The files above are unchanged.";
98
+ }
99
+ const outcomes = writeScaffold(result.files, {
100
+ root,
101
+ overwrite: args.overwrite ?? false,
102
+ allowed: context.canWrite()
103
+ });
104
+ const lines = outcomes.map((outcome) => {
105
+ const icon = outcome.status === "written" ? "\u2714" : "\u2716";
106
+ const detail = outcome.reason ? ` \u2014 ${outcome.reason}` : "";
107
+ return `- ${icon} \`${outcome.path}\` (${outcome.status})${detail}`;
108
+ });
109
+ const written = outcomes.filter(
110
+ (outcome) => outcome.status === "written"
111
+ ).length;
112
+ const blocked = outcomes.length - written;
113
+ return `# ${SCAFFOLD_DESCRIPTIONS[args.kind]}
114
+
115
+ Root: \`${root}\`
116
+
117
+ ${lines.join("\n")}
118
+
119
+ ` + (blocked ? `${blocked} file(s) were not written. Read the reason above; use \`overwrite: true\` only when replacing is intended.
120
+
121
+ ` : "") + `## Notes
122
+ ${notes}
123
+
124
+ Docs: ${docs}`;
125
+ }
126
+ });
127
+ export const scaffoldTools = [scaffoldTool];
File without changes
File without changes
File without changes
@@ -0,0 +1,53 @@
1
+ import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
2
+ import { dirname, isAbsolute, join, resolve, sep } from "node:path";
3
+ export function resolveInsideRoot(root, relative) {
4
+ if (isAbsolute(relative)) return null;
5
+ const realRoot = existsSync(root) ? realpathSync(root) : resolve(root);
6
+ const target = resolve(realRoot, relative);
7
+ let existing = target;
8
+ while (!existsSync(existing) && dirname(existing) !== existing) {
9
+ existing = dirname(existing);
10
+ }
11
+ const realExisting = existsSync(existing) ? realpathSync(existing) : existing;
12
+ const rest = target.slice(existing.length);
13
+ const realTarget = join(realExisting, rest);
14
+ const boundary = realRoot.endsWith(sep) ? realRoot : `${realRoot}${sep}`;
15
+ return realTarget === realRoot || realTarget.startsWith(boundary) ? realTarget : null;
16
+ }
17
+ export function writeScaffold(files, { root, overwrite = false, allowed = true }) {
18
+ return files.map((file) => {
19
+ if (!allowed) {
20
+ return {
21
+ path: file.path,
22
+ status: "not-allowed",
23
+ reason: "writing is only available while the app runs in development"
24
+ };
25
+ }
26
+ if (isAbsolute(file.path)) {
27
+ return {
28
+ path: file.path,
29
+ status: "absolute-path",
30
+ reason: "paths must be relative to the project root"
31
+ };
32
+ }
33
+ const absolute = resolveInsideRoot(root, file.path);
34
+ if (!absolute) {
35
+ return {
36
+ path: file.path,
37
+ status: "outside-root",
38
+ reason: `resolves outside ${root}`
39
+ };
40
+ }
41
+ if (existsSync(absolute) && !overwrite) {
42
+ return {
43
+ path: file.path,
44
+ status: "exists",
45
+ absolute,
46
+ reason: "pass overwrite: true to replace it"
47
+ };
48
+ }
49
+ mkdirSync(dirname(absolute), { recursive: true });
50
+ writeFileSync(absolute, file.content, "utf-8");
51
+ return { path: file.path, status: "written", absolute };
52
+ });
53
+ }
@@ -0,0 +1,7 @@
1
+ import { defineMcpHandler } from "@nuxtjs/mcp-toolkit/server";
2
+ import { MAPO_INSTRUCTIONS } from "../../../core/instructions.js";
3
+ export default defineMcpHandler({
4
+ name: "mapo",
5
+ description: "Mapo admin framework: docs, component and field APIs, app introspection, scaffolding.",
6
+ instructions: MAPO_INSTRUCTIONS
7
+ });
@@ -0,0 +1,3 @@
1
+ import { crudPagePrompt } from "../../../../core/prompts.js";
2
+ import { toMcpPrompt } from "../../../../nitro/to-mcp-prompt.js";
3
+ export default toMcpPrompt(crudPagePrompt);
@@ -0,0 +1,3 @@
1
+ import { customFieldPrompt } from "../../../../core/prompts.js";
2
+ import { toMcpPrompt } from "../../../../nitro/to-mcp-prompt.js";
3
+ export default toMcpPrompt(customFieldPrompt);
@@ -0,0 +1,3 @@
1
+ import { debugFormPrompt } from "../../../../core/prompts.js";
2
+ import { toMcpPrompt } from "../../../../nitro/to-mcp-prompt.js";
3
+ export default toMcpPrompt(debugFormPrompt);
@@ -0,0 +1,3 @@
1
+ import { migratePrompt } from "../../../../core/prompts.js";
2
+ import { toMcpPrompt } from "../../../../nitro/to-mcp-prompt.js";
3
+ export default toMcpPrompt(migratePrompt);
@@ -0,0 +1,3 @@
1
+ import { themePrompt } from "../../../../core/prompts.js";
2
+ import { toMcpPrompt } from "../../../../nitro/to-mcp-prompt.js";
3
+ export default toMcpPrompt(themePrompt);
@@ -0,0 +1,19 @@
1
+ import { defineMcpResource } from "@nuxtjs/mcp-toolkit/server";
2
+ import { MANIFEST_URI } from "../../../../core/resources.js";
3
+ import { useMapoManifest } from "../../../../nitro/context.js";
4
+ export default defineMcpResource({
5
+ name: "mapo-app-manifest",
6
+ title: "This app's Mapo setup",
7
+ description: "Installed Mapo modules, public Mapo config, registered field types, available components, admin routes and locales of the app currently running.",
8
+ uri: MANIFEST_URI,
9
+ metadata: { mimeType: "application/json" },
10
+ handler: (uri) => ({
11
+ contents: [
12
+ {
13
+ uri: uri.toString(),
14
+ mimeType: "application/json",
15
+ text: JSON.stringify(useMapoManifest(), null, 2)
16
+ }
17
+ ]
18
+ })
19
+ });
@@ -0,0 +1,34 @@
1
+ import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { defineMcpResource } from "@nuxtjs/mcp-toolkit/server";
3
+ import {
4
+ DOCS_URI_PREFIX,
5
+ docResourceList,
6
+ renderDocResource
7
+ } from "../../../../core/resources.js";
8
+ import { useDocsKnowledge } from "../../../../nitro/context.js";
9
+ export default defineMcpResource({
10
+ name: "mapo-doc",
11
+ title: "Mapo documentation page",
12
+ description: "A full Mapo documentation page, addressed by its path (e.g. howto/crud-list.md).",
13
+ uri: new ResourceTemplate(`${DOCS_URI_PREFIX}{+path}`, {
14
+ list: () => ({ resources: docResourceList(useDocsKnowledge()) })
15
+ }),
16
+ metadata: { mimeType: "text/markdown" },
17
+ handler: (uri, variables) => {
18
+ const raw = variables.path;
19
+ const path = Array.isArray(raw) ? raw.join("/") : raw ?? "";
20
+ const text = renderDocResource(
21
+ useDocsKnowledge(),
22
+ decodeURIComponent(path)
23
+ );
24
+ return {
25
+ contents: [
26
+ {
27
+ uri: uri.toString(),
28
+ mimeType: "text/markdown",
29
+ text: text ?? `No documentation page at "${path}".`
30
+ }
31
+ ]
32
+ };
33
+ }
34
+ });
@@ -0,0 +1,34 @@
1
+ import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { defineMcpResource } from "@nuxtjs/mcp-toolkit/server";
3
+ import {
4
+ FIELD_URI_PREFIX,
5
+ fieldResourceList,
6
+ renderFieldResource
7
+ } from "../../../../core/resources.js";
8
+ import { useApiKnowledge } from "../../../../nitro/context.js";
9
+ export default defineMcpResource({
10
+ name: "mapo-field-type",
11
+ title: "Mapo form field type",
12
+ description: "The full contract of a form field type: the component behind it, its attrs and the shared descriptor properties.",
13
+ uri: new ResourceTemplate(`${FIELD_URI_PREFIX}{type}`, {
14
+ list: () => ({ resources: fieldResourceList(useApiKnowledge()) })
15
+ }),
16
+ metadata: { mimeType: "text/markdown" },
17
+ handler: (uri, variables) => {
18
+ const raw = variables.type;
19
+ const type = Array.isArray(raw) ? raw[0] : raw ?? "";
20
+ const text = renderFieldResource(
21
+ useApiKnowledge(),
22
+ decodeURIComponent(type)
23
+ );
24
+ return {
25
+ contents: [
26
+ {
27
+ uri: uri.toString(),
28
+ mimeType: "text/markdown",
29
+ text: text ?? `No field type "${type}" is registered.`
30
+ }
31
+ ]
32
+ };
33
+ }
34
+ });
@@ -0,0 +1,22 @@
1
+ import { defineMcpResource } from "@nuxtjs/mcp-toolkit/server";
2
+ import { INDEX_URI, renderKnowledgeIndex } from "../../../../core/resources.js";
3
+ import {
4
+ useApiKnowledge,
5
+ useDocsKnowledge
6
+ } from "../../../../nitro/context.js";
7
+ export default defineMcpResource({
8
+ name: "mapo-knowledge-index",
9
+ title: "Mapo knowledge index",
10
+ description: "Everything the Mapo MCP server knows: recipes, documentation pages, components, field types and composables.",
11
+ uri: INDEX_URI,
12
+ metadata: { mimeType: "text/markdown" },
13
+ handler: (uri) => ({
14
+ contents: [
15
+ {
16
+ uri: uri.toString(),
17
+ mimeType: "text/markdown",
18
+ text: renderKnowledgeIndex(useDocsKnowledge(), useApiKnowledge())
19
+ }
20
+ ]
21
+ })
22
+ });
@@ -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
+ });
@@ -0,0 +1,3 @@
1
+ import { backendSchemaTool } from "../../../../core/tools/backend.js";
2
+ import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
3
+ export default toMcpTool(backendSchemaTool);
@@ -0,0 +1,3 @@
1
+ import { componentApiTool } from "../../../../core/tools/api.js";
2
+ import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
3
+ export default toMcpTool(componentApiTool);
@@ -0,0 +1,3 @@
1
+ import { composableApiTool } from "../../../../core/tools/api.js";
2
+ import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
3
+ export default toMcpTool(composableApiTool);
@@ -0,0 +1,3 @@
1
+ import { doctorTool } from "../../../../core/tools/app.js";
2
+ import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
3
+ export default toMcpTool(doctorTool);
@@ -0,0 +1,3 @@
1
+ import { getDocTool } from "../../../../core/tools/docs.js";
2
+ import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
3
+ export default toMcpTool(getDocTool);
@@ -0,0 +1,3 @@
1
+ import { inspectAppTool } from "../../../../core/tools/app.js";
2
+ import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
3
+ export default toMcpTool(inspectAppTool);
@@ -0,0 +1,3 @@
1
+ import { fieldTypesTool } from "../../../../core/tools/api.js";
2
+ import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
3
+ export default toMcpTool(fieldTypesTool);
@@ -0,0 +1,3 @@
1
+ import { listRecipesTool } from "../../../../core/tools/docs.js";
2
+ import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
3
+ export default toMcpTool(listRecipesTool);
@@ -0,0 +1,3 @@
1
+ import { scaffoldTool } from "../../../../core/tools/scaffold.js";
2
+ import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
3
+ export default toMcpTool(scaffoldTool);
@@ -0,0 +1,3 @@
1
+ import { searchDocsTool } from "../../../../core/tools/docs.js";
2
+ import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
3
+ export default toMcpTool(searchDocsTool);
File without changes
@@ -0,0 +1,21 @@
1
+ import context from "#mapo-mcp/context.mjs";
2
+ import { loadApiKnowledge, loadDocsKnowledge } from "../core/knowledge.js";
3
+ export function useMapoMcpContext() {
4
+ return context;
5
+ }
6
+ export function useMapoManifest() {
7
+ return context.manifest;
8
+ }
9
+ export function useDocsKnowledge() {
10
+ return loadDocsKnowledge(context.knowledgeDir);
11
+ }
12
+ export function useMapoBackend() {
13
+ const { schemaUrl, tokenEnv } = context.backend;
14
+ return {
15
+ schemaUrl: schemaUrl ?? process.env.MAPO_BACKEND_SCHEMA_URL ?? null,
16
+ token: (tokenEnv ? process.env[tokenEnv] : void 0) ?? null
17
+ };
18
+ }
19
+ export function useApiKnowledge() {
20
+ return loadApiKnowledge(context.knowledgeDir);
21
+ }
File without changes
@@ -0,0 +1,23 @@
1
+ import { defineMcpPrompt } from "@nuxtjs/mcp-toolkit/server";
2
+ export function toMcpPrompt(prompt) {
3
+ return defineMcpPrompt({
4
+ name: prompt.name,
5
+ title: prompt.title,
6
+ description: prompt.description,
7
+ inputSchema: prompt.argsSchema,
8
+ // The toolkit types the callback from the zod shape, which widens to
9
+ // `unknown` for a generic `ZodRawShape`; every argument here is an optional
10
+ // string, validated by zod before the handler runs.
11
+ handler: (args) => ({
12
+ messages: [
13
+ {
14
+ role: "user",
15
+ content: {
16
+ type: "text",
17
+ text: prompt.render(args)
18
+ }
19
+ }
20
+ ]
21
+ })
22
+ });
23
+ }
File without changes
@@ -0,0 +1,28 @@
1
+ import { defineMcpTool } from "@nuxtjs/mcp-toolkit/server";
2
+ import {
3
+ useApiKnowledge,
4
+ useDocsKnowledge,
5
+ useMapoBackend,
6
+ useMapoManifest
7
+ } from "./context.js";
8
+ export function toMcpTool(spec) {
9
+ return defineMcpTool({
10
+ name: spec.name,
11
+ title: spec.title,
12
+ description: spec.description,
13
+ inputSchema: spec.inputSchema,
14
+ annotations: spec.annotations,
15
+ inputExamples: spec.inputExamples,
16
+ handler: async (args) => spec.run(args, {
17
+ knowledge: useDocsKnowledge,
18
+ api: useApiKnowledge,
19
+ manifest: useMapoManifest,
20
+ rootDir: () => useMapoManifest().rootDir,
21
+ // The module only registers in development, but be explicit: a write
22
+ // tool reachable from a production build is a remote code execution
23
+ // primitive.
24
+ canWrite: () => useMapoManifest().dev,
25
+ backend: useMapoBackend
26
+ })
27
+ });
28
+ }
@@ -0,0 +1,6 @@
1
+ declare module "#mapo-mcp/context.mjs" {
2
+ import type { MapoMcpContext } from "../../index";
3
+
4
+ const context: MapoMcpContext;
5
+ export default context;
6
+ }