Promptlint MCP

promptlint-mcp

像检查代码一样检查 AI 提示词。节省 token。发现矛盾。

用于 AI 提示词（系统提示词、Agent 指令、工具描述）的静态分析器，可作为 CLI 和 MCP 服务运行，让 Claude Code （或任何支持 MCP 的 Agent）在发送提示词前进行检查。

---

快速演示

对一个典型的（存在隐蔽问题的）系统提示词运行 promptlint：

$ node src/cli.mjs examples/bad-prompt.md

promptlint examples/bad-prompt.md
  score  14/100
  tokens 367 → 307 (-60, 16% saved)
  issues 14

  info   [ambiguous-pronoun] Pronoun "that" has no clear referent (line 1)
         → Replace with a concrete noun, e.g. "this" → "the config file".
  ...
  error  [contradiction] Contradicting directives (length): "concise" vs "detailed"
         → Pick one, or scope each with a clear condition (e.g. by task type).
  error  [contradiction] Contradicting directives (commenting): "do not add comments" vs "explain each step"
         → Pick one, or scope each with a clear condition (e.g. by task type).
  info   [trailing-fluff] "please" fluff (match 1 of 1)
         → Delete. AIs do not need politeness tokens.
         · Please
  ...

发现两处 error 级别的矛盾，评分被限制为 14/100，通过 --trim 可回收 60 个 token（16%）。

下面是在小段输入上使用 --trim 的效果：

$ echo "You are a helpful assistant. Please always be concise. Thank you for your help! When the user asks a question, handle it carefully." | node src/cli.mjs - --trim

You are a helpful assistant. Always be concise. When the user asks a question, handle it carefully.

请参阅 docs/promo/，其中有发布草稿和（TODO）asciinema 录屏。

---

为什么使用

• 矛盾："be concise" + "be thorough" 会悄无声息地进入使用，并在每次请求中 浪费 token。promptlint 会将成对的相反要求（长度 / 语气 / 频率 / 评论 / 提问）标记为 error。
• 冗余：近似重复的句子（Jaccard > 0.6）会各自收到一条 warn — 删除其中一条即可。
• 模糊代词："use it" / "handle that" 若句中没有指代对象，就会被标记并附上行号。句首大写词不算作 指代对象，因此普通英语不会产生误报。
• 较长的代码示例：超过约 1200 个字符或 30 行的围栏代码块会触发 warn — 示例几乎总能精简为只保留结构。
• 客套赘词：可检测并统计 Please / Thanks / I hope this helps / Let me know if… / Feel free to…，还可通过 --trim 将其剔除，同时保留实际的命令句。

适用范围：英语提示词、散文 — 不包括源代码。 日语提示词或 JavaScript 文件即使存在问题，也会显示为干净。

---

安装

一次性安装 CLI 和 MCP 服务：

npm install -g promptlint-mcp

两个可执行文件会被放到你的 $PATH 中：

可执行文件	说明
promptlint	CLI（检查文件或 stdin）
promptlint-mcp	MCP 服务（stdio 传输）

无需安装即可运行

# CLI: lint a file
npx -p promptlint-mcp promptlint <file>

# CLI: lint stdin
echo "be concise and thorough" | npx -p promptlint-mcp promptlint -

# MCP server (auto-launched by Claude Code via mcp config; see below)
npx -y promptlint-mcp

从源代码构建（自行开发）

git clone https://github.com/sean-sunagaku/promptlint-mcp.git
cd promptlint-mcp
npm install
node src/cli.mjs examples/bad-prompt.md

需要 Node >= 18。除 MCP SDK 外，没有运行时依赖。

---

CLI 用法

默认的人类可读报告

node src/cli.mjs examples/bad-prompt.md

promptlint examples/bad-prompt.md
  score  14/100
  tokens 367 → 307 (-60, 16% saved)
  issues 14

  info   [ambiguous-pronoun] Pronoun "that" has no clear referent (line 1)
         → Replace with a concrete noun, e.g. "this" → "the config file".
  ...
  error  [contradiction] Contradicting directives (length): "concise" vs "detailed"
         → Pick one, or scope each with a clear condition (e.g. by task type).
  error  [contradiction] Contradicting directives (commenting): "do not add comments" vs "explain each step"
         → Pick one, or scope each with a clear condition (e.g. by task type).
  info   [trailing-fluff] "thanks" fluff (match 1 of 2)
         → Delete. AIs do not need politeness tokens.
         · Thank you
  info   [trailing-fluff] "please" fluff (match 1 of 1)
         → Delete. AIs do not need politeness tokens.
         · Please
  info   [trailing-fluff] "hope-helps" fluff (match 1 of 1)
         → Delete. AIs do not need politeness tokens.
         · I hope this helps
  ...

干净的提示词（见 examples/good-prompt.md）会返回 score 100/100，且没有任何问题 — 没有输出也是一种特性。

使用 --json 供程序读取

node src/cli.mjs examples/bad-prompt.md --json

{
  "score": 14,
  "issues": [
    {
      "rule": "ambiguous-pronoun",
      "severity": "info",
      "message": "Pronoun \"that\" has no clear referent (line 1)",
      "line": 1,
      "suggestion": "Replace with a concrete noun, e.g. \"this\" → \"the config file\"."
    },
    {
      "rule": "contradiction",
      "severity": "error",
      "message": "Contradicting directives (length): \"concise\" vs \"detailed\"",
      "suggestion": "Pick one, or scope each with a clear condition (e.g. by task type)."
    }
  ],
  "trimmed": "…",
  "tokensBefore": 367,
  "tokensAfter": 307,
  "saved": 60,
  "savedPercent": 16
}

空输入会添加 "note": "empty input"。纯客套话输入（例如 "Thanks!"）如果精简后会变为空，则会改为返回原文，并设置 "trimmerFallback": true — 安全的即插即用工具绝不会向你的大模型发送空白提示词。

使用 --trim 输出精简后的内容（用于管道）

echo "You are a helpful coding assistant. Please always be concise. Thank you for your help! When the user asks a question, handle it carefully. If they provide code, review it. Let me know if anything is unclear. I hope this helps!" \
  | node src/cli.mjs - --trim

You are a helpful coding assistant. Always be concise. When the user asks a question, handle it carefully. If they provide code, review it.

围栏代码块会原样保留。移除客套话前，会屏蔽带引号的字符串（"…"）和行内反引号（`…`），因此示例文本不会被改动。

标准输入

cat prompt.md | node src/cli.mjs -

报告标题会显示 promptlint <stdin>。

其他标志

node src/cli.mjs --rules      # list the 5 rule IDs, one per line
node src/cli.mjs --help       # usage

退出代码

代码	含义
0	没有错误（允许 warn/info）
1	至少存在一个严重级别为 error 的问题
2	用法错误（缺少文件、读取失败等）

---

MCP 服务用法

用一条命令在 Claude Code 中注册（无需克隆，无需全局安装）：

claude mcp add promptlint -- npx -y promptlint-mcp

或者将以下内容添加到 ~/.claude.json（用户范围）或项目 .mcp.json （项目范围）：

{
  "mcpServers": {
    "promptlint": {
      "command": "npx",
      "args": ["-y", "promptlint-mcp"]
    }
  }
}

如果你已全局安装该软件包，也可以使用绝对路径形式，从而跳过 npx 首次运行时的下载：

{
  "mcpServers": {
    "promptlint": {
      "command": "promptlint-mcp"
    }
  }
}

暴露的工具

工具	输入	返回
lint_prompt	{ text: string }	两个 text 内容项：[0] 人类可读的单行摘要（"score: X/100 · issues: N · tokens: A → B …"），[1] lint() 结果的完整 JSON（使用 JSON.parse(result.content[1].text) 解析）。
trim_prompt	{ text: string }	两个 text 内容项：[0] 精简后的提示词，[1] 节省量页脚（"Saved N tokens (P%). Original: A, trimmed: B."）。不会解决矛盾、冗余或歧义——这些情况请运行 lint_prompt。

两个工具都是纯函数 / 幂等的。不联网、不访问文件系统、不保留状态。

---

规则

ID	严重程度	检测内容	触发示例
contradiction	error	关于长度 / 语气 / 频率 / 禁止事项 / 注释 / 提问的成对相反指令	"be concise" + "be thorough"
redundancy	warn	Jaccard 词集相似度 > 0.6 的两个句子	两段都表达“用英语回复”，但措辞不同
long-example	warn	超过 1200 个字符或 30 行的围栏代码块	内联粘贴了一个 40 行的辅助函数
ambiguous-pronoun	info	it / this / that / these / those 在句中没有明确指代对象	"Use it to figure out what to do."
trailing-fluff	info	礼貌用语 / 填充语：please、thanks、I hope this helps、let me know if…、feel free to…、sorry、certainly/absolutely/of course	"Please refactor the code. Thanks!"

评分公式：100 - (errors*25 + warns*10 + infos*3)，然后限制为 <=59 （如果存在任何错误）以及 <=79（如果有 2 个或更多警告）。严重程度上限如同 交通信号灯：只要有错误，就进入红色区域，与错误数量无关。

---

定价与路线图

免费（OSS，MIT）

• CLI（node src/cli.mjs）——全部三种模式（报告 / JSON / 精简），全部 5 条规则。
• MCP 服务（node src/mcp.mjs）——两个工具，不限使用次数。
• 无需账户、无遥测、无网络。

Pro（计划推出，$9/mo）

• 团队共享的自定义规则词典（项目中禁止使用的短语、必需的标题、禁止的矛盾）。
• 按项目记录 lint 历史并提供差异视图。
• 跨项目 token 节省情况仪表板（“你的团队本月节省了 1.2M 个 token”）。

Pro 尚未发布。目前没有注册表单—— 👍 在早期体验议题（#1）中 登记意向。我们会按 👍 的顺序通过私信发送邀请。

---

开发

冒烟测试

npm run lint:self         # lints examples/bad-prompt.md

预期结果：退出码为 1（存在 2 个 error 级矛盾），得分在十几分左右，所有 规则均触发。如果结果发生偏移，说明某条规则出现了回归。

基准

examples/good-prompt.md 的得分必须始终为 100/100，且 0 个问题。如果 某项更改破坏了这一点，则该更改有误。

添加规则

规则位于 src/linter.mjs。每条规则都是一个普通函数：

function ruleFooBar(text) {
  // return an array of { rule, severity, message, samples?, suggestion, line? }
  return [];
}

将其添加到 lint() 内的 issues 数组，并将其 ID 追加到 RULES 导出项中。如果规则针对的是散文（而非代码），请对 maskCodeBlocks() 处理后的副本运行规则，以免围栏示例触发规则。如果需要拆分句子， 请复用 splitSentences（识别引号）或 splitSentencesPreservingDelims （识别引号，并为精简器保留分隔符）。

矛盾

扩展 src/linter.mjs 顶部的 CONTRADICTION_PAIRS。每个条目如下：

{ a: ["keyword-a", ...], b: ["keyword-b", ...], label: "short-label" }

现有标签：length、tone、frequency、prohibition、commenting、 asking。

---

社区

• 💬 讨论区 — 提问、分享想法和提示词使用经验
• 🐛 问题 — 错误、功能请求
  • #1 Pro 提前体验（置顶）
  • #2 路线图
  • #3 已知问题 / 后续待办
• ⭐ 如果它帮你节省了令牌，请为仓库点个 Star——更多人发现它，其他 AI 用户也能找到它。

构建过程

此软件包由两支 AI Agent 团队端到端打造：

• ai-auto-improve-app — 构建并打磨产品。客户 AI 使用工具并撰写反馈 → 开发者 AI 修改代码 → 不断重复。每轮提交（round-001 … round-003）都是开发者 AI 对该轮客户 AI 反馈的回应。
• ai-launch-team — 发布并推广产品。5 个子 Agent 负责发布到 npm、创建 GitHub Release、提交 awesome-mcp PR、创建讨论区帖子、起草社交媒体文案，以及生成 SVG/PNG 资源。

两者合力将产品从“空仓库”打造为“npm 上的 v0.1.2 + 2 个 awesome-mcp PR + 2 个讨论区种子帖子 + 4 个问题 + 完整的社交媒体文案”。唯一的手动步骤是平台要求的短信 / OTP 身份验证（创建 X 账号、设置 npm 双重身份验证）——其余工作都由 AI 完成。

许可证

MIT — 详见 LICENSE。