Content
# OpenFacet MCP Server
[](https://modelcontextprotocol.io/specification/2026-07-28)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
A Model Context Protocol (MCP) implementation for the [OpenFacet](https://openfacet.net) Diamond Pricing API. Provides transparent, real-time diamond pricing data with interpolation algorithms and market depth analytics.
Built with vanilla JavaScript and core modules only - zero external dependencies.
## Features
* Implements MCP 2026-07-28 (stateless per-request metadata, structured content, and HTTP metadata validation)
* Tools: `get_diamond_price`, `get_dcx_index`, `get_market_depth`
* Real-time interpolation over carat/color/clarity
* DCX Index and inventory snapshot with daily refresh
* Single-file deployable; no dependencies
* Runtime adapters:
* **Node.js**: HTTP server, CORS, configurable port
* **Cloudflare Worker**: single fetch entrypoint
## Project Structure
```
mcp-server/
├── core.js # Shared logic, tool handlers, interpolation
├── stdio.js # Local stdio transport
├── node.js # Node.js HTTP server (PORT via CLI or env)
├── worker.js # Remote Cloudflare Worker
├── test-core.js # Vanilla JS test runner
├── mcp-version.js # Protocol version constant
└── README.md
```
## Usage
Requires Node.js ≥18, clone the repository:
```bash
git clone https://github.com/openfacet/mcp-server.git
cd mcp-server
```
### Local stdio Transport
The stdio transport is the default for most MCP clients.
```bash
# Start the server
node stdio.js
```
Send a message (paste this JSON and press Enter):
```plain
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_diamond_price","arguments":{"carat":1.23,"color":"G","clarity":"VS2","shape":"emerald","shape_ratio":1.58},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}
```
You'll get a response like:
```plain
{"jsonrpc":"2.0","id":1,"result":{"resultType":"complete","content":[{"type":"text","text":"OpenFacet diamond price quote..."}],"structuredContent":{"shape":"emerald","per_carat_usd":4487,"total_usd":5519,"tracking_url":"https://openfacet.net/en/my-diamond/?..."}}}
```
### Local Node.js HTTP server
Default binds to `localhost:3000/`. Available endpoints:
* `POST /`: JSON-RPC entrypoint
* `GET /health`: Server status
* `GET /.well-known/mcp.json`: Discovery metadata
### Remote MCP Server
Remote server for testing `https://mcp.openfacet.net`. Example price query:
```bash
curl -X POST https://mcp.openfacet.net/ \
-H "Content-Type: application/json" \
-H "MCP-Protocol-Version: 2026-07-28" \
-H "Mcp-Method: tools/call" \
-H "Mcp-Name: get_diamond_price" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_diamond_price",
"arguments": {
"carat": 1.23,
"color": "G",
"clarity": "VS2",
"shape": "emerald",
"shape_ratio": 1.58
},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}'
```
## Tool Summary
### `get_diamond_price`
Returns an OpenFacet price quote using website interpolation, special-size discounts, and shape-ratio models.
Parameters:
* `carat`: number (0.3–6.0)
* `color`: string (D–M)
* `clarity`: string (FL–I3)
* `shape`: string (optional, default: "round"): `round`, `cushion`, `radiant`, `emerald`, `oval`, `pear`, `marquise`, or `heart`
* `shape_ratio`: number (optional). Uses the shape model's center ratio when omitted.
Results include a shareable OpenFacet tracking URL. Ratios outside the observed model range are identified as preference-driven.
### `get_dcx_index`
Returns composite index of diamond price trends, comparing 24-hour, 7-day, and 30-day changes. No parameters.
### `get_market_depth`
Returns observed-offer inventory data. Optional parameter:
* `carat`: number
## Testing
```bash
node core-test.js
bash bundle.sh
```
Covers:
* Per-request MCP metadata and structured tool results
* Website special-size interpolation and fancy-shape ratio adjustments
* DCX trend and market-depth parsing
* Cloudflare Worker bundle syntax
## Technical Notes
### Interpolation
* Log-space interpolation across fixed breakpoints
* Log-space interpolation with website anchor smoothing
* Website special-size discounts below 0.5, 0.7, 1.0, 1.5, 2.0, 3.0, and 5.0ct anchors
* Ratio-band multipliers for supported fancy shapes
### Specifications
* API docs: [https://openfacet.net/en/api-docs/](https://openfacet.net/en/api-docs/)
* `/matrix.json` and `/matrix_cushion.json`: base pricing matrices
* `/index.json`: DCX index and trend
* `/depth.json`: market depth by carat/color/clarity
* Pricing methodology: [https://openfacet.net/en/methodology/](https://openfacet.net/en/methodology/)
MCP Store