SouthAsia MCP Tool

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

工具名称配置

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

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

MCP_TOOL_NAME = "southAsia"  # 更改此處以修改工具名稱

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

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

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

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

注意：

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

分支说明

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

安装说明

1. 创建并激活虚拟环境：

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

1. 安装开发版本：

pip install -e .

1. 在Cursor中配置MCP工具：
   • 打开Cursor的设置文件：%USERPROFILE%\.cursor\mcp.json
   • 添加以下配置：

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

• 重启Cursor使配置生效

1. 运行服务器(测试)：

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

# 方法 2：直接運行模組
python -m southasia.server

1. 测试安装：
   • 在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 了解如何开发新的工具。基本步骤如下：

1. 在 handlers 目录下创建新的处理器文件
2. 实现工具的处理逻辑
3. 在 handle_list_tools() 中注册工具
4. 在 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}")

这个示例展示了：

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

开发建议

1. 遵循模块化结构：

   • 工具处理器放在 handlers/ 目录
   • 如需要，可以添加模型到 models/ 目录
   • 如需要，可以添加服务到 services/ 目录

2. 代码质量：

   • 添加适当的错误处理
   • 保持代码结构清晰
   • 添加详细的注释
   • 使用类型提示

3. 测试：

   • 确保新功能正常工作
   • 测试错误处理
   • 验证与现有功能的兼容性

注意事项

1. 所有更改都需要重启服务器才能生效
2. 确保在虚拟环境中进行开发
3. 遵循现有的模块化结构
4. 保持代码风格一致

相关文件

• Tool_GUIDE.md: 详细的工具开发指南
• src/southasia/handlers/hello_world.py: 示例工具实现
• src/southasia/server.py: 服务器配置和工具注册