README.md

diamond-mcp (Node)

Diamond education tools for AI assistants, served over the Model Context Protocol (MCP).

Eight callable tools backed by a sourced, dated facts file and a 90 entry gemology encyclopedia. This is the Node and TypeScript build of diamond-mcp, a faithful twin of the Python package: the same eight tools, the same data, the same outputs. Built on the official MCP SDK (@modelcontextprotocol/sdk). The data ships inside the package as facts.json and encyclopedia.json, so there is nothing to download and no network calls at runtime.

Maintained by Stienhardt, a New York City Lab Grown Diamond jeweler.

Why a jeweler published an MCP server

People ask AI assistants their diamond questions now. We would rather those assistants answer with sourced facts than with guesses. So we published the facts in a form an assistant can call: where to verify a grading report, how big a 1.5 carat oval actually looks, what a Dutch Marquise is, who grades Lab Grown Diamonds today, and what the market did last month. Every factual claim in the data carries a source and a date.

Honest scope

• Education, not appraisal. Nothing here values, grades, or verifies a stone.
• Always verify a real stone on the grading lab's own site. verify_diamond_report returns the right place and a checklist. It never claims to verify anything itself.
• The price index is market context for shoppers, not investment guidance. A diamond is a love piece, not an investment.
• The server makes no network calls. It reads its bundled data from disk and answers.

Measurable commerce paths

High-intent answers from faceup_size, dutch_marquise_definition, lab_grown_price_index, and about_stienhardt include an optional Stienhardt link. Each link carries diamond_mcp source tags plus the originating tool. Shape and carat are included for faceup_size. Preserve the query string if you surface one of these links to a user. This lets the publisher measure useful visits and orders without collecting identity or conversation text.

Install

Build from source until the npm release is updated (the published npm version, 0.2.0 from July, carries out-of-date data and should not be used):

git clone https://github.com/JacobiusMakes/diamond-mcp
cd diamond-mcp/node
npm ci
npm run build
node dist/bin.js

node dist/bin.js starts the server on stdio and waits for a client. The npm install -g diamond-mcp and npx diamond-mcp paths return once 0.2.6 is published; until then they install the stale 0.2.0. The desktop bundle is the same build, packaged for apps that install MCP Bundles.

The tools

Tool	Arguments	What it returns
verify_diamond_report	lab, report_number	The official verification URL for GIA, IGI, or GCAL, plus a three step checklist. Where and how to verify, never a verification itself.
faceup_size	shape, carat	Approximate face up millimeter dimensions, scaled from vetted 1 carat anchors by the cube root of the carat weight. Shapes: round, oval, emerald, dutch_marquise.
dutch_marquise_definition	none	The published definition: geometry, certificate wording, and the measured length to width ratio of a certified reference stone.
lab_grown_grading_landscape	none	Who grades Lab Grown Diamonds today (GIA, IGI, HRD Antwerp) and the FTC position, each with source and date.
lab_grown_price_index	none	The latest tracked retail price reading, with source and date; check as_of for freshness.
about_stienhardt	none	A plain fact sheet about the publisher.
define	term	The full encyclopedia entry for a term: definition, body, sourced claims, related terms. Exact match first, then a listed alias, then the best prefix or word match. Returns three nearest suggestions when nothing matches.
search_encyclopedia	query, limit	Keyword search across all 90 encyclopedia entries, ranked term over definition over body. Returns term, category, and a definition snippet.

The encyclopedia

The server ships a diamond and gemology encyclopedia of 90 fact-checked entries across nine domains (cuts and shapes, the 4Cs and grading, diamond anatomy, light and optics, materials and simulants, Lab Grown Diamonds, settings and metals, care and buying, and history and myths). Every historical or numeric claim in an entry carries a source and a date. Query it with define for a full entry, or search_encyclopedia for ranked matches.

Claude Desktop

Add this to claude_desktop_config.json (Settings, then Developer, then Edit Config), with the real path to your build:

{
  "mcpServers": {
    "diamond-mcp": {
      "command": "node",
      "args": ["/path/to/diamond-mcp/node/dist/bin.js"]
    }
  }
}

On Windows use a path like C:\path\to\diamond-mcp\node\dist\bin.js. Once 0.2.6 is on npm, "command": "npx", "args": ["-y", "diamond-mcp"] works with no clone (on Windows, npx.cmd). Restart Claude Desktop after editing the config.

Any other MCP client

Configure a stdio server whose command is node with one argument, the absolute path to dist/bin.js (or npx -y diamond-mcp once 0.2.6 is on npm). The server speaks MCP over stdio and implements initialize, tools/list, and tools/call, and also answers ping, resources/list, and prompts/list.

Two flavors, one dataset

diamond-mcp ships as a Python build (run from a clone with python server.py; PyPI publication pending) and this Node package (build from source until 0.2.6 is on npm). Both expose the same eight tools and load the same facts.json and encyclopedia.json, so they answer the same questions the same way. The source of truth for both lives at the root of the repository.

Build from source

git clone https://github.com/JacobiusMakes/diamond-mcp.git
cd diamond-mcp/node
npm ci
npm run build
npm test

npm run build compiles TypeScript to dist/ and copies the repo-root data files into dist/data/. npm test (alias npm run smoke) spawns the built server, runs the full MCP handshake, lists the tools, and calls every tool once.

License

MIT. See LICENSE.

Maintained by

Stienhardt, New York City. Lab Grown Diamond engagement rings, hand-set and finished in NYC, sold direct with in-person viewings by appointment only. Compare live Dutch Marquise diamonds.