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

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

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

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

在涂鴉 AI 云開(kāi)發(fā)者平臺(tái)，配置和調(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ù)啟動(dòng)器(源代碼路徑：`cook/__main__.py`)

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

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

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

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

2.2 FastMCP 服務(wù)

(`cook/recipe_mcp/recipe_mcp_server.py`)

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

聲明式工具注冊(cè)：通過(guò)裝飾器快速添加功能，開(kāi)發(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ù)源訪問(wèn)接口

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

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

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

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

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

連接管理：WebSocket 連接池和心跳檢測(cè)

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

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

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

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

1.1 登錄涂鴉平臺(tái)賬號(hào)

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

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

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

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

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

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

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

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

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

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

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

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

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

03
實(shí)戰(zhàn)開(kāi)發(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", # 涂鴉平臺(tái)提供的 WebSocket 端點(diǎn) access_id="your-access-id", # 涂鴉平臺(tái)分配的訪問(wèn) ID access_secret="your-access-secret", # 涂鴉平臺(tái)分配的訪問(wèn)密鑰 heartbeat_interval=30, # 心跳間隔 reconnect_interval=5, # 重連間隔)# 自定義 MCP 服務(wù)配置MCPClientConfig( server_endpoint="http://localhost:9000/mcp",# 本地 MCP 服務(wù)端點(diǎn) timeout=30 # 請(qǐng)求超時(shí)時(shí)間)```

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

2.1 開(kāi)發(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): """注冊(cè)自定義工具 - 這是核心部分"""
@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(): """啟動(dòng)完整的 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. 啟動(dòng)本地 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、在涂鴉平臺(tái)創(chuàng)建和配置 MCP 服務(wù)

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

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

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

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

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

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

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

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

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

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

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

4、本地開(kāi)發(fā)和測(cè)試

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 啟動(dòng)服務(wù)并驗(yàn)證

```bash# 啟動(dòng)完整服務(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、在涂鴉平臺(tái)調(diào)試 MCP 服務(wù)

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

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

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

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

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

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

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

測(cè)試 1：按分類查詢

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

測(cè)試 2：智能推薦

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

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

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

04
配置知識(shí)庫(kù)

1、創(chuàng)建知識(shí)庫(kù)

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

1.1 進(jìn)入知識(shí)庫(kù)管理

在智能體配置頁(yè)面，找到【知識(shí)庫(kù)】選項(xiàng)

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

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

2、添加知識(shí)庫(kù)內(nèi)容

2.1 手動(dòng)添加菜譜知識(shí)

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

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

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

3、知識(shí)庫(kù)管理

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

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

支持搜索和篩選知識(shí)

4、智能體集成知識(shí)庫(kù)

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

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

5.1 內(nèi)容格式

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

5.2 標(biāo)簽分類

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

5.3 設(shè)備兼容性

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

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

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

1.1 復(fù)制下方鏈接，進(jìn)入【我的智能體】頁(yè)面，點(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)測(cè)試和調(diào)試效果

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

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

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

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

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

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

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

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

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

2、調(diào)試技巧

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

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

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

3、擴(kuò)展建議

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

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