vale-mcp 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/readme.md ADDED
@@ -0,0 +1,540 @@
1
+ # Vale MCP Server
2
+
3
+ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that integrates [Vale](https://vale.sh/) prose linting into AI coding assistants like Claude Desktop, Cursor, and other MCP-compatible tools.
4
+
5
+ ## Overview
6
+
7
+ This MCP server provides AI assistants with the ability to check files for style and grammar issues using Vale's powerful linting engine. It automatically discovers Vale configuration files and provides formatted, actionable feedback about writing quality.
8
+
9
+ ## Quick install
10
+
11
+ [<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522vale%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522vale-mcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522vale%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522vale-mcp%2540latest%2522%255D%257D) [<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/install-mcp?name=Vale&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJ2YWxlLW1jcEBsYXRlc3QiXX0=)
12
+
13
+ ## Features
14
+
15
+ - ✅ File linting: Check any text file for style issues with Vale
16
+ - 🔍 Smart configuration discovery: Automatically finds `.vale.ini` files using Vale's native upward search
17
+ - 🎯 Configuration priority: Supports `VALE_CONFIG_PATH` environment variable for explicit configuration
18
+ - 📊 Rich formatting: Returns markdown-formatted results with emojis and severity grouping
19
+ - 🛡️ Graceful degradation: Provides helpful installation guidance when Vale isn't installed
20
+ - 🐛 Debug mode: Optional debug logging for troubleshooting
21
+ - 📦 Style sync: Download Vale style packages with `vale_sync` tool
22
+
23
+ ## System requirements
24
+
25
+ - **Node.js:** Version 22 or higher
26
+ - **Vale:** Version 3.0 or higher
27
+
28
+ ## Installation
29
+
30
+ ### Using npx (no install required)
31
+
32
+ You can run Vale MCP directly using `npx` without installing it globally:
33
+
34
+ ```bash
35
+ npx vale-mcp@latest
36
+ ```
37
+
38
+ This is the recommended approach for most users and is what the quick install badges above use.
39
+
40
+ ### Global install via npm
41
+
42
+ Install the `vale-mcp` package globally to create a system-wide `vale-cli` command:
43
+
44
+ ```bash
45
+ npm i @iflow-mcp/chrischinchilla-vale-mcp
46
+ ```
47
+
48
+ To uninstall:
49
+
50
+ ```bash
51
+ npm uninstall -g vale-mcp
52
+ ```
53
+
54
+ ### Build from source
55
+
56
+ ```bash
57
+ # Clone or navigate to the project directory
58
+ cd Vale-MCP
59
+
60
+ # Install dependencies
61
+ npm install
62
+
63
+ # Build the TypeScript project
64
+ npm run build
65
+
66
+ # Install globally (creates a system-wide vale-cli command)
67
+ npm run install:global
68
+ ```
69
+
70
+ This creates a global `vale-cli` command that you can use from anywhere, making it easy to configure in AI assistants.
71
+
72
+ To uninstall:
73
+
74
+ ```bash
75
+ npm run uninstall:global
76
+ ```
77
+
78
+ **Note:** If you're actively developing and making changes, you can skip global installation and use the absolute path to `build/index.js` instead (see integration examples below).
79
+
80
+ ## Using with AI assistants
81
+
82
+ AI coding assistants that support the MCP standard can integrate the Vale MCP server.
83
+
84
+ ### Claude Desktop
85
+
86
+ Add the Vale MCP server to your Claude Desktop configuration file:
87
+
88
+ **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
89
+
90
+ **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
91
+
92
+ ```json
93
+ {
94
+ "mcpServers": {
95
+ "vale": {
96
+ "command": "npx",
97
+ "args": ["vale-mcp@latest"]
98
+ }
99
+ }
100
+ }
101
+ ```
102
+
103
+ **Using global install:**
104
+
105
+ ```json
106
+ {
107
+ "mcpServers": {
108
+ "vale": {
109
+ "command": "vale-cli",
110
+ "args": []
111
+ }
112
+ }
113
+ }
114
+ ```
115
+
116
+ For debug mode:
117
+
118
+ ```json
119
+ {
120
+ "mcpServers": {
121
+ "vale": {
122
+ "command": "npx",
123
+ "args": ["vale-mcp@latest", "--debug"]
124
+ }
125
+ }
126
+ }
127
+ ```
128
+
129
+ Restart Claude Desktop after updating the configuration.
130
+
131
+ ### VS Code (GitHub Copilot)
132
+
133
+ [<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522vale%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522vale-mcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522vale%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522vale-mcp%2540latest%2522%255D%257D)
134
+
135
+ You can also add the Vale MCP server to VS Code manually:
136
+
137
+ #### Option A: Command Palette (easiest)
138
+
139
+ 1. Open the Command Palette: Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac)
140
+ 2. Run: Type `MCP: Add Server` and select it
141
+ 3. Provide server information:
142
+ - **Name:** `vale` (or any name you prefer)
143
+ - **Type:** Select `stdio`
144
+ - **Command:** `npx` (recommended, no install needed), `vale-cli` (if installed globally), or `node`
145
+ - **Arguments:**
146
+ - If using `npx`: Add `vale-mcp@latest`
147
+ - If using `vale-cli`: Leave empty or add `--debug`
148
+ - If using `node`: Add the path like `/Users/fabri/repos/FrankenMCP/Vale-MCP/build/index.js`
149
+ 4. Choose scope: User configuration (global) or Workspace (project-specific)
150
+
151
+ #### Option B: Manual configuration
152
+
153
+ Add to your VS Code settings file:
154
+
155
+ **Using npx (no install needed):**
156
+
157
+ ```json
158
+ {
159
+ "github.copilot.chat.mcp.servers": {
160
+ "vale": {
161
+ "command": "npx",
162
+ "args": ["vale-mcp@latest"]
163
+ }
164
+ }
165
+ }
166
+ ```
167
+
168
+ **Using global install:**
169
+
170
+ ```json
171
+ {
172
+ "github.copilot.chat.mcp.servers": {
173
+ "vale": {
174
+ "command": "vale-cli",
175
+ "args": []
176
+ }
177
+ }
178
+ }
179
+ ```
180
+
181
+ **Using absolute path (no global install needed):**
182
+
183
+ ```json
184
+ {
185
+ "github.copilot.chat.mcp.servers": {
186
+ "vale": {
187
+ "command": "node",
188
+ "args": ["/absolute/path/to/Vale-MCP/build/index.js"]
189
+ }
190
+ }
191
+ }
192
+ ```
193
+
194
+ **With debug mode:**
195
+
196
+ ```json
197
+ {
198
+ "github.copilot.chat.mcp.servers": {
199
+ "vale": {
200
+ "command": "npx",
201
+ "args": ["vale-mcp@latest", "--debug"]
202
+ }
203
+ }
204
+ }
205
+ ```
206
+
207
+ **Verify in VS Code:**
208
+
209
+ - Open GitHub Copilot Chat
210
+ - Type `/mcp` to see available MCP tools
211
+ - The Vale tools should appear in the list
212
+
213
+ ### Cursor
214
+
215
+ [<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/install-mcp?name=Vale&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJ2YWxlLW1jcEBsYXRlc3QiXX0=)
216
+
217
+ You can also add the Vale MCP server manually (follow [Cursor's MCP documentation](https://docs.cursor.com/advanced/model-context-protocol)):
218
+
219
+ **Using npx (no install needed):**
220
+
221
+ ```json
222
+ {
223
+ "mcpServers": {
224
+ "vale": {
225
+ "command": "npx",
226
+ "args": ["vale-mcp@latest"]
227
+ }
228
+ }
229
+ }
230
+ ```
231
+
232
+ **Using global install:**
233
+
234
+ ```json
235
+ {
236
+ "mcpServers": {
237
+ "vale": {
238
+ "command": "vale-cli"
239
+ }
240
+ }
241
+ }
242
+ ```
243
+
244
+ **Using absolute path:**
245
+
246
+ ```json
247
+ {
248
+ "mcpServers": {
249
+ "vale": {
250
+ "command": "node",
251
+ "args": ["/absolute/path/to/Vale-MCP/build/index.js"]
252
+ }
253
+ }
254
+ }
255
+ ```
256
+
257
+ ### Using a specific Vale configuration
258
+
259
+ You can specify a Vale configuration file using the `VALE_CONFIG_PATH` environment variable:
260
+
261
+ ```json
262
+ {
263
+ "mcpServers": {
264
+ "vale": {
265
+ "command": "npx",
266
+ "args": ["vale-mcp@latest"],
267
+ "env": {
268
+ "VALE_CONFIG_PATH": "/path/to/your/.vale.ini"
269
+ }
270
+ }
271
+ }
272
+ }
273
+ ```
274
+
275
+ ### Restricting file access
276
+
277
+ By default `check_file` and `check_directory` can read any file the server process can. To limit it,
278
+ set `VALE_ALLOWED_ROOTS` to one or more directories (separated by `:` on
279
+ macOS/Linux, `;` on Windows). Files and `config_path` values outside those
280
+ directories, including via symlinks, are rejected:
281
+
282
+ ```json
283
+ "env": {
284
+ "VALE_ALLOWED_ROOTS": "/path/to/docs:/path/to/other/docs"
285
+ }
286
+ ```
287
+
288
+ Vale runs have a 60 second timeout (5 minutes for `vale_sync`), and
289
+ `check_text` accepts up to 1 MB of text.
290
+
291
+ ## Usage examples
292
+
293
+ Once configured, you can ask your AI assistant to:
294
+
295
+ - "Check docs/guide.md using Vale"
296
+ - "Lint this markdown file for style issues"
297
+ - "What style issues does Vale find in README.md?"
298
+ - "Run `vale_sync` to download the style packages"
299
+ - "Is Vale installed on this system?"
300
+
301
+ ## Available tools
302
+
303
+ The server provides four MCP tools:
304
+
305
+ ### `vale_status`
306
+
307
+ Check if you have installed Vale and can access it.
308
+
309
+ **Returns:**
310
+
311
+ - Installation status (installed/not installed)
312
+ - Vale version (if installed)
313
+ - Platform-specific installation instructions (if not installed)
314
+
315
+ **Example usage in AI:**
316
+
317
+ > "Is Vale installed on this system?"
318
+
319
+ ### `vale_sync`
320
+
321
+ Download Vale styles and packages by running `vale sync`. Use this when you encounter errors about missing styles directories.
322
+
323
+ **Parameters:**
324
+
325
+ - `config_path` (optional): Path to `.vale.ini` file. If not provided, uses the server's configured path or searches in the current directory.
326
+
327
+ **Returns:**
328
+
329
+ - Success/failure status
330
+ - Output from the sync operation
331
+ - Helpful error messages if sync fails
332
+
333
+ **When to use:**
334
+
335
+ - When you see E100 errors: `"The path '/path/to/styles' does not exist"`
336
+ - After creating or updating a `.vale.ini` file
337
+ - When adding new packages to your Vale configuration
338
+
339
+ **Example usage in AI:**
340
+
341
+ > "Run `vale_sync` to download the required styles"
342
+
343
+ ### `check_file`
344
+
345
+ Lint a file at a specific path against Vale style rules.
346
+
347
+ **Parameters:**
348
+
349
+ - `path` (required): Absolute or relative path to the file
350
+ - `config_path` (optional): Path to a `.vale.ini` to use
351
+ - `min_severity` (optional): `suggestion`, `warning` or `error`; hides issues below it
352
+ - `max_issues` (optional): Return at most this many issues (the summary still counts all)
353
+
354
+ **Returns:**
355
+
356
+ - Formatted markdown with issues grouped by severity
357
+ - Detailed issue information (line, column, rule, message, suggestion)
358
+ - Summary statistics (errors, warnings, suggestions)
359
+ - Structured metadata for programmatic access
360
+
361
+ **Example usage in AI:**
362
+
363
+ > "Check the README.md file for style issues"
364
+
365
+ Issues include Vale's suggested fix (`action`) when the rule defines one, for
366
+ example substitution rules with `action: {name: replace}`. Vale only
367
+ reports actions for rules that declare them.
368
+
369
+ ### `check_directory`
370
+
371
+ Lint every file Vale supports in a directory, recursively.
372
+
373
+ **Parameters:**
374
+
375
+ - `path` (required): Absolute or relative path to the directory
376
+ - `config_path`, `min_severity`, `max_issues` (optional): as for `check_file`
377
+
378
+ **Returns:** the same structure as `check_file`, with a `file` on each issue.
379
+
380
+ **Example usage in AI:**
381
+
382
+ > "Check everything in the docs folder, errors only"
383
+
384
+ ### `check_text`
385
+
386
+ Lint AI-generated text against Vale style rules before it's written to a file or artifact.
387
+
388
+ **Parameters:**
389
+
390
+ - `text` (required): The text content to check with Vale
391
+ - `text_file_ext` (optional): The file extension to apply to the text.
392
+ Used as the value to Vale's `--ext` argument.
393
+ If not specified, the `--ext` argument is not used.
394
+ The format for this value is an optional leading dot followed by letters and digits,
395
+ such as: "md", ".md", "txt", ".txt", or "docx"
396
+ - `config_path` (optional): The path to the config file to use.
397
+ If not specified, the server's configured path is used.
398
+ - `min_severity`, `max_issues` (optional): as for `check_file`
399
+
400
+ **Returns:**
401
+
402
+ - A JSON object containing Vale's evaluation results.
403
+
404
+ **Example usage in AI:**
405
+
406
+ > "Check this text for style issues"
407
+
408
+ ## Command-line options
409
+
410
+ ```bash
411
+ vale-cli [options]
412
+
413
+ Options:
414
+ --debug, --verbose, -v Enable debug logging
415
+ --help, -h Show help message
416
+ --version Show version number
417
+ ```
418
+
419
+ ## Configuration
420
+
421
+ The server searches for Vale configuration in the following order:
422
+
423
+ 1. **Per-file:** Configuration discovered from file's directory (for `check_file` tool)
424
+ 2. **Server-wide:** `VALE_CONFIG_PATH` environment variable
425
+ 3. **Working directory:** `.vale.ini` in `process.cwd()`
426
+ 4. **Vale defaults:** Global configuration or built-in rules
427
+
428
+ ### Example .vale.ini
429
+
430
+ ```ini
431
+ StylesPath = styles
432
+ Packages = write-good, proselint
433
+
434
+ [*]
435
+ BasedOnStyles = write-good, proselint
436
+ ```
437
+
438
+ For more information about Vale configuration, see the [Vale documentation](https://vale.sh/docs/topics/config/).
439
+
440
+ ## Development
441
+
442
+ ### Project structure
443
+
444
+ ```
445
+ Vale-MCP/
446
+ ├── src/
447
+ │ ├── index.ts # Main MCP server
448
+ │ ├── vale-runner.ts # Vale execution wrapper
449
+ │ ├── config.ts # Configuration management
450
+ │ └── types.ts # TypeScript type definitions
451
+ ├── build/ # Compiled JavaScript (generated)
452
+ ├── package.json # Node.js package configuration
453
+ ├── tsconfig.json # TypeScript compiler configuration
454
+ └── readme.md # This file
455
+ ```
456
+
457
+ ### Building for development
458
+
459
+ ```bash
460
+ # Install dependencies
461
+ npm install
462
+
463
+ # Build TypeScript
464
+ npm run build
465
+
466
+ # Watch for changes
467
+ npm run watch
468
+
469
+ # Run the server directly
470
+ npm start
471
+ ```
472
+
473
+ ### Linting
474
+
475
+ ```bash
476
+ # TypeScript compilation check
477
+ npx tsc --noEmit
478
+
479
+ # Strict unused code check
480
+ npx tsc --noUnusedLocals --noUnusedParameters --noEmit
481
+ ```
482
+
483
+ ## Troubleshooting
484
+
485
+ ### Vale not found
486
+
487
+ If you see errors about missing Vale installation:
488
+
489
+ **macOS:**
490
+
491
+ ```bash
492
+ brew install vale
493
+ ```
494
+
495
+ **Linux:**
496
+
497
+ ```bash
498
+ sudo snap install vale
499
+ ```
500
+
501
+ **Windows:**
502
+
503
+ ```bash
504
+ choco install vale
505
+ # or
506
+ scoop install vale
507
+ ```
508
+
509
+ ### Missing styles directory (E100 errors)
510
+
511
+ If you see errors like "The path '/path/to/styles' does not exist":
512
+
513
+ 1. Make sure you have a `.vale.ini` file in your project
514
+ 2. Run the `vale_sync` tool through your AI assistant
515
+ 3. Or manually run: `vale sync`
516
+
517
+ ### Debug mode
518
+
519
+ Enable debug mode to see detailed logging:
520
+
521
+ ```json
522
+ {
523
+ "mcpServers": {
524
+ "vale": {
525
+ "command": "vale-cli",
526
+ "args": ["--debug"]
527
+ }
528
+ }
529
+ }
530
+ ```
531
+
532
+ Check the MCP server logs in your AI assistant for detailed information.
533
+
534
+ ## Credits
535
+
536
+ Created by @chrischinchilla and @theletterf
537
+
538
+ ## License
539
+
540
+ MIT License. Refer to the LICENSE file for details.
package/README.md DELETED
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.