# ops-mcp-server

运营 AI 入口 · MCP Server —— **多后端适配器**，一条打通两套自有系统：

- **lpb 落地页产品线**：调 `mock-server`（页面 CRUD/渲染）
- **ad-tech-labs 投放平台**：调 `media-adapter`(:18300 campaign/门禁) / `launch`(:18600 一句话起投)

机制：现成 MCP 客户端（Claude Code / Cursor / VS Code）配 stdio 即用自然语言操作；写操作一律 **dry-run → confirm + reason → 审计 + 幂等**。

## 当前状态（M0→M4 均已验）

| 段 | 内容 | 验证 |
|---|---|---|
| M0 | 骨架 + 双后端工具 + stdio | ✅ `pnpm smoke` |
| M1 | 写操作三段式（dry-run/confirm/审计/幂等） | ✅ `pnpm smoke` |
| M2 | 真后端打通（ad-tech-labs + lpb mock-server） | ✅ `live-test.ts` + `lpb-crud-test.ts` |
| M3 | 客户端接入配置（见下） | 文档 |
| M4 | 与 launch 合流：`adtech_launch_campaign` 一句话起投 | ✅ live-test 真创建 campaign |

## 快速开始

```bash
cd c:\www\mcp-server
pnpm install

# 协议自测（不需后端）
pnpm smoke

# 真后端验证（先起 ad-tech-labs 两个纯内存服务）
#   终端1: cd c:\www\ad-tech-labs && go run ./media-adapter/cmd   # :18300
#   终端2: cd c:\www\ad-tech-labs && go run ./launch/cmd          # :18600
pnpm tsx scripts/live-test.ts      # campaign 读 + 一句话起投（M4）
pnpm tsx scripts/status-test.ts    # campaign 停投/恢复
```

lpb 侧真调需另起 mock-server（`landing-page-builder/packages/mock-server`，默认 :3200）。

## 工具清单

| Tool | 读写 | 后端 | 说明 |
|---|---|---|---|
| `lpb_list_pages` / `lpb_get_page` | 读 | mock-server | 落地页列表/详情 |
| `lpb_create_page` | 写* | mock-server | 创建落地页 |
| `lpb_update_page` | 写* | mock-server | 更新落地页（改名/改状态等） |
| `lpb_delete_page` | 写* | mock-server | 删除落地页（破坏性） |
| `adtech_list_campaigns` | 读 | media-adapter :18300 | campaign 列表（租户隔离） |
| `adtech_adjust_bid` | 写* | media-adapter | 调价/预算（过预算门禁） |
| `adtech_launch_campaign` | 写* | launch :18600 | **一句话起投**（M4 合流） |
| `adtech_set_campaign_status` | 写* | media-adapter | **停投(paused)/恢复(active)** |
| `system_query_audit` | 读 | 本地 | 操作审计 |

`写*`：需 `confirm=true` + `reason`；先 `confirm=false` 拿 dry-run 预览。身份经 env（`ADTECH_TENANT/USER/ROLE`）透传为 `X-Tenant/X-User/X-Role`，服务端二次校验。

## M3：MCP 客户端接入

**Claude Code**（项目 `.mcp.json`）：
```json
{ "mcpServers": { "ops": { "command": "npx", "args": ["tsx", "c:\\www\\mcp-server\\src\\index.ts"] } } }
```

**Cursor**（项目 `.cursor/mcp.json`）：
```json
{ "mcpServers": { "ops": { "command": "npx", "args": ["tsx", "c:/www/mcp-server/src/index.ts"] } } }
```

连上后就能自然语言问/做，例如：
> "现在有哪些 campaign？" → 调 `adtech_list_campaigns`
> "给 ADX 广告位 adslot-1 一句话起投，预算 500，出价 12" → 先生成 dry-run，确认后真执行

## 架构与安全

详见 `docs/项目/运营AI入口-MCPserver架构.md`。要点：
- 后端可插拔：`src/adapters/*.ts` 实现统一契约，切宿主零改 tools
- 写操作不裸奔：dry-run → confirm+reason → 审计（`src/core/audit.ts`，幂等 op_id）
- LLM 参数不信任：schema 强约束 + 服务端（media-adapter/launch）二次 RBAC/门禁
- 服务地址走 env（`src/config.ts`），密钥不入库