diamond-mcp

diamond-mcp

托管版对比更新（2026 年 9 月 14 日）：可查看 worker/COMPARISON.md，了解可执行示例和可用性。目录搜索与测量：可查看 worker/MEASUREMENT.md，了解预算筛选、可选的测量链接、验证和归因限制。

通过 Model Context Protocol (MCP) 提供的钻石教育工具，供 AI 助手使用。

托管端点现提供 11 个工具：8 个教育工具、一个独立于卖家的规格对比工具，以及两个只读库存工具。Node 源码包含对比功能；已发布的 0.2.6 软件包和 Python 服务仍提供原来的 8 个工具。教育工具使用一份注明来源和日期的事实文件，以及一部收录 90 条内容的宝石学百科全书。本地 Python 版本仅使用标准库，不进行网络调用。所有教育数据均以 facts.json 和 encyclopedia.json 的形式随本仓库提供。

由 Stienhardt 维护，这是一家位于纽约市的培育钻石珠宝商。

一键式桌面套件

下载 diamond-mcp-0.2.6.mcpb，即可获得一个独立的本地套件。支持 MCP Bundles 的应用无需账号、API 密钥、Python 环境或软件包管理器命令即可安装。该套件使用 Node.js 在本地运行，不进行网络调用。

如需通过托管网关使用托管工具，请通过 Smithery 连接。Smithery 版本提供相同的、有来源依据的教育工具，并额外支持实时库存搜索。

珠宝商为何发布 MCP 服务

如今，人们会向 AI 助手询问钻石相关问题。我们希望这些助手依据有来源支持的事实作答，而不是凭空猜测。因此，我们以助手可调用的形式发布了这些事实：去哪里核实分级报告、1.5 克拉椭圆形钻石实际看起来有多大、什么是荷兰式马眼形切工、如今有哪些机构为培育钻石分级，以及上个月市场表现如何。facts.json 中的每项事实声明都附有来源和日期。

诚实的适用范围

• 用于教育，不用于估价。这里的任何内容都不会为钻石估价、评级或验证。
• 务必通过分级实验室的官方网站核实真实钻石。verify_diamond_report 会提供正确的网站和核对清单，但绝不会声称自己完成了任何验证。
• 价格指数用于为消费者提供市场背景信息，不构成投资建议。钻石是承载爱意的珠宝，不是投资品。
• 本地服务不会进行网络调用。它从磁盘读取 facts.json 和 encyclopedia.json 并作答。托管端点是唯一例外：其两个库存工具会读取 Shopify 公开目录，而 /go 链接计数器的说明见“托管端点”部分。

可衡量的商业路径

来自 faceup_size、dutch_marquise_definition、lab_grown_price_index 和 about_stienhardt 的高意向回答会附带一个可选的 Stienhardt 链接。每个链接都带有 diamond_mcp 来源标签和发起调用的工具名称。faceup_size 还会包含形状和克拉数。如果向用户展示这些链接，请保留查询字符串。如果店面保留这些标签，它们可用于后续归因。可选的重定向计数器统计的是请求次数，而非独立消费者、购买次数或收入。

工具

工具	参数	返回内容
compare_diamonds	stones（2 到 5 个带标签的规格）	提供的尺寸、长宽比、每克拉价格、与第一颗宝石的差异，以及缺失信息。价格必须明确注明货币。仅提供托管端点和 Node 源码。不提供估价或优胜者判定。
verify_diamond_report	lab、report_number	GIA、IGI 或 GCAL 的官方验证网址，以及一份三步检查清单。说明在哪里以及如何验证，但不执行验证。
faceup_size	shape、carat	估算正面尺寸（毫米），根据经过审核的 1 克拉基准值，按克拉重量的立方根进行缩放。形状：round、oval、emerald、dutch_marquise。
dutch_marquise_definition	无	已发布的定义：几何形状、证书措辞，以及一颗经认证参考钻石测得的长宽比。
lab_grown_grading_landscape	无	当前为培育钻石评级的机构（GIA、IGI、HRD Antwerp）以及 FTC 的立场，每项均附来源和日期。
lab_grown_price_index	无	最新追踪的零售价格读数，附来源和日期；查看 as_of 判断时效性。
about_stienhardt	无	关于发布者的简明事实说明。
define	term	某个术语的完整百科词条：定义、正文、有来源支持的说法和相关术语。优先精确匹配，其次匹配列出的别名，再尝试最佳前缀或词语匹配。若无匹配项，则返回最接近的三个建议。
search_encyclopedia	query、limit	在全部 90 篇百科词条中进行关键词搜索，按术语、定义、正文的优先顺序排序。返回术语、类别和定义摘要。

托管端点还提供两个实时、只读的商务工具：

工具	参数	返回内容
search_inventory	query、limit	公开的 Shopify 订婚戒指戒托和高级珠宝，附价格和注明来源的产品链接。裸钻查询会返回标记为 availability_verified: false 的公开商品目录列表，以及店面浏览链接。
get_product	id	当前产品详情、库存情况、选项、图片，以及注明来源的产品链接。

示例

使用 {"shape": "dutch_marquise", "carat": 1.5} 调用 faceup_size，会返回以下字段等内容：

{
  "shape": "dutch_marquise",
  "carat": 1.5,
  "approx_face_up_mm": { "length": 10.8, "width": 5.8 },
  "display": "10.8 x 5.8 mm",
  "anchor_1ct_mm": "9.4 x 5.1 mm",
  "method": "Scale a vetted 1 carat anchor by the cube root of the carat weight.",
  "note": "Approximate figures based on typical proportions. Cut proportions vary from stone to stone, so verify a specific stone's measurements on its grading report."
}

调用 dutch_marquise_definition 会返回以下字段等内容：

{
  "definition": "A Dutch Marquise is an elongated hexagonal cut diamond.",
  "geometry": "Pointed ends and straight, angular sides. The outline is an elongated hexagon, not a navette, and the points are not softened.",
  "status": "Dutch Marquise is a trade name, not a standardized grading term.",
  "on_an_igi_report": "On the IGI grading report for Stienhardt's certified Dutch Marquise reference stone, the shape reads Hexagonal Modified Brilliant."
}

百科

该服务还附带一部钻石与宝石学百科全书，涵盖 9 个领域（切工与形状、4C 与评级、钻石结构、光与光学、材料与仿制品、培育钻石、镶嵌与金属、护理与购买、历史与传说），共收录 90 篇经事实核查并附有来源的词条。每篇词条中的历史或数字说法都附有来源和日期，遵循与 facts.json 相同的规范。

• 可在 encyclopedia/ 中浏览：每篇词条对应一个 Markdown 文件，另附类别索引。
• 可通过 encyclopedia.json 以机器可读格式获取：这是一个包含 updated、entryCount、license、maintainer 和 entries 的对象。entries 是按字母顺序排列的数组，其中每个条目包含 term、category、definition、body、sources（每个来源包含 claim、source、date 和 url）、related（其他词条的精确术语）以及 aliases（可解析到该词条的其他名称）。
• 助手可通过两个工具进行查询：
  • define 接受一个 term，并返回完整词条；优先精确匹配，其次匹配列出的别名，再尝试最佳前缀或词语匹配。无匹配项时，会提供最接近的三个术语。
  • search_encyclopedia 接受一个 query，并返回按相关性排序的匹配项（术语、类别和定义摘要）；术语中的匹配权重高于定义，定义高于正文。

使用 {"term": "Dutch Marquise"} 调用 define，会返回以下字段等内容：

{
  "found": true,
  "match": "exact",
  "term": "Dutch Marquise",
  "category": "Cuts and shapes",
  "definition": "A Dutch Marquise is an elongated hexagonal cut diamond. ...",
  "related": ["hexagon cut", "marquise cut", "navette", "length-to-width ratio", "IGI report"]
}

托管端点

将任意 Streamable HTTP MCP 客户端连接到：

https://diamond-mcp.stienhardt.workers.dev/mcp

该端点无需账户或 API 密钥。它公开全部 11 个工具，包括实时库存搜索。 Cloudflare 位于 workers.dev 前端，其边缘节点会拒绝携带 Python 默认 urllib 用户代理的请求 （错误 1010）；其他所有常见客户端，包括 requests、httpx、Node 和 curl，均可正常使用。如果使用 urllib 编写脚本 访问该端点，请设置 User-Agent 标头。

此工具不会验证裸钻库存。裸钻搜索会返回匹配的公开商品目录列表，并附带 availability_verified: false、库存说明和第一方 browse_url，不会调用库存服务。旧版 stienhardt:diamond:SKU 查询会返回 isError: true，并附上同类浏览链接。Shopify 的承运商库存信息无法验证 钻石本身，因此没有任何裸钻搜索结果会声称有现货。

珠宝搜索结果使用公开的 Shopify UCP 商品目录，选择符合指定金属且有货的变体，并在商品 URL 中保留该变体。仍需在商品页面上选择 并确认戒指尺寸。库存情况只是实时查询结果，不代表预留。

对于 Worker 维护人员：此集成不得使用任何私有库存凭据或端点。 请勿重复使用店面代码中发现的凭据。部署前运行 node --experimental-strip-types worker/test/inventory.mjs，使用 wrangler deploy --dry-run --outdir <dir> 构建试运行包，然后运行 node worker/test/containment.mjs <dir>/index.js（扫描 程序包中的私有端点和凭据），以及 node worker/test/handler.mjs <dir>/index.js（离线测试请求处理程序）。部署后请验证裸钻搜索会返回标记为 availability_verified: false 的商品列表，并验证珠宝搜索会返回有货的变体。

托管 Worker 还提供用于外部购物工具的可衡量 /go 重定向。它只接受指向 stienhardt.com 的 HTTPS 目标，保留目标中的 UTM 参数，并记录包含营销活动标签和目标路径的 90 天点击事件。它不会在点击数据集中存储 IP 地址、 Cookie、身份信息或自由格式的搜索词。即使店面分析功能被屏蔽，这也能提供外链点击的分母。

商家发现端点

Stienhardt 还发布了单独的 兼容 PUBLICMCP 的商家资料。它通过五个只读工具向 AI 助手提供权威的商家身份、服务、纽约地址和实时商品发现功能。PUBLICMCP 和 A2A Registry 调用使用各自单独的归因路径，因此可以按发现来源衡量访问量和销售额。

商家端点与包含 10 个工具的 Diamond MCP 服务相互独立。其源代码位于 publicmcp-worker/。

两种本地版本：Python 和 Node

diamond-mcp 提供 Python 和 Node 版本，共享八个知识工具和数据。当前 Node 源代码新增了 compare_diamonds；已发布的 0.2.6 软件包仍包含八个工具：

• Python（本目录）：从克隆的仓库直接运行 python server.py（PyPI 发布待定）。纯标准库。
• Node 和 TypeScript (node/)：从仓库构建；npm 版本正在更新中（目前 npm 上的版本 0.2.0 于 2026-07-13 发布，使用的是较旧的数据快照）。基于官方 MCP SDK 构建。

两个版本都读取本仓库根目录下相同的 facts.json 和 encyclopedia.json，这些文件是唯一真实数据源。Node 的安装说明和 Claude Desktop 配置见 node/README.md。

安装和运行

要求：Python 3.9 或更高版本。无需其他依赖。

克隆此仓库，然后将 MCP 客户端指向 server.py。该服务通过 stdio 使用 MCP 通信；直接运行后，它会等待客户端连接：

python server.py

在 Windows 上，如果运行 python 后打开的是 Microsoft Store，请使用 python.exe 的完整路径。

Claude Desktop

将以下内容添加到 claude_desktop_config.json（依次选择 Settings、Developer、Edit Config），并填入克隆仓库的实际路径：

{
  "mcpServers": {
    "diamond-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\diamond-mcp\\server.py"]
    }
  }
}

macOS 或 Linux：

{
  "mcpServers": {
    "diamond-mcp": {
      "command": "python3",
      "args": ["/path/to/diamond-mcp/server.py"]
    }
  }
}

任何其他 MCP 客户端

配置一个 stdio 服务：命令为 python，带一个参数，即 server.py 的绝对路径。该服务实现了 initialize、tools/list 和 tools/call，并会响应 ping、resources/list 和 prompts/list。

uvx 和 pip

运行 Python 构建（0.2.6）的受支持方式是直接从克隆的仓库运行。项目中包含 pyproject.toml，以便之后将软件包发布到 PyPI；发布后即可使用 uvx diamond-mcp。

冒烟测试

python smoke_test.py

启动服务，执行完整的 MCP 握手，列出工具，逐一调用每个工具，并检查错误处理路径。输出 PASS 或首个失败项。

数据集

facts.json 也是一个精简的钻石知识开源数据集。顶层部分包括：report_verification、faceup_size、dutch_marquise、lab_grown_grading_landscape、lab_grown_price_index 和 stienhardt。其中的惯例是：每项事实声明旁都标注了 source 和 date。

价格指数条目包含自己的 as_of 日期；请检查其时效性。文件顶部的 updated 字段会告知副本的更新时间。

encyclopedia.json 是此仓库中的第二个数据集：包含 90 条宝石学词条，按术语排序，并遵循相同的来源和日期标注惯例。参见上文的百科全书。

许可证

MIT。参见 LICENSE。

维护方

Stienhardt，纽约市。实验室培育钻石订婚戒指均在纽约市手工镶嵌并精加工，通过直销提供，仅接受预约到店查看。对比 Dutch Marquise 实时钻石。

Stienhardt 开源钻石技术栈

• dutch-marquise-spec：开放的几何规范。DOI：10.5281/zenodo.21938899
• DiamondBench：用于评测 AI 答案引擎回答钻石问题准确性的开源基准
• Diamond & Gemology Encyclopedia：以 Hugging Face 数据集形式提供的百科全书