Commonlands Optics: M12 Lens and C-Mount Lens Finder + Field-of-View Calculator

Commonlands MCP

Public MCP server for Commonlands precision optics. Use it to choose M12/C-mount lenses, calculate field of view, verify live Shopify product truth, and hand buyers to Shopify-owned carts safely.

Connect

• MCP endpoint: https://mcp.commonlands.com/mcp
• UCP discovery: https://mcp.commonlands.com/.well-known/ucp
• Health check: https://mcp.commonlands.com/healthz
• Client setup details: docs/client-connections.md
• Agent instruction guide: docs/agent-instructions.md
• Full live guide: docs/live-usage-and-integrations.md

Copy-paste agent instruction

Connect to https://mcp.commonlands.com/mcp and discover its current tools.

Start with the image sensor: model, active area, resolution and pixel pitch. Establish the required horizontal field of view and working distance. Use match_lens_to_sensor to find candidates. Use calculate_field_of_view for final lens/sensor FoV and distortion; preserve its method and status. Resolve the chosen family with resolve_lens_product and select a full SKU. Use get_purchase_options for current price, stock and the requested quantity. Confirm variants, quantities and totals with the buyer before cart or RFQ actions.

Agent workflow

1. Call tools/list and trust the live list over docs.
2. For sensor-specific lens finding, call match_lens_to_sensor first, then call calculate_field_of_view for final candidate lens/sensor FoV claims.
3. Use search_lens_catalog only for broad SKU/title/mount/lens-type discovery. It does not replace per-sensor FoV calculation.
4. Get per-object grounding with resources/read for commonlands://sensors/{part} or commonlands://lenses/{sku} when needed.
5. Use get_lens_distortion_profile for distortion/model/status questions. Do not invent polynomial coefficients or claim measured correction when the response says source-display-only.
6. Use prompts/list / prompts/get with select_lens_for_sensor_fov_working_distance when a client surfaces MCP prompts.
7. Verify purchasable truth with read_shopify_products before quoting final SKU, URL, price, availability, Shopify IDs, or cart payloads.
8. Create/update a Shopify cart only after explicit buyer confirmation of line items and quantities.
9. For an agent-authorized purchase, use the cart response agent_checkout route in the buyer's separate Shop MCP connection, before converting the cart through Commonlands. Shop handles sign-in and payment approval. Otherwise send the buyer to Shopify's returned checkout URL.

FoV rule

Catalog EFL, image circle, max FoV/FOV@image-circle, and distortion display fields are insufficient to compute field of view on a specific sensor. Agents must not interpolate interior-sensor FoV or substitute their own calculations. Use calculate_field_of_view, then preserve returned hfov_deg, vfov_deg, dfov_deg, method, distortion_model, coverage_ok, image_circle_mm, sensor_diagonal_mm, rectilinear_comparison, and provenance/source metadata in the answer.

Truth hierarchy

1. read_shopify_products = live Shopify product truth.
2. calculate_field_of_view / match_lens_to_sensor = live FoV backend (AWS Lambda + DynamoDB lens catalog) when configured. Sensor inputs resolve through the live DynamoDB sensor catalog with fixture fallback. These are the routed public optics tools.
3. Compatibility aliases (compute_fov, compute_fov_catalog, match_lenses_to_sensor) still dispatch where practical, but new clients should route through the intent-named tools above.
4. Ranking tools (match_lens_to_sensor, recommend_lenses_for_application, compare_lenses) rank against live FoV-backend specs and field of view when the live backend is enabled, so they use real per-SKU specs (EFL, mount, image circle, FoV). They still exclude live Shopify stock/price/variant IDs; use read_shopify_products for purchasable truth. In production, a missing or failed backend returns an explicit error.
5. Production legacy product aliases use live Shopify resolution and are omitted from discovery. Fixture handoff tools are retired. Offline development fixtures remain labeled and cannot replace failed production reads. Sensor lookups retain their separately labeled reference fallback.

If fixture data conflicts with read_shopify_products or the live FoV/sensor backends, use the live truth.

Data sources

• Sensors (commonlands://sensors/{part} and the sensor used by calculate_field_of_view / match_lens_to_sensor): read from the Commonlands DynamoDB sensor table by part number when configured, with fixture fallback. Pixel pitch and pixel counts come straight from that table; active-area mm is derived as pixels x pitch.
• Lenses (commonlands://lenses/{sku}, calculate_field_of_view, match_lens_to_sensor, search_lens_catalog): the FoV Lambda reads lens optical parameters from its DynamoDB lens table when configured. Catalog-wide matching covers the full lens table when backend scanning is enabled.
• Distortion coefficients are computed server-side inside the Lambda and are never returned to clients. If the live backend only returns a display distortion string, MCP returns an honest distortion_model / distortion_status and does not claim measured polynomial correction.

Current live surface

The production tool list depends on enabled features. This branch adds live product resolution and quantity purchase options and removes fixture aliases from discovery. It retains create_cart, get_cart, update_cart, cancel_cart, create_checkout, and get_checkout. Commerce uses Shopify UCP at https://commonlands.com/api/ucp/mcp. complete_checkout is disabled on Commonlands. Cart responses include an agent_checkout route to the buyer's separate Shop MCP connection, where authorized agents can complete eligible purchases. Customers can also review and pay on Shopify. Always trust live tools/list. See cart and checkout integration.

Key tools:

• Public optics routing: calculate_field_of_view, match_lens_to_sensor, search_lens_catalog, get_lens_distortion_profile.
• Optical comparison: compare_lenses, recommend_lenses_for_application. Current product selection: resolve_lens_product, get_purchase_options.
• Legacy hidden aliases (still dispatch for old clients, not listed in tools/list): compute_fov, compute_fov_catalog, match_lenses_to_sensor, search_lenses, get_lens_details.
• Resources/prompts: commonlands://sensors/{part}, commonlands://lenses/{sku}, commonlands://catalog/sensors, commonlands://catalog/lenses, and prompt select_lens_for_sensor_fov_working_distance.
• Live Shopify read-only truth: read_shopify_products, get_shopify_readonly_config_status.
• Buyer-confirmed Shopify cart handoff: create_cart, get_cart, update_cart, cancel_cart, followed by create_checkout and get_checkout when visible in tools/list.
• RFQ / question handoff: submit_rfq forwards a buyer quote request or question to the fixed Commonlands engineering inbox (SendGrid). The agent cannot choose the recipient; it sends an inquiry only (no order, payment, or Shopify write) and stays inert (routes to the contact page) until SENDGRID_API_KEY + RFQ_TO_EMAIL + RFQ_FROM_EMAIL are configured.
• Diagnostics/readiness: get_catalog_snapshot_status, get_shopify_ucp_readiness. Legacy fixture purchase handoffs are retired in production.

Public-data scope (Shopify reads)

The endpoint is public and unauthenticated, so read_shopify_products returns only data that is already public on commonlands.com (enforced server-side in src/shopify-read-adapter.ts, see PUBLIC_DATA_POLICY):

• Published active products only. Products must be ACTIVE and have a Shopify-provided Online Store URL on commonlands.com. An ACTIVE product with no publication is filtered out; the adapter never invents its URL.
• Current per-variant inventory. Shopify supplies website and online sellable quantities on each request. Untracked or missing quantities are null. The old availability category remains for compatibility; inventory item/location IDs remain private. Counts do not reserve inventory or guarantee fulfillment.
• Metafields are opt-in and allowlisted. includeMetafields defaults to false; when enabled, only the custom.* display fields rendered on public product pages are returned. App/private namespaces and non-allowlisted keys (including custom.docsend_page) are always dropped.
• `read_shopify_metaobjects` was removed from the public surface (2026-07): Admin metaobject definitions can hold non-public store content. Calls return an actionable error pointing to read_shopify_products.
• The requested Admin scopes were narrowed to the read scopes the surface actually needs (no metaobject, marketing, payment-terms, or shipping scopes).

Abuse controls (cart and endpoint)

Cart tools are deliberately reachable without authentication — the same trust model as Shopify's own public Storefront cart — but they are bounded:

• Per-IP rate limits (Workers Rate Limiting API, wrangler.toml): 120 requests/min per IP across /mcp, and 10 cart mutations/min per IP for cart mutations, checkout creation, and RFQ submissions. Exceeding either returns HTTP 429 with retry-after: 60.
• Strict payloads: 1–25 line items per cart, quantity 1–999 per line, and item IDs must be live Shopify ProductVariant GIDs — fixture IDs, SKUs, and numeric IDs are rejected before any Shopify call.
• Carts are Shopify-owned and expire. The Worker is a stateless proxy; cart state, TTL, and expiry (expiryAuthority: shopify_cart_ttl_expires_at) belong to Shopify, which prunes abandoned carts automatically. No cart, session, customer, or payment state is ever stored in the Worker.
• Checkout handoff: the agent prepares a checkout and returns Shopify’s continue_url. Cart conversion requires the cart owner token; checkout reads require a separate checkout owner token. The Commonlands server cannot complete payment or place an order. For buyer-authorized agent purchases, cart responses provide the exact handoff to Shop MCP; the buyer's client sends its credentials and approved payment directly to Shop.

Safety boundaries

• Do not use fixture prices, availability, product URLs, SKU variants, or IDs as final commerce truth.
• Do not create or update carts unless the buyer has confirmed live Variant GIDs and quantities.
• Call create_checkout after buyer confirmation, preserve checkout_access_token, and return checkout.continue_url. The buyer reviews and pays on Shopify.
• Do not ask for or transmit card numbers, CVV/CVC, payment tokens, passwords, or customer account credentials through Commonlands. In the separate Shop connection, the buyer client sends only Shop-offered payment instruments back to Shop after buyer approval.
• Do not perform Shopify product, variant, collection, tag, metafield, inventory, order, customer, discount, RFQ, Acumatica, or database writes.
• Do not expose gated datasheet URLs or backend secrets.
• For live FoV, call Commonlands MCP only. Do not call the AWS Lambda/API Gateway backend directly.

Good prompts

• Find M12 lenses for IMX477 around 50° horizontal FoV. Use match_lens_to_sensor, calculate_field_of_view, then verify the final purchasable SKU with read_shopify_products.
• Compare CIL078 and CIL250 on IMX477. Preserve rectilinear_comparison and label fixture-backed context separately from live Shopify truth.
• Find the live Shopify Product and Variant GID for CIL250. Return URL, SKU, price, inventory signal, and cart path, but do not create a cart.
• Create a Shopify cart for two units of this live Variant GID: . The buyer has confirmed quantity 2.
• `List