Ops Lense

Ops Lense 是一个远程托管的用于商业运营的模型上下文协议（MCP）服务器。它帮助运营专家调查卡住的订单，了解问题所在，并在无需工程师介入每个事件的情况下采取下一步安全操作。

此任务特意深入聚焦一个工作流：卡住订单的调查与修复，涵盖订单、支付、库存和履约。

它展示了什么

运营人员可以向支持 MCP 的 AI 客户端提出如下问题：

为什么这个已支付的订单仍然卡住？

AI 可以使用 Ops Lense 来：

1. 查找订单；

2. 检查其运营时间线；

3. 从后端数据诊断可能的故障；

4. 确定拟议操作可以安全执行的程度；

5. 在运营人员确认后预览并执行有边界的修复；或

6. 将高风险操作发送到人工审核队列，而不是执行它。

因此，MCP 是核心产品界面，而不是围绕独立应用的额外集成。

安全模型

并非所有商业操作都应具有相同级别的 AI 自主权。Ops Lense 将操作分为三类。

确认流程

resync_inventory_reservation 是一个受保护的写入操作。

第一次调用：

confirmed=false

服务器验证订单并返回拟议效果，而不更改数据库。

在运营人员明确批准该操作后，客户端可以调用：

confirmed=true

然后服务器执行有边界的变更并记录审计条目。

人工审核流程

关键操作故意不作为直接的 MCP 变更提供。request_manual_review 会创建一个 pending_review 审计条目。

另一个运营人员审核、批准和执行这些请求的独立流程故意不在任务范围内。待处理的请求可通过 list_manual_reviews 查看。

MCP 工具

MCP 资源

Ops Lense 暴露一个运营资源：

ops://action-policy

它描述了三个操作类别以及 MCP 客户端在选择或执行工具时应遵循的规则。

我选择了一个资源而不是 MCP 提示，因为这是稳定的运营策略，无论用户如何表述请求都应可用。专门的提示对此刻意狭窄的工作流几乎没有额外价值。

端到端工作流示例

一个代表性事件是订单支付成功捕获但库存预留步骤缺失。

1. 运营人员询问订单为何卡住。

2. AI 在需要定位订单时使用 search_orders。

3. 它调用 get_order_timeline 检查已发生的情况。

4. 它调用 diagnose_order 关联支付和运营状态。

5. 诊断识别出 INVENTORY_RESERVATION_MISSING 并建议 resync_inventory_reservation。

6. AI 以 confirmed=false 调用该工具，并向运营人员展示拟议的修复方案。

7. 运营人员批准。

8. AI 再次以 confirmed=true 调用该工具。

9. MCP 执行修复并写入审计记录。

10. AI 再次调用 get_order_timeline 验证结果状态。

高风险请求遵循不同的路径。例如，如果运营人员要求退款，MCP 会创建一个人工审核请求，而不是修改支付状态。然后可以通过 list_manual_reviews 检查该请求。

这为演示提供了一个连贯的故事，涵盖调查 → 诊断 → 人工确认 → 变更 → 验证 → 升级。

架构

MCP-enabled AI client
        |
        | Streamable HTTP
        v
   Ops Lense MCP
        |
        +-- Investigation tools
        +-- Diagnostic logic
        +-- Safety / action policy
        +-- Guarded actions
        |
        v
   Neon PostgreSQL
   synthetic commerce data

技术栈：

• TypeScript

• Bun 用于本地开发和脚本

• Heroku 上的 Node.js 24

• Model Context Protocol 服务器包

• Express HTTP 传输

• Neon PostgreSQL

• Zod 输入验证

合成数据模拟了工作流所需的最小后端系统：客户、订单、支付、库存、履约、运营事件、调查历史和操作审计记录。

本地运行

前提条件

你需要：

• Bun

• 一个 PostgreSQL 数据库；Neon 在托管演示中效果良好

1. 安装依赖

bun install

2. 配置环境变量

在项目根目录创建 .env 文件：

DATABASE_URL=postgresql://YOUR_DATABASE_URL
MCP_AUTH_TOKEN=YOUR_STRONG_RANDOM_TOKEN
PORT=3000

3. 创建合成数据库

bun scripts/setup-db.ts

此命令会删除并重新创建任务表。不要对包含你需要保留数据的数据库运行此命令。

4. 填充演示数据

bun scripts/seed-db.ts

所有填充的客户、订单、支付、库存和履约记录均为合成数据。

5. 构建并启动 MCP 服务器

bun run build
bun run start

bun run build 将 TypeScript 编译到 dist/。然后启动命令使用 Node 运行编译后的服务器，与 Heroku 运行时路径匹配。

本地 MCP 端点为：

http://localhost:3000/mcp

部署到 Heroku

仓库包含一个 Procfile，使用 npm start 启动 web dyno。Heroku 构建 TypeScript 项目并运行编译后的 Node.js 服务器。

1. 创建 Heroku 应用

heroku create YOUR_APP_NAME

2. 配置数据库

设置 PostgreSQL 连接字符串和一个用于保护 MCP 端点的强 bearer token：

heroku config:set DATABASE_URL="YOUR_DATABASE_URL" MCP_AUTH_TOKEN="YOUR_STRONG_RANDOM_TOKEN" -a YOUR_APP_NAME

Heroku 会自动提供 PORT，因此你无需手动配置。

3. 部署

git push heroku HEAD:main

在部署期间，Heroku 会安装 Node 依赖并运行 build 脚本。然后 web dyno 启动：

node dist/index.js

托管的 MCP 端点将是：

https://YOUR_APP_NAME.herokuapp.com/mcp

如果你的 Heroku 应用使用自定义域名，请使用该域名加上 /mcp。

4. 验证部署

heroku logs --tail -a YOUR_APP_NAME

你应该看到 MCP 服务器启动并绑定到 Heroku 分配的端口。

可以在部署前从本地机器使用相同的 DATABASE_URL 初始化合成数据库，或者如果环境中可用 Bun，则通过一次性 Heroku 命令运行设置和填充脚本。为了最简单的部署路径，在部署服务器之前先在本地初始化并填充 Neon。

从 AI 客户端连接

Ops Lense 使用远程 HTTP MCP 端点。在支持远程/Streamable HTTP 服务器的 MCP 客户端中，添加端点和 bearer token：

{
  "serverUrl": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_STRONG_RANDOM_TOKEN"
  }
}

对于已部署的实例，将本地 URL 替换为托管的 MCP URL，并使用服务器上配置为 MCP_AUTH_TOKEN 的相同 token。

连接后，客户端应自动发现工具和 ops://action-policy 资源。

然后你可以自然地开始，例如：

Show me recent orders that may need attention.

Why is this order stuck? Investigate it and tell me what we can safely do.

Show me all actions currently waiting for manual review.

对于需要确认的操作，AI 应向运营人员展示预览，并在第二次以 confirmed=true 调用工具之前获得明确批准。

使用 MCP Inspector 连接

MCP Inspector 对于独立于聊天客户端测试服务器很有用。

在本地服务器运行时：

npx @modelcontextprotocol/inspector

在 Inspector 中，连接到：

http://localhost:3000/mcp

然后你可以检查发现的工具/资源并手动调用工作流。

验证

使用以下命令进行类型检查：

npm run typecheck

针对配置的合成数据库运行集中的 Vitest 集成测试套件：

npm test

tests/operations.test.ts 中的测试会创建隔离的临时记录，针对 PostgreSQL 执行真实的工具函数，然后删除这些记录。它们验证：

• 已捕获支付但缺少预留会产生 INVENTORY_RESERVATION_MISSING；

• 终态订单不会被诊断为活跃的库存故障；

• confirmed=false 不执行任何变更；

• confirmed=true 执行有边界的库存修复并记录审计条目；

• 重复执行已完成的重新同步是安全的空操作；

• 退款请求被排队等待审核而不更改支付状态；

• 重复的待处理审核请求被抑制。

该套件目前包含 8 个集成测试。成功运行报告 8 passed。

这些测试特意聚焦于工作流和安全边界，而不是广泛的覆盖率指标。

关键产品决策

保持工作流狭窄

该任务不试图构建完整的商业后端。选择卡住订单操作是因为它们提供了一个紧凑的工作流，涉及多个系统、诊断、修复、安全和验证。

给予 AI 有用的自主权，而不是无限制的写入权限

如果每个操作都是只读的，运营人员将依赖另一个系统来解决即使是简单的事件。如果允许每个变更，则会带来不必要的运营风险。

三层模型提供了一个中间地带：调查是自动的，有边界的修复需要运营人员确认，而后果严重的操作仍处于人工审核之后。

将关键操作排除在 MCP 执行之外

退款和类似操作在这个合成项目中技术上可以表示为数据库变更，但这样做会演示错误的生产行为。MCP 反而创建一个审核请求，并使边界明确。

保持 MCP 表面小

每个暴露的工具在所选工作流中都有明确的角色。目标是让 AI 客户端可靠地选择工具，而不是最大化可用工具的数量。

范围与假设

包含：

• 合成商业数据

• 订单调查

• 对支持的卡住订单条件的确定性诊断

• 受保护的库存修复

• 审计日志

• 人工审核队列

• 可远程访问的 MCP 接口

故意排除：

• 前端/管理仪表板

• 真实客户数据

• 生产支付或仓库凭证

• 用户账户、会话、OAuth 和基于角色的访问控制

• 直接退款执行

• 人工审核批准/执行界面

• 完整的商业后端

• 广泛的退货、欺诈、目录和客户支持工作流

托管作业服务器使用单个承载令牌以避免公开暴露MCP。对于生产系统，需要添加身份感知认证、授权/RBAC、密钥轮换、更强的并发控制、特定于提供商的集成、可观测性以及完整的审查工作流。

仓库结构

src/
  index.ts
  db.ts
  resources.ts
  tools/
    diagnose-order.ts
    get-stats.ts
    get-timeline.ts
    list-manual-reviews.ts
    request-manual-review.ts
    resync-inventory.ts
    search-orders.ts
scripts/
  setup-db.ts
  seed-db.ts
tests/
  operations.test.ts
vitest.config.ts

AI工作日志

此部分应包含提交前作业中实际的AI使用情况：

• 使用的AI编码工具和具体模型

• 为何为每个任务选择该模型

• 工作是如何规划和分解的

• AI与开发者各自负责的部分

• 提供给AI的重要提示/上下文

• 至少一个被拒绝或大幅修改的AI建议

• 如何审查和验证AI生成的工作

• 剩余风险或未完成的工作

开发过程中改变的一个产品决策是对重大操作的处理。与其将退款和类似关键操作作为可执行的MCP工具暴露，不如将它们移至手动审查队列之后。这保留了有用的AI自主性，同时将财务或运营上具有重大影响的决策置于直接模型执行之外。

提交内容

最终提交应包括：

• 托管的MCP URL

• 源代码仓库URL

• 本README

• 重要工作流行为的验证/测试

• 完成的AI工作日志

• 4-5分钟的异步演示

演示应优先展示实际产品工作流而非代码讲解：调查订单、诊断问题、预览安全修复、确认修复、验证结果，然后展示关键操作如何被路由到手动审查。