Diy Helper MCP Servers

🚀 DIY Helper MCP 服務器

DIY Helper 平臺的模型上下文協議（MCP）服務器。提供建築規範查詢、材料規格信息以及製造商指南訪問功能，以支持即時諮詢服務。

🚀 快速開始

安裝

前提條件

• Python 3.8 及以上版本
• pip

安裝步驟

1. 克隆倉庫：

git clone https://github.com/yourusername/diy-helper-mcp-servers.git
cd diy-helper-mcp-servers

2. 創建虛擬環境：

python -m venv venv
source venv/bin/activate  # 在 Windows 系統上使用：venv\Scripts\activate

3. 安裝依賴：

pip install -r requirements.txt

4. 配置環境：

cp .env.example .env
# 編輯 .env 文件並添加你的 API 密鑰

運行服務器

運行建築規範服務器

python src/building_codes_server/server.py

在 Claude Desktop 中使用

在你的 Claude Desktop 配置文件（claude_desktop_config.json）中添加以下內容：

{
  "mcpServers": {
    "building-codes": {
      "command": "python",
      "args": ["/path/to/diy-helper-mcp-servers/src/building_codes_server/server.py"],
      "env": {
        "CODE_DATABASE_PATH": "/path/to/codes.json"
      }
    }
  }
}

編程式使用

from anthropic import Anthropic
from mcp import ClientSession, StdioServerParameters

# 初始化 MCP 客戶端
server_params = StdioServerParameters(
    command="python",
    args=["src/building_codes_server/server.py"]
)

async with ClientSession(server_params) as session:
    # 初始化連接
    await session.initialize()
    
    # 列出可用工具
    tools = await session.list_tools()
    
    # 調用工具
    result = await session.call_tool(
        "search_building_codes",
        {"query": "客廳插座間距要求", "jurisdiction": "國家層面"}
    )
    print(result)

✨ 主要特性

服務器功能

建築規範服務器

提供住宅建築規範查詢服務，包括：

• NEC（國家電氣規範）
• IRC（國際住宅規範）
• IPC（國際給排水規範）

工具：

• search_building_codes - 自然語言規範搜索
• get_code_section - 獲取特定規範章節
• check_code_compliance - 驗證場景合規性
• list_code_categories - 瀏覽可用規範

材料規格服務器

提供即時材料搜索、定價和數量計算功能。

工具：

• search_materials - 在不同供應商中搜索產品
• get_product_details - 獲取產品詳細規格
• find_alternatives - 查找不同價格區間的類似產品
• check_compatibility - 驗證產品兼容性
• calculate_wire_needed - 計算所需電線數量
• calculate_outlets_needed - 根據 NEC 計算插座需求
• calculate_tile_needed - 計算所需瓷磚數量
• calculate_paint_needed - 計算所需塗料量
• calculate_deck_lumber - 計算甲板框架材料
• calculate_pex_pipe - 計算給排水管道需求
• create_shopping_list - 生成完整購物清單

運行命令：

python src/material_specs_server/server.py

📦 安裝指南

前提條件

• Python 3.8+
• pip

安裝步驟

1. 克隆倉庫：

git clone https://github.com/yourusername/diy-helper-mcp-servers.git
cd diy-helper-mcp-servers

2. 創建虛擬環境：

python -m venv venv
source venv/bin/activate  # 在 Windows 系統上使用：venv\Scripts\activate

3. 安裝依賴：

pip install -r requirements.txt

4. 配置環境：

cp .env.example .env
# 編輯 .env 文件並添加你的 API 密鑰

💻 使用示例

基礎用法

運行建築規範服務器

python src/building_codes_server/server.py

運行材料規格服務器

python src/material_specs_server/server.py

高級用法

在 Claude Desktop 中使用

在 claude_desktop_config.json 中配置：

{
  "mcpServers": {
    "building-codes": {
      "command": "python",
      "args": ["/path/to/diy-helper-mcp-servers/src/building_codes_server/server.py"],
      "env": {
        "CODE_DATABASE_PATH": "/path/to/codes.json"
      }
    }
  }
}

編程式使用

from anthropic import Anthropic
from mcp import ClientSession, StdioServerParameters

# 初始化 MCP 客戶端
server_params = StdioServerParameters(
    command="python",
    args=["src/building_codes_server/server.py"]
)

async with ClientSession(server_params) as session:
    # 初始化連接
    await session.initialize()
    
    # 列出可用工具
    tools = await session.list_tools()
    
    # 調用工具
    result = await session.call_tool(
        "search_building_codes",
        {"query": "廚房插座間距要求", "jurisdiction": "國家層面"}
    )
    print(result)

📚 詳細文檔

開發相關

添加新規範

編輯 src/building_codes_server/codes.json 文件：

{
  "id": "唯一標識符",
  "code_ref": "規範章節",
  "title": "規範標題",
  "category": "電氣|給排水|結構|機械|通用",
  "jurisdiction": "國家|州|城市",
  "summary": "通俗易懂的摘要",
  "source": "官方來源引用",
  "common_questions": ["問題 1", "問題 2"],
  "notes": "額外說明",
  "related_codes": ["相關規範 1", "相關規範 2"]
}

運行測試

運行所有測試

# 運行所有測試
./run_all_tests.sh

# 或者單獨運行：
python tests/test_building_codes.py
python tests/test_material_server.py

測試覆蓋率

建築規範服務器：

• ✓ 規範搜索功能
• ✓ 特定章節檢索
• ✓ 類別列表
• ✓ 常見 DIY 問題
• ✓ 管轄範圍過濾
• ✓ 邊緣情況處理

材料規格服務器：

• ✓ 產品搜索
• ✓ 產品詳情
• ✓ 材料計算器（7 種類型）
• ✓ 替代產品
• ✓ 兼容性檢查
• ✓ 購物清單生成

快速測試

# 直接測試建築規範服務器
python src/building_codes_server/server.py

# 直接測試材料規格服務器
python src/material_specs_server/server.py

網頁測試界面

對於 Linux 系統用戶或未使用 Claude Desktop 的用戶，可以使用網頁界面進行測試：

前提條件

# 安裝 Flask
pip install flask

# 設置你的 Anthropic API 密鑰
export ANTHROPIC_API_KEY='你的 API 密鑰'

運行網頁界面

python test_web_interface.py

然後在瀏覽器中打開：http://localhost:5000

功能特性

• 與 Claude 和 MCP 工具進行交互式聊天
• 即時建築規範查詢
• 材料搜索和定價
• 項目計算器
• 完整對話歷史記錄
• 提供示例查詢以幫助上手

示例查詢

在網頁界面中嘗試以下查詢：

• "廚房插座間距要求是多少？"
• "搜索 12 號電線並顯示價格"
• "計算 40 英尺電路所需的電線數量"
• "我要在距離配電盤 30 英尺處安裝洗碗機，需要什麼材料？"

🚧 路線圖

• [ ] 集成向量搜索（Pinecone/pgvector）
• [ ] 完善材料規格服務器
• [ ] 開發製造商指南服務器
• [ ] 支持轄區規範修訂
• [ ] 實現圖像分析以檢查規範合規性
• [ ] 開發成本估算工具

🤝 貢獻指南

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 提交拉取請求

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🛠️ 支持與反饋

• 文檔：docs/setup.md
• 問題反饋：https://github.com/yourusername/diy-helper-mcp-servers/issues
• 郵箱：support@yourplatform.com