上周的涂鴉技術(shù)專家直播中，我們詳細演示了如何用涂鴉 MCPSDK，把家里普通的廚電設(shè)備，開發(fā)成懂天氣、懂推薦、懂你的 AI 美食管家，受到了很多開發(fā)者的歡迎，并反饋想要文字版的教程，方便跟著上手實操。今天，我們就整理了一版超詳細的手把手開發(fā)教程，從架構(gòu)解析、代碼實戰(zhàn)，到知識庫配置與智能體調(diào)試，流程完善、操作門檻低！大家也可以根據(jù)實際場景需求，大膽發(fā)揮想象，自定義開發(fā)其他更多樣、更個性化的MCP 服務(wù)。

本次，我們將從以下四個方面入手，幫助大家更好理解整個開發(fā)流程：

厘清 Cook MCP 服務(wù)的架構(gòu)設(shè)計

基于涂鴉 MCP SDK，掌握自定義 MCP 服務(wù)的進階能力

在涂鴉 AI 云開發(fā)者平臺，配置和調(diào)試 MCP 服務(wù)

了解智能體配置和實際使用效果

01
Cook MCP 架構(gòu)設(shè)計的特別之處

1、整體架構(gòu)圖

2、核心組件架構(gòu)的設(shè)計亮點

2.1 服務(wù)啟動器(源代碼路徑：`cook/__main__.py`)

依賴管理：自動協(xié)調(diào)服務(wù)啟動順序，解決依賴問題

健康檢查：實時監(jiān)管服務(wù)狀態(tài)，支持自動修復故障

彈性設(shè)計：網(wǎng)絡(luò)中斷可自動重連，指數(shù)退避算法

信號處理：支持優(yōu)雅關(guān)閉信號，并自動清理資源

2.2 FastMCP 服務(wù)

(`cook/recipe_mcp/recipe_mcp_server.py`)

支持雙協(xié)議：HTTP API + WebSocket，適應(yīng)不同客戶端

聲明式工具注冊：通過裝飾器快速添加功能，開發(fā)更便捷

類型安全：Pydantic 模型確保參數(shù)驗證

健康監(jiān)管：內(nèi)置狀態(tài)檢查和性能監(jiān)管

2.3 統(tǒng)一代理層(`cook/recipe_agent.py`)

數(shù)據(jù)代理：統(tǒng)一數(shù)據(jù)源訪問接口

LLM 代理：封裝智能推薦算法，支持多場景推薦、智能去重

緩存策略：多級緩存提升性能，減少網(wǎng)絡(luò)請求

配置管理：支持靈活的參數(shù)配置

2.4 集成涂鴉 MCP SDK(`src/mcp_sdk/`)

認證機制：安全的簽名驗證和訪問控制

連接管理：WebSocket 連接池和心跳檢測

消息路由：高效的消息分發(fā)和處理

恢復異常：網(wǎng)絡(luò)出現(xiàn)錯誤時可自動重連、恢復狀態(tài)

02
開發(fā)前期準備

1、開發(fā)需要哪些資源？

1.1 登錄涂鴉平臺賬號

注冊并登錄涂鴉 AI 云開發(fā)者平臺：https://platform.tuya.com/

1.2 獲取 LLMAPI 訪問權(quán)限

我們推薦使用通義千問，下方是對應(yīng)的大模型，調(diào)用大模型所需的 API 密鑰，需在阿里云平臺開通授權(quán)：

`qwen3-30b-a3b-instruct-2507`

1.3 開發(fā)環(huán)境

Python 3.10+ 環(huán)境，且支持訪問涂鴉和 LLM API 的網(wǎng)絡(luò)環(huán)境。

2、提前規(guī)劃你想要實現(xiàn)的功能

美食管家：支持豐富的菜譜推薦和膳食計劃

多場景推薦：支持每日/周、聚餐三種場景的菜譜推薦

智能去重：避免推薦相似菜品，確保菜譜多樣性

科學推薦：融合天氣、地點、人數(shù)、過敏原等因素

聯(lián)動智能廚電：支持聯(lián)動烤箱、電飯煲等電器

附近食材推薦：接入高德地圖，快速定位采購點

03
實戰(zhàn)開發(fā)：從代碼到部署

1. 什么是涂鴉 MCP SDK？

1.1 MCP SDK 架構(gòu)組成

1.2配置關(guān)鍵參數(shù)

```python# Tuya MCP SDK 配置MCPSdkConfig( endpoint="wss://your-tuya-endpoint.com", # 涂鴉平臺提供的 WebSocket 端點 access_id="your-access-id", # 涂鴉平臺分配的訪問 ID access_secret="your-access-secret", # 涂鴉平臺分配的訪問密鑰 heartbeat_interval=30, # 心跳間隔 reconnect_interval=5, # 重連間隔)# 自定義 MCP 服務(wù)配置MCPClientConfig( server_endpoint="http://localhost:9000/mcp",# 本地 MCP 服務(wù)端點 timeout=30 # 請求超時時間)```

2、創(chuàng)建自定義 MCP 服務(wù)的核心代碼

2.1 開發(fā)核心業(yè)務(wù)工具

```pythonfromfastmcpimportFastMCPfrompydanticimportFieldfromtypingimportAnnotatedclassRecipeMCPServer: def__init__(self, api_key:str=None, model:str="qwen-max"): self.app = FastMCP("Cook MCP Server") self.api_key = api_key self.model = model self._register_tools()
def_register_tools(self): """注冊自定義工具 - 這是核心部分"""
@self.app.tool asyncdefget_recipes_by_category( category: Annotated[str, Field(description="菜譜分類：水產(chǎn)、早餐、葷菜等")] ) ->str: """根據(jù)分類查詢菜譜""" # 實現(xiàn)具體業(yè)務(wù)邏輯 returnawaitself._query_recipes_by_category(category)```

2.2 集成涂鴉 MCP SDK

```pythonfrommcp_sdkimportcreate_mcpsdkasyncdefstart_cook_mcp_service(): """啟動完整的 Cook MCP 服務(wù)"""
# 1. 創(chuàng)建自定義 MCP 服務(wù) mcp_server = RecipeMCPServer( data_source=config.data_sourceor"url", api_key=config.api_key, model=config.model, base_url=config.base_url )
# 2. 啟動本地 MCP 服務(wù) server_task = asyncio.create_task( mcp_server.start_server(host="localhost", port=9000) )
# 3. 連接 Tuya MCP SDK asyncwithcreate_mcpsdk( endpoint="https://your-tuya-endpoint.com", access_id="your-access-id", access_secret="your-access-secret", custom_mcp_server_endpoint="http://localhost:9000/mcp" )assdk: awaitsdk.run()```

3、在涂鴉平臺創(chuàng)建和配置 MCP 服務(wù)

3.1 創(chuàng)建自定義 MCP 服務(wù)

3.1.1 登錄涂鴉 AI 云開發(fā)者平臺，進入【MCP 管理】界面，自定義MCP 服務(wù)。

3.1.2 完成上述操作后，點擊【添加自定義 MCP】，填寫下方信息：

服務(wù)名稱：美食管家

服務(wù)描述：基于 AI 的智能菜譜推薦和膳食計劃服務(wù)，支持根據(jù)天氣、位置、人數(shù)等因素提供個性化飲食建議

圖標：上傳美食相關(guān)圖標

3.2 配置數(shù)據(jù)中心+獲取認證信息

在【服務(wù)詳情】頁面，點擊【添加數(shù)據(jù)中心】

選擇合適的數(shù)據(jù)中心區(qū)域

復制下方配置信息：

``` 接入地址 (Endpoint)：https://xxx.tuya.com Access ID：tuyaxxxxxxxxxxxx Access Secret：xxxxxxxxxxxxxxxxxxxxxxxx ```

4、本地開發(fā)和測試

4.1 環(huán)境準備和代碼部署

```bash# 1. 克隆 Cook MCP 項目gitclonehttps://github.com/flyhawk1010/cook-mcp.gitcdcook-mcp# 2. 創(chuàng)建虛擬環(huán)境python -m venv .venvsource.venv/bin/activate # Linux/macOS# .venv\Scripts\activate # Windows# 3. 安裝依賴pip install -e .```

4.2 啟動服務(wù)并驗證

```bash# 啟動完整服務(wù)（MCP 服務(wù) + Tuya SDK）python -m cook all \ --endpoint$MCP_ENDPOINT\ --access-id$MCP_ACCESS_ID\ --access-secret$MCP_ACCESS_SECRET\ --custom-mcp-server-endpoint http://localhost:9000/mcp \ --api-key$API_KEY\ --model$MODEL\ --base-url$BASE_URL# 驗證服務(wù)狀態(tài)curl http://localhost:9000/healthcurl http://localhost:9000/recipes/status```

5、在涂鴉平臺調(diào)試 MCP 服務(wù)

5.1 檢查服務(wù)狀態(tài)

在涂鴉平臺選擇【MCP 管理】>【自定義 MCP 服務(wù)】

進入【服務(wù)詳情】頁面

在數(shù)據(jù)中心配置下，檢查服務(wù)狀態(tài)是否成功連接

5.2調(diào)試測試工具

5.2.1 點擊【工具】選項卡，查看自動發(fā)現(xiàn)的工具列表（這里為菜譜功能分類）：

5.2.2 選擇一個工具進行試運行

測試 1：按分類查詢

```json { "category": "水產(chǎn)" } ```

測試 2：智能推薦

```json { "location":"北京三里屯", "weather":"北京今日天氣為晴，最低溫度 15℃，最高溫度 25℃，空氣質(zhì)量優(yōu)", "categories":"葷菜,素菜", "people_count": 4, "taste_preferences":"清淡,營養(yǎng)" } ```

3.點擊【運行】，查看返回結(jié)果

4.確認左下角顯示【調(diào)試通過】

04
配置知識庫

1、創(chuàng)建知識庫

在配置智能體之前，我們需要為智能體添加知識庫，以提升智能體在特定領(lǐng)域的專業(yè)能力。

1.1 進入知識庫管理

在智能體配置頁面，找到【知識庫】選項

點擊【創(chuàng)建知識庫】，選擇【AI Agent 知識庫】

1.2 創(chuàng)建菜譜知識庫，并按照下方圖片配置相關(guān)信息。

2、添加知識庫內(nèi)容

2.1 手動添加菜譜知識

點擊【新增知識】，添加你想要的菜譜信息。

2.2 批量導入知識

如果手頭有大量的菜譜數(shù)據(jù)，可以點擊【導入】，并按照提示完成批量知識庫的上傳。

3、知識庫管理

在知識庫列表中，擁有已發(fā)布、草稿和未發(fā)布三種狀態(tài)

支持編輯和維護知識

支持搜索和篩選知識

4、智能體集成知識庫

在智能體配置中，可添加已完成設(shè)置的菜譜知識庫。

5、配置知識庫的注意事項

5.1 內(nèi)容格式

最好使用能統(tǒng)一格式的菜譜參數(shù)，如菜品名稱、烹飪溫度、烹飪時間等。

5.2 標簽分類

為不同類型的菜譜添加分類標簽，如早餐、葷菜、快手菜等。

5.3 設(shè)備兼容性

明確標注該系統(tǒng)適用的設(shè)備類型和品牌型號。

05
配置智能體+體驗最終效果

1、創(chuàng)建智能體

1.1 復制下方鏈接，進入【我的智能體】頁面，點擊【創(chuàng)建智能體】配置基本信息：

https://platform.tuya.com/exp/ai

2、配置智能體技能

2.1 添加官方技能

在【模型能力配置】>【技能配置】中添加：天氣技能、智能家居設(shè)備控制、高德地圖關(guān)鍵字搜索。

2.2 添加自定義 Cook MCP 服務(wù)

在【技能配置】中找到【MCP 服務(wù)】

選擇【自定義 MCP 服務(wù)】

找到并添加【美食管家】服務(wù)

確認下方所有工具都已啟用

3、智能體提示詞優(yōu)化

具體提示詞的話術(shù)，大家可從角色設(shè)定、背景、核心任務(wù)、規(guī)則和約束等方面，分別給智能體進行詳細的提示，可參考下方圖片：

4、實戰(zhàn)測試和調(diào)試效果

Q
推薦一些水產(chǎn)類的菜譜
智能體：[調(diào)用 get_recipes_by_category 工具]
Q
今天 4 個人吃晚餐，有什么推薦的？
智能體：[先調(diào)用天氣工具獲取天氣]，[再調(diào)用 recommend_recipes_for_dinner 工具]

5、正式發(fā)布和體驗

點擊【發(fā)布】并選擇發(fā)布范圍（僅自己、團隊或公開），AI 美食管家的開發(fā)就大功告成！你可以在手機端跟它對話，咨詢菜譜、規(guī)劃個性化的飲食建議、推薦附近好吃的餐館；也能聯(lián)動家里的蒸箱、烤箱或電飯煲，來個一站式的懶人版自制美食。

06
開發(fā)經(jīng)驗大總結(jié)

1、開發(fā)要點

采用微服務(wù)架構(gòu)，實現(xiàn)服務(wù)間松耦合與獨立擴展

工具描述盡量清晰，參數(shù)類型細分準確

考慮到所有可能出現(xiàn)的錯誤情況，并實現(xiàn)完善的異常處理和重試機制

使用緩存機制，避免重復計算

2、調(diào)試技巧

堅持本地優(yōu)先測試，逐步部署

啟用詳細日志，快速定位問題

采用漸進式功能擴展策略，先部署基礎(chǔ)功能，再逐步添加復雜功能

3、擴展建議

集成更多食譜和營養(yǎng)信息，豐富數(shù)據(jù)源

建立用戶偏好模型，實現(xiàn)更精準的菜譜推薦