<div align="center">
<h1>MDX MCP Server</h1>
<p>Universal MCP server for intelligent MDX file processing and analysis</p>
</div>
<div align="center">
<img src="https://img.shields.io/badge/Node.js-20%2B-green?style=for-the-badge&logo=node.js&logoColor=white">
<img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge">
<img src="https://img.shields.io/badge/Platforms-Win%20%7C%20macOS%20%7C%20Linux-blue?style=for-the-badge">
<a href="https://github.com/LLMTooling/mdx-mcp-server/actions/workflows/test.yml">
<img src="https://img.shields.io/github/actions/workflow/status/LLMTooling/mdx-mcp-server/test.yml?style=for-the-badge&label=Tests">
</a>
</div>
<div align="center">
<h2>Overview</h2>
</div>
<div align="center">
MDX MCP Server is a powerful Model Context Protocol server that enables LLMs to seamlessly interact with, search, and process MDX files. It provides robust tools for reading MDX content as clean Markdown, performing contextual searches, converting files, and extracting metadata, all with built-in cross-platform compatibility and security.
</div>
<div align="center">
<h2>Core Features</h2>
</div>
<div align="center">
<table>
<tr>
<th>Feature</th>
<th>Description</th>
</tr>
<tr>
<td>MDX Reading</td>
<td>Convert MDX to clean Markdown format on the fly</td>
</tr>
<tr>
<td>Contextual Search</td>
<td>Find content within MDX files with surrounding context</td>
</tr>
<tr>
<td>Format Conversion</td>
<td>Convert and save MDX files to standard Markdown</td>
</tr>
<tr>
<td>Metadata Extraction</td>
<td>Parse and retrieve YAML frontmatter</td>
</tr>
<tr>
<td>Cross-Platform</td>
<td>Native support for Windows, Linux, and macOS</td>
</tr>
<tr>
<td>Path Safety</td>
<td>Secure path resolution preventing directory traversal</td>
</tr>
</table>
</div>
<div align="center">
<h2>MCP Tools</h2>
</div>
<div align="center">
The server exposes the following tools through the Model Context Protocol interface.
</div>
<div align="center">
<table>
<tr>
<th>Tool</th>
<th>Description</th>
<th>Key Parameters</th>
</tr>
<tr>
<td><code>read_mdx</code></td>
<td>Read an MDX file and return its contents as Markdown</td>
<td>path</td>
</tr>
<tr>
<td><code>search_mdx</code></td>
<td>Search for content within an MDX file</td>
<td>path, query, contextLines</td>
</tr>
<tr>
<td><code>convert_mdx_to_md</code></td>
<td>Convert an MDX file to a Markdown file on disk</td>
<td>sourcePath, outputPath</td>
</tr>
<tr>
<td><code>get_mdx_frontmatter</code></td>
<td>Extract YAML frontmatter from an MDX file</td>
<td>path</td>
</tr>
</table>
</div>
<div align="center">
<h2>Tool Usage Examples</h2>
</div>
<div align="center">
See how the tools can be leveraged to interact with MDX files.
</div>
```json
// Read an MDX file
{
"name": "read_mdx",
"arguments": {
"path": "docs/introduction.mdx"
}
}
// Search with context
{
"name": "search_mdx",
"arguments": {
"path": "docs/guide.mdx",
"query": "installation",
"contextLines": 2
}
}
// Convert MDX to Markdown
{
"name": "convert_mdx_to_md",
"arguments": {
"sourcePath": "docs/guide.mdx",
"outputPath": "output/guide.md"
}
}
// Extract metadata
{
"name": "get_mdx_frontmatter",
"arguments": {
"path": "docs/article.mdx"
}
}
```
<div align="center">
<h2>Installation</h2>
</div>
<div align="center">
**Prerequisites**
</div>
Ensure you have Node.js installed:
```bash
# Node.js >= 20.19.0 is required
node --version
```
<div align="center">
**Install the MCP Server**
</div>
```bash
npm install
npm run build
```
<div align="center">
<h2>Configuration</h2>
</div>
Add to your MCP settings file (e.g., `claude_desktop_config.json`):
```json
{
"mcpServers": {
"mdx": {
"command": "node",
"args": ["/absolute/path/to/mdx-mcp-server/dist/index.js"],
"env": {
"WORKSPACE_ROOT": "/path/to/your/workspace"
}
}
}
}
```
<div align="center">
<h2>Development</h2>
</div>
```bash
# Clone the repository
git clone https://github.com/LLMTooling/mdx-mcp-server.git
cd mdx-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
```
<div align="center">
<h2>Architecture</h2>
</div>
<div align="center">
The server follows a modular architecture ensuring clean separation of concerns.
</div>
<div align="center">
<table>
<tr>
<th>Component</th>
<th>Responsibility</th>
</tr>
<tr>
<td>Server Entry</td>
<td>Main MCP server setup and configuration (<code>src/index.ts</code>)</td>
</tr>
<tr>
<td>Tools Module</td>
<td>Implementation of individual MCP tools (<code>src/tools/</code>)</td>
</tr>
<tr>
<td>Path Resolver</td>
<td>Cross-platform path handling and security (<code>src/utils/path-resolver.ts</code>)</td>
</tr>
<tr>
<td>MDX Processor</td>
<td>Core MDX processing logic (<code>src/utils/mdx-processor.ts</code>)</td>
</tr>
</table>
</div>
<div align="center">
<h2>Contributing</h2>
</div>
<div align="center">
Contributions are welcome! Please feel free to submit issues or pull requests.
</div>
<div align="center">
<h2>License</h2>
</div>
<div align="center">
MIT License
</div>
