Skip to content

Commit 3a1c2da

Browse files
author
Wilson
committed
Implement markdownlint MCP server with configuration, validation, and usage documentation
1 parent bca5e4f commit 3a1c2da

File tree

13 files changed

+5104
-0
lines changed

13 files changed

+5104
-0
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
13+
strategy:
14+
matrix:
15+
node-version: [18.x, 20.x]
16+
17+
steps:
18+
- uses: actions/checkout@v4
19+
20+
- name: Use Node.js ${{ matrix.node-version }}
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: ${{ matrix.node-version }}
24+
cache: 'npm'
25+
26+
- name: Install dependencies
27+
run: npm ci
28+
29+
- name: Run build
30+
run: npm run build
31+
32+
- name: Run type check
33+
run: npx tsc --noEmit

‎.github/workflows/release.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: Release
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
release:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
13+
- name: Use Node.js
14+
uses: actions/setup-node@v4
15+
with:
16+
node-version: '20.x'
17+
registry-url: 'https://registry.npmjs.org'
18+
cache: 'npm'
19+
20+
- name: Install dependencies
21+
run: npm ci
22+
23+
- name: Build
24+
run: npm run build
25+
26+
- name: Publish to npm
27+
run: npm publish --access public
28+
env:
29+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎CURSOR_GUIDE.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Cursor MCP Server Integration Guide
2+
3+
This guide explains how to integrate the markdownlint MCP server with Cursor to validate and improve markdown generation.
4+
5+
## Prerequisites
6+
7+
- Node.js 18.x or later
8+
- npm 7 or later
9+
- Cursor with MCP server support
10+
11+
## Installation
12+
13+
No installation is required as we'll use `npx` to run the package directly.
14+
15+
## Cursor Configuration
16+
17+
To configure Cursor to use the markdownlint MCP server, create or update the MCP server configuration file:
18+
19+
1. Create or edit the file named `cursor-mcp-servers.json` in your Cursor configuration directory (typically `~/.cursor/` or `%APPDATA%/Cursor/` on Windows)
20+
21+
2. Add the markdownlint MCP server configuration:
22+
```json
23+
{
24+
"mcpServers": {
25+
"markdownlint-mcp": {
26+
"command": "npx",
27+
"args": [
28+
"-y",
29+
"markdownlint-mcp-server"
30+
],
31+
"env": {}
32+
}
33+
}
34+
}
35+
```
36+
37+
3. Restart Cursor to apply the configuration
38+
39+
The configuration file supports the following options:
40+
- `command`: The command to start the MCP server (use "npx")
41+
- `args`: Array of command-line arguments (use ["-y", "markdownlint-mcp-server"])
42+
- `env`: Environment variables (optional)
43+
44+
## Usage in Cursor
45+
46+
Once configured, Cursor will automatically use the markdownlint MCP server when generating markdown content. The server provides two tools:
47+
48+
### 1. Validate Tool
49+
50+
Validates markdown content against markdownlint rules:
51+
52+
```typescript
53+
// Example request
54+
{
55+
"tool": "validate",
56+
"params": {
57+
"content": "# Heading 1\n\nThis is some content.",
58+
"config": {
59+
"MD013": false // Optional: disable line length rule
60+
}
61+
}
62+
}
63+
64+
// Example response
65+
{
66+
"isValid": true,
67+
"errors": []
68+
}
69+
```
70+
71+
### 2. Rules Tool
72+
73+
Retrieves the available markdownlint rules:
74+
75+
```typescript
76+
// Example request
77+
{
78+
"tool": "rules",
79+
"params": {}
80+
}
81+
82+
// Example response
83+
{
84+
"MD001": true,
85+
"MD003": { "style": "consistent" },
86+
// ... other rules
87+
}
88+
```
89+
90+
## Error Handling
91+
92+
When validation errors occur, Cursor will receive detailed information about each issue:
93+
94+
```typescript
95+
{
96+
"isValid": false,
97+
"errors": [
98+
{
99+
"lineNumber": 1,
100+
"ruleDescription": "Heading levels should only increment by one level at a time",
101+
"ruleInformation": "MD001",
102+
"errorDetail": "Expected: h2; Actual: h1",
103+
"errorContext": "# Heading 1",
104+
"errorRange": [0, 10]
105+
}
106+
]
107+
}
108+
```
109+
110+
## Custom Configuration
111+
112+
You can customize the markdownlint rules by providing a configuration object when using the validate tool:
113+
114+
```typescript
115+
{
116+
"tool": "validate",
117+
"params": {
118+
"content": "# Heading 1\n\nThis is some content.",
119+
"config": {
120+
"MD013": false, // Disable line length rule
121+
"MD025": false // Disable multiple top level headings rule
122+
}
123+
}
124+
}
125+
```
126+
127+
## Troubleshooting
128+
129+
1. **Server Not Starting**
130+
- Ensure Node.js is installed and in your PATH
131+
- Check if the port is already in use
132+
- Verify the installation with `markdownlint-mcp-server --version`
133+
- Verify the JSON configuration file is in the correct location and format
134+
135+
2. **Connection Issues**
136+
- Verify the MCP server is running
137+
- Check the JSON configuration file format
138+
- Ensure stdio communication is working
139+
- Check Cursor logs for configuration errors
140+
141+
3. **Validation Errors**
142+
- Review the error messages for specific issues
143+
- Check the markdownlint documentation for rule explanations
144+
- Adjust the configuration if needed
145+
146+
## Support
147+
148+
For issues or questions:
149+
- Open an issue on GitHub
150+
- Check the markdownlint documentation
151+
- Review the MCP server logs
152+
- Check Cursor's MCP server documentation
153+
154+
## License
155+
156+
MIT

‎README.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# markdownlint-mcp-server
2+
3+
A Model Context Protocol (MCP) server implementation for markdownlint that validates markdown content against markdownlint rules.
4+
5+
## Features
6+
7+
- Validates markdown content using markdownlint
8+
- Provides access to markdownlint rules
9+
- Supports custom configuration
10+
- Implements the MCP protocol for AI/LLM integration
11+
- Can be used by Cursor to validate generated markdown
12+
13+
## Installation
14+
15+
```bash
16+
npm install markdownlint-mcp-server
17+
```
18+
19+
## Usage
20+
21+
### As a CLI
22+
23+
```bash
24+
markdownlint-mcp-server
25+
```
26+
27+
The server will start and listen for MCP protocol messages on stdio.
28+
29+
### As a Library
30+
31+
```typescript
32+
import { markdownlintMcpServer } from 'markdownlint-mcp-server';
33+
34+
const server = markdownlintMcpServer();
35+
// Use the server with your preferred MCP transport
36+
```
37+
38+
### Integration with Cursor
39+
40+
Cursor can use this MCP server to validate its markdown generation:
41+
42+
1. Start the MCP server
43+
2. Cursor will connect to the server
44+
3. When generating markdown content, Cursor will:
45+
- Send the content to the `validate` tool
46+
- Check for any linting errors
47+
- Use the validation results to improve its markdown generation
48+
- Ensure the final output follows markdownlint rules
49+
50+
Example workflow:
51+
```typescript
52+
// Cursor's markdown generation process
53+
const markdown = generateMarkdown();
54+
const validation = await validateMarkdown(markdown);
55+
if (!validation.isValid) {
56+
// Use the validation errors to improve markdown generation
57+
// The errors provide detailed information about what needs to be fixed
58+
console.log('Markdown validation errors:', validation.errors);
59+
// Cursor can use this information to adjust its generation
60+
}
61+
return markdown;
62+
```
63+
64+
The validation results include detailed information about any issues found:
65+
- Line numbers where issues occur
66+
- Rule descriptions and information
67+
- Error details and context
68+
- Range of text affected
69+
70+
## API
71+
72+
The server provides two tools:
73+
74+
1. `validate` - Validates markdown content
75+
```typescript
76+
{
77+
content: string; // The markdown content to validate
78+
config?: object; // Optional markdownlint configuration
79+
}
80+
```
81+
82+
2. `rules` - Returns the available markdownlint rules
83+
```typescript
84+
{} // No parameters needed
85+
```
86+
87+
## Configuration
88+
89+
The server uses a default configuration based on markdownlint's recommended rules. You can override these rules by providing a custom configuration when using the validate tool.
90+
91+
## Development
92+
93+
### Building
94+
95+
```bash
96+
npm run build
97+
```
98+
99+
### Project Structure
100+
101+
- `src/`
102+
- `index.ts` - Main server implementation
103+
- `config.ts` - Default markdownlint configuration
104+
- `types.ts` - Shared types and schemas
105+
- `validation.ts` - Markdown validation logic
106+
- `bin.ts` - CLI entry point
107+
108+
### CI/CD
109+
110+
The project uses GitHub Actions for continuous integration and deployment:
111+
112+
- **CI Pipeline**: Runs on every push and pull request
113+
- Tests on Node.js 18.x and 20.x
114+
- Builds the project
115+
- Runs type checking
116+
117+
- **Release Pipeline**: Runs when a new release is published
118+
- Builds the project
119+
- Publishes to npm
120+
121+
To create a new release:
122+
1. Update the version in `package.json`
123+
2. Create a new release on GitHub
124+
3. The release workflow will automatically publish to npm
125+
126+
## License
127+
128+
MIT

0 commit comments

Comments
 (0)