mcp-server-nuxt 0.0.0-stage → 0.2.0
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/LICENSE +21 -0
- package/README.md +243 -2
- package/dist/index.d.ts +1 -0
- package/dist/index.js +2151 -0
- package/package.json +58 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 mcp-server-nuxt contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,244 @@
|
|
|
1
|
-
#
|
|
1
|
+
# mcp-server-nuxt
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
A production-ready Model Context Protocol server that gives LLMs Nuxt's resolved state.
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/mcp-server-nuxt)
|
|
8
|
+
[](./LICENSE)
|
|
9
|
+
[](https://nodejs.org)
|
|
10
|
+
[](#)
|
|
11
|
+
|
|
12
|
+
Generic LLMs get file-based routing, auto-imports, `extends` layers, and Nitro wrong more often than anything else in Nuxt.
|
|
13
|
+
|
|
14
|
+
</div>
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Why an MCP server for Nuxt?
|
|
19
|
+
|
|
20
|
+
A generic AI agent looking at a Nuxt repo sees a directory tree. It does not see:
|
|
21
|
+
|
|
22
|
+
- `pages/users/[id].vue` maps to `/users/:id`, or the `definePageMeta` middleware and layout contract.
|
|
23
|
+
- `components/base/BaseButton.vue` is available as `<BaseButton>` with no import statement.
|
|
24
|
+
- `composables/useFoo.ts` exports `useFoo()`, typed and callable anywhere.
|
|
25
|
+
- `extends: ['../ui-kit']` layers an override chain of components, pages, and config over the app.
|
|
26
|
+
- `server/api/hello.get.ts` registers `GET /api/hello` in the Nitro runtime.
|
|
27
|
+
|
|
28
|
+
Without that context the model guesses. It invents import paths, misnames auto-imported components, and misreads layer precedence. The gap is between the source tree and Nuxt's resolved runtime state.
|
|
29
|
+
|
|
30
|
+
`mcp-server-nuxt` exposes that resolved state through 22 tools and 7 read-only resources over MCP. It reads Nuxt's own output rather than scanning files.
|
|
31
|
+
|
|
32
|
+
### Design principles
|
|
33
|
+
|
|
34
|
+
| Principle | What it means in code |
|
|
35
|
+
| --- | --- |
|
|
36
|
+
| Deep Nuxt Kit integration | `loadNuxtConfig()` and `.nuxt/` build outputs first, with a source-level parser as fallback |
|
|
37
|
+
| Layer-aware | Resolves the `extends` graph and tags each route, component, and composable with its origin layer |
|
|
38
|
+
| Auto-imports registry | Serves the auto-imports index with source paths and TypeScript signatures from `.nuxt/imports.d.ts` |
|
|
39
|
+
| Write protection | Mutation tools default to `dry-run` and require `--allow-writes` |
|
|
40
|
+
| Strict TypeScript | `strict`, `noUncheckedIndexedAccess`, `noImplicitOverride` |
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Quick start
|
|
45
|
+
|
|
46
|
+
Prerequisites: Node.js 18 or newer.
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
# via npx
|
|
50
|
+
npx mcp-server-nuxt@latest /path/to/your/nuxt/app
|
|
51
|
+
|
|
52
|
+
# or install globally
|
|
53
|
+
npm install -g mcp-server-nuxt
|
|
54
|
+
mcp-server-nuxt /path/to/your/nuxt/app
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The server speaks MCP over `stdio`; it is not a web service. To run from a local checkout:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
git clone https://github.com/<your-org>/mcp-server-nuxt.git
|
|
61
|
+
cd mcp-server-nuxt
|
|
62
|
+
npm install
|
|
63
|
+
npm run build
|
|
64
|
+
node dist/index.js /path/to/your/nuxt/app
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Omit the path to use the current directory. Pass `--allow-writes` or set `MCP_NUXT_ALLOW_WRITES=1` to enable write tools. See [Write protection](#write-protection).
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Client configuration
|
|
72
|
+
|
|
73
|
+
### Cursor (`.cursor/mcp.json`)
|
|
74
|
+
|
|
75
|
+
```jsonc
|
|
76
|
+
{
|
|
77
|
+
"mcpServers": {
|
|
78
|
+
"mcp-server-nuxt": {
|
|
79
|
+
"command": "npx",
|
|
80
|
+
"args": ["mcp-server-nuxt@latest", "/path/to/your/nuxt/app"],
|
|
81
|
+
"env": {
|
|
82
|
+
// set this only if the agent may write files
|
|
83
|
+
"MCP_NUXT_ALLOW_WRITES": "1"
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Claude Desktop (`claude_desktop_config.json`)
|
|
91
|
+
|
|
92
|
+
```jsonc
|
|
93
|
+
{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"mcp-server-nuxt": {
|
|
96
|
+
"command": "npx",
|
|
97
|
+
"args": ["mcp-server-nuxt@latest", "/path/to/your/nuxt/app"],
|
|
98
|
+
"env": {
|
|
99
|
+
"MCP_NUXT_ALLOW_WRITES": "1"
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Start without `MCP_NUXT_ALLOW_WRITES`. The agent can still plan every change and show you the diff before applying.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Core architecture and resources
|
|
111
|
+
|
|
112
|
+
The server exposes read-only resources (`resources/*`) for large, cacheable datasets, and tools (`tools/call`) for targeted queries and mutations. Resources carry the bulk context so the agent does not re-scan files each turn.
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
┌─────────────────────────────────────────┐
|
|
116
|
+
│ mcp-server-nuxt │
|
|
117
|
+
│ │
|
|
118
|
+
MCP client ───────► │ ┌──────────────┐ ┌───────────────┐ │
|
|
119
|
+
(Claude/Cursor/v0) │ │ 22 Tools │ │ 7 Resources │ │
|
|
120
|
+
│ └──────┬───────┘ └───────┬───────┘ │
|
|
121
|
+
│ │ │ │
|
|
122
|
+
│ ▼ ▼ │
|
|
123
|
+
│ NuxtProjectContext (cached snapshot) │
|
|
124
|
+
└─────────┬───────────────────┬───────────┘
|
|
125
|
+
│ │
|
|
126
|
+
@nuxt/kit loadNuxtConfig .nuxt/imports.d.ts
|
|
127
|
+
extends resolution .nuxt/tsconfig.json
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### Resources
|
|
131
|
+
|
|
132
|
+
| URI | Content |
|
|
133
|
+
| --- | --- |
|
|
134
|
+
| `nuxt://project/overview` | Project summary: Nuxt version, layers, directories, and route/component/composable/module counts |
|
|
135
|
+
| `nuxt://project/routes` | Resolved route map: files, params, middleware, layouts, children |
|
|
136
|
+
| `nuxt://project/config` | Resolved `nuxt.config` object via `loadNuxtConfig`, with a source-level fallback |
|
|
137
|
+
| `nuxt://project/modules` | Installed modules with status, source, and configuration |
|
|
138
|
+
| `nuxt://project/layers` | `extends` hierarchy with override priority order and per-layer config |
|
|
139
|
+
| `nuxt://project/auto-imports` | Parsed registry of auto-imported symbols with source paths and TypeScript signatures |
|
|
140
|
+
| `nuxt://project/types` | Raw generated types (`.nuxt/imports.d.ts`, `.nuxt/types`, schema) |
|
|
141
|
+
|
|
142
|
+
### Layers and auto-imports
|
|
143
|
+
|
|
144
|
+
`nuxt://project/layers` resolves the `extends` graph and orders it by precedence (`project > later extends > earlier extends`), so the agent knows which `BaseButton.vue` wins when several layers define one.
|
|
145
|
+
|
|
146
|
+
`nuxt://project/auto-imports` reads `.nuxt/imports.d.ts` and returns the registry of auto-imported symbols (`ref`, `useFoo`, `BaseButton`) with their file origins and type signatures. The model does not have to guess an import path.
|
|
147
|
+
|
|
148
|
+
`nuxt://project/auto-imports` needs the app to have been prepared or built (`nuxi prepare` or `nuxi build`) so `.nuxt/imports.d.ts` exists.
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## Tools reference
|
|
153
|
+
|
|
154
|
+
### Project and core
|
|
155
|
+
|
|
156
|
+
| Tool | Description |
|
|
157
|
+
| --- | --- |
|
|
158
|
+
| `get_project_overview` | Summary: Nuxt version, layers, module/route/component counts, directories |
|
|
159
|
+
| `read_config` | Read the resolved `nuxt.config`, with dot-notation key filtering |
|
|
160
|
+
| `update_config` | Update a config value, keep comments and formatting, return a diff |
|
|
161
|
+
| `list_modules` | Active and inactive Nuxt modules with version, source, and config |
|
|
162
|
+
| `add_nuxt_module` | Add a module to the `modules` array, with optional options |
|
|
163
|
+
| `inspect_layers` | Resolve and return the full `extends` hierarchy |
|
|
164
|
+
|
|
165
|
+
### Routing and architecture
|
|
166
|
+
|
|
167
|
+
| Tool | Description |
|
|
168
|
+
| --- | --- |
|
|
169
|
+
| `list_routes` | File-based, dynamic, optional, catch-all, and nested routes |
|
|
170
|
+
| `get_route` | One route by path, e.g. `/users/:id` |
|
|
171
|
+
| `add_route` | Scaffold a page under `pages/` following Nuxt conventions |
|
|
172
|
+
| `inspect_route_meta` | `definePageMeta`, layout, middleware, and props/emits/slots for a page |
|
|
173
|
+
| `list_server_routes` | Nitro endpoints, middleware, and plugins with method and middleware chain |
|
|
174
|
+
| `scaffold_nitro_api` | Generate an H3 handler with optional Zod body validation |
|
|
175
|
+
|
|
176
|
+
### Components, composables, and auto-imports
|
|
177
|
+
|
|
178
|
+
| Tool | Description |
|
|
179
|
+
| --- | --- |
|
|
180
|
+
| `list_components` | All components, including those injected by layers and modules |
|
|
181
|
+
| `inspect_component` | Props types, emits, slots, and `<script setup>` details |
|
|
182
|
+
| `generate_component` | Generate a typed Vue SFC |
|
|
183
|
+
| `list_composables` | User-defined and auto-imported composables |
|
|
184
|
+
| `get_auto_imports` | The `.nuxt/imports.d.ts` registry with source paths and signatures |
|
|
185
|
+
| `get_type_info` | Raw generated type info (`.nuxt/types`, schema) |
|
|
186
|
+
|
|
187
|
+
### Quality and diagnostics
|
|
188
|
+
|
|
189
|
+
| Tool | Description |
|
|
190
|
+
| --- | --- |
|
|
191
|
+
| `check_type_errors` | Run `tsc --noEmit` against `.nuxt/tsconfig.json` |
|
|
192
|
+
| `analyze_bundle_deps` | Classify Nuxt modules vs runtime/dev deps, flag missing or misplaced ones |
|
|
193
|
+
| `search_code` | Search the codebase with line numbers and context lines |
|
|
194
|
+
| `get_nuxt_docs` | Offline Nuxt guidance for routing, nitro, modules, layers |
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## Write protection
|
|
199
|
+
|
|
200
|
+
`update_config`, `add_route`, `add_nuxt_module`, `scaffold_nitro_api`, and `generate_component` all follow the same contract:
|
|
201
|
+
|
|
202
|
+
1. `dryRun` is `true` by default. The tool returns the planned file or a diff without writing to disk.
|
|
203
|
+
2. A real write needs `dryRun: false` and a server started with writes enabled:
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
# CLI flag
|
|
207
|
+
mcp-server-nuxt /path/to/app --allow-writes
|
|
208
|
+
|
|
209
|
+
# or environment variable
|
|
210
|
+
MCP_NUXT_ALLOW_WRITES=1 mcp-server-nuxt /path/to/app
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
```jsonc
|
|
214
|
+
// in the client config
|
|
215
|
+
"env": { "MCP_NUXT_ALLOW_WRITES": "1" }
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
3. Config edits touch only the affected lines. Comments and unrelated keys stay, and every change returns a diff you can review.
|
|
219
|
+
|
|
220
|
+
Dry-run first, check the diff, then enable writes.
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## Contributing
|
|
225
|
+
|
|
226
|
+
Pull requests are welcome.
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
git clone https://github.com/<your-org>/mcp-server-nuxt.git
|
|
230
|
+
cd mcp-server-nuxt
|
|
231
|
+
npm install
|
|
232
|
+
npm run typecheck # tsc --noEmit (strict)
|
|
233
|
+
npm test # vitest
|
|
234
|
+
npm run build # tsup
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
- Follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `chore:`).
|
|
238
|
+
- Add tests for new tools and resources under `tests/`.
|
|
239
|
+
- Keep `@nuxt/kit` an optional dependency; each integration needs a fallback.
|
|
240
|
+
- Write tools default to `dry-run` and go through `WriteGuard`.
|
|
241
|
+
|
|
242
|
+
## License
|
|
243
|
+
|
|
244
|
+
[MIT](./LICENSE) © 2026 mcp-server-nuxt contributors.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
#!/usr/bin/env node
|