Go MCP Server Mds

🚀 go-mcp-server-mds

A Model Context Protocol (MCP) server implemented in Go, designed to serve Markdown files from the file system.

🚀 Quick Start

The go-mcp-server-mds is a server implemented in Go that provides access to Markdown files via the Model Context Protocol (MCP). It supports Markdown files with YAML or TOML front matter and allows users to list and read Markdown files as resources.

✨ Features

• Serve Markdown files through the MCP protocol.
• List all available Markdown files and their metadata.
• Read the content of a single Markdown file.
• Support YAML and TOML front matter.
• Implement file system abstraction using fs.FS.
• Manage resources based on URIs.

📦 Installation

To install the package, use the following command:

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

💻 Usage Examples

Basic Usage

Here is a basic example of creating and using an MCP Markdown server:

package main

import (
    "context"
    "os"

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

func main() {
    // Create a new server instance 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)
    }
}

Advanced Usage

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

Installation

To build the command-line tool:

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

Running the Server

To run the server, execute the built binary. It will serve Markdown files from the specified directory.

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

Parameters:

• -path: Specify the directory containing the Markdown files to be served. The default is the current directory (.).
• -name: Set the server name. The default is mcp-server-mds.
• -description: Set the server description. The default is Markdown document server.

📚 Documentation

Front Matter Support

The server supports Markdown files with YAML or TOML front matter. Front matter refers to metadata placed at the beginning of a file and enclosed by delimiters.

YAML Front Matter

YAML uses --- as the delimiter:

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

# Document Content

TOML Front Matter

TOML uses +++ as the delimiter:

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

# Document Content

The front matter will be parsed and can be obtained through server tools and resource descriptions. This metadata can contain any valid YAML or TOML data, suitable for organizing and describing Markdown documents.

Available Tools

list_{server-name}_markdown_files

List all Markdown files managed by the server. The returned information includes:

• File path
• File size
• Parsed front matter (if available)

read_{server-name}_markdown_file

Read a specific Markdown file. The following parameter is required:

• path: The path of the Markdown file

The returned information includes:

• File path
• File size
• Parsed front matter
• Complete file content

Resource Access

Resources can be accessed via file:// URIs. Each Markdown file is registered as a resource with the following attributes:

📄 License

This project is licensed under the MIT License. For more details, please refer to LICENSE.

🤝 Contribution Guidelines

Contributions are welcome! Please refer to CONTRIBUTING.md to learn how to participate in the development.

📖 References

• Model Context Protocol (MCP)
• Go Official Documentation
• W3C WebAssembly Component Model