npm package: @ryancavanaugh/mcp-server-md-fragments
Description: MCP server for internal documentation
Latest version: 0.0.2

# 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:

```md
# Main Topic

## Subtopic

Brief description of the subtopic

### Specific Question

> Summary of what this section covers

Detailed content about the specific question
```

### Example:

```md
# 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

```bash
npm install
npm run build
```

## Usage

### Running the Server

The server requires a path to a markdown file:

```bash
npm start path/to/your/documentation.md
```

For testing with the sample file:

```bash
npm start sample-docs.md
```

The server communicates via stdio and can be integrated with MCP-compatible clients.

## Tool Examples

### Search Documentation
```json
{
  "name": "search_docs",
  "arguments": {
    "query": "birds",
    "tags": ["animals"]
  }
}
```

### Create New Documentation
```json
{
  "name": "create_doc", 
  "arguments": {
    "id": "new-topic",
    "title": "New Topic",
    "content": "Content for the new topic...",
    "tags": ["category", "new"]
  }
}
```

### Update Documentation
```json
{
  "name": "update_doc",
  "arguments": {
    "id": "existing-id",
    "content": "Updated content..."
  }
}
```

### List All Documentation
```json
{
  "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**:
   ```bash
   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