SouthAsia MCP Tool

這是一個基於 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/ 目錄
代碼品質：
- 添加適當的錯誤處理
- 保持代碼結構清晰
- 添加詳細的註釋
- 使用類型提示
測試：
- 確保新功能正常工作
- 測試錯誤處理
- 驗證與現有功能的兼容性

注意事項

所有更改都需要重啟服務器才能生效
確保在虛擬環境中進行開發
遵循現有的模組化結構
保持代碼風格一致

SouthAsia MCP Tool

Integrations

SouthAsia MCP Tool

工具名稱配置

分支說明

安裝說明

專案結構

開發新工具

Hello World 示例

開發建議

注意事項

相關文件

Tools