使用说明

项目简介

该项目 'mcp-hello' 是一个Model Context Protocol (MCP) 服务器的入门级示例，旨在演示如何使用 MCP 协议构建应用后端，并与 Claude Desktop 等 MCP 客户端进行交互。此示例实现了一个简单的工具，可以将用户输入的内容插入到预定义的 Markdown 模板中，并生成 Markdown 文件。

主要功能点

工具注册与执行: 实现了一个名为 'create_markdown' 的工具，该工具接受用户输入的内容，并将其插入到 Markdown 模板中。
Markdown 文件生成: 服务器能够根据用户输入和模板，动态生成 Markdown 格式的文件，并将文件保存到指定位置。
基础 MCP 服务器框架: 项目基于 'mcp' 库构建，展示了如何搭建一个基本的 MCP 服务器，处理客户端请求。
Stdio 传输协议: 服务器使用标准输入输出 (stdio) 作为传输协议与 MCP 客户端通信。
简单的日志记录: 集成了基础的日志记录功能，方便开发者监控服务器运行状态。

安装步骤

创建项目目录并进入:

mkdir mcp-hello
cd mcp-hello

创建并激活虚拟环境:

uv venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate  # Windows

安装必要的 Python 包:

uv pip install create-mcp-server mcp python-dotenv anyio

创建 MCP 服务器脚手架 (如果尚未创建):
```
uvx create-mcp-server module1/src/create_markdown_server
```
按照提示填写项目信息，例如项目名称 'markdown-creator' 和描述 'Creates a markdown file from user input and a template'，并选择启用 Claude.app 集成。
替换服务器逻辑: 将仓库提供的 'module1/src/create_markdown_server/server.py' 文件内容替换到你本地项目 'module1/src/create_markdown_server/server.py' 文件中，以实现 Markdown 文件生成工具的功能。

服务器配置

为了让 MCP 客户端（例如 Claude Desktop 或 MCP Inspector）连接到此服务器，需要进行如下配置。以 Claude Desktop 为例，你需要编辑 'claude_desktop_config.json' 文件，通常位于：

macOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%/Claude/claude_desktop_config.json'

在 'mcpServers' 字段下添加一个新的服务器配置项，配置信息如下：

{
    "mcpServers": {
        "markdown-creator": {  // 服务器名称，在 Claude Desktop 中会显示
        "command": "uv",      // 启动服务器的命令，这里使用 uv 运行器
        "args": [             // 启动命令的参数
            "--directory",     // 指定工作目录
            "/path/to/your/mcp-hello/module1/src/create_markdown_server/", //  **请替换为你的 'mcp-hello/module1/src/create_markdown_server/' 目录的绝对路径**
            "run",             // uv 运行命令
            "mcp-simple-prompt" //  运行 '__main__.py' 入口，实际启动 server.py 中的服务器
          ],
        "env": {}             // 环境变量，这里为空
        }
     }
}

注意:

请务必将 '"/path/to/your/mcp-hello/module1/src/create_markdown_server/"' 替换为你本地 'mcp-hello/module1/src/create_markdown_server/' 目录的绝对路径。
'server name' (这里是 '"markdown-creator"') 将会在 MCP 客户端中显示为服务器的名称。
'command' 和 'args' 共同定义了启动 MCP 服务器的完整命令。

基本使用方法

启动 MCP 服务器: 打开终端，进入 'mcp-hello' 目录，确保已激活虚拟环境，然后运行以下命令启动服务器：
```
uv run module1/src/create_markdown_server
```
服务器成功启动后，将会在终端保持运行状态，等待客户端连接和请求。
连接 MCP 客户端并测试:
- 使用 Claude Desktop: 重启 Claude Desktop 应用，在新的对话中，点击 🔌 图标，选择你配置的 '"markdown-creator"' 服务器。在对话框中输入 '/tools' 命令，Claude 应该会列出可用的工具 'create_markdown'。选择 'create_markdown' 工具，并输入 'content' 参数 (例如: 'content: "My test content"')，发送请求。服务器会根据你的输入生成 'output.md' 文件在项目根目录下，Claude Desktop 也会返回工具执行成功的消息。
- 使用 MCP Inspector: 在另一个终端窗口，同样进入 'mcp-hello' 目录并激活虚拟环境，运行 'npx @modelcontextprotocol/inspector uv --directory module1/src/create_markdown_server run create_markdown_server' 启动 MCP Inspector。连接到服务器后，可以在 "Tools" 标签页中找到 'create_markdown' 工具进行测试。

通过以上步骤，你就可以成功运行并测试这个简单的 MCP 服务器示例，体验 MCP 协议的基本工作流程。

关键词