使用说明

项目简介

本项目是一个示例，展示了如何使用 Model Context Protocol (MCP) 构建服务器，为大型语言模型 (LLM) 提供 Markdown 文件处理能力。该服务器提供读取指定目录下 Markdown 文件内容和向指定目录写入 Markdown 文件的工具，使得 LLM 可以通过 MCP 协议与本地文件系统进行交互。

主要功能点

读取Markdown文件内容: 允许 LLM 读取指定目录下的所有 Markdown 文件内容，并以字符串形式返回。
写入Markdown文件: 允许 LLM 在指定目录下创建新的 Markdown 文件，并将指定内容写入文件。该工具可以防止覆盖已存在的文件。

安装步骤

克隆仓库:

git clone [email protected]/keli-wen/mcp_chatbot.git
cd mcp_chatbot

创建并激活虚拟环境 (推荐):

# 安装 uv (如果尚未安装)
pip install uv

# 创建虚拟环境并安装依赖
uv venv .venv --python=3.10

# 激活虚拟环境
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

安装依赖:

pip install -r requirements.txt
# 或者使用 uv 加速安装
uv pip install -r requirements.txt

配置环境变量:
- 复制 '.env.example' 文件为 '.env':
```
cp .env.example .env
```
- 编辑 '.env' 文件，根据需要配置 LLM API 相关的参数（本项目主要演示 MCP 服务器功能，LLM 配置仅用于客户端示例，可使用任意 LLM API 或占位符）。

服务器配置

MCP 服务器的配置在 'mcp_servers/servers_config.json' 文件中。你需要根据你的本地环境修改服务器的启动配置。

打开 'mcp_servers/servers_config.json' 文件，可以看到类似以下的配置：

{
    "mcpServers": {
        "markdown_processor": {
            "command": "/path/to/your/uv",
            "args": [
                "--directory",
                "/path/to/your/project/mcp_servers",
                "run",
                "markdown_processor.py"
            ]
        }
    }
}

'"markdown_processor"': 服务器的名称，客户端需要使用此名称来引用该服务器。
'"command"': 启动 MCP 服务器的命令。示例中使用的是 'uv'，你需要将其替换为你本地 'uv' 可执行文件的绝对路径。可以使用 'which uv' 命令查找 'uv' 的路径。如果你的环境中没有 'uv'，也可以替换为 'python3' 或 'python'，并相应修改 'args' 中的命令。
'"args"': 传递给启动命令的参数列表。
- '"--directory", "/path/to/your/project/mcp_servers"': 指定服务器脚本所在的目录，你需要将 '"/path/to/your/project/mcp_servers"' 替换为 'mcp_servers' 目录的绝对路径。
- '"run", "markdown_processor.py"': 指定要运行的服务器脚本文件名为 'markdown_processor.py'。

修改示例配置：

假设你的项目 'mcp_chatbot' 位于 '/Users/yourname/Projects/mcp_chatbot' 目录下，并且你使用 'python3' 命令运行脚本，那么配置可能需要修改为：

{
    "mcpServers": {
        "markdown_processor": {
            "command": "python3",
            "args": [
                "/Users/yourname/Projects/mcp_chatbot/mcp_servers/markdown_processor.py"
            ]
        }
    }
}

注意： 请务必将路径替换为你本地环境的绝对路径。

基本使用方法

启动 MCP 服务器: MCP 服务器会在客户端程序运行时自动启动，无需手动单独启动。
运行客户端示例程序: 仓库提供了 'run_example.py' 和 'main.py' 两个客户端示例程序。
- 运行 'run_example.py': 该脚本会初始化 MCP 服务器，连接到 LLM API，并调用 'markdown_processor' 服务器提供的工具，处理指定目录下的 Markdown 文件，生成摘要。你需要先在 '.env' 文件中配置 'MARKDOWN_FOLDER_PATH' 和 'RESULT_FOLDER_PATH' 环境变量，指定 Markdown 文件所在的目录和结果输出目录。
```
python run_example.py
```
- 运行 'main.py': 该脚本启动一个交互式聊天会话，你可以与 AI 对话，并指示 AI 使用 'markdown_processor' 服务器提供的工具。
```
python main.py
```
在聊天会话中，你可以尝试指示 AI 读取 Markdown 文件或写入 Markdown 文件，例如：
- '读取 data-example 目录下的所有 markdown 文件'
- '将 "Hello MCP!" 写入到 result 目录下的 test.md 文件中'

注意: 客户端程序 ('run_example.py' 和 'main.py') 依赖于 'mcp_servers/servers_config.json' 中配置的服务器启动命令和参数来连接和使用 MCP 服务器。

关键词