go-mcp-server-mds

A Go implementation of a Model Context Protocol (MCP) server that serves markdown files from a filesystem.

Overview

This server provides a way to expose markdown files through the Model Context Protocol, making them accessible as resources and providing tools to list and read markdown files. It supports markdown files with YAML or TOML frontmatter.

Features

• Serve markdown files via MCP
• List all available markdown files with metadata
• Read individual markdown file contents
• Support for YAML and TOML frontmatter
• File system abstraction using fs.FS
• Resource management with URI-based access

Frontmatter Support

The server supports markdown files with YAML or TOML frontmatter. Frontmatter is metadata placed at the beginning of a markdown file, enclosed by delimiters.

YAML Frontmatter

YAML frontmatter uses --- as delimiters:

---
title: My Document
date: 2024-03-21
tags: [documentation, markdown]
---

# Document Content

TOML Frontmatter

TOML frontmatter uses +++ as delimiters:

+++
title = "My Document"
date = 2024-03-21
tags = ["documentation", "markdown"]
+++

# Document Content

The frontmatter metadata is parsed and made available through the server's tools and resource descriptions. This metadata can include any valid YAML or TOML data and is useful for organizing and describing your markdown documents.

Installation

go get github.com/Warashi/go-mcp-server-mds

Usage

Here's a basic example of how to create and use the MCP markdown server:

package main

import (
    "context"
    "os"

    mcpmds "github.com/Warashi/go-mcp-server-mds"
)

func main() {
    // Create a new server using the current directory
    server, err := mcpmds.New(
        "markdown-server",
        "A server that provides access to markdown files",
        os.DirFS("."),
    )
    if err != nil {
        panic(err)
    }

    // Start the server
    if err := server.ServeStdio(context.Background()); err != nil {
        panic(err)
    }
}

Command-Line Tool (mcp-server-mds)

This repository includes a command-line tool mcp-server-mds that runs the server directly.

Installing

To build the command-line tool:

go install github.com/Warashi/go-mcp-server-mds/cmd/mcp-server-mds@latest

Running

To run the server, execute the built binary. It serves markdown files from a specified directory over standard input/output.

$HOME/go/bin/mcp-server-mds -path /path/to/your/markdown/files

Flags:

• -path: Specifies the directory containing the markdown files to serve. Defaults to the current directory (.).
• -name: Sets the server name. Defaults to mcp-server-mds.
• -description: Sets the server description. Defaults to Markdown Documents Server.

Available Tools

list_{server-name}_markdown_files

Lists all markdown files managed by the server. Returns metadata including:

• File path
• File size
• Parsed frontmatter (if available)

read_{server-name}_markdown_file

Reads a specific markdown file. Requires:

• path: The path to the markdown file

Returns:

• File path
• File size
• Parsed frontmatter
• Full file content

Resource Access

Resources are accessible via file:// URIs. Each markdown file is registered as a resource with:

• URI: file://{path}
• Name: Base filename
• Description: JSON-encoded frontmatter
• MimeType: text/markdown
• Size: File size in bytes

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.