MCP Server

🚀 OpenFacet MCP Server

An implementation of the Model Context Protocol (MCP) for the OpenFacet Diamond Pricing API, offering transparent and real-time diamond pricing data with interpolation algorithms and market depth analytics.

🚀 Quick Start

This project requires Node.js ≥18. Clone the repository with the following commands:

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

✨ Features

• Implements MCP 2025‑06‑18 (no batch support, structured content, version headers).
• Provides tools: get_diamond_price, get_dcx_index, get_market_depth.
• Enables real-time interpolation over carat/color/clarity.
• Offers DCX Index and inventory snapshot with daily refresh.
• Is single-file deployable with no dependencies.
• Has 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 Examples

🔌 Local stdio Transport

The stdio transport is the default for most MCP clients. Start the server with:

node stdio.js

Send a message (paste this JSON and press Enter):

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

You'll receive a response like:

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"💎 **Diamond Price Quote**\n\n**Specifications:**\n• Carat: 1.23ct\n• Color: G\n• Clarity: VS2\n• Shape: round\n\n**Pricing:**\n• Per Carat: $4,487\n• Total Price: $5,519.01\n\n*Prices from OpenFacet.net API*"}],"_meta":{"timestamp":"2025-07-11T10:21:50.460Z","source":"OpenFacet.net API"}}}

🌐 Local Node.js HTTP server

By default, it binds to localhost:3000/. Available endpoints are:

• POST /: JSON-RPC entrypoint
• GET /health: Server status
• GET /.well-known/mcp.json: Discovery metadata

🌍 Remote MCP Server

Use the remote server for testing at https://mcp.openfacet.net. Here is an example price query:

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"
      }
    }
  }'

📚 Tool Summary

get_diamond_price

Returns interpolated pricing for round/cushion GIA diamonds. Parameters:

• carat: number (0.3–6.0)
• color: string (D–M)
• clarity: string (FL–I3)
• shape: string (optional, default: "round")

get_dcx_index

Returns the composite index of diamond price trends. No parameters required.

get_market_depth

Returns inventory data. Optional parameter:

• carat: number

🧪 Testing

Run the following command to perform tests:

node test-core.js

The tests cover:

• Interpolation behavior
• DCX/market depth parsing
• Error conditions
• JSON-RPC correctness

🔧 Technical Details

Interpolation

• Uses log-space interpolation across fixed breakpoints.
• Applies anchor smoothing near psychological thresholds (0.3, 0.5, 1.0, etc.).
• Provides dynamic boost if the price trend continues beyond a band.

Specifications

• 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/

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.