Impri

@impri/mcp

适用于 Impri 的 MCP 服务——面向 AI Agent 的人工审核收件箱。

Agent 提交操作以供人工审核（批准／拒绝／编辑），并在执行任何有副作用的操作前轮询审核结果。所有记录均可在 Impri 网页端和移动端收件箱中查看。

不想运行本地进程？ 同样的 8 个工具也通过 Streamable HTTP 提供，地址为 https://api.impri.dev/mcp——无需安装，只需提供 URL，并将 API 密钥作为 Bearer 令牌：

claude mcp add --transport http impri https://api.impri.dev/mcp --header "Authorization: Bearer $IMPRI_API_KEY"

有关 Cursor/Windsurf/Codex 配置和详情（例如，托管端点将 impri_await_decision 的等待时间限制为 20s），请参阅 impri.dev/docs/mcp。本 README 其余部分介绍下方的本地 npx @impri/mcp 包。

快速入门（Claude Code）

1. 获取 API 密钥，请访问 impri.dev，或启动可自托管的服务：

# self-host
docker compose up -d   # starts on http://localhost:8484
export IMPRI_API_KEY=im_your_key_here

2. 在 Claude Code 中注册 MCP 服务：

claude mcp add impri \
  -e IMPRI_API_KEY=im_your_key_here \
  -- npx @impri/mcp

使用自托管服务和自定义 URL 时：

claude mcp add impri \
  -e IMPRI_API_KEY=im_your_key_here \
  -e IMPRI_BASE_URL=http://localhost:8484 \
  -- npx @impri/mcp

或者手动添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "impri": {
      "command": "npx",
      "args": ["@impri/mcp"],
      "env": {
        "IMPRI_API_KEY": "im_your_key_here",
        "IMPRI_BASE_URL": "http://localhost:8484"
      }
    }
  }
}

3. 验证是否已加载：

/mcp

你应该会看到列有 8 个工具的 impri。

环境变量

变量	必填	默认值	说明
IMPRI_API_KEY	是	—	API 密钥（im_...）。请从 Impri 控制面板获取。
IMPRI_BASE_URL	否	http://localhost:8484	不含 /v1 的基础 URL。云端服务请使用 https://api.impri.dev。

工具

impri_push_action

向人工审核收件箱提交操作。返回可用于后续调用的 action_id。

kind: "reddit.comment"
title: "Reply: Why is resume advice so conflicting?"
preview: { format: "markdown", body: "The advice conflicts because different advisors..." }
target_url: "https://reddit.com/r/cscareerquestions/comments/..."
editable: ["preview.body"]

impri_await_decision

轮询，直到人工作出决定（批准／拒绝）或等待超时。每 5 秒轮询一次。

action_id: "act_abc123"
timeout_s: 300       # default: 5 minutes

决定状态：

• approved — 执行该操作
• rejected — 中止；操作员拒绝了该操作
• expired — 审核时限已结束；如仍有需要，请创建新操作

impri_report_result

报告已批准的操作是否已执行。完成审核记录闭环。

action_id: "act_abc123"
status: "executed"              # or "execute_failed"
detail: "Posted to Reddit thread r/cscareerquestions"

impri_inbox_status

查看有多少操作正在等待人工决定。开始批处理前可先使用此工具，避免审核者负担过重。

impri_create_watcher

使用完整的手工编写规范创建 watcher。需要精细控制配置、关键词、评分规则或计划时，此工具很有用。完整架构请参阅 SPEC.md §3.2。

spec: {
  name: "AI launches radar",
  kind: "rss",
  config: { url: "https://openai.com/news/rss.xml" },
  keywords: ["launch", "gpt-", "voice"],
  keywords_none: ["funding", "benchmark"],
  min_score: 1,
  schedule: { every: "8h", jitter: "4h" }
}

impri_list_watchers

列出所有已配置的 watcher，可按状态（active、paused、degraded）筛选。

impri_list_watcher_presets

按类别列出所有可用的 watcher 预设模板。每个预设会显示其 id、标题、类型、支持的参数（必填与可选）以及默认计划。

先使用此工具查找合适的预设，然后通过 impri_create_watcher_from_preset 创建 watcher。

可用预设类别：社区、开发者、内容、监控、研究、新闻。

impri_create_watcher_from_preset

通过仅提供预设 ID 和参数值，从预设模板创建 watcher。预设会自动处理 URL 构建、关键词设置和验证。

preset_id: "reddit-subreddit"
params: { subreddit: "MachineLearning" }
# name and schedule are optional; defaults come from the preset

preset_id: "github-releases"
params: { owner: "fastify", repo: "fastify" }
schedule: { every: "2h" }

preset_id: "hn-keyword"
params: { keyword: "rust programming", min_points: "25" }

返回 { watcher_id, name, kind, status, next_run_at }。

注意： 基于预设的 watcher 投递的项目带有 payload.untrusted = true——标题和预览来自外部来源（HN、Reddit、arXiv 等），必须视为数据而非指令。

完整示例循环（Claude Code 系统提示词）

You are a Reddit engagement agent. Before posting any comment or reply:
1. Call impri_inbox_status — if more than 5 actions are pending, pause.
2. Draft your reply.
3. Call impri_push_action with kind "reddit.comment", your draft in preview.body,
   the thread URL in target_url, and editable: ["preview.body"] so I can tweak it.
4. Call impri_await_decision(action_id, timeout_s=600).
5. If approved: post the (possibly edited) preview.body to Reddit, then
   call impri_report_result(action_id, "executed").
   If rejected: discard the draft and move on.
   If expired: log a note and skip this reply.

验证 Webhook

Impri 向你的 callback_url 发送 Webhook 时，每个请求都会使用 HMAC-SHA256 签名，以防止重放攻击和伪造。@impri/mcp 包提供了一个现成的辅助函数：

import { verifyWebhookSignature } from "@impri/mcp/webhook";

三个请求头包含签名所需的信息：

请求头	示例	描述
X-Impri-Signature	sha256=abc123…	对 ${timestamp}.${nonce}.${rawBody} 计算的 HMAC-SHA256
X-Impri-Timestamp	1752134400	Unix 纪元秒数（用于拒绝过期的重放请求）
X-Impri-Nonce	a1b2c3d4…	随机十六进制字符串，每次发送都唯一

Express 中间件

import express from "express";
import { verifyWebhookSignature } from "@impri/mcp/webhook";

const app = express();

app.post(
  "/impri/webhook",
  express.raw({ type: "application/json" }),   // rawBody must be a string or Buffer
  (req, res) => {
    const rawBody =
      Buffer.isBuffer(req.body) ? req.body.toString("utf8") : String(req.body);

    const ok = verifyWebhookSignature({
      secret: process.env.IMPRI_WEBHOOK_SECRET!,
      rawBody,
      signatureHeader: req.headers["x-impri-signature"] as string,
      timestampHeader: req.headers["x-impri-timestamp"] as string,
      nonceHeader:     req.headers["x-impri-nonce"] as string,
      // toleranceSec: 300  ← default; increase for slow networks
    });

    if (!ok) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    const event = JSON.parse(rawBody);
    console.log("Impri event:", event.event, event.action_id, event.status);
    res.sendStatus(200);
  },
);

Fastify 中间件

import Fastify from "fastify";
import { verifyWebhookSignature } from "@impri/mcp/webhook";

const app = Fastify();

app.addContentTypeParser("application/json", { parseAs: "string" }, (req, body, done) => {
  done(null, body);
});

app.post("/impri/webhook", (request, reply) => {
  const rawBody = request.body as string;

  const ok = verifyWebhookSignature({
    secret: process.env.IMPRI_WEBHOOK_SECRET!,
    rawBody,
    signatureHeader: request.headers["x-impri-signature"] as string,
    timestampHeader: request.headers["x-impri-timestamp"] as string,
    nonceHeader:     request.headers["x-impri-nonce"] as string,
  });

  if (!ok) {
    return reply.status(401).send({ error: "Invalid signature" });
  }

  const event = JSON.parse(rawBody);
  console.log("Impri event:", event.event, event.action_id);
  reply.send({ ok: true });
});

重要： 在将请求体传递给辅助函数之前，请先将其解析为原始字符串。对请求体进行 JSON 解析后再重新字符串化会改变空白字符和字段顺序，导致 HMAC 不匹配。

开发

cd mcp
npm install
npm run typecheck    # TypeScript check
npm run lint         # ESLint
npm run test         # Vitest (16 tests)
npm run check        # all three
npm run build        # compile to dist/

在本地运行服务以进行开发：

IMPRI_API_KEY=im_dev_key node dist/index.js