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