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

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

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

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

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

了解智能體配置和實(shí)際使用效果

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

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

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

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

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

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

彈性設(shè)計(jì)：網(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ù)驗(yàn)證

健康監(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/`)

認(rèn)證機(jī)制：安全的簽名驗(yàn)證和訪問控制

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

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

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

02
開發(fā)前期準(zhǔn)備

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ī)劃你想要實(shí)現(xiàn)的功能

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

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

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

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

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

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

03
實(shí)戰(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 端點(diǎn) 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ù)端點(diǎn) timeout=30 # 請求超時(shí)時(shí)間)```

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ù)分類查詢菜譜""" # 實(shí)現(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ā)者平臺，進(jìn)入【MCP 管理】界面，自定義MCP 服務(wù)。

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

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

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

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

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

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

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

復(fù)制下方配置信息：

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

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

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

```bash# 1. 克隆 Cook MCP 項(xiàng)目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ù)并驗(yàn)證

```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# 驗(yàn)證服務(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ù)】

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

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

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

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

5.2.2 選擇一個工具進(jìn)行試運(yùn)行

測試 1：按分類查詢

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

測試 2：智能推薦

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

3.點(diǎn)擊【運(yùn)行】，查看返回結(jié)果

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

04
配置知識庫

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

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

1.1 進(jìn)入知識庫管理

在智能體配置頁面，找到【知識庫】選項(xiàng)

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

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

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

2.1 手動添加菜譜知識

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

2.2 批量導(dǎo)入知識

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

3、知識庫管理

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

支持編輯和維護(hù)知識

支持搜索和篩選知識

4、智能體集成知識庫

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

5、配置知識庫的注意事項(xiàng)

5.1 內(nèi)容格式

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

5.2 標(biāo)簽分類

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

5.3 設(shè)備兼容性

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

05
配置智能體+體驗(yàn)最終效果

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

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

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

2、配置智能體技能

2.1 添加官方技能

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

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

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

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

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

確認(rèn)下方所有工具都已啟用

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

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

4、實(shí)戰(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ā)布和體驗(yàn)

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

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

1、開發(fā)要點(diǎn)

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

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

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

使用緩存機(jī)制，避免重復(fù)計(jì)算

2、調(diào)試技巧

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

啟用詳細(xì)日志，快速定位問題

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

3、擴(kuò)展建議

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

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