Ops Lense

Ops Lenseは、リモートでホストされるコマースオペレーション向けModel Context Protocol（MCP）サーバーです。オペレーションスペシャリストが、スタックした注文を調査し、何が問題だったのかを理解し、エンジニアを介さずに次の安全なアクションを実行するのを支援します。

この課題は、スタックした注文の調査と是正という1つのワークフローに焦点を当てています。対象は、注文、支払い、在庫、フルフィルメントです。

デモの内容

オペレーターは、MCP対応のAIクライアントに次のような質問をすることができます。

なぜこの支払い済みの注文がまだスタックしているのですか？

AIはOps Lenseを使用して以下のことができます。

1. 注文を検索する。

2. 運用タイムラインを調査する。

3. バックエンドデータから考えられる障害を診断する。

4. 提案されたアクションをどの程度安全に実行できるかを判断する。

5. オペレーターの確認後、範囲を限定した是正をプレビューおよび実行する。

6. または、高リスクのアクションを実行せずに手動レビューキューに送信する。

したがって、MCPはコアとなるプロダクトインターフェースであり、別のアプリケーションに追加で統合するものではありません。

セーフティモデル

すべてのコマースオペレーションに同じレベルのAI自律性を与えるべきではありません。Ops Lenseはアクションを3つのカテゴリに分類します。

確認フロー

resync_inventory_reservationは保護された書き込み操作です。

最初の呼び出し：

confirmed=false

サーバーは注文を検証し、データベースを変更せずに提案された効果を返します。

オペレーターがアクションを明示的に承認した後、クライアントは以下を呼び出すことができます。

confirmed=true

サーバーは範囲を限定した変更を実行し、監査エントリを記録します。

手動レビューフロー

重要なアクションは、直接的なMCP変更として意図的に利用できません。request_manual_reviewは、代わりにpending_review監査エントリを作成します。

別のオペレーターがこれらのリクエストをレビュー、承認、実行する別のプロセスは、この課題の範囲外です。保留中のリクエストはlist_manual_reviewsを通じて表示可能です。

MCPツール

MCPリソース

Ops Lenseは1つの運用リソースを公開します。

ops://action-policy

これは、3つのアクションカテゴリと、MCPクライアントがツールを選択または実行する際に従うべきルールを説明します。

ユーザーのリクエストの表現方法に関係なく、この安定した運用ポリシーが利用可能であるべきであるため、MCPプロンプトではなくリソースを選択しました。専用のプロンプトは、この意図的に狭いワークフローにほとんど価値を追加しません。

エンドツーエンドのワークフロー例

代表的なインシデントは、支払いが正常にキャプチャされたが、在庫予約ステップが欠落している注文です。

1. オペレーターが注文がスタックしている理由を尋ねます。

2. AIは、注文を見つける必要がある場合、search_ordersを使用します。

3. get_order_timelineを呼び出して、何が起こったかを調査します。

4. diagnose_orderを呼び出して、支払いと運用状態を関連付けます。

5. 診断によりINVENTORY_RESERVATION_MISSINGが特定され、resync_inventory_reservationが推奨されます。

6. AIはconfirmed=falseでツールを呼び出し、提案された是正措置をオペレーターに表示します。

7. オペレーターが承認します。

8. AIはconfirmed=trueで再度ツールを呼び出します。

9. MCPが是正措置を実行し、監査レコードを書き込みます。

10. AIは再度get_order_timelineを呼び出して、結果の状態を確認します。

高リスクのリクエストは異なるパスをたどります。たとえば、オペレーターが返金を要求した場合、MCPは支払い状態を変更するのではなく、手動レビューリクエストを作成します。その後、リクエストはlist_manual_reviewsで検査できます。

これにより、デモは調査→診断→人間による確認→変更→検証→エスカレーションという一貫したストーリーを提供します。

アーキテクチャ

MCP-enabled AI client
        |
        | Streamable HTTP
        v
   Ops Lense MCP
        |
        +-- Investigation tools
        +-- Diagnostic logic
        +-- Safety / action policy
        +-- Guarded actions
        |
        v
   Neon PostgreSQL
   synthetic commerce data

テクノロジー：

• TypeScript

• ローカル開発とスクリプト用のBun

• Heroku上のNode.js 24

• Model Context Protocolサーバーパッケージ

• Express HTTPトランスポート

• Neon PostgreSQL

• Zod入力バリデーション

合成データは、ワークフローに必要な最小限のバックエンドシステム（顧客、注文、支払い、在庫、フルフィルメント、運用イベント、調査履歴、アクション監査レコード）をモデル化しています。

ローカルでの実行

前提条件

以下が必要です。

• Bun

• PostgreSQLデータベース（ホストされたデモにはNeonが適しています）

1. 依存関係のインストール

bun install

2. 環境変数の設定

プロジェクトルートに.envファイルを作成します。

DATABASE_URL=postgresql://YOUR_DATABASE_URL
MCP_AUTH_TOKEN=YOUR_STRONG_RANDOM_TOKEN
PORT=3000

3. 合成データベースの作成

bun scripts/setup-db.ts

このコマンドは、課題のテーブルをドロップして再作成します。保持する必要があるデータを含むデータベースに対して実行しないでください。

4. デモデータのシード

bun scripts/seed-db.ts

シードされたすべての顧客、注文、支払い、在庫、フルフィルメントレコードは合成データです。

5. MCPサーバーのビルドと起動

bun run build
bun run start

bun run buildはTypeScriptをdist/にコンパイルします。次に、startコマンドがコンパイルされたサーバーをNodeで実行し、Herokuのランタイムパスと一致させます。

ローカルのMCPエンドポイントは次のとおりです。

http://localhost:3000/mcp

Herokuへのデプロイ

リポジトリには、npm startでWeb dynoを起動するProcfileが含まれています。HerokuはTypeScriptプロジェクトをビルドし、コンパイルされたNode.jsサーバーを実行します。

1. Herokuアプリの作成

heroku create YOUR_APP_NAME

2. データベースの設定

PostgreSQL接続文字列と、MCPエンドポイントを保護するために使用される強力なベアラートークンを設定します。

heroku config:set DATABASE_URL="YOUR_DATABASE_URL" MCP_AUTH_TOKEN="YOUR_STRONG_RANDOM_TOKEN" -a YOUR_APP_NAME

Herokuは自動的にPORTを提供するため、手動で設定する必要はありません。

3. デプロイ

git push heroku HEAD:main

デプロイ中、HerokuはNodeの依存関係をインストールし、buildスクリプトを実行します。その後、Web dynoが起動します。

node dist/index.js

ホストされたMCPエンドポイントは次のようになります。

https://YOUR_APP_NAME.herokuapp.com/mcp

Herokuアプリがカスタムドメインを使用している場合は、そのドメインを/mcpとともに使用します。

4. デプロイの確認

heroku logs --tail -a YOUR_APP_NAME

MCPサーバーが起動し、Herokuの割り当てられたポートにバインドするのが確認できるはずです。

合成データベースは、同じDATABASE_URLを使用してローカルマシンからデプロイ前に初期化するか、Bunがその環境で利用可能な場合は、セットアップスクリプトとシードスクリプトを1回限りのHerokuコマンドとして実行することで初期化できます。最も簡単なデプロイパスとしては、サーバーをデプロイする前にローカルでNeonを初期化およびシードしてください。

AIクライアントからの接続

Ops LenseはリモートHTTP MCPエンドポイントを使用します。リモート/Streamable HTTPサーバーをサポートするMCPクライアントで、エンドポイントとベアラートークンを追加します。

{
  "serverUrl": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_STRONG_RANDOM_TOKEN"
  }
}

デプロイされたインスタンスの場合は、ローカルURLをホストされたMCP URLに置き換え、サーバーでMCP_AUTH_TOKENとして設定された同じトークンを使用します。

接続後、クライアントはツールとops://action-policyリソースを自動的に検出するはずです。

その後、自然に開始できます。例：

Show me recent orders that may need attention.

Why is this order stuck? Investigate it and tell me what we can safely do.

Show me all actions currently waiting for manual review.

確認が必要な操作の場合、AIはプレビューをオペレーターに提示し、confirmed=trueで2回目のツール呼び出しを行う前に明示的な承認を得る必要があります。

MCP Inspectorでの接続

MCP Inspectorは、チャットクライアントとは独立してサーバーをテストするのに役立ちます。

ローカルサーバーが実行中の状態で：

npx @modelcontextprotocol/inspector

Inspectorで、以下に接続します。

http://localhost:3000/mcp

その後、検出されたツール/リソースを検査し、手動でワークフローを呼び出すことができます。

検証

プロジェクトの型チェックを行います。

npm run typecheck

設定された合成データベースに対して、焦点を絞ったVitest統合スイートを実行します。

npm test

tests/operations.test.tsのテストは、分離された一時レコードを作成し、PostgreSQLに対して実際のツール関数を実行し、その後それらのレコードを削除します。これらは以下を検証します。

• キャプチャされた支払いと欠落した予約でINVENTORY_RESERVATION_MISSINGが生成されること。

• 終端状態の注文がアクティブな在庫障害として診断されないこと。

• confirmed=falseは変更を実行しないこと。

• confirmed=trueは範囲を限定した在庫是正を実行し、監査エントリを記録すること。

• 既に完了した再同期を繰り返しても安全で何も起こらないこと。

• 返金リクエストは支払い状態を変更せずにレビュー用にキューに入れられること。

• 重複した保留中のレビューリクエストは抑制されること。

スイートには現在8つの統合テストが含まれています。正常に実行されると8 passedと報告されます。

これらのテストは、広範なカバレッジ指標ではなく、ワークフローとセーフティ境界に意図的に焦点を当てています。

主要なプロダクト決定

ワークフローを狭く保つ

この課題は、完全なコマースバックエンドを構築しようとするものではありません。スタックした注文の操作は、複数のシステム、診断、是正、安全性、検証を含むコンパクトなワークフローを提供するため選択されました。

AIに有用な自律性を与えるが、無制限の書き込みアクセスは与えない

すべての操作を読み取り専用にすると、単純なインシデントを解決するためにもオペレーターは別のシステムに依存することになります。すべての変更を許可すると、不必要な運用リスクが生じます。

3層モデルは中間の道を提供します。調査は自動化され、範囲を限定した是正にはオペレーターの確認が必要であり、重大なアクションは手動レビューの背後に残ります。

重要なアクションをMCP実行の対象外にする

返金や同様の操作は、この合成プロジェクトではデータベース変更として技術的に表現可能ですが、そうすることは誤った本番動作を示すことになります。代わりにMCPはレビューリクエストを作成し、境界を明確にします。

MCPの表面積を小さく保つ

公開される各ツールは、選択されたワークフローにおいて明確な役割を持っています。目標は、利用可能なツールの数を最大化することではなく、AIクライアントがツールを確実に選択できるようにすることです。

範囲と前提条件

含まれるもの：

• 合成コマースデータ

• 注文調査

• サポートされているスタック注文状態の決定論的診断

• 保護された在庫是正

• 監査ログ

• 手動レビューキュー

• リモートアクセス可能なMCPインターフェース

意図的に除外されるもの：

• フロントエンド/管理ダッシュボード

• 実際の顧客データ

• 本番の支払いまたは倉庫の認証情報

• ユーザーアカウント、セッション、OAuth、ロールベースのアクセス制御

• 直接的な返金実行

• 手動レビューの承認/実行UI

• 完全なコマースバックエンド

• 広範な返品、不正、カタログ、カスタマーサポートのワークフロー

ホストされたアサインメントサーバーは、MCPを公開しないように単一のベアラートークンを使用しています。本番システムでは、アイデンティティを認識した認証、認可/RBAC、シークレットローテーション、より強力な同時実行制御、プロバイダー固有の統合、可観測性、そして完全なレビューワークフローを追加する必要があります。

リポジトリ構造

src/
  index.ts
  db.ts
  resources.ts
  tools/
    diagnose-order.ts
    get-stats.ts
    get-timeline.ts
    list-manual-reviews.ts
    request-manual-review.ts
    resync-inventory.ts
    search-orders.ts
scripts/
  setup-db.ts
  seed-db.ts
tests/
  operations.test.ts
vitest.config.ts

AI作業ログ

このセクションには、提出前の課題における実際のAI使用状況を含める必要があります：

• 使用したAIコーディングツールと正確なモデル

• 各モデルがそのタスクに選ばれた理由

• 作業の計画と分解方法

• AIと開発者が担当した責任

• AIに提供した重要なプロンプト/コンテキスト

• 拒否された、または大幅に変更されたAIの提案が少なくとも1つ

• AIが生成した作業のレビューと検証方法

• 残存リスクまたは未完了の作業

開発中に変更された製品上の決定の1つは、結果を伴う操作の扱いでした。返金や同様の重要なアクションを実行可能なMCPツールとして公開する代わりに、手動レビューキューに移しました。これにより、有用なAIの自律性を維持しつつ、財務的または運用的に結果を伴う決定をモデルの直接実行の外に置くことができます。

提出物

• ホストされたMCPのURL

• ソースリポジトリのURL

• このREADME

• 重要なワークフローの動作に対する検証/テスト

• 完了したAI作業ログ

• 4～5分の非同期デモ

デモはコードのウォークスルーよりも実際の製品ワークフローを優先する必要があります：注文を調査し、診断し、安全な修復をプレビューし、確認し、結果を検証し、その後、重要なアクションが手動レビューにルーティングされる方法を示します。