内容
# 层叠MCP服务器
MCP（模型上下文协议）服务器，暴露 [层叠 API](https://api.layers.com) 作为工具，使 AI 代理可以管理项目，生成短形式社交内容，并直接从任何 MCP 客户端发布。
> 工具覆盖范围跟踪层叠 API 参考。
## 安装
```sh
claude mcp add layers -- npx -y @layers/mcp-server@latest --api-key lp_YOUR_KEY
```
或在任何 MCP 客户端的 JSON 配置中：
```json
{
"mcpServers": {
"layers": {
"command": "npx",
"args": ["-y", "@layers/mcp-server@latest", "--api-key", "lp_YOUR_KEY"]
}
}
}
```
> 在生产环境中，请固定版本号（`@layers/mcp-server@0.1.0`），而不是使用 `@latest`，以确保您这边发布的内容是经过深思熟虑的。
## 配置
命令行标志优先；环境变量是备用方案。
| 标志 | 环境变量 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `--api-key` | `LAYERS_API_KEY` | — （必填） | 层叠 API 密钥（`lp_...`）。如果缺少该密钥，服务器将退出并报错。 |
| `--base-url` | `LAYERS_BASE_URL` | `https://api.layers.com` | API 主机。路径在 `/v1` 下版本化。 |
| `--read-only` | `LAYERS_READ_ONLY=1` | 关闭 | 仅注册读取工具（52 个工具中的 25 个）。变异工具完全不暴露。 |
| `--organization` | `LAYERS_ORGANIZATION` | 未设置 | 代表子组织（`org_...`）操作，发送 `X-Layers-Organization` 头部到每个请求。需要 `org:admin` 父密钥。 |
**安全注意：** 命令行标志最终出现在客户端配置文件和进程 argv 中（可通过 `ps` 查看）。如果客户端支持，请优先使用环境变量存储密钥：
```json
{
"mcpServers": {
"layers": {
"command": "npx",
"args": ["-y", "@layers/mcp-server@latest"],
"env": { "LAYERS_API_KEY": "lp_YOUR_KEY" }
}
}
}
```
沙箱密钥（`lp_test_...`）在开发过程中跳过真实平台调用 — 内容、OAuth 和发布返回固定结果。
## 工具
52 个工具，每个 API 路由对应一个工具。写入工具（标记为 W）被 `--read-only` 隐藏。
### 核心
`whoami` · `list_projects` · `get_project` · `get_credits` ·
`list_credit_events` · `create_project` (W) · `update_project` (W) ·
`archive_project` (W)
### 创意
`list_influencers` · `get_influencer` · `get_keywords` · `list_content` ·
`get_content` · `get_content_progress` · `get_content_asset` · `get_hooks` ·
`get_source_recommendations` · `get_content_review_policy` ·
`create_influencer` (W) · `clone_influencer` (W) · `update_influencer` (W) ·
`delete_influencer` (W) · `refresh_keywords` (W) · `generate_slideshow` (W) ·
`generate_ugc_remix` (W) · `generate_video_remix` (W) ·
`generate_slideshow_remix` (W) · `create_content_upload` (W) ·
`upload_content_from_url` (W) · `finalize_content_upload` (W) ·
`update_content_caption` (W) · `approve_content` (W) · `reject_content` (W) ·
`update_content_review_policy` (W)
### 分发
`list_social_accounts` · `get_scheduled_post` · `list_scheduled_posts` ·
`list_tiktok_music` · `get_engagement_config` · `publish_content` (W) ·
`schedule_content` (W) · `reschedule_post` (W) · `cancel_scheduled_post` (W) ·
`notify_device` (W) · `update_engagement_config` (W)
### 衡量
`get_metrics` · `get_top_performers` · `list_ads_content` ·
`list_recommendations` · `update_ads_content` (W) · `update_recommendation` (W)
### 框架
`list_audit_log`
### 惯例
- **异步作业。** 生成、创建/克隆影响者、刷新关键词返回 `202` 作业信封（`jobId`、`containerIds`/`influencerId`）。轮询匹配的读取工具（`get_content_progress`、`get_influencer`、`get_keywords`）直到资源终端。
- **上传您自己的媒体。** 两种传输方式，都生成上传的内容容器，您可以随后安排/发布。对于已托管的文件，`upload_content_from_url` 是一个同步调用。对于大/私有文件，`create_content_upload` 返回预签名的 `PUT` URL — 您的客户端直接将字节上传到存储（在该服务器之外，约 15 分钟内），然后调用 `finalize_content_upload` 每个容器。之后，使用 `update_content_caption` 修复标题（仅限上传内容）。
- **分页。** 列表工具接受 `cursor` + `limit` 并返回 `{ items, nextCursor }`；原样传递 `nextCursor`。
- **幂等性。** 服务器在每个变异 POST/PATCH 上自动盖上新鲜的 UUID `Idempotency-Key`。
- **错误** 以工具错误形式呈现层叠信封：`Layers API <status> <code>: <message>` 加上 `requestId` 和 `details` — 在支持票中包含 `requestId`。
- **时间戳** 均为 ISO 8601 UTC，带有 `Z` 后缀（偏移形式被 API 拒绝）。`scheduledFor` 是字面 UTC 瞬间 — 在调用前从本地时间转换。
## 开发
需要 Node 20+。
```sh
npm install
npm run build # tsc -> dist/
# 将本地构建连接到 Claude Code：
claude mcp add layers -- node $(pwd)/dist/index.js --api-key lp_YOUR_KEY
# 或使用 MCP 检查器交互式探索：
npx @modelcontextprotocol/inspector node dist/index.js --api-key lp_test_dummy
```
标准输出是 JSON-RPC 通道 — 所有日志记录都输出到 stderr。
## 测试
```sh
npm test # 完整的测试套件 — 无 API 密钥，无网络
npm run smoke # 可选的实时测试；需要 LAYERS_TEST_KEY=lp_test_...
```
`npm test` 构建，然后使用 Node 内置测试运行器在 localhost 模拟器上运行合约套件 — 验证工具注册、`--read-only` 门控、注解提示、标准输出协议纪律和请求合约（身份验证、幂等性、查询编码、每个工具路由、错误渲染）。无需凭证或外部网络；这是 CI 运行的内容。参见 [`test/README.md`](test/README.md) 以获取完整分析 和 沙箱烟雾脚本。
## 许可证
Apache-2.0 — 参见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
版权 2026 Layers AI, Inc.
