AI导哈

Markdown文档管理服务

为Cursor AI IDE提供的Markdown文档CRUD操作及高级管理功能的MCP服务器。

  • by huntkil
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 huntkil/mcp_python

使用说明

Markdown MCP服务器

Cursor AI IDE提供的Markdown文档管理模型上下文协议（MCP）服务器。

概述

该项目提供MCP服务器，使Cursor AI IDE能够有效地执行Markdown文档的CRUD操作。不仅支持创建、读取、修改、删除文档，还支持搜索、元数据管理等高级功能。

主要功能

基本CRUD操作

  • 创建文档：创建新的Markdown文件
  • 读取文档：读取现有Markdown文件内容
  • 修改文档：修改或添加现有文件内容
  • 删除文档：删除Markdown文件

高级功能

  • 查询文档列表：查看目录中的Markdown文件列表
  • 搜索内容：在文件内容中搜索关键字
  • 元数据管理：YAML frontmatter管理（添加、修改、删除）

技术堆栈

  • 语言：Python 3.9+
  • 框架：MCP Python SDK
  • 文档格式：Markdown（.md，.Markdown）
  • 依赖性: mcp, pyyaml, pathlib2, typing-extensions

设置

1.存储库克隆

git clone <repository-url>
cd markdown-mcp-server

2.安装依赖性

pip install -r requirements.txt

3.安装开发模式（可选）

pip install -e .

使用方法

Cursor AI IDE设置

在Cursor AI IDE的配置文件中添加MCP服务器：

{
  "mcp": {
    "servers": {
      "markdown-manager": {
        "command": "python",
        "args": ["-m", "src.server"],
        "cwd": "/path/to/markdown-mcp-server"
      }
    }
  }
}

环境变量

  • MARKDOWN_MCP_BASE_PATH：文件操作的默认目录（默认：当前目录）

API参考

1.read_markdown

读取Markdown文件并返回内容。

参数：

  • file_path （string）：要读取的文件的路径
  • encoding （optional，string）：文件编码（默认值：“utf-8”）

반환값:

{
  "success": true,
  "content": "파일 내용",
  "content_without_frontmatter": "frontmatter 제외한 내용",
  "frontmatter": {"title": "제목", "author": "작성자"},
  "file_info": {"name": "파일명", "size": 1024, ...},
  "encoding": "utf-8"
}

2.创建_降价

创建新的Markdown文件。

参数：

  • file_path （string）：要创建的文件的路径
  • content （string）：文件内容
  • overwrite （optional，boolean）：是否覆盖现有文件（默认值：false）

반환값:

{
  "success": true,
  "message": "File created successfully: file.md",
  "file_path": "/full/path/to/file.md",
  "file_info": {"name": "file.md", "size": 1024, ...}
}

3.更新_降价

修改现有Markdown文件的内容。

参数：

  • file_path （string）：要修改的文件的路径
  • content （string）：新增内容
  • append （optional，boolean）：是否添加内容（默认值：false）

반환값:

{
  "success": true,
  "message": "File updated successfully: file.md",
  "file_path": "/full/path/to/file.md",
  "file_info": {"name": "file.md", "size": 1024, ...}
}

4.删除_降价

删除指定的Markdown文件。

参数：

  • file_path （string）：要删除的文件的路径
  • confirm （optional，boolean）：确认删除（默认值：false）

반환값:

{
  "success": true,
  "message": "File deleted successfully: file.md"
}

5.列表标记文件

返回指定目录的Markdown文件列表。

参数：

  • directory （optional，string）：要搜索的目录路径（默认值：“.”）
  • recursive （optional，boolean）：是否包含子目录（默认值：false）
  • pattern （optional，string）：文件模式（默认为“*.md”）

반환값:

{
  "success": true,
  "files": [
    {
      "name": "file1.md",
      "size": 1024,
      "modified": 1234567890,
      "relative_path": "file1.md"
    }
  ],
  "count": 1,
  "directory": "."
}

6.搜索_标记

在Markdown文件内容中搜索关键字。

参数：

  • directory （string）：要搜索的目录
  • query （string）：搜索关键字
  • case_sensitive （optional，boolean）：区分大小写（默认值：false）

반환값:

{
  "success": true,
  "results": [
    {
      "file_path": "file1.md",
      "matches": [
        {"line_number": 5, "line_content": "This line contains the keyword"}
      ],
      "match_count": 1
    }
  ],
  "total_files_searched": 10,
  "files_with_matches": 1,
  "query": "keyword",
  "case_sensitive": false
}

7.管理事项

管理Markdown文件中的YAML frontmatter。

参数：

  • file_path （string）：目标文件路径
  • action （string）：任务类型（“get”、“set”、“update”、“remove”）
  • metadata （optional，object）：元数据信息（需要set/update操作）

返回值（get操作）：

{
  "success": true,
  "frontmatter": {"title": "제목", "author": "작성자"},
  "has_frontmatter": true
}

返回值（其他操作）：

{
  "success": true,
  "message": "Frontmatter set completed successfully",
  "file_path": "/full/path/to/file.md",
  "action": "set"
}

使用示例

在Cursor AI IDE中使用

  1. 创建新的项目文档

    "새로운 프로젝트 문서를 생성해주세요. 파일명: project-overview.md"

  2. 按关键字搜索文档

    "'API 문서' 키워드가 포함된 모든 마크다운 파일을 찾아주세요"

  3. 将内容添加到现有文档

    "README.md 파일에 설치 가이드 섹션을 추가해주세요"

  4. 元数据管理

    "project.md 파일의 frontmatter에 버전 정보를 추가해주세요"

开发

项目结构

markdown-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py              # MCP 서버 메인 로직
│   ├── markdown_manager.py    # Markdown 문서 관리 클래스
│   └── utils.py              # 유틸리티 함수
├── tests/
│   ├── __init__.py
│   ├── test_server.py
│   └── test_markdown_manager.py
├── requirements.txt
├── setup.py
└── README.md

运行测试

# 단위 테스트 실행
python -m unittest tests.test_markdown_manager

# 통합 테스트 실행
python -m unittest tests.test_server

# 모든 테스트 실행
python -m unittest discover tests

运行服务器

# 직접 실행
python -m src.server

# 환경 변수와 함께 실행
MARKDOWN_MCP_BASE_PATH=/path/to/docs python -m src.server

安全注意事项

  • 验证路径：验证所有文件路径以防止path traversal攻击。
  • 验证权限：验证文件系统访问权限。
  • 验证输入：验证所有用户输入。
  • 安全的文件处理：处理文件大小限制和编码问题。

错误处理

所有API调用都返回一致的错误响应格式：

{
  "error": "에러 메시지 설명"
}

常见错误情况：

  • 如果文件不存在
  • 如果您没有权限
  • 文件路径无效
  • 编码错误
  • 目录不存在

记录

服务器提供结构化日志记录：

  • INFO：常规任务日志
  • WARNING:警告情况
  • ERROR：错误情况

日志级别是环境变量 LOG_LEVEL可以设置为。

贡献

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add some amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

许可证

该项目在MIT许可下分发。有关详细信息，请访问 LICENSE 请参考文件。

支持

如果您遇到问题或有任何疑问，请通过GitHub Issues与我们联系。

变更历史记录

v0.1.0

  • 初始版本版本
  • 实现基本CRUD功能
  • 添加搜索和元数据管理功能
  • MCP服务器集成
  • 编写测试代码

相关 MCP