内容
# `@amplytools/amply-mcp`
适用于 [Amply](https://amply.tools) 的本地 MCP 服务器 — 让您的 AI 代理可以注册、登录、创建项目、注册应用程序并获取 API 密钥，而无需打开 Amply 管理界面。与 [`amply-integration` 技能](../amply-skill/) 配合使用，实现无需手动干预的 SDK 集成。
## 为什么存在
当代理将 Amply SDK 集成到移动应用程序中时，仍然需要人类执行以下操作：
1. 在 `amply.tools` 上注册。
2. 创建项目。
3. 注册应用程序（bundleId + 平台）。
4. 从管理界面复制 `appId` / `apiKeyPublic` / `apiKeySecret` 到 `.env.local`。
此 MCP 消除了步骤 1-4。代理调用 `amply_ensure_app` 并获取可直接粘贴的 env 块。
## 安装
### Claude 代码
```bash
claude mcp add amply -- npx -y @amplytools/amply-mcp
```
首次发布到 npm 之后。在此之前，请从本地检出进行安装：
```bash
git clone https://github.com/amply-tools/sdk-mcp.git
cd sdk-mcp && yarn install && yarn build
claude mcp add amply -- node "$(pwd)/dist/index.js"
```
### Codex CLI
```bash
codex mcp add amply -- npx -y @amplytools/amply-mcp
```
（语法取决于 Codex CLI 版本 — 在 `codex-cli 0.128` 上验证。如果不确定，请先运行 `codex mcp --help`；较旧的版本使用 `--command` / `--args` 标志。）
### 其他主机
任何支持 stdio 服务器的主机都可以直接启动捆绑的 `dist/index.js`。二进制文件通过 stdin/stdout 讲述标准的 MCP JSON-RPC 协议。
## 配置
| 环境变量 | 目的 | 默认值 |
| --- | --- | --- |
| `AMPLY_ENDPOINT` | 重写 GraphQL 端点。传递完整 URL（`https://api.amply.tools/mcp/`）或仅主机 — `/mcp/` 会自动追加。 | `https://api.amply.tools/mcp/` |
| `AMPLY_CREDS_FILE` | 重写 JWT + 刷新令牌的持久化位置。必须是绝对路径。 | `~/.amply/credentials.json` |
| `AMPLY_MCP_DEBUG` | 设置为 `1` 以发出诊断 stderr 日志（带有机密删除）。 | 未设置 |
端点也可以作为 `--endpoint <url>` 传递给二进制文件。
## 工具
| 工具 | 功能 |
| --- | --- |
| `amply_status` | 报告当前端点 + 是否缓存凭证。永不命中网络。 |
| `amply_signup` | 创建新帐户 + 组织。缓存会话。 |
| `amply_login` | 登录现有帐户。缓存会话。 |
| `amply_logout` | 清除缓存的会话。 |
| `amply_whoami` | 返回当前用户 + 组织（调用 `me` 查询）。 |
| `amply_list_projects` | 列出项目（分页）。 |
| `amply_create_project` | 创建项目。 |
| `amply_list_applications` | 列出项目下的应用程序（需要 projectId）。 |
| `amply_get_application` | 获取具有 API 密钥的应用程序。 |
| `amply_create_application` | 注册新应用程序；返回自动生成的第一个 API 密钥。 |
| `amply_create_api_key` | 为现有应用程序颁发其他 API 密钥。 |
| `amply_ensure_app` | 幂等项目 + 应用程序 + API 密钥解析。返回 `created` / `reused` / `reused_new_key` / `conflict_cross_project`。 |
| `amply_find_application` | 纯只读发现；当省略 `projectId` 时，会分页遍历组织中的每个项目。 |
| `amply_list_campaigns` | 列出应用程序的活动。 |
| `amply_get_campaign` | 获取具有触发、定位和内容的单个活动。 |
| `amply_set_campaign_state` | 激活、暂停或存档活动。 |
| `amply_create_campaign_from_template` | 从精选模板创建活动。始终为草稿；显式激活。 |
| `amply_create_campaign` | 从完整定义（事件属性过滤器、每 N 次重复、设备/自定义属性定位）创建活动。始终为草稿。 |
| `amply_update_campaign` | 就地编辑活动；顶级替换；保留当前状态。 |
| `amply_describe_targeting` | 描述定位 + 触发词汇（插槽、比较器、谓词形状）。 |
每个工具都在 MCP `content[0].text` 块内返回 JSON 正文。在失败时，设置 `isError: true`，JSON 包含 `{ error: { code, message, hint? } }`，其中 `code` 为以下之一：`auth_required`、`invalid_credentials`、`not_found`、`validation_error`、`conflict`、`access_denied`、`network_error`、`graphql_error`、`internal_error`。
## 安全模型
- **JWT + 刷新令牌以明文缓存在** `~/.amply/credentials.json` 中，模式为 `0600`。这对于开发机器来说是可以接受的，但 **不要** 在共享机器上使用或将凭证文件提交到任何地方。令牌不会通过任何工具的响应返回。
- **“机密”API 密钥** (`apiKeySecret`) 是一个真正的机密，因为后端在创建时只会返回一次。然而，它旨在嵌入到您的移动应用程序的包中 — 它是一个每个应用程序的标识符，而不是服务器端管理员密钥。不要跨应用程序共享它，也不要将其提交到公共存储库中。
- **stdio 传输** 意味着 MCP 写入 stdout 的任何内容都是协议的一部分。服务器完全避免 stdout 日志记录；诊断输出通过 `AMPLY_MCP_DEBUG=1` 进入 stderr，并使用正则表达式扫描删除十六进制机密字符串后写入。
- **`AMPLY_CREDS_FILE`** 必须是绝对路径。相对路径、包含 `..` 的路径和常见代码存储库目录下的路径在启动时会被标记。原子写入（`tmp` + `rename`）减少（但不消除）刷新令牌旋转时部分写入的可能性；如果发生部分写入，用户将被注销并必须重新登录。
## 代理的典型流程
```
amply_status → { authenticated: false, ... }
amply_signup({email, password, name, organization})
→ 缓存会话
amply_ensure_app({bundleId: "com.acme.app", name: "Acme", platform: "iOS",
projectName: "Acme"})
→ { application, firstApiKey: { public, secret }, envBlock, status: "created" }
```
代理将 `envBlock` 粘贴到 `.env.local` 并完成。
## 开发
```bash
yarn install
yarn build # tsup → dist/index.js (具有依赖项的单个 ESM 文件)
yarn typecheck # tsc --noEmit, 严格
yarn dev # tsup 监视
yarn smoke # 针对本地存根的 JSON-RPC 烟雾测试
```
## 许可证
Apache 2.0 — 与 Amply SDK 相同。
