本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# WorkSpaces 應用程式 MCP 伺服器
<a name="agent-access-mcp-server"></a>

WorkSpaces 應用程式 MCP 伺服器是一項全受管服務，為 AI 代理器提供模型內容協定 (MCP) 工具，以在串流工作階段期間與桌面應用程式互動。客服人員可以按一下按鈕、輸入文字、捲動和擷取桌面的螢幕擷取畫面。

## 概觀
<a name="agent-access-mcp-server-overview"></a>

當您在堆疊上啟用代理程式存取時，代理程式可以連線至受管 MCP 伺服器，以與桌面應用程式互動。MCP 伺服器會處理您的代理程式與串流工作階段之間的通訊。您的代理程式會傳送 MCP 工具請求，而伺服器會在桌面上執行這些請求。

MCP 伺服器託管在 AWS 雲端。您不需要安裝或維護任何伺服器元件。伺服器使用可串流 HTTP 做為其傳輸通訊協定。

## 連線至 MCP 伺服器
<a name="agent-access-mcp-server-endpoint"></a>

代理程式會在下列端點連線至 MCP 伺服器：

```
https://agentaccess-mcp.{{region}}.api.aws/mcp
```

每個請求必須包含下列項目：
+ **SigV4 簽署** — 所有請求必須使用服務名稱為 的 IAM 憑證簽署`agentaccess-mcp`。
+ **串流 URL 標頭** — 來自 `CreateStreamingURL` API 的串流 URL 必須在每個請求上做為 `X-Amzn-AgentAccess-Streaming-Session-Url`標頭傳遞。

下列 Python 範例示範如何使用 進行連線`mcp-proxy-for-aws`：

```
aws_iam_streamablehttp_client(
    endpoint="https://agentaccess-mcp.{{region}}.api.aws/mcp",
    aws_service="agentaccess-mcp",
    aws_region="{{region}}",
    headers={
        "X-Amzn-AgentAccess-Streaming-Session-Url": streaming_url,
    },
)
```

對於其他語言，您需要為傳出 MCP 請求撰寫自己的簽署邏輯，或尋找支援 SigV4 簽署的可用程式庫。

如需 的詳細資訊`mcp-proxy-for-aws`，請參閱 GitHub 上的 [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws)。

## 可用的工具
<a name="agent-access-mcp-server-tools"></a>

MCP 伺服器提供下列工具，可讓客服人員在串流工作階段期間與桌面互動。所有工具名稱都使用 `agentaccess___`字首。

### 滑鼠工具
<a name="agent-access-mcp-tools-mouse"></a>

`left_click`  
在指定的座標執行左鍵按一下。  
參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用，例如 `ctrl`或 `ctrl+shift`)。

`double_click`  
在指定的座標上執行按兩下。  
參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。

`triple_click`  
在指定的座標上執行三下點選。  
參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。

`right_click`  
在指定的座標執行滑鼠右鍵按一下。  
參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。

`middle_click`  
在指定的座標執行中間按一下。  
參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。

`left_click_drag`  
執行滑鼠左鍵從開始座標拖曳到結束座標。  
參數： `start_x`（必要）、 `start_y` （必要）、 `end_x` （必要）、 `end_y`（必要）。

`left_mouse_down`  
在指定的座標上按住滑鼠左鍵。  
參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。

`left_mouse_up`  
釋放指定座標的滑鼠左鍵。  
參數： `x`（必要）、 `y` （必要）、 `modifiers`（選用）。

`move_pointer`  
將指標移至指定的座標。  
參數： `x` （必要）、 `y`（必要）。

`scroll`  
在指定的座標上捲動滑鼠滾輪。  
參數： `x`（必要）、 `y` （必要）、 `scroll_direction`（必要 — `Up`、`Down`、 或 `Right`)`Left`、 `scroll_amount` （必要 — 在刻度中，其中 120 個刻度等於一個車輪凹口）、 `modifiers`（選用）。

### 鍵盤工具
<a name="agent-access-mcp-tools-keyboard"></a>

`type_text`  
透過模擬每個角色的鍵盤事件來輸入文字。  
參數：`text`（必要 — 最多 10，000 個字元）。

`key`  
按金鑰或金鑰組合。  
參數：`keys`（必要 — 由 加入的單一金鑰或組合`+`，例如 `a`、 `ctrl+c`或 `ctrl+shift+s`)。

`hold_key`  
在指定的持續時間內保留金鑰或金鑰組合。  
參數： `keys` （必要）、 `duration`（必要 — 1 到 30 秒）。

### 螢幕工具
<a name="agent-access-mcp-tools-screen"></a>

`screenshot`  
擷取桌面的螢幕擷取畫面。傳回的影像維度會定義所有滑鼠工具的座標空間。  
參數：`include_cursor`（選用 — 預設為 `false`)。

## 相容架構
<a name="agent-access-mcp-server-frameworks"></a>

您可以從支援可串流 HTTP 和 SigV4 簽署的任何 MCP 相容代理程式架構連線至 WorkSpaces 應用程式 MCP 伺服器。已測試下列架構：
+ [Strands Agents SDK](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) — 提供原生 MCP 用戶端支援。
+ [mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws) — 在 Python 中處理 MCP 請求的 SigV4 簽署的輕量傳輸。

## 監控
<a name="agent-access-mcp-server-monitoring"></a>

您可以透過下列服務監控客服人員活動：
+ **AWS CloudTrail** — 客服人員工作階段事件會記錄在 CloudTrail 中。您可以檢視客服人員何時連線、他們使用哪些工具，以及工作階段何時結束。工具呼叫是資料事件，需要您設定線索來記錄資料事件。如需詳細資訊，請參閱《*CloudTrail 使用者指南*》中的[記錄資料事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html)。
+ **CloudWatch** — CloudWatch 提供代理程式工作階段的操作指標。
+ **Amazon S3** — 如果您設定螢幕擷取畫面儲存，則在您指定的 Amazon S3 儲存貯體中，可以使用客服人員工作階段期間擷取的螢幕擷取畫面。螢幕擷取畫面會以下列金鑰格式儲存：

  ```
  agentaccess/screenshots/year={{YYYY}}/month={{MM}}/day={{DD}}/{{session-id}}/{{timestamp}}.png
  ```

  路徑中的 UUID 是 WorkSpaces 應用程式串流工作階段 ID。

## 開始使用
<a name="agent-access-mcp-server-get-started"></a>

若要開始使用 WorkSpaces 應用程式 MCP 伺服器，請參閱 [開始為客服人員提供 WorkSpaces 應用程式的存取權](getting-started-agent-access.md)。