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. 安裝步驟```bash
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 工具
1. **找到 Cursor 設定檔**:
* 通常位於使用者家目錄下的 `.cursor` 資料夾中。
* Windows: `%USERPROFILE%\.cursor\mcp.json`
* macOS/Linux: `~/.cursor/mcp.json`
2. **編輯 `mcp.json`**:
* 如果檔案不存在,請建立它。
* 加入以下內容 (如果已有其他工具,請確保 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 可能需要不同的參數。
3. 重啟 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。
📄 授權條款
本專案採用 MIT 授權條款。
