MCP Server

🚀 OpenFacet MCP Server

OpenFacet MCP Server是為OpenFacet鑽石定價API實現的一個模型上下文協議（MCP）。它藉助插值算法和市場深度分析，提供透明、即時的鑽石定價數據。該項目僅使用原生JavaScript和核心模塊構建，零外部依賴。

](https://spec.modelcontextprotocol.io/) ](https://opensource.org/licenses/MIT) ](https://nodejs.org/)

✨ 主要特性

• 實現MCP 2025‑06‑18（不支持批量處理、結構化內容、版本頭）
• 提供工具：get_diamond_price、get_dcx_index、get_market_depth
• 支持基於克拉/顏色/淨度的即時插值
• 提供DCX指數和庫存快照，每日更新
• 單文件可部署，無依賴
• 運行時適配器：
  • Node.js：HTTP服務器、CORS、可配置端口
  • Cloudflare Worker：單fetch入口點

📦 安裝指南

本項目需要Node.js ≥18，可按以下步驟克隆倉庫：

git clone https://github.com/openfacet/mcp-server.git
cd mcp-server

💻 使用示例

基礎用法

本地標準輸入輸出傳輸

標準輸入輸出傳輸是大多數MCP客戶端的默認方式。

# 啟動服務器
node stdio.js

發送消息（粘貼以下JSON並按回車鍵）：

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_diamond_price","arguments":{"carat":1.23,"color":"G","clarity":"VS2"}}}

你將得到類似如下的響應：

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"💎 **鑽石價格報價**\n\n**規格：**\n• 克拉：1.23ct\n• 顏色：G\n• 淨度：VS2\n• 形狀：圓形\n\n**定價：**\n• 每克拉：$4,487\n• 總價：$5,519.01\n\n*價格來自OpenFacet.net API*"}],"_meta":{"timestamp":"2025-07-11T10:21:50.460Z","source":"OpenFacet.net API"}}}

本地Node.js HTTP服務器

默認綁定到localhost:3000/，可用的端點如下：

• POST /：JSON-RPC入口點
• GET /health：服務器狀態
• GET /.well-known/mcp.json：發現元數據

遠程MCP服務器

用於測試的遠程服務器地址為https://mcp.openfacet.net。以下是一個價格查詢示例：

curl -X POST https://mcp.openfacet.net/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_diamond_price",
      "arguments": {
        "carat": 1.23,
        "color": "G",
        "clarity": "VS2"
      }
    }
  }'

工具概要

get_diamond_price

返回圓形/墊形GIA鑽石的插值定價。 參數：

• carat：數字（0.3 - 6.0）
• color：字符串（D - M）
• clarity：字符串（FL - I3）
• shape：字符串（可選，默認值："round"）

get_dcx_index

返回鑽石價格趨勢的綜合指數，無參數。

get_market_depth

返回庫存數據，可選參數：

• carat：數字

📚 詳細文檔

項目結構

mcp-server/
├── core.js         # 共享邏輯、工具處理程序、插值
├── stdio.js        # 本地標準輸入輸出傳輸
├── node.js         # Node.js HTTP服務器（通過CLI或環境變量設置端口）
├── worker.js       # 遠程Cloudflare Worker
├── test-core.js    # 原生JS測試運行器
├── mcp-version.js  # 協議版本常量
└── README.md

測試

node test-core.js

測試覆蓋以下方面：

• 插值行為
• DCX/市場深度解析
• 錯誤處理
• JSON-RPC正確性

🔧 技術細節

插值

• 在固定斷點間進行對數空間插值
• 在心理閾值（0.3、0.5、1.0等）附近進行錨點平滑處理
• 如果價格趨勢超出某個區間，進行動態提升

規格說明

• API文檔：https://openfacet.net/en/api-docs/
  • /matrix.json和/matrix_cushion.json：基礎定價矩陣
  • /index.json：DCX指數和趨勢
  • /depth.json：按克拉/顏色/淨度劃分的市場深度
• 定價方法：https://openfacet.net/en/methodology/

📄 許可證

本項目採用MIT許可證，詳情請見https://opensource.org/licenses/MIT。