Demo MCP 服务器

一个使用简单的 cowsay 工具演示基本 MCP（模型上下文协议）功能的最小 FastMCP Python 服务器。

功能

• FastMCP 服务器：简单的 MCP 服务器实现
• Cowsay 工具：生成ASCII艺术风格的奶牛说自定义消息
• 环境配置：支持使用 Pydantic 设置的 .env 文件
• Docker 支持：完整的 Docker 和 docker-compose 配置
• 测试：使用 pytest 的基本单元测试
• KISS 原则：保持简单，专注于实现

快速开始

本地开发

1. 安装依赖项：

   make install-dev
   

2. 运行服务器（端口 8005 上的 HTTP 模式）：

   make run-http
   

3. 运行测试：

   make test
   

Docker

1. 构建并运行：

   make docker-build
   make docker-run
   

2. 对于 HTTP 传输：

   make docker-run-http
   

项目结构

my-mcp-server/
├── src/
│   ├── config/
│   │   └── settings.py          # 环境配置
│   └── mcp/
│       ├── __main__.py          # 入口点
│       ├── server.py            # FastMCP 服务器设置
│       └── tools/
│           └── cowsay.py        # Cowsay MCP 工具
├── tests/                       # 单元测试
├── .env.example                 # 环境变量模板
├── docker-compose.yml           # Docker compose 配置
├── Dockerfile                   # Docker 容器定义
├── Makefile                     # 常用命令
└── pyproject.toml              # Python 项目配置

可用工具

cowsay

生成ASCII艺术风格的奶牛说一条消息。

参数：

• message (str)：奶牛要说的消息
• cow (str, 可选)：使用的奶牛类型（默认："default"）

示例：

result = await cowsay("Hello, World!")

输出：

 _______________
< Hello, World! >
 ---------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

配置

服务器使用环境变量进行配置。复制 .env.example 到 .env 并自定义：

cp .env.example .env

可用设置

变量	默认值	描述
APP_NAME	"Demo MCP Server"	应用名称
LOG_LEVEL	"INFO"	日志级别
MCP_TRANSPORT	"stdio"	MCP 传输方法
MCP_HOST	"127.0.0.1"	HTTP 传输主机
MCP_PORT	"8000"	HTTP 传输端口
MAX_MESSAGE_LENGTH	"500"	最大 cowsay 消息长度

使用 MCP 客户端

Claude Desktop

添加到您的 MCP 设置中：

{
  "mcpServers": {
    "demo-mcp-server": {
      "command": "python",
      "args": ["-m", "src.mcp"],
      "cwd": "/path/to/my-mcp-server"
    }
  }
}

命令行

# STDIO 传输（默认）
python -m src.mcp --transport stdio

# HTTP 传输
python -m src.mcp --transport http --port 8000

# 帮助
python -m src.mcp --help

开发

可用 Make 命令

make help              # 显示所有可用命令

# 开发
make install           # 安装依赖项
make install-dev       # 安装带有开发依赖项
make test             # 运行测试
make test-verbose     # 运行带有详细输出的测试

# 运行
make run              # 在本地运行服务器（STDIO）
make run-http         # 在本地运行服务器（HTTP）
make health           # 检查服务器健康状况

# Docker
make docker-build     # 构建 Docker 镜像
make docker-run       # 在 Docker 中运行（STDIO）
make docker-run-http  # 在 Docker 中运行（HTTP）
make docker-stop      # 停止容器
make docker-clean     # 清理容器和镜像

# 清理
make clean            # 清理构建工件

测试

# 运行所有测试
make test

# 运行带有覆盖率
python -m pytest --cov=src --cov-report=html

# 运行特定测试
python -m pytest tests/test_cowsay.py -v

添加新工具

1. 在 src/mcp/tools/ 中创建一个新的工具文件
2. 使用 FastMCP 模式实现工具
3. 在 src/mcp/server.py 中注册它
4. 在 tests/ 中添加测试

示例工具结构：

from fastmcp.tools import Tool

def create_my_tool() -> Tool:
    async def my_tool(param: str) -> dict:
        # 工具实现
        return {"success": True, "result": param}
    
    return Tool(
        name="my_tool",
        description="我的工具描述",
        func=my_tool,
    )

Docker

构建

docker-compose build

运行

STDIO 模式（用于 MCP 客户端）：

docker-compose up demo-mcp-server

HTTP 模式（用于测试）：

docker-compose --profile http up demo-mcp-http

Docker 中的环境变量

创建一个 .env 文件或在 docker-compose.yml 中设置环境变量：

environment:
  - APP_NAME=My Custom MCP Server
  - LOG_LEVEL=DEBUG

健康检查

检查服务器健康状况：

make health

或者直接：

python -c "from src.mcp.server import get_server_health; import json; print(json.dumps(get_server_health(), indent=2))"

许可证

MIT 许可证 - 欢迎将其作为您自己的 MCP 服务器的起点。

贡献

这是一个演示/种子项目。欢迎 fork 并根据需要扩展它。

---

愉快的 MCP 开发！ 🐄