ayrshare-social-media-api-claude-plugin

# Ayrshare for Claude 代码 适用于 AI 代理的统一社交媒体 API。在 Claude 代码中直接发布、安排和分析 13+ 个网络的帖子，查看历史记录以匹配品牌声音，并针对每个平台的规则进行验证后再发布。由 [Ayrshare](https://www.ayrshare.com) API 提供支持。 ## 安装 ```bash claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin claude plugin install ayrshare@ayrshare ``` 然后运行 `/ayrshare:setup` 添加您的 API 密钥并 **重启 Claude 代码**。范围和其他安装路径在下面的 [安装](#installation) 中。 安装后，通过 **用纯英文询问**（例如，“显示我最近的 Instagram 帖子”，“明天 9 点在 LinkedIn 上发布此内容”）来使用插件；工具根据意图触发，触发技能路由它们。 `/ayrshare:setup` 是唯一的斜杠命令，因此没有 `/ayrshare:post` 或 `/ayrshare:get_post_history` 需要输入。 ## 概述 该插件允许代理在不离开 Claude 代码的情况下运行完整的社交工作流。在发布之前，代理会针对目标网络的规则验证每个帖子，并要求您确认，这样可以避免在内容上线之前进行可避免的拒绝。单个请求可发布到 Facebook、Instagram、LinkedIn、X、TikTok、YouTube、Pinterest、Reddit、Telegram、Threads、Bluesky 等。发布历史记录可用于匹配品牌声音，分析数据可以反馈以指导下一个帖子。平台集成由 Ayrshare 维护，因此上游 API 更改在您的代码之外进行处理。该 API 目前每天处理 2500 万+ 次调用。 ## 循环 - **学习**。检索一个配置文件的发布历史，以获取品牌声音的上下文，并查看过去的帖子表现如何。 - **执行**。在单个调用中发布和安排 13+ 个网络。 - **观察**。读取实时分析数据，以指导下一个帖子。 - **保持安全**。在发布前验证每个帖子是否符合平台规则，然后确认。 --- ## 为什么使用 API 而不是自定义集成？ LLM 可以生成 OAuth 流，但它不涵盖 Meta Tech Provider 批准、X 的按使用付费 API 更改或网络更改其规则时的持续维护。插件处理： - **发布前验证**。`validate_post` 在发布前针对每个网络的规则（长度、格式、媒体要求）进行内容验证，`validate_media` 在 `mediaUrls` 中附加媒体 URL 之前检查媒体 URL 是否可达。X BYOK 支持 2026 年强制执行，平台集成得以维护，因此上游 API 更改不会破坏您的集成。 - **一次调用，13+ 个网络**。单个请求发布到所有连接的平台，每个平台都针对其自己的规则进行验证。 - **多租户**。代表许多用户配置文件发布，而不是单个品牌。 - **历史 API**。检索配置文件的过去帖子，以获取品牌声音的上下文，并使用历史性能数据指导未来帖子。 ### 安全 默认情况下，插件验证帖子并在发布前请求确认。代理准备草稿；用户批准。 --- ## 先决条件 - [Claude 代码](https://claude.ai/code) 已安装 - Ayrshare 账户，带有 API 密钥 - 在 [app.ayrshare.com](https://app.ayrshare.com) 的 **设置 → API 密钥** 下获取一个，或[在此处获取 28 天免费试用](https://billing.ayrshare.com/b/9B6bJ15Oidr9fz615u1Nu0h?utm_source=github) --- ## 安装 ### 插件安装范围 插件范围控制命令、代理和技能在何处可用。首先，将此存储库注册为市场（一次性）： ```bash claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin ``` 然后在您想要的范围内安装 `ayrshare` 插件（`plugin@marketplace`）： | 范围 | 命令 | 可用位置 | |---|---|---| | 全局（默认） | `claude plugin install ayrshare@ayrshare` | 此机器上的每个项目 | | 仅限此项目 | `claude plugin install ayrshare@ayrshare --scope local` | 当前项目，不提交到 git | | 此项目（共享） | `claude plugin install ayrshare@ayrshare --scope project` | 当前项目，与团队一起提交到 git | 安装后，配置您的 API 密钥： ```text /ayrshare:setup ``` `/ayrshare:setup` 将要求您提供密钥以及存储位置 — 选择与您安装插件的方式相匹配的选项。 --- ### 详细步骤 #### 全局 — 在所有项目中可用 ```bash # 1. 注册市场（一次性） claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin # 2. 全局安装插件（用户是默认范围） claude plugin install ayrshare@ayrshare # 3. 配置您的 API 密钥（在 ~/.claude/settings.json 中设置 AYRSHARE_API_KEY） # 在 Claude 代码中运行： /ayrshare:setup # 接受默认的“全局”选项 ``` 命令、代理和技能在每个项目中都可用。密钥存储为 `AYRSHARE_API_KEY`，位于 `~/.claude/settings.json` 中，这正是插件的 MCP 服务器读取的内容。不会修改任何项目文件。 --- #### 仅限此项目 — 本地，不提交 ```bash # 1. 注册市场（一次性） claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin # 2. 安装到当前项目（不提交到 git） claude plugin install ayrshare@ayrshare --scope local # 3. 配置您的 API 密钥（在 ./.claude/settings.local.json 中设置 AYRSHARE_API_KEY） # 在 Claude 代码中运行： /ayrshare:setup # 选择“此项目”选项 ``` 命令、代理和技能仅在该项目中出现。密钥写入 `./.claude/settings.local.json`，因此它不会被提交到 git。确保该路径在您的 `.gitignore` 中（默认的 `*.local` 模式 **不** 匹配 `settings.local.json`），并确认 `git status` 不会列出它。使用已提交的 `./.claude/settings.json` 仅当您故意要通过存储库与团队共享一个密钥时（不推荐用于机密）。 --- #### 此项目 — 与团队提交 ```bash # 1. 注册市场（一次性） claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin # 2. 安装到项目（提交到 git） claude plugin install ayrshare@ayrshare --scope project # 3. 配置您的 API 密钥（在 ./.claude/settings.local.json 中设置您的密钥；gitignore 该路径） # 在 Claude 代码中运行： /ayrshare:setup # 选择“此项目”选项 ``` 插件提交到存储库，因此整个团队可以自动获取。每个开发人员分别运行 `/ayrshare:setup` 以配置他们自己的 API 密钥。每个开发人员的密钥应位于 `./.claude/settings.local.json` 中，并且该路径应添加到 `.gitignore` 中（默认的 `*.local` 模式 **不** 匹配 `settings.local.json`），以便密钥永远不会被提交。 --- ### 仅限 MCP（无插件） 如果您只想要原始 MCP 工具，而没有命令、代理或技能： ```bash claude mcp add ayrshare --transport http \ https://api.ayrshare.com/mcp \ --header "Authorization: Bearer YOUR_API_KEY" ``` 添加 `--scope local` 以限制在当前项目中。密钥永久存储在 Claude 代码的配置中 — 运行一次，您就完成了。 --- ### 环境变量（CI / 高级） 对于 CI 环境或通过 shell 配置文件管理环境变量的用户： ```bash export AYRSHARE_API_KEY=your_key_here claude plugin marketplace add ayrshare/ayrshare-social-media-api-claude-plugin claude plugin install ayrshare@ayrshare ``` 插件的 `.mcp.json` 使用 `${AYRSHARE_API_KEY}` — Claude 代码在启动时替换它。不需要设置命令。 --- ## 各个界面凭证 安装插件一次。插件读取相同的四个变量（`AYRSHARE_API_KEY` 是必需的；`AYRSHARE_PROFILE_KEY`、`X_TWITTER_OAUTH1_API_KEY` 和 `X_TWITTER_OAUTH1_API_SECRET` 是可选的），但 *在哪里* 您提供它们取决于界面，而目前唯一完全支持的界面是 **Claude 代码**： | 界面 | 如何提供凭证 | 配置文件密钥 | X BYOK | |---|---|---|---| | **Claude 代码**（CLI / IDE / 桌面“代码”选项卡） | `settings.json` `env` 块通过 `/ayrshare:setup`（或自己设置变量）；在启动前进行 shell `export` 也有效 | `AYRSHARE_PROFILE_KEY` 环境变量，或每个调用的 `profileKey` 参数 | `X_TWITTER_OAUTH1_API_KEY` + `X_TWITTER_OAUTH1_API_SECRET` 环境变量 | | **Cowork / claude.ai 桌面应用** | **尚不支持。** 技能已安装，但 API 工具无法在那里验证：Cowork 不读取 `settings.json` `env` 或扩展 `${VAR}`，连接器 UI 仅限 OAuth（每次调用 `403`），而 Claude 代码托管的 MCP 配置不适用于 Cowork。需要 OAuth（参见 [路线图](#roadmap)）。 | 暂不可用 | 暂不可用 | | **CI / 无头** | 启动前设置的操作系统环境变量 | `AYRSHARE_PROFILE_KEY` 环境变量 | 两个环境变量 | 为 Claude 代码设置的密钥 **不会** 转移到 Cowork：`${VAR}` 插值是 Claude 代码的功能，而 Cowork 没有支持的凭证提供方式（参见下文）。因此， `/ayrshare:setup` 中的“Claude 代码，所有项目”选项意味着所有 Claude 代码项目，而不是所有 Claude 界面。 ## Cowork 和桌面应用（尚不支持） 插件的技能安装在 Cowork 和 claude.ai 桌面应用中，但其 API 工具 **无法在那里验证**。根据路由，工具要么无法加载，要么出现但每次调用都返回身份验证错误。这是平台限制，而不是您可以更改的设置： - Cowork 不读取 `~/.claude/settings.json` `env`，也不扩展 `${VAR}`，因此捆绑的 `.mcp.json` `Authorization` 标头保持为空， `/ayrshare:setup` 永远不会到达它。 - 将 Ayrshare 添加为 **claude.ai / org 连接器** 会加载工具，但不提供 `Authorization` 标头的字段，因此每次调用都返回 `403`（`code 102`）。 - Claude 代码 **托管的 mcp.json**（管理员/企业托管的 MCP 配置文件；参见 [托管 MCP 文档](https://code.claude.com/docs/en/managed-mcp.md)）**不适用于** Cowork；它是 Claude 代码的功能。部署一个不会帮助 Cowork，它会占用 MCP 的独家、机器范围控制，抑制此插件的服务器和您的其他 MCP 服务器 **在 Claude 代码中**。不要为 Cowork 使用它。 解决方法是每个用户的 MCP 端点 OAuth 2.1（参见 [路线图](#roadmap)）。在此之前，请在 **Claude 代码**（CLI、IDE 或桌面 **代码** 选项卡）中使用插件，其中 `/ayrshare:setup` 在几秒钟内配置它。 --- ## 命令 | 命令 | 描述 | |---|---| | `/ayrshare:setup` | 配置或轮换您的 API 密钥 | 前 `/ayrshare:post`、`/ayrshare:analytics` 和 `/ayrshare:profiles` 命令已合并到 **social-manager** 和 **profile-manager** 代理以及下面的基于触发器的技能中。 --- ## 技能 基于触发器的技能根据意图自动激活（即使您没有提及 Ayrshare），并教会 Claude 如何正确驱动 MCP 工具：身份验证模型（API 密钥，以及可选的按 `Profile-Key` 头或每个调用的 `profileKey` 参数选择的配置文件），重试安全性和平台怪癖。它们涵盖了服务器的 27 种工具。**从 `getting-started` 开始**；每个组技能都链接到它。 | 技能 | 工具 | 何时使用 | |---|---|---| | `getting-started` | （跨切割） | 安装/配置插件，任何 401/403，“我使用哪个凭证”，为客户配置，缺少 `AYRSHARE_API_KEY`。身份验证模型（API 密钥，以及 `Profile-Key` 头或每个调用的 `profileKey` 参数），引导序列，重试/ `explain_error` 规则和免费试用链接。 | | `post` | `create_post`，`validate_post`，`get_post`，`update_post`，`retry_post` | 验证、发布、安排、编辑、获取或重试社交内容。 | | `history` | `get_post_history`，`get_platform_history` | 列出通过 Ayrshare 发送的帖子，或原生帖子（包括非通过 Ayrshare 创建的帖子），并查找原生社交帖子 ID。 | | `analytics` | `get_post_analytics`，`get_post_analytics_by_social_id`，`get_social_network_analytics` | 每个帖子的分析数据（按 Ayrshare 或原生社交帖子 ID），或账户/网络分析数据（关注者、覆盖范围、印象）。 | | `comments` | `get_comments`，`add_comment`，`reply_comment` | 读取、添加或回复帖子的评论。 | | `messages` | `get_messages`，`send_message`，`get_auto_response`，`set_auto_response` | 读取/发送直接消息（Facebook、Instagram、X）或配置 DM 自动回复。 | | `profiles` | `list_profiles`，`create_profile`，`generate_jwt_social_linking_url` | 创建或列出客户端配置文件（账户级别），或为目标配置文件生成客户端的社交账户链接 URL（由 `profileKey` 参数或 `Profile-Key` 头设置；商业/企业计划）。 | | `media` | `validate_media` | 在发布前检查媒体 URL 是否可达（媒体按 URL 引用；没有上传/库/调整大小工具）。 | | `generate` | `generate_post`，`recommend_hashtags` | 起草 AI 帖子副本（从不发布）或为关键词建议哈希标签（源自 TikTok；使用目标配置文件的链接 TikTok 账户）。 | | `webhooks` | `register_webhook`，`unregister_webhook`，`list_webhooks` | 订阅推送通知（例如，当预定帖子发布时）而不是轮询。 | | `errors` | `explain_error` | 将 Ayrshare 错误代码解码为纯英文原因 + 修复。 | | `draft-in-brand-voice` | （工作流：`get_platform_history`/`get_post_history` → `get_post_analytics` → `generate_post` → `validate_post`） | 通过从配置文件历史记录中匹配已建立的声音来编写品牌内容；仅限草稿。 | | `plan-and-schedule-campaign` | （工作流：`validate_post` → `create_post` 每个帖子，带有 `scheduleDate`） | 计划和安排多帖子、多平台活动或内容日历，在验证每个帖子。 | 最后两个是多步骤 **工作流** 技能：它们协调上面的工具，而不是添加新的工具。工具名称遵循插件的 `mcp__ayrshare__<action>` 约定（例如 `mcp__ayrshare__create_post`）。 --- ## 可选配置 API 密钥通过 `AYRSHARE_API_KEY` 环境变量提供，该变量由 `ayrshare` 服务器的 `.mcp.json` 插入到其 `Authorization` 标头（`Bearer ${AYRSHARE_API_KEY}`）中。 `/ayrshare:setup` 为您设置该变量在 `settings.json` `env` 块中。 配置文件范围有两个等效输入：`Profile-Key` 连接头（每个调用的默认值）或可选的 `profileKey` 工具参数（参数优先于标头；少数实用程序/AI 工具除外，例如 `generate_post` 和 `recommend_hashtags`，参见 `getting-started`）。捆绑的 `.mcp.json` 已经声明可选的 `Profile-Key` 和 X BYOK 标头，带有空默认值（`${VAR:-}`），因此您通过在任何操作系统上的相同 `settings.json` `env` 块中设置匹配的环境变量（与 `AYRSHARE_API_KEY` 相同）并重启来启用每个。保留一个变量未设置，其标头将为空，服务器将其视为未提供。无需编辑 `.mcp.json`，在 `claude plugin update` 之后无需重新操作。 ### 作为特定客户端配置文件（`AYRSHARE_PROFILE_KEY` 或 `profileKey` 参数） 在您的 `settings.json` `env` 中设置 `AYRSHARE_PROFILE_KEY`（在您的启动）以将整个连接默认为一个客户端；捆绑的 `Profile-Key: ${AYRSHARE_PROFILE_KEY:-}` 标头随之携带。未设置时，调用将作用于帐户的主要配置文件。要在单个调用中代替作为客户端，请在配置文件范围的调用上将 `profileKey` 作为工具参数传递（它优先于标头，无需重新启动）。`generate_jwt_social_linking_url` 工具使用相同的目标配置文件值（通过任一输入要求）。您不会传递私钥或域（服务器从您的身份验证帐户派生它们），但帐户仍必须有一个 **已配置的社交链接域（商业/企业）**；如果没有，则调用将返回“未为此帐户配置社交链接域”的错误。 ### 自带 X/Twitter 应用（BYOK） 发布到 X/Twitter 需要您自己的 X 开发者应用（[X BYO-key 强制执行](https://www.ayrshare.com/docs/apis/overview#x/twitter-byo-credentials)，有效期至 2026 年 3 月 31 日）。链接 X 与您的应用凭证后，设置 **两个** 环境变量并重启（值永远不会被记录）： - `X_TWITTER_OAUTH1_API_KEY`：您的 X API 密钥（消费者密钥）；作为 `X-Twitter-OAuth1-Api-Key` 标头发送。 - `X_TWITTER_OAUTH1_API_SECRET`：您的 X API 机密（消费者机密）；作为 `X-Twitter-OAuth1-Api-Secret` 标头发送。 这些是 Ayrshare 使用的唯一 X BYO 标头：每个 Ayrshare 账户使用一对密钥，在每个针对 X 的请求中发送（所有子配置文件使用相同的密钥对）。Ayrshare 在此处 **不** 使用 OAuth 2.0 客户端凭证。设置两者或都不设置：设置两者或都不设置：设置两个值时，X/Twitter 请求将返回错误 `419`（`x_credentials_required`）；只设置一个值时，将返回错误 `400`。 --- ## 支持的平台 Facebook、Instagram、LinkedIn、X（Twitter）、TikTok、YouTube、Pinterest、Reddit、Telegram、Threads、Bluesky、Snapchat 和 Google Business Profile — 取决于您的 Ayrshare 计划和连接的配置文件。 --- ## 路線图 - **每用户零配置身份验证（MCP OAuth 2.1）：我们首要的身份验证优先级。** 这是使 Cowork 和 claude.ai 桌面应用成为一流界面的唯一途径，因此它是下一个主要的身份验证投资。我们计划在 `api.ayrshare.com/mcp` 上添加 MCP 规范 OAuth 2.1（PKCE、动态客户端注册、授权服务器和受保护资源元数据）。一旦发布，安装的组织插件将对每个用户进行身份验证（“连接到 Ayrshare”，仪表盘登录，每个用户令牌），在 **每个** 界面上没有手动密钥步骤和没有文件。Claude 代码已经通过 `/mcp` 身份验证支持此流程，因此设置将折叠为“安装，然后点击连接”在每个地方。直到它上线，**Claude 代码** 是受支持的界面（通过 `/ayrshare:setup` 编写的 `settings.json` `env` 块），而 **Cowork 和 claude.ai 桌面应用不受支持**，因为插件的承载标头 MCP 服务器无法在那里验证。 --- ## 资源 - [Ayrshare API 文档](https://docs.ayrshare.com) - [Ayrshare 仪表盘](https://app.ayrshare.com) - [Claude 代码文档](https://docs.anthropic.com/claude-code)