MCP 服务器

SouthAsia MCP Tool

一个基于模型控制协议 (MCP) 框架构建工具的模板，提供了一种结构化的方法来开发自定义工具并将其与 Cursor 集成。 (Alternative, slightly more formal translation): 一个用于构建基于模型控制协议 (MCP) 框架的工具的模板，它提供了一种结构化的方式来开发自定义工具并将其集成到 Cursor 中。

Tools

hello_world

A simple demonstration tool that returns a greeting message

hello_name

A demonstration tool that greets you by name

README

SouthAsia MCP 工具

这是一个基于 MCP (Model Control Protocol) 框架的工具开发模板。

工具名称配置

如果您想要更改工具名称（默认为 "southAsia"），需要修改以下位置：

src/southasia/server.py 中的常量配置：

MCP_TOOL_NAME = "southAsia"  # 更改此处以修改工具名称

pyproject.toml 中的命令行工具名称（使用小写）：

[project.scripts]
southasia = "southasia.server:main"  # 更改 "southasia" 为您想要的名称

Cursor 配置文件中的工具名称：

{
  "southAsia": {  // 更改此处为您的工具名称
    "command": "cmd",
    "args": [
      "/c",
      "southasia"  // 更改此处为您的命令行工具名称
    ]
  }
}

注意：

工具名称区分大小写
命令行工具名称建议使用小写
修改后需要重新安装套件并重启 Cursor

分支说明

main: 主分支，包含完整的笔记管理工具实现
empty: 空白分支，仅包含基本框架和 Hello World 示例工具，适合开始新工具开发

安装说明

创建并激活虚拟环境：

# 在 southAsia 目录下
python -m venv .venv
.\.venv\Scripts\Activate.ps1

安装开发版本：

pip install -e .

在 Cursor 中配置 MCP 工具：
- 打开 Cursor 的设定档案：%USERPROFILE%\.cursor\mcp.json
- 添加以下配置：

{
  "southAsia": {
    "command": "cmd",
    "args": [
      "/c",
      "southasia"
    ]
  }
}

重启 Cursor 使配置生效

运行服务器(测试)：

# 方法 1：使用安装的命令
southasia

# 方法 2：直接运行模块
python -m southasia.server

测试安装：
- 在 Cursor 中输入指令：@southAsia hello_world
- 如果看到问候讯息，表示安装成功

专案结构

src/southasia/
├── __init__.py          # 入口点
├── server.py            # 服务器配置
├── handlers/            # 请求处理
│   ├── __init__.py
│   └── hello_world.py   # Hello World 示例工具
├── models/              # 资料模型（可选）
│   └── __init__.py
└── services/           # 业务逻辑（可选）
    └── __init__.py

开发新工具

请参考 Tool_GUIDE.md 了解如何开发新的工具。基本步骤如下：

在 handlers 目录下创建新的处理器文件
实现工具的处理逻辑
在 handle_list_tools() 中注册工具
在 server.py 中导入和注册处理器

Hello World 示例

hello_world.py 提供了一个简单的示例工具实现：

from typing import Dict, Any
from mcp.server.models import types

# 工具列表
def handle_list_tools() -> list[types.Tool]:
    """返回可用工具列表"""
    return [
        types.Tool(
            name="mcp_southAsia_hello_world",
            description="A simple demonstration tool that returns a greeting message",
            inputSchema={
                "type": "object",
                "properties": {
                    "random_string": {
                        "type": "string",
                        "description": "Dummy parameter for no-parameter tools"
                    }
                },
                "required": ["random_string"],
            },
        ),
        # 可以在这里添加更多工具...
    ]

async def handle_call_tool(tool_name: str, params: Dict[str, Any]) -> Dict[str, Any]:
    """处理工具调用"""
    if tool_name == "mcp_southAsia_hello_world":
        return {
            "message": "Hello World! 这是您的第一个 SouthAsia 工具！"
        }
    
    raise ValueError(f"未知的工具：{tool_name}")

这个示例展示了：

如何定义工具列表（handle_list_tools）
如何处理工具调用（handle_call_tool）
如何进行参数验证和错误处理

开发建议

遵循模块化结构：
- 工具处理器放在 handlers/ 目录
- 如需要，可以添加模型到 models/ 目录
- 如需要，可以添加服务到 services/ 目录
代码品质：
- 添加适当的错误处理
- 保持代码结构清晰
- 添加详细的注释
- 使用类型提示
测试：
- 确保新功能正常工作
- 测试错误处理
- 验证与现有功能的兼容性