@mapomodule/mcp 1.0.0-beta.1 → 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 +71 -41
- package/dist/cli.d.mts +1 -1
- package/dist/cli.d.ts +1 -1
- package/dist/cli.mjs +17 -6
- package/dist/knowledge/api.json +1 -1
- package/dist/knowledge/docs.json +1 -1
- package/dist/module.json +1 -1
- package/dist/module.mjs +5 -2
- package/dist/runtime/core/endpoint.d.ts +0 -0
- package/dist/runtime/core/endpoint.js +8 -0
- package/dist/runtime/core/indexer.js +2 -1
- package/dist/runtime/core/instructions.d.ts +0 -0
- package/dist/runtime/core/instructions.js +10 -0
- package/dist/runtime/core/overview.d.ts +0 -0
- package/dist/runtime/core/overview.js +15 -0
- package/dist/runtime/core/recipes.js +202 -3
- package/dist/runtime/core/resources.js +4 -0
- package/dist/runtime/core/tools/app.js +1 -1
- package/dist/runtime/core/tools/docs.js +6 -2
- package/dist/runtime/mcp/handlers/mapo/index.js +2 -8
- package/dist/runtime/mcp/handlers/mapo/resources/overview.js +20 -0
- package/package.json +1 -1
- package/src/__tests__/cli.test.ts +16 -0
- package/src/__tests__/endpoint.test.ts +31 -0
- package/src/__tests__/knowledge.test.ts +16 -0
- package/src/__tests__/overview.test.ts +105 -0
- package/src/__tests__/recipes.test.ts +11 -0
- package/src/cli.ts +22 -11
- package/src/module.ts +7 -8
- package/src/runtime/core/endpoint.ts +27 -0
- package/src/runtime/core/indexer.ts +10 -4
- package/src/runtime/core/instructions.ts +18 -0
- package/src/runtime/core/overview.ts +44 -0
- package/src/runtime/core/recipes.ts +213 -0
- package/src/runtime/core/resources.ts +6 -0
- package/src/runtime/core/tools/app.ts +4 -3
- package/src/runtime/core/tools/docs.ts +5 -2
- package/src/runtime/mcp/handlers/mapo/index.ts +2 -8
- package/src/runtime/mcp/handlers/mapo/resources/overview.ts +22 -0
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
|
|
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
|
-
|
|
195
|
-
|
|
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" })
|
|
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
|
|
323
|
-
name
|
|
324
|
-
|
|
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 `
|
|
334
|
-
|
|
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
|
|
339
|
-
opt-in (`write: true`), development-only, refuses to escape the project root and never
|
|
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
|
|
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
|
-
|
|
394
|
-
|
|
395
|
-
|
|
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
|
-
|
|
405
|
-
|
|
406
|
-
|
|
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:
|
|
431
|
-
│ #
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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}`, {
|