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

Commonlands MCP

Commonlands の精密光学機器を扱う公開 MCP サーバーです。M12/C マウントレンズの選定、視野の計算、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
• エージェント向け手順ガイド：docs/agent-instructions.md
• 最新情報を網羅したガイド：docs/live-usage-and-integrations.md

エージェント向けのコピー＆ペースト用指示

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.

エージェントのワークフロー

1. tools/list を呼び出し、ドキュメントよりも最新のツール一覧を優先します。
2. センサーに適したレンズを探す場合は、まず match_lens_to_sensor を呼び出し、最終候補のレンズとセンサーの FoV に関する主張について calculate_field_of_view を呼び出します。
3. search_lens_catalog は、SKU、タイトル、マウント、レンズタイプを広く探す場合にのみ使用します。センサーごとの FoV 計算の代わりにはなりません。
4. 必要に応じて、commonlands://sensors/{part} または commonlands://lenses/{sku} に対して resources/read を呼び出し、オブジェクトごとの根拠情報を取得します。
5. 歪み、モデル、ステータスに関する質問には get_lens_distortion_profile を使用します。応答に source-display-only とある場合は、多項式係数をでっち上げたり、補正を測定済みと主張したりしないでください。
6. クライアントが MCP プロンプトを表示する場合は、select_lens_for_sensor_fov_working_distance と併せて prompts/list／prompts/get を使用します。
7. 最終的な SKU、URL、価格、在庫状況、Shopify ID、カートのペイロードを提示する前に、read_shopify_products で購入可能な最新情報を確認します。
8. 明細項目と数量について購入者から明示的な確認を得てから、Shopify カートを作成または更新します。
9. 購入者には、Shopify から返されたカート／チェックアウトの URL を案内します。チェックアウトツールが tools/list に表示されるまでは、Checkout MCP が利用可能だと主張しないでください。

FoV のルール

カタログの EFL、イメージサークル、最大 FoV／FOV@image-circle、歪み表示フィールドだけでは、特定のセンサーにおける視野を計算できません。エージェントは、センサーの内部領域の FoV を補間したり、独自の計算で代用したりしてはいけません。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 ＝ 最新の FoV バックエンド（AWS Lambda + DynamoDB レンズカタログ）。センサー入力は、フィクスチャによるフォールバックを備えた最新の DynamoDB センサーカタログで解決されます。これらは公開向けにルーティングされた光学ツールです。
3. 互換性エイリアス（compute_fov、compute_fov_catalog、match_lenses_to_sensor）も実用上可能な範囲で引き続きディスパッチされますが、新しいクライアントでは上記の意図が明確なツールを経由してください。
4. 最新のバックエンドが有効な場合、ランキングツール（match_lens_to_sensor、recommend_lenses_for_application、compare_lenses）は、最新の FoV バックエンドの仕様と視野に基づいて順位付けするため、実際の SKU ごとの仕様（EFL、マウント、イメージサークル、FoV）を使用します。ただし、Shopify の最新の在庫、価格、バリアント ID は対象外です。購入可能な最新情報には read_shopify_products を使用してください。最新のバックエンドが未設定の場合は、フィクスチャの足場にフォールバックします。
5. 残りのフィクスチャカタログ／商品ページツールは、エンジニアリング上の参考情報としては有用ですが、最終的な販売情報ではありません。最新のバックエンドが未設定になった場合、FoV ツールはフェイルクローズし、センサー検索は小規模な参照用フィクスチャにフォールバックします。

フィクスチャデータが read_shopify_products または最新の FoV／センサーバックエンドの情報と食い違う場合は、最新の情報を使用してください。

データソース

• センサー（commonlands://sensors/{part} および calculate_field_of_view／match_lens_to_sensor で使用するセンサー）：設定されている場合は、部品番号をキーに Commonlands の DynamoDB センサーテーブルから読み取ります。設定されていない場合はフィクスチャにフォールバックします。ピクセルピッチとピクセル数はテーブルから直接取得し、有効領域の mm は pixels x pitch から算出します。
• レンズ（commonlands://lenses/{sku}、calculate_field_of_view、match_lens_to_sensor、search_lens_catalog）：設定されている場合、FoV Lambda は DynamoDB レンズテーブルからレンズの光学パラメーターを読み取ります。バックエンドのスキャンが有効な場合、カタログ全体を対象にマッチングします。
• 歪み係数は Lambda 内のサーバー側で計算され、クライアントには返されません。ライブバックエンドが表示用の歪み文字列のみを返す場合、MCP は正確に distortion_model／distortion_status を返し、実測による多項式補正が行われたとは主張しません。

現在のライブ機能

標準のカートツールを3つ有効にすると、このバージョンではカタログ／検索、FoV、Shopify の読み取り専用機能、カート、UCP カタログ、RFQ、購入引き継ぎにわたる21個のツールが公開されます。この設定では、チェックアウトツール、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）に転送します。エージェントは宛先を選択できません。送信されるのは問い合わせのみで（注文、支払い、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 で、commonlands.com 上の Shopify 提供のオンラインストア 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 ごとに 1 分あたり 120 リクエスト、create_cart／update_cart で IP ごとに 1 分あたり 10 回のカート変更です。いずれかを超過すると、retry-after: 60 を付けて HTTP 429 が返されます。
• **ペイロードを厳格に検証します。**カートごとに明細は 1～25 件、各明細の数量は 1～999 です。商品 ID は有効な Shopify ProductVariant GID でなければなりません。フィクスチャ ID、SKU、数値 ID は、Shopify を呼び出す前に拒否されます。
• **カートは Shopify が管理し、有効期限があります。**Worker はステートレスなプロキシです。カートの状態、TTL、有効期限（expiryAuthority: shopify_cart_ttl_expires_at）は Shopify が管理し、放棄されたカートは自動的に削除されます。カート、セッション、顧客、決済の状態が Worker に保存されることはありません。
• **チェックアウト機能はありません。**チェックアウト／キャンセルツールは非表示です。サーバーは決済の受け付け、注文や顧客の作成、割引の適用、在庫の書き込みができないため、不正な呼び出しによって永続的な変更が行われることはありません。

安全上の境界

• フィクスチャの価格、在庫状況、商品 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 の順に使い、最後に購入可能な SKU を read_shopify_products で確認してください。
• IMX477 上の CIL078 と CIL250 を比較してください。rectilinear_comparison を維持し、フィクスチャに基づく情報と Shopify のライブ情報を明確に区別してください。
• CIL250 の Shopify 上で有効な Product GID と Variant GID を探してください。URL、SKU、価格、在庫シグナル、カートの手順を返してください。ただし、カートは作成しないでください。
• この有効な Variant GID の商品を 2 個入れた Shopify カートを作成してください：<gid>。購入者は数量 2 を確認しています。
• Commonlands MCP のツールを一覧表示し、それぞれをフィクスチャ情報、ライブ 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"

エージェントが実際に呼び出している MCP ツールを確認するには、blob4 を使用してください。呼び出し回数が多く成功率も高いツールは、さらに投資する候補です。呼び出し回数が少ないツールやエラーが繰り返し発生するツールは、説明の改善、統合、または非推奨化を検討する候補です。リクエスト／レスポンスのメタデータを確認できるよう、Cloudflare の呼び出しログは有効にしたままにしてください。ただし、リクエスト引数を保存せずに JSON-RPC メソッドとツール名を記録できるため、ツール単位の判断には Analytics Engine を使用してください。

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] に記述します。認証情報は Cloudflare ダッシュボードまたは wrangler secret put で設定する Worker シークレットです（コミットしないでください）。

設定	場所	用途
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 はフォールバックとしてフィクスチャの 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 バックエンドを呼び出します。 このアダプターを独自にホストするには、認可された互換性のあるバックエンドが必要です。 ソースコードのライセンスは、バックエンドの認証情報や非公開のコードまたはデータセットへのアクセスを許可するものではありません。