> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 工具目錄

> Ayrshare MCP Server 提供的 27 個工具 —— 涵蓋貼文、歷史、分析、留言、私訊、設定檔、媒體、產生、Webhook 與錯誤 —— 按領域分組，包含適用範圍與用途。

Ayrshare [MCP Server](/additional/mcp-action-server) 一共提供 **27 個工具**，下方按領域分組列出。每個工具都會在行程內透過真實的 Ayrshare API 處理鏈進行分派。

## 適用範圍

每個工具的適用範圍不是 **Profile（設定檔級）**，就是 **Account（帳戶級）**：

<ul class="custom-bullets">
  <li>**Profile** —— 工具接受 `profileKey` 參數，以某個子設定檔為目標。</li>
  <li>**Account** —— 工具 **不接受** `profileKey`，它在帳戶層級執行操作。</li>
</ul>

**不接受** `profileKey` 參數的 6 個工具為：`create_profile`、`list_profiles`、`explain_error`、`validate_media`、`generate_post` 與 `recommend_hashtags`。其他所有工具都接受 `profileKey`;其中 `generate_jwt_social_linking_url` **必須** 提供 `profileKey`。注意：`recommend_hashtags` 雖然不接受 `profileKey` 參數，但它仍會讀取連線上的 `Profile-Key` 標頭，以決定使用哪一個已連結的 TikTok 帳戶，因此其結果與特定設定檔相關。

當本次呼叫的 `profileKey` 參數與 `Profile-Key` 標頭同時存在時，參數優先生效。優先順序規則詳見 [Connect & Setup](/additional/mcp-action-connect#precedence-argument-wins-over-header)。

## 貼文（Posts）

| 工具              | 適用範圍    | 用途                                    |
| --------------- | ------- | ------------------------------------- |
| `create_post`   | Profile | 發布到一個或多個已連結的平台。                       |
| `validate_post` | Profile | 試跑（dry-run）驗證，輸入格式與 `create_post` 相同。 |
| `get_post`      | Profile | 依 Ayrshare Post ID 取得某則貼文。            |
| `update_post`   | Profile | 更新已排程或等待審核的貼文。                        |
| `retry_post`    | Profile | 重新提交一則失敗的貼文。                          |

## 歷史（History）

| 工具                     | 適用範圍    | 用途                                                                                                                                         |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_post_history`     | Profile | 透過 Ayrshare 發送的貼文。                                                                                                                         |
| `get_platform_history` | Profile | 直接來自平台的貼文與分析資料，包含非 Ayrshare 發送的貼文。對於 X/Twitter 的 `userId` / `userName` 查詢，必須僅使用帳戶 API 金鑰;此時傳入 `profileKey` 參數或 `Profile-Key` 標頭會回傳 400 錯誤。 |

## 分析（Analytics）

| 工具                                | 適用範圍    | 用途                                                                                                                             |
| --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `get_post_analytics`              | Profile | 依 Ayrshare Post ID 取得單則貼文的指標。                                                                                                  |
| `get_post_analytics_by_social_id` | Profile | 依平台原生 Social Post ID 取得單則貼文的指標。                                                                                                |
| `get_social_network_analytics`    | Profile | 取得已連結社群帳戶的帳戶層級分析與受眾資訊。對於 X/Twitter 的 `userId` / `userName` 查詢，必須僅使用帳戶 API 金鑰;此時傳入 `profileKey` 參數或 `Profile-Key` 標頭會回傳 400 錯誤。 |

## 留言（Comments）

| 工具              | 適用範圍    | 用途         |
| --------------- | ------- | ---------- |
| `get_comments`  | Profile | 讀取某則貼文的留言。 |
| `add_comment`   | Profile | 發表最上層留言。   |
| `reply_comment` | Profile | 回覆某則留言。    |

## 訊息 / 私訊（Messages / DMs）

| 工具                  | 適用範圍    | 用途          |
| ------------------- | ------- | ----------- |
| `get_messages`      | Profile | 取得某個平台的私訊。  |
| `send_message`      | Profile | 傳送一則私訊。     |
| `get_auto_response` | Profile | 讀取私訊自動回覆設定。 |
| `set_auto_response` | Profile | 設定私訊自動回覆。   |

## 設定檔（Profiles）

| 工具                                | 適用範圍    | 用途                                  |
| --------------------------------- | ------- | ----------------------------------- |
| `list_profiles`                   | Account | 列出子設定檔。                             |
| `create_profile`                  | Account | 建立子設定檔。                             |
| `generate_jwt_social_linking_url` | Profile | 產生 JWT 社群連結 URL（必須提供 `profileKey`）。 |

## 媒體（Media）

| 工具               | 適用範圍    | 用途                                          |
| ---------------- | ------- | ------------------------------------------- |
| `validate_media` | Account | 透過 HEAD 請求檢查媒體 URL 是否可存取，並回傳 `contentType`。 |

## 產生（Generate）

| 工具                   | 適用範圍    | 用途                                                                                     |
| -------------------- | ------- | -------------------------------------------------------------------------------------- |
| `generate_post`      | Account | 以 AI 產生貼文文案。                                                                           |
| `recommend_hashtags` | Account | 依 TikTok 觀看次數資料推薦主題標籤。使用由 `Profile-Key` 標頭指定之設定檔下已連結的 TikTok 帳戶;不接受單次呼叫的 `profileKey`。 |

## Webhook

| 工具                   | 適用範圍    | 用途              |
| -------------------- | ------- | --------------- |
| `register_webhook`   | Profile | 註冊 Webhook。     |
| `unregister_webhook` | Profile | 取消註冊 Webhook。   |
| `list_webhooks`      | Profile | 列出已註冊的 Webhook。 |

## 錯誤（Errors）

| 工具              | 適用範圍    | 用途                           |
| --------------- | ------- | ---------------------------- |
| `explain_error` | Account | 將 Ayrshare 錯誤碼解讀為原因、分類與修正建議。 |

<Info>
  本目錄與線上伺服器的 `tools/list` 一致。後續還規劃了更多工具（例如 Links 相關工具）。如有疑慮，請以 `tools/list` 的回傳結果為準。本目錄由 MCP 伺服器團隊維護。
</Info>