@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.
- package/README.md +509 -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 +274 -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 +124 -0
- package/dist/runtime/core/doctor.d.ts +0 -0
- package/dist/runtime/core/doctor.js +128 -0
- package/dist/runtime/core/endpoint.d.ts +0 -0
- package/dist/runtime/core/endpoint.js +8 -0
- package/dist/runtime/core/indexer.d.ts +0 -0
- package/dist/runtime/core/indexer.js +194 -0
- package/dist/runtime/core/instructions.d.ts +0 -0
- package/dist/runtime/core/instructions.js +10 -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/overview.d.ts +0 -0
- package/dist/runtime/core/overview.js +15 -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 +496 -0
- package/dist/runtime/core/resources.d.ts +0 -0
- package/dist/runtime/core/resources.js +92 -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 +154 -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 +7 -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/resources/overview.js +20 -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 +137 -0
- package/src/__tests__/doctor.test.ts +145 -0
- package/src/__tests__/endpoint.test.ts +31 -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 +225 -0
- package/src/__tests__/openapi.test.ts +256 -0
- package/src/__tests__/overview.test.ts +105 -0
- package/src/__tests__/recipes.test.ts +55 -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 +375 -0
- package/src/index.ts +65 -0
- package/src/module.ts +213 -0
- package/src/runtime/core/doctor.ts +204 -0
- package/src/runtime/core/endpoint.ts +27 -0
- package/src/runtime/core/indexer.ts +285 -0
- package/src/runtime/core/instructions.ts +18 -0
- package/src/runtime/core/knowledge.ts +121 -0
- package/src/runtime/core/openapi.ts +417 -0
- package/src/runtime/core/overview.ts +44 -0
- package/src/runtime/core/prompts.ts +150 -0
- package/src/runtime/core/recipes.ts +574 -0
- package/src/runtime/core/resources.ts +150 -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 +201 -0
- package/src/runtime/core/tools/backend.ts +197 -0
- package/src/runtime/core/tools/docs.ts +218 -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 +16 -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/resources/overview.ts +22 -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
package/README.md
CHANGED
|
@@ -1,3 +1,510 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mapomodule/mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An [MCP](https://modelcontextprotocol.io) server that teaches AI assistants how to use **Mapo** —
|
|
4
|
+
the Nuxt 4 admin framework — inside your own project.
|
|
5
|
+
|
|
6
|
+
Without it, an assistant working in a Mapo app has nothing to go on: the documentation lives in a
|
|
7
|
+
private workspace package it never sees, component APIs are `.vue` files buried in `node_modules`,
|
|
8
|
+
and the app's real configuration (which field types are registered, which auth endpoints are set)
|
|
9
|
+
is only knowable from the running Nuxt instance. The predictable result is invented props,
|
|
10
|
+
invented field types, and Mapo v1 code in a v2 project.
|
|
11
|
+
|
|
12
|
+
This package gives the assistant the real thing: **grounded documentation search**, **curated
|
|
13
|
+
recipes**, and — when the dev server is running — **introspection of the actual app**.
|
|
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
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Table of contents
|
|
21
|
+
|
|
22
|
+
- [How it works](#how-it-works)
|
|
23
|
+
- [Quick start](#quick-start)
|
|
24
|
+
- [Connecting your IDE](#connecting-your-ide)
|
|
25
|
+
- [Tools](#tools)
|
|
26
|
+
- [Prompts](#prompts)
|
|
27
|
+
- [Resources](#resources)
|
|
28
|
+
- [Recipes](#recipes)
|
|
29
|
+
- [Configuration](#configuration)
|
|
30
|
+
- [Security model](#security-model)
|
|
31
|
+
- [How the knowledge base is built](#how-the-knowledge-base-is-built)
|
|
32
|
+
- [Development](#development)
|
|
33
|
+
- [Troubleshooting](#troubleshooting)
|
|
34
|
+
- [Status](#status)
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## How it works
|
|
39
|
+
|
|
40
|
+
The package ships **two ways to reach the same tools**:
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
build time (this package) dev time (your app)
|
|
44
|
+
docs/**/*.md ────┐ ┌──────────────────────────────┐
|
|
45
|
+
uikit/form .vue ─┼─► src/build/* ────────────────────► │ @mapomodule/mcp (Nuxt module)│
|
|
46
|
+
descriptor.ts │ dist/knowledge/docs.json │ · installs mcp-toolkit │
|
|
47
|
+
module.ts ┘ /api.json │ · injects its definitions │
|
|
48
|
+
│ │ · POST /mcp/mapo │
|
|
49
|
+
▼ └──────────────────────────────┘
|
|
50
|
+
src/runtime/core/*
|
|
51
|
+
(specs + search + recipes)
|
|
52
|
+
│
|
|
53
|
+
└───────────────────────► bin/mapo-mcp (stdio, no server needed)
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
1. **Nuxt module** — auto-installed by `mapomodule` in development. It registers
|
|
57
|
+
[`@nuxtjs/mcp-toolkit`](https://mcp-toolkit.nuxt.dev) and injects its own tools through the
|
|
58
|
+
toolkit's `mcp:definitions:paths` hook, as a **named handler**. Result: a dedicated endpoint at
|
|
59
|
+
`POST /mcp/mapo` that does not interfere with any MCP definitions your app itself may declare
|
|
60
|
+
(the toolkit's default `defaultHandlerStrategy: 'orphans'` keeps them separate).
|
|
61
|
+
2. **stdio CLI** (`mapo-mcp`) — the same tools, spawned directly by the IDE. Works with the dev
|
|
62
|
+
server down, which is exactly when you are still deciding what to build; the two live tools are
|
|
63
|
+
forwarded to the app when it happens to be up.
|
|
64
|
+
|
|
65
|
+
Both adapters wrap a single set of tool specs in `src/runtime/core/tools/`, so behaviour never
|
|
66
|
+
diverges between the two transports.
|
|
67
|
+
|
|
68
|
+
### Why a bundled knowledge base
|
|
69
|
+
|
|
70
|
+
Everything is extracted **at package build time** into `dist/knowledge/`: `docs.json` (heading-sized
|
|
71
|
+
chunks plus a BM25 inverted index) and `api.json` (components, field types and composables read from
|
|
72
|
+
the packages' sources). That means:
|
|
73
|
+
|
|
74
|
+
- it works offline, with no API keys and no embedding service;
|
|
75
|
+
- the knowledge always matches the installed version of Mapo, not whatever is on the website;
|
|
76
|
+
- answers are _sections_, not whole files — the assistant's context stays small;
|
|
77
|
+
- the API surface cannot drift from the code, because it _is_ the code.
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## Quick start
|
|
82
|
+
|
|
83
|
+
The module is part of `mapomodule` and turns itself on in development:
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
// nuxt.config.ts
|
|
87
|
+
export default defineNuxtConfig({
|
|
88
|
+
modules: ["@nuxt/ui", "mapomodule"],
|
|
89
|
+
mapo: {
|
|
90
|
+
// ...your usual Mapo config
|
|
91
|
+
// mcp: false, // ← opt out entirely
|
|
92
|
+
// mcp: { enabled: true } // ← force it on (also outside dev)
|
|
93
|
+
},
|
|
94
|
+
});
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Start the app and the endpoint is live:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
pnpm dev
|
|
101
|
+
curl -s -X POST http://localhost:3000/mcp/mapo \
|
|
102
|
+
-H 'content-type: application/json' \
|
|
103
|
+
-H 'accept: application/json, text/event-stream' \
|
|
104
|
+
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
|
|
105
|
+
```
|
|
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
|
+
|
|
112
|
+
For the transport-independent variant, add the package explicitly — it ships as a dependency of
|
|
113
|
+
`mapomodule`, and package managers only expose the binaries of **direct** dependencies:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pnpm add -D @mapomodule/mcp@next
|
|
117
|
+
npx mapo-mcp serve # MCP over stdio, no dev server required
|
|
118
|
+
```
|
|
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
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## Connecting your IDE
|
|
128
|
+
|
|
129
|
+
All snippets assume `pnpm add -D @mapomodule/mcp@next` has been run in the app, so `npx` resolves
|
|
130
|
+
`mapo-mcp` from the local `node_modules/.bin`.
|
|
131
|
+
|
|
132
|
+
### Claude Code (`.mcp.json` in the project root)
|
|
133
|
+
|
|
134
|
+
```json
|
|
135
|
+
{
|
|
136
|
+
"mcpServers": {
|
|
137
|
+
"mapo": {
|
|
138
|
+
"command": "npx",
|
|
139
|
+
"args": ["mapo-mcp", "serve"]
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Cursor (`.cursor/mcp.json`) / Windsurf
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{
|
|
149
|
+
"mcpServers": {
|
|
150
|
+
"mapo": { "command": "npx", "args": ["mapo-mcp", "serve"] }
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### VS Code (`.vscode/mcp.json`)
|
|
156
|
+
|
|
157
|
+
```json
|
|
158
|
+
{
|
|
159
|
+
"servers": {
|
|
160
|
+
"mapo": { "type": "stdio", "command": "npx", "args": ["mapo-mcp", "serve"] }
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### HTTP instead of stdio
|
|
166
|
+
|
|
167
|
+
If your client speaks Streamable HTTP and you keep the dev server running, point it at
|
|
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
|
+
```
|
|
178
|
+
|
|
179
|
+
> **stdio vs HTTP** — stdio always works and knows the docs; HTTP additionally knows _your_ app.
|
|
180
|
+
> Configuring both is a perfectly reasonable setup.
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Tools
|
|
185
|
+
|
|
186
|
+
Every tool is prefixed `mapo_` so it stays unambiguous when several MCP servers are connected. All
|
|
187
|
+
are annotated `readOnlyHint: true` except `mapo_scaffold`, which can create files and says so — no
|
|
188
|
+
tool is ever `destructiveHint`, because nothing here deletes or replaces without an explicit flag.
|
|
189
|
+
|
|
190
|
+
| Tool | What it does |
|
|
191
|
+
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
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`. |
|
|
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`. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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). |
|
|
202
|
+
|
|
203
|
+
Typical sequence an assistant follows:
|
|
204
|
+
|
|
205
|
+
```
|
|
206
|
+
mapo_list_recipes({ task: "editors need to reorder navigation entries" })
|
|
207
|
+
→ "Build a navigation menu editor" → howto/menu-manager.md
|
|
208
|
+
mapo_get_doc({ path: "howto/menu-manager.md" })
|
|
209
|
+
→ writes code against the real API
|
|
210
|
+
mapo_component_api({ name: "MapoMenuManager" })
|
|
211
|
+
→ props and slots as the component actually declares them
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
**Why the API tools read source, not docs**: `docs/uikit/api.md` listed 11 props for `MapoDetail`
|
|
215
|
+
while the component declared 17. Prose drifts; source does not.
|
|
216
|
+
|
|
217
|
+
**The two live tools need the app.** Over HTTP they answer directly. Over stdio the CLI forwards
|
|
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.
|
|
222
|
+
|
|
223
|
+
### Scaffolding
|
|
224
|
+
|
|
225
|
+
`mapo_scaffold` is the only tool that can change the project, so its contract is deliberately
|
|
226
|
+
narrow:
|
|
227
|
+
|
|
228
|
+
- **Dry run by default.** It returns the files; nothing touches disk until `write: true`.
|
|
229
|
+
- **Field types are validated against the registry.** `fields: ["title:text", "body:wysiwyg"]`
|
|
230
|
+
fails with the list of real types rather than emitting a descriptor that renders nothing.
|
|
231
|
+
- **Writing is guarded** by [`write.ts`](src/runtime/core/write.ts): development only, paths
|
|
232
|
+
resolved and proven to stay inside the project root (symlinks followed), and an existing file is
|
|
233
|
+
never replaced without `overwrite: true`. Each file reports its own outcome instead of the batch
|
|
234
|
+
aborting halfway.
|
|
235
|
+
- The generated pages are modelled on the recipes in `docs/howto/` and on the pages that actually
|
|
236
|
+
run in `apps/example-e2e`, and are verified end to end: a scaffolded list page renders in the
|
|
237
|
+
example app unmodified.
|
|
238
|
+
|
|
239
|
+
After scaffolding new pages, **restart the dev server**: Nuxt hot-reloads `routes.mjs` but the
|
|
240
|
+
server-side router keeps the old table, so a brand-new route 404s until it restarts.
|
|
241
|
+
|
|
242
|
+
### From the backend schema to a page
|
|
243
|
+
|
|
244
|
+
`mapo_backend_schema` closes the last gap: the assistant knows Mapo _and_ the API this project
|
|
245
|
+
talks to.
|
|
246
|
+
|
|
247
|
+
```
|
|
248
|
+
mapo_backend_schema({ action: "list_models" }) # what the API exposes
|
|
249
|
+
mapo_backend_schema({ action: "describe_model", model: "Article" })
|
|
250
|
+
mapo_backend_schema({ action: "to_fields", model: "Article" })
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
The mapping is deliberate rather than mechanical:
|
|
254
|
+
|
|
255
|
+
- `enum` → `select` with readable item labels; `format: date-time` → `datetime`; `binary` → `file`;
|
|
256
|
+
a short `maxLength` stays a `text`, a long one becomes a `textarea`.
|
|
257
|
+
- A nested component becomes `fks` and an array of components becomes `m2m` — **with the real
|
|
258
|
+
endpoint**, found by scanning `paths` for the collection route that serves that component
|
|
259
|
+
(`{count, results}` pagination and bare arrays both recognised).
|
|
260
|
+
- `readOnly` properties are skipped, and the tool says so; `includeReadOnly: true` keeps them as
|
|
261
|
+
readonly descriptors.
|
|
262
|
+
- Anything uncertain carries an inline comment (`// no list endpoint found for Editor`) instead of
|
|
263
|
+
a confident guess.
|
|
264
|
+
- A property whose mapping is not registered in _this_ app is skipped, not emitted.
|
|
265
|
+
|
|
266
|
+
The response ends with a ready-made `mapo_scaffold` payload, so schema → descriptors → page is
|
|
267
|
+
three calls.
|
|
268
|
+
|
|
269
|
+
The source is `mapo.mcp.backend.schemaUrl`, `$MAPO_BACKEND_SCHEMA_URL`, or the tool's `url`
|
|
270
|
+
argument — an http(s) URL **or a local file**, so a team can commit an exported schema and work
|
|
271
|
+
offline. drf-spectacular serves YAML by default: the tool detects it and tells you to add
|
|
272
|
+
`?format=json`.
|
|
273
|
+
|
|
274
|
+
## Prompts
|
|
275
|
+
|
|
276
|
+
Slash-commands in clients that support MCP prompts. Each one names the tools to call and their
|
|
277
|
+
order, which is the part a model improvises worst:
|
|
278
|
+
|
|
279
|
+
| Prompt | Workflow |
|
|
280
|
+
| ------------------- | ---------------------------------------------------------------------------------- |
|
|
281
|
+
| `mapo-crud-page` | inspect the app → pick field types → scaffold list + detail → check component APIs |
|
|
282
|
+
| `mapo-custom-field` | check no built-in type fits → read the registry contract → scaffold → implement |
|
|
283
|
+
| `mapo-debug-form` | doctor → inspect registered types → compare `attrs` → search the docs |
|
|
284
|
+
| `mapo-migrate-v1` | read the migration page → verify every symbol against the installed source |
|
|
285
|
+
| `mapo-theme` | pick the lightest layer: tokens → scaffold override → slots → MapoOverride |
|
|
286
|
+
|
|
287
|
+
## Resources
|
|
288
|
+
|
|
289
|
+
Attachable context, for clients that support MCP resources:
|
|
290
|
+
|
|
291
|
+
| URI | Contents |
|
|
292
|
+
| ------------------------ | ----------------------------------------------------------------------------------------- |
|
|
293
|
+
| `mapo://overview` | How Mapo fits together: the `guide/concepts.md` page, whole. |
|
|
294
|
+
| `mapo://knowledge/index` | Everything this server knows: recipes, doc pages, components, field types, composables. |
|
|
295
|
+
| `mapo://docs/{path}` | A full documentation page. Clients can list every page. |
|
|
296
|
+
| `mapo://fields/{type}` | The complete contract of one field type. Clients can list every type. |
|
|
297
|
+
| `mapo://app/manifest` | The running app's Mapo setup — HTTP transport only, since the CLI has no app to describe. |
|
|
298
|
+
|
|
299
|
+
### Ranking, briefly
|
|
300
|
+
|
|
301
|
+
Plain BM25 over developer documentation has a known failure mode: prop tables win on term
|
|
302
|
+
frequency, so "register a custom field" returns the props of `MapoFormField` instead of the
|
|
303
|
+
registration recipe. The ranker therefore adds:
|
|
304
|
+
|
|
305
|
+
- **light stemming** so `paginate` / `paginated` / `pagination` collapse to one term;
|
|
306
|
+
- **page context** — a section gets a share of the score of its sibling sections, so a page that is
|
|
307
|
+
broadly about the topic beats an incidental mention elsewhere;
|
|
308
|
+
- **title/path affinity**, ignoring generic segments (`api`, `index`, `uikit`, …);
|
|
309
|
+
- **a reference penalty** on props/slots/emits tables, lifted when the query is explicitly about an
|
|
310
|
+
API surface ("what props does MapoDetail accept");
|
|
311
|
+
- **at most two sections per page**, so one page cannot fill the result list.
|
|
312
|
+
|
|
313
|
+
On top of that sits the recipe layer, which is the part that actually fixes _intent_.
|
|
314
|
+
|
|
315
|
+
---
|
|
316
|
+
|
|
317
|
+
## Recipes
|
|
318
|
+
|
|
319
|
+
[`src/runtime/core/recipes.ts`](src/runtime/core/recipes.ts) is a curated table mapping a task to
|
|
320
|
+
its canonical documentation page — the thing keyword search cannot infer. Each entry has an `id`, a
|
|
321
|
+
`task` phrased the way a developer would ask for it, `keywords`, the target `doc` (optionally a
|
|
322
|
+
`heading`), `seeAlso` links and a one-line `summary`.
|
|
323
|
+
|
|
324
|
+
**This is the file to update when a feature ships.** A test verifies that every `doc`, `heading` and
|
|
325
|
+
`seeAlso` in the table still exists in the generated knowledge base, so a renamed page fails CI
|
|
326
|
+
instead of silently sending assistants to a 404.
|
|
327
|
+
|
|
328
|
+
---
|
|
329
|
+
|
|
330
|
+
## Configuration
|
|
331
|
+
|
|
332
|
+
```ts
|
|
333
|
+
mapo: {
|
|
334
|
+
mcp: {
|
|
335
|
+
enabled: true, // default: nuxt.options.dev
|
|
336
|
+
backend: {
|
|
337
|
+
schemaUrl: "http://localhost:8000/api/schema/?format=json",
|
|
338
|
+
tokenEnv: "MAPO_BACKEND_TOKEN", // env var name; the value is never echoed back
|
|
339
|
+
},
|
|
340
|
+
},
|
|
341
|
+
}
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
| Option | Default | Description |
|
|
345
|
+
| ------------------- | ------------------------- | --------------------------------------------------------------------------------------- |
|
|
346
|
+
| `enabled` | `nuxt.options.dev` | Register the server. It is a development tool; production builds skip it unless forced. |
|
|
347
|
+
| `backend.schemaUrl` | `MAPO_BACKEND_SCHEMA_URL` | OpenAPI/DRF schema used by the backend tools. |
|
|
348
|
+
| `backend.tokenEnv` | `"MAPO_BACKEND_TOKEN"` | Name of the env var holding the schema bearer token. |
|
|
349
|
+
|
|
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.
|
|
354
|
+
|
|
355
|
+
The module can also be used standalone (`modules: ["@mapomodule/mcp"]`, config key `mapoMcp`) if you
|
|
356
|
+
are not installing the `mapomodule` meta-package.
|
|
357
|
+
|
|
358
|
+
---
|
|
359
|
+
|
|
360
|
+
## Security model
|
|
361
|
+
|
|
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.
|
|
364
|
+
- **No secrets in responses.** The app snapshot exposes public runtime config only; private keys
|
|
365
|
+
appear as key names, never values. Backend credentials are read from the environment and are never
|
|
366
|
+
included in tool output.
|
|
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`.
|
|
370
|
+
- The toolkit's `security.allowedOrigins` default is left in place, so cross-site browser clients
|
|
371
|
+
must present an allowed `Origin`.
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
## How the knowledge base is built
|
|
376
|
+
|
|
377
|
+
```bash
|
|
378
|
+
pnpm --filter @mapomodule/mcp build # module + CLI, then the knowledge index
|
|
379
|
+
pnpm --filter @mapomodule/mcp knowledge # index only
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
[`scripts/build-knowledge.mjs`](scripts/build-knowledge.mjs) drives the generator in
|
|
383
|
+
[`src/build/`](src/build/), which produces two files.
|
|
384
|
+
|
|
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),
|
|
387
|
+
splits each page at its H2/H3 headings — ignoring headings inside fenced code blocks — and writes
|
|
388
|
+
every chunk plus the inverted index. Each chunk carries its path, section, package,
|
|
389
|
+
VitePress-compatible anchor, the symbols it mentions (`MapoList`, `useCrud`, field types) and
|
|
390
|
+
whether it is API reference.
|
|
391
|
+
|
|
392
|
+
**`api.json`** — reads the packages' sources:
|
|
393
|
+
|
|
394
|
+
| Extractor | Source | Produces |
|
|
395
|
+
| ------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
396
|
+
| [`extract-components.ts`](src/build/extract-components.ts) | `uikit` + `form` `.vue` files, via `vue-component-meta` | props, events, slots, exposed, with resolved types, defaults and JSDoc |
|
|
397
|
+
| [`extract-fields.ts`](src/build/extract-fields.ts) | `registry/defaults.ts` (through jiti) + `types/descriptor.ts` (TypeScript compiler API) | every field `type`, its component, its `attrs`, and the shared descriptor properties |
|
|
398
|
+
| [`extract-composables.ts`](src/build/extract-composables.ts) | each module's `addImports([...])` calls | the auto-imported composables with their signatures |
|
|
399
|
+
|
|
400
|
+
Each extracted symbol is cross-linked back to the doc sections that document it.
|
|
401
|
+
|
|
402
|
+
Two deliberate choices: the generator reuses the **compiled** indexer (or the TypeScript source
|
|
403
|
+
through jiti in stub mode) rather than reimplementing tokenisation — index and query side must
|
|
404
|
+
produce identical tokens or recall silently degrades — and it lives in its own bundle entry so
|
|
405
|
+
`vue-component-meta`, `typescript` and `jiti` never reach the runtime.
|
|
406
|
+
|
|
407
|
+
Field types are extracted from the **declared** type text, not the checker's expansion: the latter
|
|
408
|
+
turns `DeepKeyOf<T>` into an unreadable wall of conditional types.
|
|
409
|
+
|
|
410
|
+
`MAPO_DOCS_ROOT` overrides the docs location; `MAPO_MCP_KNOWLEDGE_DIR` overrides where the runtime
|
|
411
|
+
looks for the generated files.
|
|
412
|
+
|
|
413
|
+
---
|
|
414
|
+
|
|
415
|
+
## Development
|
|
416
|
+
|
|
417
|
+
```bash
|
|
418
|
+
pnpm --filter @mapomodule/mcp build
|
|
419
|
+
pnpm --filter @mapomodule/mcp test # unit + real-index regressions + stdio integration
|
|
420
|
+
pnpm --filter @mapomodule/mcp typecheck
|
|
421
|
+
```
|
|
422
|
+
|
|
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).
|
|
427
|
+
|
|
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`.
|
|
432
|
+
|
|
433
|
+
Tools return markdown on purpose: assistants read it directly, and it costs fewer tokens than JSON
|
|
434
|
+
wrapped in prose.
|
|
435
|
+
|
|
436
|
+
### Layout
|
|
437
|
+
|
|
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
|
|
443
|
+
src/
|
|
444
|
+
├── module.ts # Nuxt module: toolkit install, definition injection, app snapshot
|
|
445
|
+
├── cli.ts # citty CLI → MCP over stdio
|
|
446
|
+
├── index.ts # public types
|
|
447
|
+
├── build/ # build-time only: docs indexing + source extraction
|
|
448
|
+
│ ├── index.ts # orchestrator → dist/knowledge/{docs,api}.json
|
|
449
|
+
│ ├── extract-components.ts # vue-component-meta
|
|
450
|
+
│ ├── extract-fields.ts # registry + descriptor interfaces
|
|
451
|
+
│ └── extract-composables.ts # addImports declarations
|
|
452
|
+
└── runtime/
|
|
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/)
|
|
457
|
+
├── nitro/ # server-side adapters
|
|
458
|
+
│ ├── context.ts # reads the build-time context virtual module
|
|
459
|
+
│ ├── to-mcp-tool.ts # spec → defineMcpTool
|
|
460
|
+
│ └── to-mcp-prompt.ts # spec → defineMcpPrompt
|
|
461
|
+
├── mcp/handlers/mapo/ # the named handler with its tools, resources and prompts
|
|
462
|
+
└── types/ # virtual module declarations
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
> `runtime/mcp/` must contain **nothing but** `handlers/`. The toolkit treats every top-level file
|
|
466
|
+
> of a scanned path as a handler definition, so a helper module placed there is loaded as a handler
|
|
467
|
+
> and breaks the Nitro build.
|
|
468
|
+
|
|
469
|
+
---
|
|
470
|
+
|
|
471
|
+
## Troubleshooting
|
|
472
|
+
|
|
473
|
+
**`POST /mcp/mapo` returns 404**
|
|
474
|
+
The module only registers in development. Check that the dev server is running, that
|
|
475
|
+
`mapo.mcp` is not `false`, and that the startup log contains the `mapo:mcp` line announcing the
|
|
476
|
+
endpoint.
|
|
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
|
+
|
|
484
|
+
**"Mapo knowledge base not found"**
|
|
485
|
+
The index was not generated. Run `pnpm --filter @mapomodule/mcp build`. Inside a consumer project
|
|
486
|
+
this cannot happen — the index ships in the published tarball.
|
|
487
|
+
|
|
488
|
+
**Search returns reference tables instead of a how-to**
|
|
489
|
+
Phrase the query as a task ("how do I …") rather than as a symbol; the ranker demotes prop tables
|
|
490
|
+
for task-shaped queries. If a task deserves a canonical answer, add it to `recipes.ts`.
|
|
491
|
+
|
|
492
|
+
**The assistant still invents props**
|
|
493
|
+
Make sure the client actually loaded the server (`tools/list` should show the `mapo_*` tools) and
|
|
494
|
+
that the handler `instructions` reached it — some clients ignore them, in which case a short project
|
|
495
|
+
rule ("always check Mapo docs with the mapo\_\* tools") does the job.
|
|
496
|
+
|
|
497
|
+
**A component is missing from `mapo_component_api`**
|
|
498
|
+
The build logs `skipped <Name>` when `vue-component-meta` cannot resolve a component. Only `Mapo*`
|
|
499
|
+
components under `src/runtime/components/` of `uikit` and `form` are extracted.
|
|
500
|
+
|
|
501
|
+
---
|
|
502
|
+
|
|
503
|
+
## Status
|
|
504
|
+
|
|
505
|
+
Shipped: documentation search with curated recipes, page retrieval, component/field/composable APIs
|
|
506
|
+
extracted from source, live app introspection and diagnostics, guarded scaffolding, backend schema
|
|
507
|
+
mapping, MCP resources and prompts, the dev-only Nuxt module with its namespaced handler, and the
|
|
508
|
+
stdio CLI with transparent forwarding of the live tools.
|
|
509
|
+
|
|
510
|
+
Planned: `mapo-mcp install` / Agent Skill / MCP App inspector.
|
package/bin/mapo-mcp.mjs
ADDED
package/dist/build.d.mts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { DocsKnowledge, ApiKnowledge } from '../dist/runtime/core/types.js';
|
|
2
|
+
|
|
3
|
+
declare const DOCS_FILE = "docs.json";
|
|
4
|
+
declare const API_FILE = "api.json";
|
|
5
|
+
interface BuildKnowledgeOptions {
|
|
6
|
+
docsRoot: string;
|
|
7
|
+
repoRoot: string;
|
|
8
|
+
outDir: string;
|
|
9
|
+
}
|
|
10
|
+
interface BuildKnowledgeResult {
|
|
11
|
+
docs: DocsKnowledge;
|
|
12
|
+
api: ApiKnowledge;
|
|
13
|
+
}
|
|
14
|
+
/** Generates `docs.json` and `api.json` into `outDir`. */
|
|
15
|
+
declare function buildKnowledge({ docsRoot, repoRoot, outDir, }: BuildKnowledgeOptions): Promise<BuildKnowledgeResult>;
|
|
16
|
+
|
|
17
|
+
export { API_FILE, DOCS_FILE, buildKnowledge };
|
|
18
|
+
export type { BuildKnowledgeOptions, BuildKnowledgeResult };
|
package/dist/build.d.ts
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { DocsKnowledge, ApiKnowledge } from '../dist/runtime/core/types.js';
|
|
2
|
+
|
|
3
|
+
declare const DOCS_FILE = "docs.json";
|
|
4
|
+
declare const API_FILE = "api.json";
|
|
5
|
+
interface BuildKnowledgeOptions {
|
|
6
|
+
docsRoot: string;
|
|
7
|
+
repoRoot: string;
|
|
8
|
+
outDir: string;
|
|
9
|
+
}
|
|
10
|
+
interface BuildKnowledgeResult {
|
|
11
|
+
docs: DocsKnowledge;
|
|
12
|
+
api: ApiKnowledge;
|
|
13
|
+
}
|
|
14
|
+
/** Generates `docs.json` and `api.json` into `outDir`. */
|
|
15
|
+
declare function buildKnowledge({ docsRoot, repoRoot, outDir, }: BuildKnowledgeOptions): Promise<BuildKnowledgeResult>;
|
|
16
|
+
|
|
17
|
+
export { API_FILE, DOCS_FILE, buildKnowledge };
|
|
18
|
+
export type { BuildKnowledgeOptions, BuildKnowledgeResult };
|