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

Commonlands MCP

Commonlands 精密光学产品的公共 MCP 服务。可用于选择 M12/C-mount 镜头、计算视场、核实 Shopify 实时商品信息，并安全地将买家引导至 Shopify 自有购物车。

连接

• MCP 端点：https://mcp.commonlands.com/mcp
• UCP 发现：https://mcp.commonlands.com/.well-known/ucp
• 健康检查：https://mcp.commonlands.com/healthz
• 客户端设置详情：docs/client-connections.md
• Agent 指令指南：docs/agent-instructions.md
• 完整实时指南：docs/live-usage-and-integrations.md

可复制粘贴的 Agent 指令

Use Commonlands MCP at https://mcp.commonlands.com/mcp for lens selection. Start with tools/list. Catalog EFL, image circle, max FoV/FOV@image-circle, and distortion display fields are insufficient to compute FoV on a specific sensor; do not interpolate or estimate sensor FoV from those fields. Use calculate_field_of_view for one lens/sensor pair, match_lens_to_sensor for sensor/target-FoV selection, search_lens_catalog for broad catalog discovery, and get_lens_distortion_profile for distortion status. Preserve the returned method, distortion_model, coverage_ok, image_circle_mm, sensor_diagonal_mm, and rectilinear_comparison. Call read_shopify_products before stating live price, availability, Product/Variant GIDs, URL, SKU, media, metafields, inventory, or cart payload. Only call create_cart/update_cart after the buyer confirms exact live Variant GIDs and quantities. Checkout tools are not live unless they appear in tools/list. Never ask for card data or perform Shopify catalog/inventory/order/customer writes.

Agent 工作流

1. 调用 tools/list，并以实时列表为准，而非文档。
2. 针对特定传感器查找镜头时，先调用 match_lens_to_sensor，再调用 calculate_field_of_view，以确认最终候选镜头/传感器视场声明。
3. 仅使用 search_lens_catalog 广泛查找 SKU/标题/卡口/镜头类型。它不能替代针对每种传感器的视场计算。
4. 如有需要，通过 resources/read 获取单个对象的依据，资源为 commonlands://sensors/{part} 或 commonlands://lenses/{sku}。
5. 针对畸变/模型/状态问题，使用 get_lens_distortion_profile。如果响应说明仅供来源展示，不要编造多项式系数，也不要声称进行了实测校正。
6. 如果客户端提供 MCP 提示词，使用 prompts/list / prompts/get 和 select_lens_for_sensor_fov_working_distance。
7. 在提供最终 SKU、URL、价格、库存情况、Shopify ID 或购物车负载前，使用 read_shopify_products 核实可购买商品信息。
8. 只有在买家明确确认商品条目和数量后，才创建/更新 Shopify 购物车。
9. 将买家引导至 Shopify 返回的购物车/结账 URL。在 tools/list 中出现结账工具之前，不要声称 Checkout MCP 已上线。

视场规则

目录中的 EFL、像圈、最大视场/FOV@image-circle 和畸变展示字段不足以计算特定传感器上的视场。Agent 不得插值计算传感器内部区域的视场，也不得用自行计算的结果替代。请使用 calculate_field_of_view，并在回答中保留返回的 hfov_deg、vfov_deg、dfov_deg、method、distortion_model、coverage_ok、image_circle_mm、sensor_diagonal_mm、rectilinear_comparison 以及来源/出处元数据。

信息可信度层级

1. read_shopify_products = Shopify 实时商品信息。
2. 如果已配置，calculate_field_of_view / match_lens_to_sensor = 实时视场后端（AWS Lambda + DynamoDB 镜头目录）。传感器输入通过实时 DynamoDB 传感器目录解析，并在必要时回退到 fixture。它们是路由后的公共光学工具。
3. 兼容性别名（compute_fov、compute_fov_catalog、match_lenses_to_sensor）在可行时仍会分发请求，但新客户端应通过上述按意图命名的工具路由。
4. 如果启用了实时后端，排名工具（match_lens_to_sensor、recommend_lenses_for_application、compare_lenses）会依据实时视场后端规格和视场进行排名，因此使用真实的逐 SKU 规格（EFL、卡口、像圈、视场）。但它们仍不包含 Shopify 实时库存/价格/变体 ID；请使用 read_shopify_products 获取可购买商品信息。如果未配置实时后端，则回退至 fixture 脚手架。
5. 其余 fixture 目录/商品页面工具可提供有用的工程背景信息，但不能作为最终商品交易信息。如果实时后端未配置，视场工具会关闭故障，传感器查询则回退到精简的参考 fixture。

如果 fixture 数据与 read_shopify_products 或实时视场/传感器后端冲突，请以实时信息为准。

数据源

• 传感器（commonlands://sensors/{part}，以及 calculate_field_of_view / match_lens_to_sensor 使用的传感器）：配置后，按部件号从 Commonlands DynamoDB 传感器表读取；否则使用固定数据回退。像素间距和像素数量直接来自该表；有效面积（mm）由 像素数 x 像素间距 得出。
• 镜头（commonlands://lenses/{sku}、calculate_field_of_view、match_lens_to_sensor、search_lens_catalog）：配置后，FoV Lambda 会从其 DynamoDB 镜头表读取镜头光学参数。启用后端扫描时，全目录匹配会覆盖整个镜头表。
• 畸变系数由 Lambda 在服务端计算，绝不会返回给客户端。如果实时后端仅返回用于显示的畸变字符串，MCP 会如实返回 distortion_model / distortion_status，不会声称进行了实测多项式校正。

当前实时功能

启用三个标准购物车工具后，此版本会公开 21 个工具，涵盖目录/搜索、FoV、Shopify 只读、购物车、UCP 目录、RFQ 和购买交接。结账工具、cancel_cart 和 read_shopify_metaobjects 仍未包含在该配置中。始终以实时 tools/list 为准，而非任何文档。

主要工具：

• 公共光学路由：calculate_field_of_view、match_lens_to_sensor、search_lens_catalog、get_lens_distortion_profile。
• 目录/上下文（位于 tools/list 中）：search_catalog、lookup_catalog、get_product、get_product_page_details、compare_lenses、recommend_lenses_for_application。
• 旧版隐藏别名（仍可供旧客户端调用，但不会列在 tools/list 中）：compute_fov、compute_fov_catalog、match_lenses_to_sensor、search_lenses、get_lens_details。
• 资源/提示词：commonlands://sensors/{part}、commonlands://lenses/{sku}、commonlands://catalog/sensors、commonlands://catalog/lenses，以及提示词 select_lens_for_sensor_fov_working_distance。
• Shopify 实时只读数据：read_shopify_products、get_shopify_readonly_config_status。
• 经买家确认的 Shopify 购物车交接：当 tools/list 中显示时可用 create_cart、get_cart、update_cart。
• RFQ / 问题交接：submit_rfq 会将买家的报价请求或问题转发至固定的 Commonlands 工程团队收件箱（SendGrid）。Agent 无法选择收件人；此工具仅发送咨询（不下订单、不付款，也不写入 Shopify），且在配置 SENDGRID_API_KEY + RFQ_TO_EMAIL + RFQ_FROM_EMAIL 之前保持不启用（会转至联系页面）。
• 诊断/就绪状态：get_catalog_snapshot_status、get_shopify_ucp_readiness、prepare_shopify_purchase_handoff、get_purchase_route_options。

公共数据范围（Shopify 读取）

该端点公开且无需身份验证，因此 read_shopify_products 只会返回 commonlands.com 上已公开的数据（由服务器端的 src/shopify-read-adapter.ts 强制执行，参见 PUBLIC_DATA_POLICY）：

• 仅限已发布的活跃产品。 产品必须处于 ACTIVE 状态，并且具有 Shopify 提供的 commonlands.com 在线商店 URL。没有发布信息的 ACTIVE 产品会被过滤掉；适配器绝不会自行编造 URL。
• 不提供精确库存。 变体包含粗略的 availability 信号（in_stock / low_stock / out_of_stock / untracked）；绝不返回原始数量和库存商品 ID。
• 元字段需选择启用，并受允许列表限制。 includeMetafields 默认值为 false；启用后，只会返回公开产品页面上显示的 custom.* 字段。应用/私有命名空间和不在允许列表中的键（包括 custom.docsend_page）始终会被剔除。
• read_shopify_metaobjects 已从公共接口移除（2026-07）：Admin 元对象定义可能包含非公开的商店内容。调用会返回可执行的错误提示，指向 read_shopify_products。
• 已收窄所请求的 Admin 权限范围，仅保留接口实际需要的读取权限（不包含元对象、营销、付款条件或配送权限）。

滥用防护（购物车和端点）

购物车工具有意设置为无需身份验证即可访问——信任模型与 Shopify 自有的公共 Storefront 购物车相同，但会受到以下限制：

• 按 IP 限流（Workers Rate Limiting API，wrangler.toml）：/mcp 的所有请求按 IP 每分钟 120 次；create_cart/update_cart 的购物车变更请求按 IP 每分钟 10 次。超出任一限制时，会返回 HTTP 429，并附带 retry-after: 60。
• 严格限制请求负载： 每个购物车包含 1–25 个商品项，每项数量为 1–999；商品 ID 必须是有效的 Shopify ProductVariant GID——在调用 Shopify 之前就会拒绝 fixture ID、SKU 和数字 ID。
• 购物车由 Shopify 管理且会过期。 Worker 是无状态代理；购物车状态、TTL 和过期时间（expiryAuthority: shopify_cart_ttl_expires_at）均由 Shopify 管理，Shopify 会自动清理被弃用的购物车。Worker 绝不存储购物车、会话、客户或付款状态。
• 不提供结账接口： 结账/取消工具处于隐藏状态；服务器无法收款、创建订单或客户、应用折扣或写入库存，因此滥用调用者无法更改任何持久数据。

安全边界

• 不要将 fixture 价格、供货情况、产品 URL、SKU 变体或 ID 作为最终的商业信息依据。
• 除非买家已确认有效的 Variant GID 和数量，否则不要创建或更新购物车。
• 暂时不要使用 Checkout MCP；结账端点将在验证并获批后启用。
• 不要索取或传输卡号、CVV/CVC、付款令牌、密码或客户账户凭据。
• 不要执行 Shopify 产品、变体、系列、标签、元字段、库存、订单、客户、折扣、RFQ、Acumatica 或数据库的写入操作。
• 不要暴露受限的数据表 URL 或后端机密信息。
• 对于实时 FoV，只能调用 Commonlands MCP。不要直接调用 AWS Lambda/API Gateway 后端。

优质提示词

• 查找适用于 IMX477、水平 FoV 约为 50° 的 M12 镜头。使用 match_lens_to_sensor、calculate_field_of_view，然后通过 read_shopify_products 验证最终可购买的 SKU。
• 比较 IMX477 上的 CIL078 和 CIL250。保留 rectilinear_comparison，并将 fixture 支持的上下文与实时 Shopify 信息分别标注。
• 查找 CIL250 对应的实时 Shopify Product 和 Variant GID。返回 URL、SKU、价格、库存信号和购物车路径，但不要创建购物车。
• 为此实时 Variant GID 创建一个包含两个单位的 Shopify 购物车：<gid>。买家已确认数量为 2。
• 列出 Commonlands MCP 工具，并将每个工具分类为 fixture 上下文、实时 FoV、只读实时 Shopify 或 Shopify 购物车。

可观测性

0.4.2 版本还会从旧版工具响应（包括嵌套的 UCP 变体和购买路由）及目录资源中隐藏样例价格、可用性和产品 URL。使用 read_shopify_products 获取当前商务数据；样例响应会提供 commerceLookup 指令，而不是过时的报价。 提供水平 FoV 目标时，排名会优先考虑完整传感器覆盖，其次是目标绝对误差，然后是启发式评分和 SKU。封顶评分不再导致精确匹配目标的镜头输给字母顺序更靠前的镜头。

配置名为 MCP_ANALYTICS 的 Cloudflare Analytics Engine 绑定后，Worker 可以写入保护隐私的请求／工具遥测数据。遥测仅记录方法、路径、MCP 方法、工具名称、状态、客户端标签、环境／版本、HTTP 状态和耗时。它不会记录请求参数、Shopify 负载、客户数据、产品 ID、购物车 ID、机密或响应正文。

绑定示例：

[[analytics_engine_datasets]]
binding = "MCP_ANALYTICS"
dataset = "commonlands_mcp_events"

部署后，验证遥测是否正常运行：

curl https://mcp.commonlands.com/healthz
curl -X POST https://mcp.commonlands.com/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'mcp-client-name: telemetry-smoke' \
  -d '{"jsonrpc":"2.0","id":"telemetry-smoke","method":"tools/list","params":{}}'

/healthz 应报告 "telemetry":{"analyticsEngine":"configured"}。然后查询 commonlands_mcp_events Analytics Engine 数据集。列顺序为：blob1=request method、blob2=path、blob3=MCP method、blob4=tool、blob5=status、blob6=client、blob7=environment、blob8=version、double1=HTTP status，以及 double2=duration ms。

工具使用情况汇总：

curl "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/analytics_engine/sql" \
  -H "Authorization: Bearer $CLOUDFLARE_ANALYTICS_READ_TOKEN" \
  --data "SELECT blob4 AS tool, blob5 AS status, SUM(_sample_interval) AS calls, SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_duration_ms FROM commonlands_mcp_events WHERE timestamp >= NOW() - INTERVAL '7' DAY AND blob3 = 'tools/call' GROUP BY tool, status ORDER BY calls DESC LIMIT 50 FORMAT JSON"

客户端／工具汇总：

curl "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/analytics_engine/sql" \
  -H "Authorization: Bearer $CLOUDFLARE_ANALYTICS_READ_TOKEN" \
  --data "SELECT blob6 AS client, blob4 AS tool, SUM(_sample_interval) AS calls, SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_duration_ms FROM commonlands_mcp_events WHERE timestamp >= NOW() - INTERVAL '7' DAY AND blob3 = 'tools/call' AND blob5 = 'ok' GROUP BY client, tool ORDER BY calls DESC LIMIT 100 FORMAT JSON"

使用 blob4 查看 Agent 实际调用了哪些 MCP 工具。调用频繁且成功率高的工具适合加大投入；调用较少或反复出错的工具适合改进描述、整合或弃用。保持启用 Cloudflare 调用日志，以记录请求／响应元数据；但工具级决策应使用 Analytics Engine，因为它会捕获 JSON-RPC 方法和工具名称，而不会存储请求参数。

从 0.4.2 开始，连接器操作失败时也会设置 MCP isError: true，并在 blob5 中记录 tool_error_not_configured、tool_error_invalid_request、tool_error_shopify_error 或 tool_error_delivery_failed。成功的 RFQ 预览仍计为成功调用；这并不表示邮件已送达。客户端标签描述的是软件，而非独立个人。

较早版本会将这些应用层失败记录为 ok，因此历史成功率可能被高估。由于此数据集有意排除请求／响应负载，无法从中还原实际结果。比较修正后的成功率时，请按 blob8（部署版本）筛选。

快速配置客户端

Codex

[mcp_servers.commonlands]
url = "https://mcp.commonlands.com/mcp"
tool_timeout_sec = 60

通过 mcp-remote 使用 Claude Desktop / Claude Code

{
  "mcpServers": {
    "commonlands": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.commonlands.com/mcp"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "commonlands": {
      "url": "https://mcp.commonlands.com/mcp"
    }
  }
}

配置

非敏感配置存放在 wrangler.toml 的 [vars] 中；凭据作为 Worker 密钥，通过 Cloudflare 控制面板或 wrangler secret put 设置（绝不提交）。

设置	位置	用途
account_id	wrangler.toml	固定 Cloudflare 账户，避免部署时调用 /memberships（账户范围的 API 令牌无法访问该接口，因此会触发身份验证错误 9106）。
FOV_LIVE_BACKEND_ENABLED	[vars]	"true" 会将 FoV 请求路由到实时 Lambda 后端。
FOV_LAMBDA_ENDPOINT	[vars]	列入允许列表的 FoV Lambda/API Gateway URL。
FOV_BACKEND_SCANS_FULL_CATALOG	[vars]	"true" 会使 compute_fov_catalog 省略 partNums，让 Lambda 扫描完整的 DynamoDB 镜头表。Lambda 上必须设置 ALLOW_LENS_SCAN=true。当值为 "false" 时，Worker 会发送 fixture SKU 作为备用方案。
SENSOR_DDB_TABLE	[vars]	DynamoDB 传感器表名称。
SENSOR_DDB_REGION	[vars]	DynamoDB 传感器表所在区域。
FOV_API_KEY	密钥	Worker 发送给 FoV Lambda 的共享密钥（x-api-key）；必须与 Lambda 的 FOV_API_KEY 完全一致（逐字节相同，且末尾不得有换行符）。
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	密钥	Worker 用于读取传感器 DynamoDB 表的只读 IAM 用户凭据（SigV4）。
CLOUDFLARE_API_TOKEN	GitHub Actions 密钥	供 Deploy 工作流使用、具有 Workers Scripts: Edit 权限的令牌。

AWS / DynamoDB 注意事项

• Worker 使用只读 IAM 用户直接读取传感器表（仅对该表 ARN 执行 dynamodb:Scan/Query/GetItem/DescribeTable）。代码路径中不存在写入操作。
• FoV Lambda 使用自己的只读执行角色读取镜头表。若要让 compute_fov_catalog 覆盖完整目录，Lambda 必须设置 ALLOW_LENS_SCAN=true，并具有对镜头表执行 dynamodb:Scan 的权限。
• 传感器表的分区键是部件编号（id）；使用的属性包括：sensormfg、sensorhpix、sensorvpix、sensorpitch、sensortype（快门类型）。
• 镜头表的分区键是 SKU；必须相应设置 Lambda 的 LENS_PK。

本地开发

要求：Node.js 22+。

npm install
npm run verify
npm run dev

本地冒烟测试：

curl http://localhost:8787/healthz
curl -X POST http://localhost:8787/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

部署

生产环境部署需在可信任的计算机上，使用 Wrangler 的浏览器 OAuth 登录手动完成。GitHub 仅运行检查；GitHub Actions 无需 Cloudflare 部署令牌。合并经过审核的发布分支，并在部署前拉取该分支。 源文件 wrangler.toml 有意不定义本地构建元数据。

npm ci
npm run verify
# Clear token overrides in this terminal so Wrangler uses browser OAuth.
Remove-Item Env:CLOUDFLARE_API_TOKEN, Env:CF_API_TOKEN, Env:CLOUDFLARE_API_KEY, Env:CF_API_KEY -ErrorAction SilentlyContinue
npx wrangler login
npx wrangler whoami
npm run deploy
Invoke-RestMethod https://mcp.commonlands.com/healthz

如果任何命令失败，请停止。确认 whoami 有权访问 wrangler.toml 中的账户。部署后，确认 /healthz 报告了预期的版本和 Git 提交，然后运行客户端冒烟测试，详见 docs/client-connections.md。

npm run deploy 会运行 scripts/deploy.mjs， 通过 --keep-vars 执行部署，并注入相同的生产构建元数据。npm run deploy:raw 是未封装的 Wrangler 部署命令。

Wrangler 会在仓库之外的本地位置存储 OAuth 凭据。绝不提交凭据。已停用的 GitHub CLOUDFLARE_API_TOKEN 密钥可在仓库的 Settings > Secrets and variables > Actions 中删除；删除工作流不会删除已存储的密钥。单独的分析令牌不是部署凭据。请参阅 Wrangler 身份验证。

许可证和私有后端

Apache-2.0 适用于本仓库中由 Commonlands 所有并分发的源代码。 单独托管的 Commonlands Lambda 实现和私有光学数据集不会在本仓库的许可证下分发或授权。 适用的第三方许可证和声明仍然有效。

公共 MCP 端点可供用户访问托管服务，无需获取其后端源代码。用户连接到 https://mcp.commonlands.com/mcp； 该服务使用服务器端凭据调用私有 Lambda 后端。 独立托管此适配器需要获授权的兼容后端； 源代码许可证不授予后端凭据，也不授予对私有代码或数据集的访问权限。