README - SouthAsia by igs-pochenkuo

SouthAsia MCP 工具

歡迎使用 SouthAsia MCP 工具專案！這是一個基於 MCP (Model Control Protocol)-like 框架的工具集，旨在擴充 AI 助理（例如 Cursor）的功能，使其能夠執行更複雜、更貼近本地開發環境的任務。

這個儲存庫可以作為您開發自訂 MCP 工具的模板和起點。

✨ 功能特色

目前包含以下範例工具 (在 hello_world handler 中)：

mcp_hello_world: 一個簡單的工具，返回固定的問候語。
mcp_hello_name: 接收一個 name 參數，並返回包含該名字的問候語。

您可以輕易地擴充此專案，加入更多實用的工具！

🚀 開始使用

1. 環境準備

Git: 用於克隆儲存庫。
Python: 版本需 >= 3.10。
(推薦) uv: 一個快速的 Python 套件安裝與管理工具 (安裝指南)。如果沒有 uv，也可以使用 Python 內建的 venv 和 pip。

2. 安裝步驟

# 1. 克隆儲存庫
git clone <您的儲存庫 URL>
cd southAsia_Tool # 進入專案目錄

# 2. 建立並啟用虛擬環境
# 使用 uv (推薦)
uv venv
source .venv/bin/activate  # Linux/macOS
# 或者 .\.venv\Scripts\Activate.ps1  # Windows PowerShell
# 或者 .\.venv\Scripts\activate.bat # Windows Cmd

# 使用 Python 內建 venv
# python -m venv .venv
# source .venv/bin/activate  # Linux/macOS
# 或者 .\.venv\Scripts\Activate.ps1  # Windows PowerShell
# 或者 .\.venv\Scripts\activate.bat # Windows Cmd

# 3. 安裝依賴
# 使用 uv (推薦)
uv pip sync pyproject.toml

# 4. 使用 pip 編譯工具
pip install -e .

3. 設定 Cursor MCP 工具

找到 Cursor 設定檔:
- 通常位於使用者家目錄下的 .cursor 資料夾中。
- Windows: %USERPROFILE%\.cursor\mcp.json
- macOS/Linux: ~/.cursor/mcp.json
編輯 mcp.json:
- 如果檔案不存在，請建立它。
- 加入以下內容 (如果已有其他工具，請確保 JSON 格式正確)：
```
{
  "southAsia": {
    "command": "cmd", // 或 "bash", "zsh" 等，依您的系統
    "args": [
      "/c", // Windows cmd 的參數，bash/zsh 通常不需要
      "southasia" // 對應 pyproject.toml 中定義的命令名稱
    ]
  }
}
```
- 重要:
  - "southAsia": 這是你在 Cursor 中 @ 後面輸入的工具名稱，必須與 server.py 中的 MCP_TOOL_NAME (或您修改後的名稱) 大小寫一致。
  - "southasia": 這是您在步驟 2 安裝後可在終端運行的命令，對應 pyproject.toml 中 [project.scripts] 的設定 (建議小寫)。
  - command 和 args: 請根據您的作業系統和 Shell 調整。Windows PowerShell 可能需要不同的參數。
重啟 Cursor: 關閉並重新開啟 Cursor 以載入新的 MCP 工具設定。

4. 測試安裝

在 Cursor 的聊天視窗中輸入：

@southAsia mcp_hello_world

如果看到類似 "Hello World! 這是您的第一個 SouthAsia 工具！" 的回應，表示安裝和設定成功！

您也可以測試帶參數的工具：

@southAsia mcp_hello_name name="工程師"

🔧 使用方法

在 Cursor 中，您可以透過 @<工具集名稱> (預設是 @southAsia) 來呼叫此 MCP 工具提供的功能。

基本語法: @<工具集名稱> <工具名稱> [參數]
範例:
- @southAsia mcp_hello_world
- @southAsia mcp_hello_name name="您的名字"

當您加入更多工具後，可以用同樣的方式呼叫它們。

💻 開發新工具

想要擴充這個工具集嗎？

主要結構:
- src/southasia/handlers/: 存放工具處理邏輯的 Python 檔案。每個檔案可以包含一組相關的工具。
- src/southasia/server.py: MCP 伺服器的主要設定檔，您需要在此處註冊新的 Handler。
開發指南:
- 我們為您準備了詳細的開發指南！在 Cursor 中，當您編輯 src/southasia/handlers/ 目錄下的 Python 檔案時，會自動載入 @100-Lang-PythonMCPHandlerGuide.mdc 規則，其中包含了建立新工具的步驟和建議。
- 您也可以直接在 Cursor 中 @100-Lang-PythonMCPHandlerGuide.mdc 來查閱。
基本步驟:
- 在 handlers 目錄下建立新的 .py 檔案 (例如 my_tools.py)。
- 在檔案中實作 handle_list_tools (定義工具) 和 handle_call_tool (處理呼叫) 函數。
- 在 server.py 中導入您的 Handler 並將其加入 HANDLERS 列表。

✏️ 重新命名專案

如果您不想使用 "southAsia" 這個名稱，可以將整個專案重新命名。這是一個比較進階的操作，涉及修改多個檔案和設定。

詳細步驟請參考專案內的 MDC 規則：在 Cursor 中 @010-Core-ProjectRenamingGuide.mdc。

❓ 故障排除提示

如果在安裝、設定或使用過程中遇到問題，可以嘗試以下步驟：

確認虛擬環境: 確保你已經在專案的虛擬環境中執行安裝和運行命令。
檢查 Cursor 設定 (mcp.json):
- 仔細核對工具集名稱 (例如 "southAsia") 是否與 server.py 中的 MCP_TOOL_NAME 大小寫完全一致。
- 確認 args 中的命令行工具名稱 (例如 "southasia") 是否與 pyproject.toml 中 [project.scripts] 定義的大小寫完全一致。
- 檢查 command 和 args 是否適合你的作業系統和 Shell 環境。
手動運行服務器: 在已啟用虛擬環境的終端中，直接運行 southasia (或你修改後的命令)。觀察是否有任何錯誤訊息或日誌輸出。這有助於判斷 MCP 服務本身是否能正常啟動。
檢查 Cursor 輸出: 查看 Cursor 的「輸出」(Output) 面板，有時 MCP 相關的錯誤會顯示在那裡。
重啟 Cursor: 在修改 mcp.json 或重新安裝後，重啟 Cursor。