@mapomodule/mcp 0.0.0-stage → 1.0.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +479 -2
- package/bin/mapo-mcp.mjs +3 -0
- package/dist/build.d.mts +18 -0
- package/dist/build.d.ts +18 -0
- package/dist/build.mjs +351 -0
- package/dist/cli.d.mts +7 -0
- package/dist/cli.d.ts +7 -0
- package/dist/cli.mjs +263 -0
- package/dist/index.d.mts +68 -0
- package/dist/index.d.ts +68 -0
- package/dist/index.mjs +1 -0
- package/dist/knowledge/api.json +1 -0
- package/dist/knowledge/docs.json +1 -0
- package/dist/module.d.mts +16 -0
- package/dist/module.d.ts +16 -0
- package/dist/module.json +9 -0
- package/dist/module.mjs +121 -0
- package/dist/runtime/core/doctor.d.ts +0 -0
- package/dist/runtime/core/doctor.js +128 -0
- package/dist/runtime/core/indexer.d.ts +0 -0
- package/dist/runtime/core/indexer.js +193 -0
- package/dist/runtime/core/knowledge.d.ts +0 -0
- package/dist/runtime/core/knowledge.js +76 -0
- package/dist/runtime/core/openapi.d.ts +0 -0
- package/dist/runtime/core/openapi.js +229 -0
- package/dist/runtime/core/prompts.d.ts +0 -0
- package/dist/runtime/core/prompts.js +108 -0
- package/dist/runtime/core/recipes.d.ts +0 -0
- package/dist/runtime/core/recipes.js +297 -0
- package/dist/runtime/core/resources.d.ts +0 -0
- package/dist/runtime/core/resources.js +88 -0
- package/dist/runtime/core/scaffold/fields.d.ts +0 -0
- package/dist/runtime/core/scaffold/fields.js +64 -0
- package/dist/runtime/core/scaffold/index.d.ts +0 -0
- package/dist/runtime/core/scaffold/index.js +74 -0
- package/dist/runtime/core/scaffold/templates.d.ts +0 -0
- package/dist/runtime/core/scaffold/templates.js +349 -0
- package/dist/runtime/core/schema-source.d.ts +0 -0
- package/dist/runtime/core/schema-source.js +70 -0
- package/dist/runtime/core/search.d.ts +0 -0
- package/dist/runtime/core/search.js +173 -0
- package/dist/runtime/core/tokenize.d.ts +0 -0
- package/dist/runtime/core/tokenize.js +96 -0
- package/dist/runtime/core/tool-spec.d.ts +0 -0
- package/dist/runtime/core/tool-spec.js +3 -0
- package/dist/runtime/core/tools/api.d.ts +0 -0
- package/dist/runtime/core/tools/api.js +192 -0
- package/dist/runtime/core/tools/app.d.ts +0 -0
- package/dist/runtime/core/tools/app.js +141 -0
- package/dist/runtime/core/tools/backend.d.ts +0 -0
- package/dist/runtime/core/tools/backend.js +143 -0
- package/dist/runtime/core/tools/docs.d.ts +0 -0
- package/dist/runtime/core/tools/docs.js +150 -0
- package/dist/runtime/core/tools/scaffold.d.ts +0 -0
- package/dist/runtime/core/tools/scaffold.js +127 -0
- package/dist/runtime/core/types.d.ts +0 -0
- package/dist/runtime/core/types.js +0 -0
- package/dist/runtime/core/write.d.ts +0 -0
- package/dist/runtime/core/write.js +53 -0
- package/dist/runtime/mcp/handlers/mapo/index.js +13 -0
- package/dist/runtime/mcp/handlers/mapo/prompts/crud-page.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/prompts/custom-field.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/prompts/debug-form.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/prompts/migrate-v1.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/prompts/theme.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/resources/app-manifest.js +19 -0
- package/dist/runtime/mcp/handlers/mapo/resources/docs.js +34 -0
- package/dist/runtime/mcp/handlers/mapo/resources/fields.js +34 -0
- package/dist/runtime/mcp/handlers/mapo/resources/knowledge-index.js +22 -0
- package/dist/runtime/mcp/handlers/mapo/tools/backend-schema.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/component-api.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/composable-api.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/doctor.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/get-doc.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/inspect-app.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/list-field-types.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/list-recipes.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/scaffold.js +3 -0
- package/dist/runtime/mcp/handlers/mapo/tools/search-docs.js +3 -0
- package/dist/runtime/nitro/context.d.ts +0 -0
- package/dist/runtime/nitro/context.js +21 -0
- package/dist/runtime/nitro/to-mcp-prompt.d.ts +0 -0
- package/dist/runtime/nitro/to-mcp-prompt.js +23 -0
- package/dist/runtime/nitro/to-mcp-tool.d.ts +0 -0
- package/dist/runtime/nitro/to-mcp-tool.js +28 -0
- package/dist/runtime/types/virtual-modules.d.ts +6 -0
- package/dist/types.d.mts +9 -0
- package/package.json +73 -4
- package/src/__tests__/cli.test.ts +121 -0
- package/src/__tests__/doctor.test.ts +145 -0
- package/src/__tests__/fixtures/drf-schema.json +142 -0
- package/src/__tests__/fixtures.ts +198 -0
- package/src/__tests__/indexer.test.ts +114 -0
- package/src/__tests__/knowledge.test.ts +209 -0
- package/src/__tests__/openapi.test.ts +256 -0
- package/src/__tests__/recipes.test.ts +44 -0
- package/src/__tests__/resources.test.ts +69 -0
- package/src/__tests__/scaffold.test.ts +153 -0
- package/src/__tests__/search.test.ts +105 -0
- package/src/__tests__/tools.test.ts +226 -0
- package/src/__tests__/write.test.ts +134 -0
- package/src/build/extract-components.ts +135 -0
- package/src/build/extract-composables.ts +125 -0
- package/src/build/extract-fields.ts +250 -0
- package/src/build/index.ts +103 -0
- package/src/cli.ts +364 -0
- package/src/index.ts +65 -0
- package/src/module.ts +214 -0
- package/src/runtime/core/doctor.ts +204 -0
- package/src/runtime/core/indexer.ts +279 -0
- package/src/runtime/core/knowledge.ts +121 -0
- package/src/runtime/core/openapi.ts +417 -0
- package/src/runtime/core/prompts.ts +150 -0
- package/src/runtime/core/recipes.ts +361 -0
- package/src/runtime/core/resources.ts +144 -0
- package/src/runtime/core/scaffold/fields.ts +127 -0
- package/src/runtime/core/scaffold/index.ts +120 -0
- package/src/runtime/core/scaffold/templates.ts +394 -0
- package/src/runtime/core/schema-source.ts +123 -0
- package/src/runtime/core/search.ts +282 -0
- package/src/runtime/core/tokenize.ts +146 -0
- package/src/runtime/core/tool-spec.ts +74 -0
- package/src/runtime/core/tools/api.ts +300 -0
- package/src/runtime/core/tools/app.ts +200 -0
- package/src/runtime/core/tools/backend.ts +197 -0
- package/src/runtime/core/tools/docs.ts +215 -0
- package/src/runtime/core/tools/scaffold.ts +176 -0
- package/src/runtime/core/types.ts +133 -0
- package/src/runtime/core/write.ts +119 -0
- package/src/runtime/mcp/handlers/mapo/index.ts +22 -0
- package/src/runtime/mcp/handlers/mapo/prompts/crud-page.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/prompts/custom-field.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/prompts/debug-form.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/prompts/migrate-v1.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/prompts/theme.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/resources/app-manifest.ts +28 -0
- package/src/runtime/mcp/handlers/mapo/resources/docs.ts +41 -0
- package/src/runtime/mcp/handlers/mapo/resources/fields.ts +37 -0
- package/src/runtime/mcp/handlers/mapo/resources/knowledge-index.ts +24 -0
- package/src/runtime/mcp/handlers/mapo/tools/backend-schema.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/component-api.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/composable-api.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/doctor.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/get-doc.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/inspect-app.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/list-field-types.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/list-recipes.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/scaffold.ts +4 -0
- package/src/runtime/mcp/handlers/mapo/tools/search-docs.ts +4 -0
- package/src/runtime/nitro/context.ts +41 -0
- package/src/runtime/nitro/to-mcp-prompt.ts +30 -0
- package/src/runtime/nitro/to-mcp-tool.ts +35 -0
- package/src/runtime/types/virtual-modules.d.ts +6 -0
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
/** Docs tools: grounded search, curated recipes and exact section retrieval. */
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { matchRecipes, RECIPES } from "../recipes.js";
|
|
4
|
+
import { getDoc, searchDocs } from "../search.js";
|
|
5
|
+
import { defineMapoTool } from "../tool-spec.js";
|
|
6
|
+
import type { RecipeMatch } from "../recipes.js";
|
|
7
|
+
import type { AnyMapoToolSpec, MapoToolContext } from "../tool-spec.js";
|
|
8
|
+
|
|
9
|
+
/** Curated task hits, rendered above the ranked sections. */
|
|
10
|
+
function renderRecipes(recipes: RecipeMatch[]): string {
|
|
11
|
+
if (!recipes.length) return "";
|
|
12
|
+
|
|
13
|
+
const lines = recipes.map((recipe) => {
|
|
14
|
+
const section = recipe.heading ? ` (section "${recipe.heading}")` : "";
|
|
15
|
+
const seeAlso = recipe.seeAlso?.length
|
|
16
|
+
? `\n see also: ${recipe.seeAlso.join(", ")}`
|
|
17
|
+
: "";
|
|
18
|
+
return `- **${recipe.task}** → \`${recipe.doc}\`${section}\n ${recipe.summary}${seeAlso}`;
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
return `## Canonical recipe${recipes.length > 1 ? "s" : ""} for this task\n${lines.join("\n")}\n\n`;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
const SECTIONS = [
|
|
25
|
+
"howto",
|
|
26
|
+
"guide",
|
|
27
|
+
"uikit",
|
|
28
|
+
"form",
|
|
29
|
+
"modules",
|
|
30
|
+
"migration",
|
|
31
|
+
] as const;
|
|
32
|
+
|
|
33
|
+
interface SearchDocsArgs {
|
|
34
|
+
query: string;
|
|
35
|
+
section?: (typeof SECTIONS)[number];
|
|
36
|
+
pkg?: string;
|
|
37
|
+
limit?: number;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export const searchDocsTool = defineMapoTool({
|
|
41
|
+
name: "mapo_search_docs",
|
|
42
|
+
title: "Search Mapo documentation",
|
|
43
|
+
description:
|
|
44
|
+
"Search the official Mapo documentation and return the most relevant sections (never whole files). " +
|
|
45
|
+
"Use this before writing any Mapo code; follow up with mapo_get_doc to read a full section.",
|
|
46
|
+
inputSchema: {
|
|
47
|
+
query: z
|
|
48
|
+
.string()
|
|
49
|
+
.describe(
|
|
50
|
+
"Natural-language question or keywords, e.g. 'paginated list with filters'",
|
|
51
|
+
),
|
|
52
|
+
section: z.enum(SECTIONS).optional().describe("Restrict to one docs area"),
|
|
53
|
+
pkg: z
|
|
54
|
+
.string()
|
|
55
|
+
.optional()
|
|
56
|
+
.describe("Restrict to a package, e.g. '@mapomodule/form' or 'uikit'"),
|
|
57
|
+
limit: z
|
|
58
|
+
.number()
|
|
59
|
+
.int()
|
|
60
|
+
.min(1)
|
|
61
|
+
.max(20)
|
|
62
|
+
.optional()
|
|
63
|
+
.describe("Number of sections to return (default 5)"),
|
|
64
|
+
},
|
|
65
|
+
annotations: {
|
|
66
|
+
readOnlyHint: true,
|
|
67
|
+
destructiveHint: false,
|
|
68
|
+
idempotentHint: true,
|
|
69
|
+
openWorldHint: false,
|
|
70
|
+
},
|
|
71
|
+
inputExamples: [
|
|
72
|
+
{ query: "CRUD list with filters and bulk actions" },
|
|
73
|
+
{ query: "custom form field registration", section: "form" },
|
|
74
|
+
],
|
|
75
|
+
run: (args: SearchDocsArgs, context: MapoToolContext) => {
|
|
76
|
+
const hits = searchDocs(context.knowledge(), args.query, {
|
|
77
|
+
...(args.section ? { section: args.section } : {}),
|
|
78
|
+
...(args.pkg ? { pkg: args.pkg } : {}),
|
|
79
|
+
...(args.limit ? { limit: args.limit } : {}),
|
|
80
|
+
});
|
|
81
|
+
const recipes = renderRecipes(matchRecipes(args.query));
|
|
82
|
+
|
|
83
|
+
if (!hits.length) {
|
|
84
|
+
return recipes
|
|
85
|
+
? `${recipes}No section matched the keywords, but the recipe above covers this task.`
|
|
86
|
+
: `No documentation section matched "${args.query}". Try fewer or more general keywords, or drop the section filter.`;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
const body = hits
|
|
90
|
+
.map(
|
|
91
|
+
(hit, position) =>
|
|
92
|
+
`### ${position + 1}. ${hit.title} — ${hit.heading}\n` +
|
|
93
|
+
`path: \`${hit.path}\`${hit.anchor ? ` · anchor: \`#${hit.anchor}\`` : ""} · score: ${hit.score}\n` +
|
|
94
|
+
(hit.tags.length ? `symbols: ${hit.tags.join(", ")}\n` : "") +
|
|
95
|
+
`\n${hit.snippet}\n`,
|
|
96
|
+
)
|
|
97
|
+
.join("\n---\n\n");
|
|
98
|
+
|
|
99
|
+
return (
|
|
100
|
+
`${recipes}${hits.length} matching section(s) for "${args.query}":\n\n${body}\n` +
|
|
101
|
+
`---\nRead a full section with mapo_get_doc({ path, heading }).`
|
|
102
|
+
);
|
|
103
|
+
},
|
|
104
|
+
});
|
|
105
|
+
|
|
106
|
+
interface GetDocArgs {
|
|
107
|
+
path: string;
|
|
108
|
+
heading?: string;
|
|
109
|
+
maxChars?: number;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
export const getDocTool = defineMapoTool({
|
|
113
|
+
name: "mapo_get_doc",
|
|
114
|
+
title: "Read a Mapo documentation page",
|
|
115
|
+
description:
|
|
116
|
+
"Return the exact markdown of a documentation page, or of one of its sections when `heading` is given. " +
|
|
117
|
+
"Paths come from mapo_search_docs (e.g. 'howto/crud-list.md').",
|
|
118
|
+
inputSchema: {
|
|
119
|
+
path: z
|
|
120
|
+
.string()
|
|
121
|
+
.describe(
|
|
122
|
+
"Doc path relative to the docs root, e.g. 'howto/crud-detail.md'",
|
|
123
|
+
),
|
|
124
|
+
heading: z
|
|
125
|
+
.string()
|
|
126
|
+
.optional()
|
|
127
|
+
.describe(
|
|
128
|
+
"Section heading or anchor to return instead of the whole page",
|
|
129
|
+
),
|
|
130
|
+
maxChars: z
|
|
131
|
+
.number()
|
|
132
|
+
.int()
|
|
133
|
+
.min(500)
|
|
134
|
+
.max(40000)
|
|
135
|
+
.optional()
|
|
136
|
+
.describe("Truncation limit (default 8000)"),
|
|
137
|
+
},
|
|
138
|
+
annotations: {
|
|
139
|
+
readOnlyHint: true,
|
|
140
|
+
destructiveHint: false,
|
|
141
|
+
idempotentHint: true,
|
|
142
|
+
openWorldHint: false,
|
|
143
|
+
},
|
|
144
|
+
inputExamples: [
|
|
145
|
+
{ path: "howto/crud-list.md" },
|
|
146
|
+
{ path: "uikit/form/validation.md", heading: "Async validation" },
|
|
147
|
+
],
|
|
148
|
+
run: (args: GetDocArgs, context: MapoToolContext) => {
|
|
149
|
+
const doc = getDoc(context.knowledge(), args.path, {
|
|
150
|
+
...(args.heading ? { heading: args.heading } : {}),
|
|
151
|
+
...(args.maxChars ? { maxChars: args.maxChars } : {}),
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
if (!doc) {
|
|
155
|
+
return `No such documentation page: "${args.path}". Use mapo_search_docs to find the correct path.`;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
return (
|
|
159
|
+
`# ${doc.title}\nsource: \`${doc.path}\`\n` +
|
|
160
|
+
`sections: ${doc.headings.join(" · ") || "(none)"}\n\n${doc.content}`
|
|
161
|
+
);
|
|
162
|
+
},
|
|
163
|
+
});
|
|
164
|
+
|
|
165
|
+
interface ListRecipesArgs {
|
|
166
|
+
task?: string;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
export const listRecipesTool = defineMapoTool({
|
|
170
|
+
name: "mapo_list_recipes",
|
|
171
|
+
title: "List Mapo task recipes",
|
|
172
|
+
description:
|
|
173
|
+
"List the canonical Mapo recipes (task → documentation page). Call this to discover what Mapo " +
|
|
174
|
+
"can do out of the box before designing a solution, or pass `task` to find the recipe for a goal.",
|
|
175
|
+
inputSchema: {
|
|
176
|
+
task: z
|
|
177
|
+
.string()
|
|
178
|
+
.optional()
|
|
179
|
+
.describe(
|
|
180
|
+
"Goal in plain words, e.g. 'let editors reorder navigation entries'",
|
|
181
|
+
),
|
|
182
|
+
},
|
|
183
|
+
annotations: {
|
|
184
|
+
readOnlyHint: true,
|
|
185
|
+
destructiveHint: false,
|
|
186
|
+
idempotentHint: true,
|
|
187
|
+
openWorldHint: false,
|
|
188
|
+
},
|
|
189
|
+
inputExamples: [{}, { task: "upload images and pick them in a form" }],
|
|
190
|
+
run: (args: ListRecipesArgs) => {
|
|
191
|
+
if (args.task) {
|
|
192
|
+
const matches = matchRecipes(args.task, 3);
|
|
193
|
+
if (!matches.length) {
|
|
194
|
+
return (
|
|
195
|
+
`No curated recipe matches "${args.task}". Fall back to mapo_search_docs, ` +
|
|
196
|
+
`or call mapo_list_recipes with no argument to see every recipe.`
|
|
197
|
+
);
|
|
198
|
+
}
|
|
199
|
+
return `${renderRecipes(matches)}Read the page with mapo_get_doc({ path }).`;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
const lines = RECIPES.map(
|
|
203
|
+
(recipe) =>
|
|
204
|
+
`- **${recipe.task}** → \`${recipe.doc}\` — ${recipe.summary}`,
|
|
205
|
+
);
|
|
206
|
+
return `${RECIPES.length} Mapo recipes:\n\n${lines.join("\n")}\n\nRead one with mapo_get_doc({ path }).`;
|
|
207
|
+
},
|
|
208
|
+
});
|
|
209
|
+
|
|
210
|
+
/** Tools that work without a running dev server. */
|
|
211
|
+
export const docsTools: AnyMapoToolSpec[] = [
|
|
212
|
+
searchDocsTool,
|
|
213
|
+
getDocTool,
|
|
214
|
+
listRecipesTool,
|
|
215
|
+
];
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The only tool that can change the project.
|
|
3
|
+
*
|
|
4
|
+
* It generates code from templates modelled on the canonical recipes, and by
|
|
5
|
+
* default only *shows* it: `write` is an explicit opt-in, guarded by
|
|
6
|
+
* `../write.ts`. Generation and writing stay separate so an agent can propose
|
|
7
|
+
* before it touches anything.
|
|
8
|
+
*/
|
|
9
|
+
import { z } from "zod";
|
|
10
|
+
import {
|
|
11
|
+
SCAFFOLD_DESCRIPTIONS,
|
|
12
|
+
SCAFFOLD_KINDS,
|
|
13
|
+
UnknownFieldTypeError,
|
|
14
|
+
scaffold,
|
|
15
|
+
} from "../scaffold/index.js";
|
|
16
|
+
import { defineMapoTool } from "../tool-spec.js";
|
|
17
|
+
import { writeScaffold } from "../write.js";
|
|
18
|
+
import type { ScaffoldKind } from "../scaffold/index.js";
|
|
19
|
+
import type { AnyMapoToolSpec, MapoToolContext } from "../tool-spec.js";
|
|
20
|
+
|
|
21
|
+
interface ScaffoldArgs {
|
|
22
|
+
kind: ScaffoldKind;
|
|
23
|
+
name?: string;
|
|
24
|
+
endpoint?: string;
|
|
25
|
+
route?: string;
|
|
26
|
+
fields?: string[];
|
|
27
|
+
write?: boolean;
|
|
28
|
+
overwrite?: boolean;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Fence language, so the client renders the file with the right highlighting. */
|
|
32
|
+
function languageOf(path: string): string {
|
|
33
|
+
if (path.endsWith(".vue")) return "vue";
|
|
34
|
+
if (path.endsWith(".ts")) return "ts";
|
|
35
|
+
if (path.endsWith(".css")) return "css";
|
|
36
|
+
return "";
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
const KIND_LIST = SCAFFOLD_KINDS.map(
|
|
40
|
+
(kind) => `\`${kind}\` (${SCAFFOLD_DESCRIPTIONS[kind]})`,
|
|
41
|
+
).join(", ");
|
|
42
|
+
|
|
43
|
+
export const scaffoldTool = defineMapoTool({
|
|
44
|
+
name: "mapo_scaffold",
|
|
45
|
+
title: "Scaffold Mapo code",
|
|
46
|
+
description:
|
|
47
|
+
"Generate Mapo code that follows the framework's canonical patterns: list and detail pages, " +
|
|
48
|
+
"standalone forms, custom field types, login page, theming, backend proxy, menu and media " +
|
|
49
|
+
"pages. Returns the files for review; pass `write: true` to create them in the project. " +
|
|
50
|
+
`Kinds: ${KIND_LIST}.`,
|
|
51
|
+
inputSchema: {
|
|
52
|
+
kind: z.enum(SCAFFOLD_KINDS).describe("What to generate"),
|
|
53
|
+
name: z
|
|
54
|
+
.string()
|
|
55
|
+
.optional()
|
|
56
|
+
.describe(
|
|
57
|
+
"Resource name, e.g. 'articles' — or the type name for custom-field",
|
|
58
|
+
),
|
|
59
|
+
endpoint: z
|
|
60
|
+
.string()
|
|
61
|
+
.optional()
|
|
62
|
+
.describe("REST endpoint (default `/api/<name>`)"),
|
|
63
|
+
route: z.string().optional().describe("Route base (default `/<name>`)"),
|
|
64
|
+
fields: z
|
|
65
|
+
.array(z.string())
|
|
66
|
+
.optional()
|
|
67
|
+
.describe(
|
|
68
|
+
"Field specs `key[:type[:label]]`, e.g. ['title:text:Title', 'body:editor']",
|
|
69
|
+
),
|
|
70
|
+
write: z
|
|
71
|
+
.boolean()
|
|
72
|
+
.optional()
|
|
73
|
+
.describe(
|
|
74
|
+
"Create the files instead of only showing them (development only)",
|
|
75
|
+
),
|
|
76
|
+
overwrite: z
|
|
77
|
+
.boolean()
|
|
78
|
+
.optional()
|
|
79
|
+
.describe("Allow replacing files that already exist"),
|
|
80
|
+
},
|
|
81
|
+
annotations: {
|
|
82
|
+
// Not read-only: with `write` it creates files. Never destructive: existing
|
|
83
|
+
// files are refused unless `overwrite` is set.
|
|
84
|
+
readOnlyHint: false,
|
|
85
|
+
destructiveHint: false,
|
|
86
|
+
idempotentHint: true,
|
|
87
|
+
openWorldHint: false,
|
|
88
|
+
},
|
|
89
|
+
inputExamples: [
|
|
90
|
+
{
|
|
91
|
+
kind: "list-page",
|
|
92
|
+
name: "articles",
|
|
93
|
+
fields: ["title:text:Title", "status:select:Status"],
|
|
94
|
+
},
|
|
95
|
+
{
|
|
96
|
+
kind: "detail-page",
|
|
97
|
+
name: "articles",
|
|
98
|
+
fields: ["title:text", "body:editor"],
|
|
99
|
+
write: true,
|
|
100
|
+
},
|
|
101
|
+
{ kind: "custom-field", name: "star-rating" },
|
|
102
|
+
],
|
|
103
|
+
run: (args: ScaffoldArgs, context: MapoToolContext) => {
|
|
104
|
+
let result;
|
|
105
|
+
try {
|
|
106
|
+
// The registry is the source of truth for field types: reject anything
|
|
107
|
+
// that would not render, instead of generating a broken descriptor.
|
|
108
|
+
result = scaffold({
|
|
109
|
+
kind: args.kind,
|
|
110
|
+
...(args.name ? { name: args.name } : {}),
|
|
111
|
+
...(args.endpoint ? { endpoint: args.endpoint } : {}),
|
|
112
|
+
...(args.route ? { route: args.route } : {}),
|
|
113
|
+
...(args.fields ? { fields: args.fields } : {}),
|
|
114
|
+
api: context.api(),
|
|
115
|
+
});
|
|
116
|
+
} catch (error) {
|
|
117
|
+
if (error instanceof UnknownFieldTypeError) return error.message;
|
|
118
|
+
throw error;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const notes = result.notes.map((note) => `- ${note}`).join("\n");
|
|
122
|
+
const docs = result.docs.map((doc) => `\`${doc}\``).join(", ");
|
|
123
|
+
|
|
124
|
+
if (!args.write) {
|
|
125
|
+
const blocks = result.files
|
|
126
|
+
.map(
|
|
127
|
+
(file) =>
|
|
128
|
+
`### \`${file.path}\`\n\n\`\`\`${languageOf(file.path)}\n${file.content}\`\`\``,
|
|
129
|
+
)
|
|
130
|
+
.join("\n\n");
|
|
131
|
+
|
|
132
|
+
return (
|
|
133
|
+
`# ${SCAFFOLD_DESCRIPTIONS[args.kind]}\n\n${blocks}\n\n` +
|
|
134
|
+
`## Notes\n${notes}\n\nDocs: ${docs}\n\n` +
|
|
135
|
+
`Nothing was written. Call again with \`write: true\` to create these files.`
|
|
136
|
+
);
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
const root = context.rootDir();
|
|
140
|
+
if (!root) {
|
|
141
|
+
return (
|
|
142
|
+
"Cannot write: the project root is unknown.\n\n" +
|
|
143
|
+
"Connect to the app's endpoint (`/mcp/mapo`) so the server knows where the project is, " +
|
|
144
|
+
"or run `mapo-mcp serve --root <path>`. The files above are unchanged."
|
|
145
|
+
);
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
const outcomes = writeScaffold(result.files, {
|
|
149
|
+
root,
|
|
150
|
+
overwrite: args.overwrite ?? false,
|
|
151
|
+
allowed: context.canWrite(),
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
const lines = outcomes.map((outcome) => {
|
|
155
|
+
const icon = outcome.status === "written" ? "✔" : "✖";
|
|
156
|
+
const detail = outcome.reason ? ` — ${outcome.reason}` : "";
|
|
157
|
+
return `- ${icon} \`${outcome.path}\` (${outcome.status})${detail}`;
|
|
158
|
+
});
|
|
159
|
+
|
|
160
|
+
const written = outcomes.filter(
|
|
161
|
+
(outcome) => outcome.status === "written",
|
|
162
|
+
).length;
|
|
163
|
+
const blocked = outcomes.length - written;
|
|
164
|
+
|
|
165
|
+
return (
|
|
166
|
+
`# ${SCAFFOLD_DESCRIPTIONS[args.kind]}\n\n` +
|
|
167
|
+
`Root: \`${root}\`\n\n${lines.join("\n")}\n\n` +
|
|
168
|
+
(blocked
|
|
169
|
+
? `${blocked} file(s) were not written. Read the reason above; use \`overwrite: true\` only when replacing is intended.\n\n`
|
|
170
|
+
: "") +
|
|
171
|
+
`## Notes\n${notes}\n\nDocs: ${docs}`
|
|
172
|
+
);
|
|
173
|
+
},
|
|
174
|
+
});
|
|
175
|
+
|
|
176
|
+
export const scaffoldTools: AnyMapoToolSpec[] = [scaffoldTool];
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/** Shared shapes for the bundled knowledge base. */
|
|
2
|
+
|
|
3
|
+
/** One searchable slice of a documentation page (usually an H2 section). */
|
|
4
|
+
export interface DocChunk {
|
|
5
|
+
/** `<path>#<anchor>`, unique across the knowledge base. */
|
|
6
|
+
id: string;
|
|
7
|
+
/** Path relative to the docs root, e.g. `howto/crud-list.md`. */
|
|
8
|
+
path: string;
|
|
9
|
+
/** First path segment: `howto`, `guide`, `uikit`, `modules`, `migration`, `root`. */
|
|
10
|
+
section: string;
|
|
11
|
+
/** Second path segment when present, e.g. `form` for `uikit/form/validation.md`. */
|
|
12
|
+
group?: string;
|
|
13
|
+
/** Owning package, e.g. `@mapomodule/uikit`. */
|
|
14
|
+
pkg?: string;
|
|
15
|
+
/** H1 of the page. */
|
|
16
|
+
title: string;
|
|
17
|
+
/** Heading of this slice (equals `title` for the page preamble). */
|
|
18
|
+
heading: string;
|
|
19
|
+
/** GitHub-style slug of `heading`. */
|
|
20
|
+
anchor: string;
|
|
21
|
+
/** Heading depth: 1 for the preamble, 2 for H2, 3 for H3. */
|
|
22
|
+
level: number;
|
|
23
|
+
/**
|
|
24
|
+
* `reference` marks API tables (props/slots/emits). They answer "what are the
|
|
25
|
+
* props of X" but rarely "how do I do Y", so ranking demotes them unless the
|
|
26
|
+
* query is explicitly about an API surface.
|
|
27
|
+
*/
|
|
28
|
+
kind?: "reference";
|
|
29
|
+
/** Raw markdown of the slice, code fences included. */
|
|
30
|
+
text: string;
|
|
31
|
+
/** Symbols mentioned in the slice: `MapoList`, `useCrud`, field types… */
|
|
32
|
+
tags: string[];
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Inverted index: `terms[token] = [chunkIndex, termFrequency][]`.
|
|
37
|
+
*
|
|
38
|
+
* Chunk indices — not ids — keep the serialised file small (textual ids would
|
|
39
|
+
* grow it by ~5x). The price is that `terms` and `lengths` are only valid
|
|
40
|
+
* against the exact `chunks` array they were built from: reordering or
|
|
41
|
+
* filtering it after the fact corrupts every score without raising anything.
|
|
42
|
+
* A term's document frequency is the length of its posting list.
|
|
43
|
+
*/
|
|
44
|
+
export interface Bm25Index {
|
|
45
|
+
terms: Record<string, Array<[number, number]>>;
|
|
46
|
+
/** Token count per chunk, aligned with the `chunks` array. */
|
|
47
|
+
lengths: number[];
|
|
48
|
+
avgLength: number;
|
|
49
|
+
total: number;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
export interface DocsKnowledge {
|
|
53
|
+
version: number;
|
|
54
|
+
generatedAt: string;
|
|
55
|
+
/** Doc paths are relative to this (repo-relative, informational only). */
|
|
56
|
+
docsRoot: string;
|
|
57
|
+
chunks: DocChunk[];
|
|
58
|
+
index: Bm25Index;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** One entry of a component's public API. */
|
|
62
|
+
export interface ApiMember {
|
|
63
|
+
name: string;
|
|
64
|
+
type?: string;
|
|
65
|
+
required?: boolean;
|
|
66
|
+
default?: string;
|
|
67
|
+
description?: string;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** A `Mapo*` component as extracted from its source at build time. */
|
|
71
|
+
export interface ComponentApi {
|
|
72
|
+
name: string;
|
|
73
|
+
pkg: string;
|
|
74
|
+
/** Repo-relative source path. */
|
|
75
|
+
file: string;
|
|
76
|
+
description?: string;
|
|
77
|
+
props: ApiMember[];
|
|
78
|
+
events: ApiMember[];
|
|
79
|
+
slots: ApiMember[];
|
|
80
|
+
exposed: ApiMember[];
|
|
81
|
+
/** Documentation sections that talk about this component (`path#anchor`). */
|
|
82
|
+
docs: string[];
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** A field `type` accepted by the form registry, with the descriptor it expects. */
|
|
86
|
+
export interface FieldTypeApi {
|
|
87
|
+
type: string;
|
|
88
|
+
/** Component the registry maps this type to. */
|
|
89
|
+
component?: string;
|
|
90
|
+
/** Descriptor interface that documents it, e.g. `TextDescriptor`. */
|
|
91
|
+
descriptor?: string;
|
|
92
|
+
description?: string;
|
|
93
|
+
/** `attrs` accepted by this field type. */
|
|
94
|
+
attrs: ApiMember[];
|
|
95
|
+
/** Registry-level default `attrs` merged into every field of this type. */
|
|
96
|
+
defaultAttrs?: Record<string, unknown>;
|
|
97
|
+
/** Whether the registry installs a default get/set accessor for the type. */
|
|
98
|
+
hasAccessor?: boolean;
|
|
99
|
+
docs: string[];
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** An auto-imported composable or helper exposed by a Mapo module. */
|
|
103
|
+
export interface ComposableApi {
|
|
104
|
+
name: string;
|
|
105
|
+
pkg: string;
|
|
106
|
+
file: string;
|
|
107
|
+
signature?: string;
|
|
108
|
+
description?: string;
|
|
109
|
+
docs: string[];
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** Everything extracted from source, shipped next to the docs index. */
|
|
113
|
+
export interface ApiKnowledge {
|
|
114
|
+
version: number;
|
|
115
|
+
generatedAt: string;
|
|
116
|
+
components: ComponentApi[];
|
|
117
|
+
fieldTypes: FieldTypeApi[];
|
|
118
|
+
/** Properties every field descriptor accepts, whatever its type. */
|
|
119
|
+
fieldCommon: ApiMember[];
|
|
120
|
+
composables: ComposableApi[];
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
export interface SearchHit {
|
|
124
|
+
id: string;
|
|
125
|
+
path: string;
|
|
126
|
+
section: string;
|
|
127
|
+
title: string;
|
|
128
|
+
heading: string;
|
|
129
|
+
anchor: string;
|
|
130
|
+
score: number;
|
|
131
|
+
snippet: string;
|
|
132
|
+
tags: string[];
|
|
133
|
+
}
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The only place in this package that writes to disk.
|
|
3
|
+
*
|
|
4
|
+
* Scaffolding is a dry run by default; when the caller opts in, every path goes
|
|
5
|
+
* through here. Kept small and separate so the dangerous surface is one file
|
|
6
|
+
* with one test suite: containment inside the project root, no silent
|
|
7
|
+
* overwrite, and no writing at all unless the adapter allows it.
|
|
8
|
+
*/
|
|
9
|
+
import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
|
|
10
|
+
import { dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
11
|
+
|
|
12
|
+
export interface WriteRequest {
|
|
13
|
+
/** Path relative to the project root. */
|
|
14
|
+
path: string;
|
|
15
|
+
content: string;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export type WriteStatus =
|
|
19
|
+
| "written"
|
|
20
|
+
| "exists"
|
|
21
|
+
| "outside-root"
|
|
22
|
+
| "absolute-path"
|
|
23
|
+
| "not-allowed";
|
|
24
|
+
|
|
25
|
+
export interface WriteOutcome {
|
|
26
|
+
path: string;
|
|
27
|
+
status: WriteStatus;
|
|
28
|
+
/** Absolute destination, when the write was attempted. */
|
|
29
|
+
absolute?: string;
|
|
30
|
+
reason?: string;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export interface WriteOptions {
|
|
34
|
+
/** Absolute path of the project. Everything must land inside it. */
|
|
35
|
+
root: string;
|
|
36
|
+
/** Overwrite existing files. Off by default: generated code is a proposal. */
|
|
37
|
+
overwrite?: boolean;
|
|
38
|
+
/**
|
|
39
|
+
* Adapters pass `false` outside development. A write tool that works in
|
|
40
|
+
* production is a remote code execution primitive.
|
|
41
|
+
*/
|
|
42
|
+
allowed?: boolean;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Resolves `relative` against `root` and proves the result stays inside it,
|
|
47
|
+
* following symlinks on the deepest existing ancestor — `pages` could itself be
|
|
48
|
+
* a link pointing anywhere.
|
|
49
|
+
*/
|
|
50
|
+
export function resolveInsideRoot(
|
|
51
|
+
root: string,
|
|
52
|
+
relative: string,
|
|
53
|
+
): string | null {
|
|
54
|
+
if (isAbsolute(relative)) return null;
|
|
55
|
+
|
|
56
|
+
const realRoot = existsSync(root) ? realpathSync(root) : resolve(root);
|
|
57
|
+
const target = resolve(realRoot, relative);
|
|
58
|
+
|
|
59
|
+
// Walk up to the closest existing directory and resolve *that* for real.
|
|
60
|
+
let existing = target;
|
|
61
|
+
while (!existsSync(existing) && dirname(existing) !== existing) {
|
|
62
|
+
existing = dirname(existing);
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const realExisting = existsSync(existing) ? realpathSync(existing) : existing;
|
|
66
|
+
const rest = target.slice(existing.length);
|
|
67
|
+
const realTarget = join(realExisting, rest);
|
|
68
|
+
|
|
69
|
+
const boundary = realRoot.endsWith(sep) ? realRoot : `${realRoot}${sep}`;
|
|
70
|
+
return realTarget === realRoot || realTarget.startsWith(boundary)
|
|
71
|
+
? realTarget
|
|
72
|
+
: null;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Writes the scaffolded files, reporting what happened to each one. */
|
|
76
|
+
export function writeScaffold(
|
|
77
|
+
files: WriteRequest[],
|
|
78
|
+
{ root, overwrite = false, allowed = true }: WriteOptions,
|
|
79
|
+
): WriteOutcome[] {
|
|
80
|
+
return files.map((file) => {
|
|
81
|
+
if (!allowed) {
|
|
82
|
+
return {
|
|
83
|
+
path: file.path,
|
|
84
|
+
status: "not-allowed" as const,
|
|
85
|
+
reason: "writing is only available while the app runs in development",
|
|
86
|
+
};
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
if (isAbsolute(file.path)) {
|
|
90
|
+
return {
|
|
91
|
+
path: file.path,
|
|
92
|
+
status: "absolute-path" as const,
|
|
93
|
+
reason: "paths must be relative to the project root",
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
const absolute = resolveInsideRoot(root, file.path);
|
|
98
|
+
if (!absolute) {
|
|
99
|
+
return {
|
|
100
|
+
path: file.path,
|
|
101
|
+
status: "outside-root" as const,
|
|
102
|
+
reason: `resolves outside ${root}`,
|
|
103
|
+
};
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
if (existsSync(absolute) && !overwrite) {
|
|
107
|
+
return {
|
|
108
|
+
path: file.path,
|
|
109
|
+
status: "exists" as const,
|
|
110
|
+
absolute,
|
|
111
|
+
reason: "pass overwrite: true to replace it",
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
mkdirSync(dirname(absolute), { recursive: true });
|
|
116
|
+
writeFileSync(absolute, file.content, "utf-8");
|
|
117
|
+
return { path: file.path, status: "written" as const, absolute };
|
|
118
|
+
});
|
|
119
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { defineMcpHandler } from "@nuxtjs/mcp-toolkit/server";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Named handler → route `<mcp.route>/mapo` (default `/mcp/mapo`).
|
|
5
|
+
*
|
|
6
|
+
* Tools, resources and prompts are auto-attributed from the sibling folders,
|
|
7
|
+
* so they never leak into the consuming app's own `/mcp` endpoint
|
|
8
|
+
* (`defaultHandlerStrategy` defaults to `'orphans'`).
|
|
9
|
+
*/
|
|
10
|
+
export default defineMcpHandler({
|
|
11
|
+
name: "mapo",
|
|
12
|
+
description:
|
|
13
|
+
"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.`,
|
|
22
|
+
});
|