MD Fragments MCP Server

A Model Context Protocol (MCP) server for managing internal documentation from markdown files. This server provides tools and resources for creating, updating, searching, and accessing documentation entries parsed from a structured markdown file.

Features

Markdown Documentation Parser

• Parses structured markdown files with hierarchical sections
• Extracts summaries from blockquotes (lines starting with >)
• Creates searchable documents from markdown headings and content
• Automatically generates tags based on document hierarchy

Resources

• Documentation Access: Access documentation entries via doc:// URIs
• Structured Content: Each document includes title, content, tags, summary, and last updated date

Tools

1. search_docs: Search through documentation using queries and optional tag filters
2. create_doc: Create new documentation entries
3. update_doc: Update existing documentation entries
4. list_docs: List all available documentation with optional tag filtering

Markdown Format

The expected markdown format uses hierarchical headers with optional summaries:

# Main Topic

## Subtopic

Brief description of the subtopic

### Specific Question

> Summary of what this section covers

Detailed content about the specific question

Example:

# Animals

## Birds

Birds are an avian species that are super fun and usually fly

### How do birds fly?

> Explains how birds fly

They flap their wings

### Are they cute?

> Discusses the cuteness of birds and how to determine if a given bird is cute or not

Always

Installation

npm install
npm run build

Usage

Running the Server

The server requires a path to a markdown file:

npm start path/to/your/documentation.md

For testing with the sample file:

npm start sample-docs.md

The server communicates via stdio and can be integrated with MCP-compatible clients.

Tool Examples

Search Documentation

{
  "name": "search_docs",
  "arguments": {
    "query": "birds",
    "tags": ["animals"]
  }
}

Create New Documentation

{
  "name": "create_doc", 
  "arguments": {
    "id": "new-topic",
    "title": "New Topic",
    "content": "Content for the new topic...",
    "tags": ["category", "new"]
  }
}

Update Documentation

{
  "name": "update_doc",
  "arguments": {
    "id": "existing-id",
    "content": "Updated content..."
  }
}

List All Documentation

{
  "name": "list_docs",
  "arguments": {
    "tag_filter": "birds"
  }
}

Resource Access

Access documentation directly via URIs:

• doc://animals-birds-how-do-birds-fly
• doc://animals-birds-are-they-cute

Document IDs are automatically generated from the heading hierarchy, converted to lowercase with special characters replaced by hyphens.

VS Code Integration (Self-Consuming Setup)

This repository is configured to consume its own MCP server within VS Code, creating a self-documenting development environment.

Setup

1. Build the project:

   npm run build

2. Open in VS Code: The .vscode/settings.json automatically configures the MCP server to run with the sample documentation.

3. Enable MCP in VS Code:

   • Install the MCP extension for VS Code
   • The server will automatically start and connect to VS Code
   • You can now access the documentation through VS Code's MCP interface

VS Code Configuration Files

• .vscode/settings.json: MCP server configuration
• .vscode/tasks.json: Build and development tasks
• .vscode/launch.json: Debug configurations
• .vscode/extensions.json: Recommended extensions

Available VS Code Tasks

• Build: Compile TypeScript (Ctrl+Shift+P → "Tasks: Run Task" → "npm: build")
• Dev Mode: Watch compilation (npm: dev)
• Start MCP Server: Manual server startup for testing

Debugging

Use the "Debug MCP Server" configuration to debug the server with VS Code's debugger:

1. Set breakpoints in the TypeScript source
2. Press F5 or use "Run and Debug" panel
3. The server will start with the debugger attached

Development

• Build: npm run build
• Watch: npm run dev
• Start: npm start <markdown-file>

Testing

This project includes a smoke testing system that generates JSON baselines for all commands:

• Generate test baselines: npm run test:baselines

This command will:

1. Build the project
2. Parse the sample documentation
3. Run all commands with various test inputs
4. Generate JSON output files in the baselines/ directory:
   • baseline-<timestamp>.json: Timestamped baseline file
   • latest.json: Always contains the most recent test results

The baseline files contain the input/output for:

• list-topics: All available topics
• show-topic: Individual topic retrieval (tests first 3 topics)
• show-topics: Multiple topic retrieval
• search-topic-descriptions: Search with various queries
• Error cases: Invalid arguments and nonexistent topics

Use these baselines during development to verify that changes don't break existing functionality by comparing new baseline outputs with previous ones.

Dependencies

• @modelcontextprotocol/sdk: Official MCP SDK
• marked: Markdown parser for processing documentation files
• zod: Runtime validation and type safety

License

MIT