Custom MCP Server with Enhanced Tools

带增强工具的自定义 MCP 服务

本项目展示了一个功能强大的 MCP（Model Context Protocol）服务，其中包含 5 个自定义工具，可直接在 Cursor 中扩展 AI 助手的能力。该服务基于 AI Makerspace MCP 框架构建，包含网页搜索、实用工具和内容生成能力。

🚀 功能

可用工具：

🔍 网页搜索 - 使用 Tavily API 集成搜索网页
🎲 骰子模拟器 - 使用自定义记法掷骰子（例如，2d20k1）
📱 二维码生成器 - 为任意文本或 URL 生成二维码
🔄 单位转换器 - 在不同单位之间转换（长度、重量、温度、体积）
🔗 URL 缩短器 - 使用 TinyURL 或 is.gd 服务缩短 URL

项目概览

MCP 服务通过 Model Context Protocol 与 Cursor 无缝集成，可在 AI 助手中直接即时使用强大的工具。该服务设计为在标准输入/输出（stdio）传输模式下运行，并包含：

• TavilyClient：使用 Tavily API 提供网页搜索能力
• 二维码生成：使用 qrcode 库生成 Base64 编码的二维码
• 单位转换：全面的单位转换，并手动处理温度转换
• URL 缩短：支持多种服务（TinyURL、is.gd）
• 掷骰子：支持高级骰子记法和保留最大值功能

前置条件

• Python 3.13 或更高版本
• 有效的 Tavily API 密钥
• UV 包管理器（用于依赖管理）

⚠️NOTE FOR WINDOWS:⚠️

你需要在操作系统的 Windows 端安装此工具。

这需要安装两个用于 Powershell 的 CLI 工具，步骤如下：

• winget install astral-sh.uv
• winget install --id Git.Git -e --source winget

安装好这些 CLI 工具后，请在 Windows 中打开 Cursor。

安装

1. 克隆仓库：

   git clone https://github.com/suh4s/my-mcp-server.git
   cd my-mcp-server
   

2. 安装依赖：

   uv sync
   

3. 配置环境变量： 创建 .env 文件并添加 Tavily API 密钥：

   TAVILY_API_KEY=your_api_key_here
   

运行 MCP 服务

要启动 MCP 服务，需要将以下内容添加到 Cursor 的 MCP 配置文件中：

注意：要打开 MCP 配置，请使用命令面板（CMD/CTRL+SHIFT+P），选择“View: Open MCP Settings”，然后将内容替换为以下 JSON 配置。

{
    "mcpServers": {
        "mcp-server": {
            "command": "uv",
            "args": ["--directory", "/FULL/PATH/TO/YOUR/REPOSITORY", "run", "server.py"]
        }
    }
}

服务启动后，将通过标准输入/输出监听命令。

🛠️ 工具使用示例

二维码生成器

"Generate a QR code for 'Hello World'"
"Create a QR code for https://github.com/suh4s/my-mcp-server"

单位转换器

"Convert 100 fahrenheit to celsius"
"Convert 5 miles to kilometers"
"Convert 2 pounds to grams"

URL 缩短器

"Shorten this URL: https://github.com/suh4s/my-mcp-server"
"Shorten https://example.com using is.gd"

骰子模拟器

"Roll 2d20k1" (roll 2 20-sided dice, keep highest)
"Roll 3d6" (roll 3 6-sided dice)

网页搜索

"Search for 'MCP protocol documentation'"
"Find recent AI news"

🔧 技术实现

依赖项：

• mcp[cli] - Model Context Protocol 框架
• tavily-python - 网页搜索 API 集成
• qrcode + pillow - 二维码生成
• pint - 单位转换库
• requests - 用于缩短 URL 的 HTTP 请求
• python-dotenv - 环境变量管理

架构：

• FastMCP Server：处理工具注册和协议通信
• 工具函数：使用 @mcp.tool() 装饰器，以便自动发现
• 错误处理：全面的错误处理并提供有用的消息
• 类型安全：所有工具参数均包含完整类型提示

🎯 高级功能

• 温度转换：使用自定义公式处理华氏度与摄氏度转换
• 二维码自定义：可调整尺寸和边框参数
• 多种 URL 服务：支持 TinyURL 和 is.gd，并提供备用处理
• 骰子记法：支持带保留最大值逻辑的复杂骰子表达式

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

贡献

欢迎贡献！如需进行任何更改，请创建 issue 或提交 pull request。

致谢

本项目在 AI Makerspace MCP Session 中构建。原始框架由 AI-Maker-Space 提供。