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