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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +71 -41
  2. package/dist/cli.d.mts +1 -1
  3. package/dist/cli.d.ts +1 -1
  4. package/dist/cli.mjs +17 -6
  5. package/dist/knowledge/api.json +1 -1
  6. package/dist/knowledge/docs.json +1 -1
  7. package/dist/module.json +1 -1
  8. package/dist/module.mjs +5 -2
  9. package/dist/runtime/core/endpoint.d.ts +0 -0
  10. package/dist/runtime/core/endpoint.js +8 -0
  11. package/dist/runtime/core/indexer.js +2 -1
  12. package/dist/runtime/core/instructions.d.ts +0 -0
  13. package/dist/runtime/core/instructions.js +10 -0
  14. package/dist/runtime/core/overview.d.ts +0 -0
  15. package/dist/runtime/core/overview.js +15 -0
  16. package/dist/runtime/core/recipes.js +221 -3
  17. package/dist/runtime/core/resources.js +4 -0
  18. package/dist/runtime/core/tools/app.js +1 -1
  19. package/dist/runtime/core/tools/docs.js +6 -2
  20. package/dist/runtime/mcp/handlers/mapo/index.js +2 -8
  21. package/dist/runtime/mcp/handlers/mapo/resources/overview.js +20 -0
  22. package/package.json +1 -1
  23. package/src/__tests__/cli.test.ts +16 -0
  24. package/src/__tests__/endpoint.test.ts +31 -0
  25. package/src/__tests__/knowledge.test.ts +16 -0
  26. package/src/__tests__/overview.test.ts +105 -0
  27. package/src/__tests__/recipes.test.ts +13 -0
  28. package/src/cli.ts +22 -11
  29. package/src/module.ts +7 -8
  30. package/src/runtime/core/endpoint.ts +27 -0
  31. package/src/runtime/core/indexer.ts +10 -4
  32. package/src/runtime/core/instructions.ts +18 -0
  33. package/src/runtime/core/overview.ts +44 -0
  34. package/src/runtime/core/recipes.ts +233 -0
  35. package/src/runtime/core/resources.ts +6 -0
  36. package/src/runtime/core/tools/app.ts +4 -3
  37. package/src/runtime/core/tools/docs.ts +5 -2
  38. package/src/runtime/mcp/handlers/mapo/index.ts +2 -8
  39. package/src/runtime/mcp/handlers/mapo/resources/overview.ts +22 -0
package/README.md CHANGED
@@ -12,6 +12,9 @@ invented field types, and Mapo v1 code in a v2 project.
12
12
  This package gives the assistant the real thing: **grounded documentation search**, **curated
13
13
  recipes**, and — when the dev server is running — **introspection of the actual app**.
14
14
 
15
+ Setting it up in an app: [How-to: set up your AI assistant](https://lotrekagency.github.io/mapo-new/howto/ai-assistant).
16
+ Reference on the docs site: [@mapomodule/mcp](https://lotrekagency.github.io/mapo-new/modules/mcp).
17
+
15
18
  ---
16
19
 
17
20
  ## Table of contents
@@ -101,19 +104,29 @@ curl -s -X POST http://localhost:3000/mcp/mapo \
101
104
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
102
105
  ```
103
106
 
107
+ The endpoint sits under the app's `app.baseURL`, like every server route: an app served under
108
+ `/backoffice/` answers at `/backoffice/mcp/mapo`, and `/mcp/mapo` redirects to the app. The
109
+ `mapo:mcp` line of the startup log prints the full URL; behind a proxy, use the address you open
110
+ the app with (for example `http://localhost/backoffice/mcp/mapo`).
111
+
104
112
  For the transport-independent variant, add the package explicitly — it ships as a dependency of
105
113
  `mapomodule`, and package managers only expose the binaries of **direct** dependencies:
106
114
 
107
115
  ```bash
108
- pnpm add -D @mapomodule/mcp
116
+ pnpm add -D @mapomodule/mcp@next
109
117
  npx mapo-mcp serve # MCP over stdio, no dev server required
110
118
  ```
111
119
 
120
+ Mapo v2 is published on the `next` dist-tag while it is in beta. `mapo-mcp serve` accepts
121
+ `--app <url>` (the endpoint the live tools are forwarded to), `--root <dir>` (the project root for
122
+ scaffolding, by default the working directory) and `--knowledge <dir>` (a prebuilt knowledge base
123
+ instead of the bundled one).
124
+
112
125
  ---
113
126
 
114
127
  ## Connecting your IDE
115
128
 
116
- All snippets assume `pnpm add -D @mapomodule/mcp` has been run in the app, so `npx` resolves
129
+ All snippets assume `pnpm add -D @mapomodule/mcp@next` has been run in the app, so `npx` resolves
117
130
  `mapo-mcp` from the local `node_modules/.bin`.
118
131
 
119
132
  ### Claude Code (`.mcp.json` in the project root)
@@ -152,8 +165,16 @@ All snippets assume `pnpm add -D @mapomodule/mcp` has been run in the app, so `n
152
165
  ### HTTP instead of stdio
153
166
 
154
167
  If your client speaks Streamable HTTP and you keep the dev server running, point it at
155
- `http://localhost:3000/mcp/mapo` instead. That variant additionally exposes the tools that need
156
- the live app.
168
+ `http://localhost:3000/mcp/mapo` instead, or at the URL the startup log prints when the app runs
169
+ elsewhere. That variant additionally exposes the tools that need the live app. In Claude Code:
170
+
171
+ ```json
172
+ {
173
+ "mcpServers": {
174
+ "mapo": { "type": "http", "url": "http://localhost:3000/mcp/mapo" }
175
+ }
176
+ }
177
+ ```
157
178
 
158
179
  > **stdio vs HTTP** — stdio always works and knows the docs; HTTP additionally knows _your_ app.
159
180
  > Configuring both is a perfectly reasonable setup.
@@ -170,10 +191,14 @@ tool is ever `destructiveHint`, because nothing here deletes or replaces without
170
191
  | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
171
192
  | `mapo_search_docs` | Ranked search over the Mapo docs. Returns the matching **sections** with their `path`, `#anchor`, matched symbols and an excerpt — plus the canonical recipe when the query matches a known task. Filters: `section` (`howto`, `guide`, `uikit`, `form`, `modules`, `migration`), `pkg` (`@mapomodule/form`, `uikit`, …), `limit`. |
172
193
  | `mapo_get_doc` | Returns the exact markdown of a page, or of a single section via `heading` (accepts the heading text or its anchor). Reports the page's full heading list so the assistant can narrow down, and truncates at `maxChars`. |
173
- | `mapo_list_recipes` | The curated task → documentation map. With no argument it lists everything Mapo does out of the box; with `task` it returns the canonical recipe for a goal. |
194
+ | `mapo_list_recipes` | The curated task → documentation map. With no argument it opens with what Mapo is and lists everything Mapo does out of the box; with `task` it returns the canonical recipe for a goal. |
174
195
  | `mapo_component_api` | Props, events, slots and exposed methods of a `Mapo*` component, **extracted from its source**: real types, defaults and JSDoc. Partial names resolve (`list` → `MapoList`); `include` narrows the answer to one section. |
175
196
  | `mapo_list_field_types` | The form registry: every `type` a `FieldDescriptor` accepts, the component behind it, its `attrs` with types and descriptions, the registry-level default attrs, and a skeleton descriptor to copy. |
176
197
  | `mapo_composable_api` | The auto-imported composables and stores (`useCrud`, `useMapoAuth`, `useMediaStore`, …) with their real signatures, grouped by package. |
198
+ | `mapo_inspect_app` | **Live.** How Mapo is set up in the running app: installed modules and versions, public Mapo configuration, registered field types, available components, routes and locales. |
199
+ | `mapo_doctor` | **Live.** Checks the running app for known misconfigurations (module order, missing login route, untouched auth endpoints, locales without catalogs, media endpoints) and returns each problem with its fix. |
200
+ | `mapo_scaffold` | Generates pages, forms, custom fields, a login page, a theme override, a backend proxy, menu and media pages in Mapo's own patterns. A dry run unless `write: true`. See [Scaffolding](#scaffolding). |
201
+ | `mapo_backend_schema` | Reads the backend's OpenAPI/DRF schema and turns a serializer into field descriptors, with choices, required and read-only flags and the endpoint of every relation. See [From the backend schema to a page](#from-the-backend-schema-to-a-page). |
177
202
 
178
203
  Typical sequence an assistant follows:
179
204
 
@@ -190,9 +215,10 @@ mapo_component_api({ name: "MapoMenuManager" })
190
215
  while the component declared 17. Prose drifts; source does not.
191
216
 
192
217
  **The two live tools need the app.** Over HTTP they answer directly. Over stdio the CLI forwards
193
- them to `http://localhost:3000/mcp/mapo` (override with `--app` or `MAPO_MCP_APP_URL`),
194
- reconnecting on every call because the dev server routinely starts after the editor. When it is
195
- down they explain how to bring it up instead of guessing.
218
+ them to `http://localhost:3000/mcp/mapo` (override with `--app` or `MAPO_MCP_APP_URL` when the
219
+ app runs on another port, behind a proxy or under an `app.baseURL`), reconnecting on every call
220
+ because the dev server routinely starts after the editor. When it is down they explain how to
221
+ bring it up instead of guessing.
196
222
 
197
223
  ### Scaffolding
198
224
 
@@ -219,7 +245,8 @@ server-side router keeps the old table, so a brand-new route 404s until it resta
219
245
  talks to.
220
246
 
221
247
  ```
222
- mapo_backend_schema({ action: "list_models" }) # what the API exposes
248
+ mapo_backend_schema({ action: "list_models" }) # what the API exposes
249
+ mapo_backend_schema({ action: "describe_model", model: "Article" })
223
250
  mapo_backend_schema({ action: "to_fields", model: "Article" })
224
251
  ```
225
252
 
@@ -263,6 +290,7 @@ Attachable context, for clients that support MCP resources:
263
290
 
264
291
  | URI | Contents |
265
292
  | ------------------------ | ----------------------------------------------------------------------------------------- |
293
+ | `mapo://overview` | How Mapo fits together: the `guide/concepts.md` page, whole. |
266
294
  | `mapo://knowledge/index` | Everything this server knows: recipes, doc pages, components, field types, composables. |
267
295
  | `mapo://docs/{path}` | A full documentation page. Clients can list every page. |
268
296
  | `mapo://fields/{type}` | The complete contract of one field type. Clients can list every type. |
@@ -319,9 +347,10 @@ mapo: {
319
347
  | `backend.schemaUrl` | `MAPO_BACKEND_SCHEMA_URL` | OpenAPI/DRF schema used by the backend tools. |
320
348
  | `backend.tokenEnv` | `"MAPO_BACKEND_TOKEN"` | Name of the env var holding the schema bearer token. |
321
349
 
322
- The route is fixed at `<mcp.route>/mapo`: the toolkit derives a folder handler's
323
- name from its directory. Use the toolkit's own `mcp.route` option to move the
324
- prefix.
350
+ The route is fixed at `/mcp/mapo`, under the app's `app.baseURL`: the toolkit mounts named
351
+ handlers at `/mcp/<name>`, takes the name from the handler's directory, and its own `mcp.route`
352
+ option moves only its default handler. [`src/runtime/core/endpoint.ts`](src/runtime/core/endpoint.ts)
353
+ computes the URL the startup log prints.
325
354
 
326
355
  The module can also be used standalone (`modules: ["@mapomodule/mcp"]`, config key `mapoMcp`) if you
327
356
  are not installing the `mapomodule` meta-package.
@@ -330,14 +359,14 @@ are not installing the `mapomodule` meta-package.
330
359
 
331
360
  ## Security model
332
361
 
333
- - **Development only by default.** The module returns early unless `nuxt.options.dev`, so the route
334
- never exists in a production build.
362
+ - **Development only by default.** The module returns early unless `enabled`, which defaults to
363
+ `nuxt.options.dev`, so the route does not exist in a production build unless you force it on.
335
364
  - **No secrets in responses.** The app snapshot exposes public runtime config only; private keys
336
365
  appear as key names, never values. Backend credentials are read from the environment and are never
337
366
  included in tool output.
338
- - **Read-only today.** Every shipped tool is annotated read-only. When scaffolding lands, writing is
339
- opt-in (`write: true`), development-only, refuses to escape the project root and never overwrites
340
- an existing file without `overwrite: true`.
367
+ - **Read-only except scaffolding.** Every tool is annotated read-only except `mapo_scaffold`, whose
368
+ writing is opt-in (`write: true`), development-only, refuses to escape the project root and never
369
+ overwrites an existing file without `overwrite: true`.
341
370
  - The toolkit's `security.allowedOrigins` default is left in place, so cross-site browser clients
342
371
  must present an allowed `Origin`.
343
372
 
@@ -353,7 +382,8 @@ pnpm --filter @mapomodule/mcp knowledge # index only
353
382
  [`scripts/build-knowledge.mjs`](scripts/build-knowledge.mjs) drives the generator in
354
383
  [`src/build/`](src/build/), which produces two files.
355
384
 
356
- **`docs.json`** — walks `docs/**/*.md` (skipping `roadmap/` and `DECISIONS.md`, which are internal),
385
+ **`docs.json`** — walks `docs/**/*.md` (skipping `roadmap/`, `contributing/`, `DECISIONS.md` and the
386
+ `AGENTS.md` / `CLAUDE.md` agent manuals, which are not app-building docs),
357
387
  splits each page at its H2/H3 headings — ignoring headings inside fenced code blocks — and writes
358
388
  every chunk plus the inverted index. Each chunk carries its path, section, package,
359
389
  VitePress-compatible anchor, the symbols it mentions (`MapoList`, `useCrud`, field types) and
@@ -390,26 +420,15 @@ pnpm --filter @mapomodule/mcp test # unit + real-index regressions + stdi
390
420
  pnpm --filter @mapomodule/mcp typecheck
391
421
  ```
392
422
 
393
- [TESTING.md](TESTING.md) walks through the full verification: build, suites, both
394
- transports, the consumer flow, search-quality spot-checks and a troubleshooting
395
- table.
396
-
397
- ### Adding a tool
398
-
399
- 1. Write the spec in `src/runtime/core/tools/<area>.ts` with `defineMapoTool` — an explicit `Args`
400
- interface, a zod `inputSchema`, annotations, `inputExamples`, and a `run` returning markdown.
401
- 2. Export it from the area's tool array.
402
- 3. Add a one-line Nitro wrapper in `src/runtime/mcp/handlers/mapo/tools/<name>.ts`:
423
+ How to add a recipe, a prompt, a resource or a tool, and what to update when Mapo changes, is in
424
+ [Working on the MCP server](https://lotrekagency.github.io/mapo-new/contributing/mcp-server).
425
+ Verification across the monorepo is in
426
+ [Testing and verification](https://lotrekagency.github.io/mapo-new/contributing/testing).
403
427
 
404
- ```ts
405
- import { myTool } from "../../../../core/tools/<area>.js";
406
- import { toMcpTool } from "../../../../nitro/to-mcp-tool.js";
407
-
408
- export default toMcpTool(myTool);
409
- ```
410
-
411
- 4. If the tool works without the dev server, add it to `staticTools()` in `src/cli.ts` too, and
412
- update the expected list in `src/__tests__/cli.test.ts`.
428
+ What the server says about Mapo has two sources: the instructions in
429
+ [`src/runtime/core/instructions.ts`](src/runtime/core/instructions.ts), shared by both transports,
430
+ and the [Concepts](https://lotrekagency.github.io/mapo-new/guide/concepts) page, served as
431
+ `mapo://overview`.
413
432
 
414
433
  Tools return markdown on purpose: assistants read it directly, and it costs fewer tokens than JSON
415
434
  wrapped in prose.
@@ -417,6 +436,10 @@ wrapped in prose.
417
436
  ### Layout
418
437
 
419
438
  ```
439
+ bin/mapo-mcp.mjs # the CLI entry point
440
+ scripts/
441
+ ├── build-knowledge.mjs # drives src/build → dist/knowledge/
442
+ └── clean-handler-dts.mjs # strips .d.ts files from the handler folder after the build
420
443
  src/
421
444
  ├── module.ts # Nuxt module: toolkit install, definition injection, app snapshot
422
445
  ├── cli.ts # citty CLI → MCP over stdio
@@ -427,8 +450,10 @@ src/
427
450
  │ ├── extract-fields.ts # registry + descriptor interfaces
428
451
  │ └── extract-composables.ts # addImports declarations
429
452
  └── runtime/
430
- ├── core/ # transport-agnostic: tokenizer, indexer, search, recipes,
431
- │ # doctor, scaffold/, write guard, openapi, prompts, tools
453
+ ├── core/ # transport-agnostic: instructions, overview, knowledge loader,
454
+ │ # tokenizer, indexer, search, recipes, prompts, resources,
455
+ │ # doctor, openapi + schema source, endpoint URL, scaffold/,
456
+ │ # write guard, tool specs (tools/)
432
457
  ├── nitro/ # server-side adapters
433
458
  │ ├── context.ts # reads the build-time context virtual module
434
459
  │ ├── to-mcp-tool.ts # spec → defineMcpTool
@@ -450,6 +475,12 @@ The module only registers in development. Check that the dev server is running,
450
475
  `mapo.mcp` is not `false`, and that the startup log contains the `mapo:mcp` line announcing the
451
476
  endpoint.
452
477
 
478
+ **`POST /mcp/mapo` redirects, or the live tools say the app is not answering**
479
+ Clients follow the redirect as a GET and report `Method not allowed. Use POST for MCP requests.`
480
+ The app has an `app.baseURL` or runs behind a proxy, so the handler answers below the base URL.
481
+ Use the URL of the `mapo:mcp` startup line (for example `http://localhost/backoffice/mcp/mapo`)
482
+ as the HTTP `url`, or pass it to the stdio CLI with `--app` or `MAPO_MCP_APP_URL`.
483
+
453
484
  **"Mapo knowledge base not found"**
454
485
  The index was not generated. Run `pnpm --filter @mapomodule/mcp build`. Inside a consumer project
455
486
  this cannot happen — the index ships in the published tarball.
@@ -476,5 +507,4 @@ extracted from source, live app introspection and diagnostics, guarded scaffoldi
476
507
  mapping, MCP resources and prompts, the dev-only Nuxt module with its namespaced handler, and the
477
508
  stdio CLI with transparent forwarding of the live tools.
478
509
 
479
- Planned (see [docs/roadmap/MCP_SERVER_PLAN.md](../../../docs/roadmap/MCP_SERVER_PLAN.md)):
480
- `mapo-mcp install` / Agent Skill / MCP App inspector.
510
+ Planned: `mapo-mcp install` / Agent Skill / MCP App inspector.
package/dist/cli.d.mts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
2
 
3
3
  /** Default endpoint of the Nuxt module, overridable with `--app`. */
4
- declare const DEFAULT_APP_URL = "http://localhost:3000/mcp/mapo";
4
+ declare const DEFAULT_APP_URL: string;
5
5
  declare function createStdioServer(knowledgeDir: string | null, appUrl?: string, rootDir?: string, schemaUrl?: string | null): Promise<McpServer>;
6
6
 
7
7
  export { DEFAULT_APP_URL, createStdioServer };
package/dist/cli.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
2
 
3
3
  /** Default endpoint of the Nuxt module, overridable with `--app`. */
4
- declare const DEFAULT_APP_URL = "http://localhost:3000/mcp/mapo";
4
+ declare const DEFAULT_APP_URL: string;
5
5
  declare function createStdioServer(knowledgeDir: string | null, appUrl?: string, rootDir?: string, schemaUrl?: string | null): Promise<McpServer>;
6
6
 
7
7
  export { DEFAULT_APP_URL, createStdioServer };
package/dist/cli.mjs CHANGED
@@ -4,7 +4,10 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
4
4
  import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
5
5
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
6
6
  import { defineCommand, runMain } from 'citty';
7
- import { INDEX_URI, renderKnowledgeIndex, DOCS_URI_PREFIX, docResourceList, renderDocResource, FIELD_URI_PREFIX, fieldResourceList, renderFieldResource } from '../dist/runtime/core/resources.js';
7
+ import { INDEX_URI, renderKnowledgeIndex, OVERVIEW_URI, DOCS_URI_PREFIX, docResourceList, renderDocResource, FIELD_URI_PREFIX, fieldResourceList, renderFieldResource } from '../dist/runtime/core/resources.js';
8
+ import { mcpEndpointUrl } from '../dist/runtime/core/endpoint.js';
9
+ import { MAPO_INSTRUCTIONS } from '../dist/runtime/core/instructions.js';
10
+ import { renderOverview } from '../dist/runtime/core/overview.js';
8
11
  import { apiTools } from '../dist/runtime/core/tools/api.js';
9
12
  import { appTools } from '../dist/runtime/core/tools/app.js';
10
13
  import { docsTools } from '../dist/runtime/core/tools/docs.js';
@@ -23,7 +26,7 @@ function readVersion() {
23
26
  return "0.0.0";
24
27
  }
25
28
  }
26
- const DEFAULT_APP_URL = "http://localhost:3000/mcp/mapo";
29
+ const DEFAULT_APP_URL = mcpEndpointUrl("http://localhost:3000");
27
30
  function staticTools() {
28
31
  return [...docsTools, ...apiTools, ...scaffoldTools, ...backendTools];
29
32
  }
@@ -71,16 +74,14 @@ function createAppProxy(appUrl) {
71
74
  const message = error instanceof Error ? error.message : String(error);
72
75
  return `\`${name}\` needs the running app, and ${appUrl} is not answering (${message}).
73
76
 
74
- Start the dev server (\`pnpm dev\`) and call the tool again, or point the client directly at the app endpoint. Documentation and API tools work without it.`;
77
+ Start the dev server (\`pnpm dev\`) and call the tool again. If the app runs on another port, behind a proxy or under an \`app.baseURL\`, pass its endpoint with \`--app\` or \`MAPO_MCP_APP_URL\` (for example \`http://localhost/backoffice/mcp/mapo\`): the dev server prints it at startup. Documentation and API tools work without it.`;
75
78
  }
76
79
  };
77
80
  }
78
81
  async function createStdioServer(knowledgeDir, appUrl = DEFAULT_APP_URL, rootDir = process.cwd(), schemaUrl = null) {
79
82
  const server = new McpServer(
80
83
  { name: "mapo", version: readVersion() },
81
- {
82
- instructions: "Mapo admin framework (Nuxt 4). Start from mapo_list_recipes, then mapo_search_docs / mapo_get_doc for how-to, and mapo_component_api / mapo_list_field_types / mapo_composable_api for exact APIs \u2014 Mapo v2 differs substantially from v1, so never recall its API from memory. mapo_inspect_app and mapo_doctor describe the project itself and need its dev server running."
83
- }
84
+ { instructions: MAPO_INSTRUCTIONS }
84
85
  );
85
86
  const context = createToolContext(knowledgeDir, rootDir, schemaUrl);
86
87
  for (const spec of staticTools()) {
@@ -166,6 +167,16 @@ function registerResources(server, context) {
166
167
  },
167
168
  (uri) => markdown(uri, renderKnowledgeIndex(context.knowledge(), context.api()))
168
169
  );
170
+ server.registerResource(
171
+ "mapo-overview",
172
+ OVERVIEW_URI,
173
+ {
174
+ title: "Mapo overview",
175
+ description: "How Mapo fits together: the packages, the backend contract, declarative pages, the form engine and the customization layers.",
176
+ mimeType: "text/markdown"
177
+ },
178
+ (uri) => markdown(uri, renderOverview(context.knowledge()))
179
+ );
169
180
  server.registerResource(
170
181
  "mapo-doc",
171
182
  new ResourceTemplate(`${DOCS_URI_PREFIX}{+path}`, {