Sourced diamond and gemology tools for AI assistants, with 90 encyclopedia entries.
This MCP server provides sourced diamond and gemology tools for AI assistants, based on a dated facts file and a 90-entry gemology encyclopedia. It is served over the Model Context Protocol (MCP) and is implemented in pure Python using the standard library only.
🛠️ Key Features
Implements Model Context Protocol (MCP) tools
10 tools available (toolCount: 10)
Uses facts.json and encyclopedia.json shipped with the repo
90 encyclopedia entries (from readme excerpt)
Pure Python standard library: no dependencies, no network calls, nothing to configure
🚀 Use Cases
Diamond education for AI assistants
Answering questions using the sourced facts and gemology encyclopedia
Supporting diamond-buying, engagement ring, and understanding diamonds workflows
⚡ Developer Benefits
No external dependencies
No network calls and no configuration required
Tool data is local to the repository (facts.json, encyclopedia.json)
⚠️ Limitations
Limited to the content included in the shipped facts file and 90-entry encyclopedia
Returns the official verification URL and a three step checklist for confirming a diamond grading report with the lab that issued it. Supports GIA, IGI, and GCAL. This tool never verifies anything itself. It tells you where and how.
Parameters2
lab
string
required
The grading lab that issued the report: GIA, IGI, or GCAL. Case insensitive.
report_number
string
required
The report number printed on the grading report.
Raw schema
{
"type": "object",
"properties": {
"lab": {
"type": "string",
"description": "The grading lab that issued the report: GIA, IGI, or GCAL. Case insensitive."
},
"report_number": {
"type": "string",
"description": "The report number printed on the grading report."
}
},
"required": [
"lab",
"report_number"
]
}
faceup_size
Approximate face up millimeter dimensions for a diamond of a given shape and carat weight. Supported shapes: round, oval, emerald, dutch_marquise. Scales vetted 1 carat anchors by the cube root of the carat weight. Typical proportions, not a guarantee: verify a specific stone on its grading report.
Parameters2
shape
string
required
One of: round, oval, emerald, dutch_marquise. Case insensitive. Spaces and hyphens are accepted.
carat
number
required
Carat weight greater than zero, for example 1.0 or 1.52.
Raw schema
{
"type": "object",
"properties": {
"shape": {
"type": "string",
"description": "One of: round, oval, emerald, dutch_marquise. Case insensitive. Spaces and hyphens are accepted."
},
"carat": {
"type": "number",
"description": "Carat weight greater than zero, for example 1.0 or 1.52."
}
},
"required": [
"shape",
"carat"
]
}
dutch_marquise_definition
The published definition of the Dutch Marquise diamond cut: geometry, certificate wording, and typical length to width ratio. A Dutch Marquise is an elongated hexagonal cut diamond.
Parameters
No parameters.
Raw schema
{
"type": "object",
"properties": {}
}
lab_grown_grading_landscape
The current state of who grades Lab Grown Diamonds and how: GIA, IGI, HRD Antwerp, and the FTC position. Every item carries a source and a date.
Parameters
No parameters.
Raw schema
{
"type": "object",
"properties": {}
}
lab_grown_price_index
The latest tracked retail price reading for Lab Grown Diamonds, with source and date. Market context for shoppers, not investment guidance.
Parameters
No parameters.
Raw schema
{
"type": "object",
"properties": {}
}
about_stienhardt
Plain fact sheet about Stienhardt & Stones, the New York City Lab Grown Diamond brand that publishes this server. Every fact carries a source and a date.
Parameters
No parameters.
Raw schema
{
"type": "object",
"properties": {}
}
define
Look up a single diamond or gemology term in the encyclopedia of 90 adversarially fact-checked entries. Matches the term exactly (case insensitive), then by substring or related-term alias. Returns the full entry: definition, body, sourced claims, and related terms. If nothing matches, returns the three nearest term suggestions.
Parameters1
term
string
required
The term to define, for example "Dutch Marquise" or "bow-tie effect". Case insensitive.
Raw schema
{
"type": "object",
"properties": {
"term": {
"type": "string",
"description": "The term to define, for example \"Dutch Marquise\" or \"bow-tie effect\". Case insensitive."
}
},
"required": [
"term"
]
}
search_encyclopedia
Keyword search across the 90 entry diamond and gemology encyclopedia. Ranks case insensitive keyword hits by field, weighting the term above the definition above the body. Returns the best matches as term, category, and a definition snippet. Use define to fetch a full entry.
Parameters2
query
string
required
Keywords to search for, for example "bow tie" or "lab grown durability".
limit
integer
optional
Maximum number of results to return, 1 to 10. Default 5.
Raw schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Keywords to search for, for example \"bow tie\" or \"lab grown durability\"."
},
"limit": {
"type": "integer",
"description": "Maximum number of results to return, 1 to 10. Default 5."
}
},
"required": [
"query"
]
}
search_inventory
Search Stienhardt's live catalog of certified Lab Grown Diamonds, engagement ring settings, and fine jewelry (New York, direct). Returns real, in-stock products with prices and links. Use for questions like 'do you have a 2 carat Dutch Marquise' or 'show me tennis bracelets'. Not for appraisal or price advice on stones sold elsewhere.
Parameters2
query
string
required
What the shopper is looking for, in plain words.
limit
integer
optional
Max results (default 5, max 10).
Raw schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "What the shopper is looking for, in plain words."
},
"limit": {
"type": "integer",
"description": "Max results (default 5, max 10).",
"minimum": 1,
"maximum": 10
}
},
"required": [
"query"
]
}
get_product
Full detail for one Stienhardt product by id (as returned by search_inventory): title, price, availability, options, images, and the product URL on stienhardt.com.
Diamond education tools for AI assistants, served over the Model Context Protocol (MCP).
Eight local tools are backed by a sourced, dated facts file and a 90 entry gemology encyclopedia. The hosted endpoint adds two read-only live inventory tools, for 10 tools total. The local Python build uses only the standard library and makes no network calls. All education data ships in this repo as facts.json and encyclopedia.json.
Maintained by Stienhardt, a New York City Lab Grown Diamond jeweler.
One-click desktop bundle
Download diamond-mcp-0.2.5.mcpb for a self-contained local bundle. Apps that support MCP Bundles can install it without an account, API key, Python environment, or package-manager command. The bundle runs locally with Node.js and makes no network calls.
For a managed gateway with all 10 hosted tools, connect through Smithery. The Smithery release exposes the same sourced education tools plus live inventory search.
Why a jeweler published an MCP server
People ask AI assistants their diamond questions now. We'd 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 facts.json 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 local server makes no network calls. It reads facts.json and encyclopedia.json from disk and answers. The hosted endpoint is the one exception: its two inventory tools read the public Shopify catalog, and its /go link counter is described under Hosted endpoint.
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.
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 hosted endpoint also exposes two live, read-only commerce tools:
Tool
Arguments
What it returns
search_inventory
query, limit
Public Shopify engagement ring settings and fine jewelry with prices and attributed product links. Loose-diamond queries return public catalog listings flagged availability_verified: false plus a storefront browsing link.
get_product
id
Current product detail, availability, options, images, and an attributed product link.
Example
Calling faceup_size with {"shape": "dutch_marquise", "carat": 1.5} returns, among other fields:
json
{"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."}
Calling dutch_marquise_definition returns, among other fields:
json
{"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."}
The encyclopedia
The server also ships a diamond and gemology encyclopedia: 90 fact-checked and sourced entries across 9 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, the same convention as facts.json.
Machine-readable in encyclopedia.json: an object with updated, entryCount, license, maintainer, and entries, a sorted array in which each entry has term, category, definition, body, sources (each with claim, source, date, and url), related (exact terms of other entries), and aliases (alternative names that resolve to the entry).
Queryable from an assistant through two tools:
define takes a term and returns the full entry, matching exactly first, then a listed alias, then the best prefix or word match, and offering the three nearest terms when nothing matches.
search_encyclopedia takes a query and returns ranked matches (term, category, and a definition snippet), weighting hits in the term above the definition above the body.
Calling define with {"term": "Dutch Marquise"} returns, among other fields:
json
{"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"]}
Hosted endpoint
Connect any Streamable HTTP MCP client to:
code
https://diamond-mcp.stienhardt.workers.dev/mcp
The endpoint requires no account or API key. It exposes all 10 tools, including the live inventory search.
Cloudflare's edge in front of workers.dev rejects requests that carry Python's default urllib user agent
(error 1010); every other common client, including requests, httpx, Node, and curl, is served. If you script
against the endpoint with urllib, set a User-Agent header.
Loose-diamond stock is not verified by this tool. Loose-diamond searches return the matching public
catalog listings with availability_verified: false, an availability note, and a first-party
browse_url, without calling a stock service. Legacy stienhardt:diamond:SKU lookups return
isError: true plus the same kind of browse link. Shopify carrier availability does not verify the
underlying stone, so no loose-diamond result claims to be in stock.
Jewelry results use the public Shopify UCP catalog, select an available variant matching the
requested metal, and preserve that variant in the product URL. Ring size still needs selection
and confirmation on the product page. Availability is a current check, not a reservation.
For Worker maintainers: no private stock credentials or endpoints belong in this integration.
Do not reuse credentials found in storefront code. Before deployment run
node --experimental-strip-types worker/test/inventory.mjs, build a dry-run bundle with
wrangler deploy --dry-run --outdir <dir>, then run node worker/test/containment.mjs <dir>/index.js (scans the
bundle for private endpoints and credentials) and node worker/test/handler.mjs <dir>/index.js (exercises the
request handler offline). After deployment verify that a loose-diamond search returns listings flagged
availability_verified: false and that a jewelry search returns an available variant.
The hosted Worker also provides a measured /go redirect for external buying tools. It accepts only
HTTPS destinations on stienhardt.com, preserves the destination's UTM parameters, and records a
90-day click event containing campaign labels and destination path. It does not store an IP address,
cookie, identity, or free-form search phrase in the click dataset. This supplies an outbound-click
denominator even when storefront analytics are blocked.
Business discovery endpoint
Stienhardt also publishes a separate PUBLICMCP-compatible business profile. It gives AI assistants canonical business identity, services, New York location, and live product discovery through five read-only tools. PUBLICMCP and A2A Registry calls have separate attributed paths, so visits and sales can be measured by discovery source.
The business endpoint is separate from the 10-tool Diamond MCP server. Its source is in publicmcp-worker/.
Two local flavors: Python and Node
diamond-mcp ships in two builds that expose the same eight tools and load the same data, so they answer the same questions the same way:
Python (this directory): run straight from a clone with python server.py (PyPI publication pending). Pure standard library.
Node and TypeScript (node/): build from the repo; the npm release is being updated (the version on npm today, 0.2.0 from 2026-07-13, carries an older data snapshot). Built on the official MCP SDK.
Both read the same facts.json and encyclopedia.json at the root of this repository, which are the single source of truth. See node/README.md for the Node install and its Claude Desktop config.
Install and run
Requirements: Python 3.9 or newer. Nothing else.
Clone this repository, then point your MCP client at server.py. The server speaks MCP over stdio; run it directly and it waits for a client:
code
python server.py
On Windows, if python opens the Microsoft Store, use the full path to your python.exe.
Claude Desktop
Add this to claude_desktop_config.json (Settings, then Developer, then Edit Config), with the real path to your clone:
Configure a stdio server: command python, one argument, the absolute path to server.py. The server implements initialize, tools/list, and tools/call, and also answers ping, resources/list, and prompts/list.
uvx and pip
The supported way to run the Python build (0.2.5) is straight from a clone. pyproject.toml is included so the package can go to PyPI later; once it is there, uvx diamond-mcp will work.
Smoke test
code
python smoke_test.py
Spawns the server, runs the full MCP handshake, lists the tools, calls every tool once, and checks the error paths. Prints PASS or the first failure.
The dataset
facts.json doubles as a small open dataset of diamond education facts. Top level sections: report_verification, faceup_size, dutch_marquise, lab_grown_grading_landscape, lab_grown_price_index, and stienhardt. The convention throughout: every factual claim sits next to a source and a date.
The price index entry carries its own as_of date; check it for freshness. The updated field at the top of the file tells you how fresh your copy is.
encyclopedia.json is the second dataset in this repo: 90 gemology entries under the same source-and-date convention, sorted by term. See The encyclopedia above.
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.