内容
# promptspeak-mcp-server
[](https://github.com/chrbailey/promptspeak-mcp-server/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@chrbailey/promptspeak-mcp-server)
[](https://opensource.org/licenses/MIT)
[](https://github.com/chrbailey/promptspeak-mcp-server/actions)
**AI 智能代理预执行治理。拦截危险的工具调用，防止其执行。**
AI 智能代理调用工具（文件写入、API 请求、shell 命令）时，没有验证层来验证调用意图和执行之间的安全性。提示词注入、幻觉参数或目标漂移可能会触发不可逆转的操作。PromptSpeak 拦截每个 MCP 工具调用，根据确定性规则验证调用，并阻止或暂停高风险操作，等待人工审批 — 在 0.1 毫秒内，在任何操作执行之前。
## 使用场景
- 您运行调用工具的 AI 智能代理（MCP 服务器、函数调用、工具使用），需要在代理和工具之间添加一层治理。
- 您需要对高风险操作（生产部署、金融交易、法律归档）进行人工审批。
- 您需要检测行为漂移 — 智能代理逐渐偏离其指定任务。
- 您需要一个审计 trail 记录智能代理尝试调用的每个工具，无论是否允许或阻止。
- 您在受监管的领域（法律、金融、医疗保健）运营，智能代理的操作必须受到确定性约束。
## 安装
### Claude Code
将以下内容添加到 `~/.claude/settings.json`（或项目级 `.claude/settings.json`）：
```json
{
"mcpServers": {
"promptspeak": {
"command": "npx",
"args": ["promptspeak-mcp-server"]
}
}
}
```
重启 Claude Code。所有 56 个治理工具立即可用。
### Claude Desktop
将以下内容添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"promptspeak": {
"command": "npx",
"args": ["promptspeak-mcp-server"]
}
}
}
```
### 作为库
```bash
npm install promptspeak-mcp-server
```
### 从源代码构建
```bash
git clone https://github.com/chrbailey/promptspeak-mcp-server.git
cd promptspeak-mcp-server
npm install && npm run build
npm start
```
## 使用示例
### 1. 验证治理框架
验证 PromptSpeak 框架在执行任何操作前是否结构和语义正确。框架将治理约束编码为符号序列 — 模式优先，然后是域、操作和实体。
```jsonc
// 工具调用：ps_validate
{
"name": "ps_validate",
"arguments": {
"frame": "⊕◊▶α",
"validationLevel": "full"
}
}
```
```jsonc
// 响应
{
"valid": true,
"frame": "⊕◊▶α",
"parsedFrame": {
"mode": { "symbol": "⊕", "meaning": "strict" },
"domain": { "symbol": "◊", "meaning": "financial" },
"action": { "symbol": "▶", "meaning": "execute" },
"entity": { "symbol": "α", "meaning": "primary" }
},
"parseConfidence": 1.0,
"report": {
"valid": true,
"errors": [],
"warnings": [
{ "code": "ACTION_MISSING_DOMAIN", "message": "Consider adding domain context", "severity": "warning" }
]
},
"summary": { "errors": 0, "warnings": 1, "passed": 16 }
}
```
无效框架返回可行的建议：
```jsonc
// 工具调用：验证具有冲突模式的框架
{
"name": "ps_validate",
"arguments": { "frame": "⊕⊖▶", "validationLevel": "semantic" }
}
// 响应：阻止 — 严格 + 灵活模式冲突
{
"valid": false,
"summary": { "errors": 1, "warnings": 0, "passed": 10 },
"suggestions": ["Remove either ⊕ (strict) or ⊖ (flexible) - cannot have both"]
}
```
### 2. 暂停队列工作流 — 人工审批
当智能代理尝试进行高风险操作（高漂移分数、低置信度、安全发现）时，该操作将被暂停，等待人工审查。以下是完整的暂停生命周期：列表、检查、批准或拒绝。
**步骤 1：列出待处理的暂停**
```jsonc
// 工具调用：ps_hold_list
{
"name": "ps_hold_list",
"arguments": {}
}
```
```jsonc
// 响应：一个暂停待审
{
"holds": [
{
"holdId": "hold_7k2m9x",
"agentId": "devops-agent",
"frame": "⊕◈▶α",
"tool": "deploy_to_production",
"severity": "high",
"reason": "drift_prediction",
"state": "pending",
"evidence": { "driftScore": 0.72, "predictedDrift": 0.85 }
}
],
"count": 1,
"expiredCount": 0
}
```
**步骤 2：批准并修改（或拒绝）**
```jsonc
// 工具调用：ps_hold_approve — 批准但降级到暂存环境
{
"name": "ps_hold_approve",
"arguments": {
"holdId": "hold_7k2m9x",
"reason": "Reviewed — safe for staging, not production",
"modifiedArgs": { "environment": "staging" }
}
}
```
```jsonc
// 响应
{
"success": true,
"decision": {
"holdId": "hold_7k2m9x",
"state": "approved",
"decidedBy": "human",
"reason": "Reviewed — safe for staging, not production"
},
"executionResult": { "success": true }
}
```
拒绝：
```jsonc
{
"name": "ps_hold_reject",
"arguments": {
"holdId": "hold_7k2m9x",
"reason": "Drift too high — recalibrate agent first",
"haltAgent": true
}
}
// 智能代理被暂停（断路器触发），操作被拒绝。
```
### 3. 安全扫描 — 在执行前捕获漏洞
在智能代理将代码写入磁盘之前，扫描代码内容中的安全问题。关键发现会阻止执行；高严重性发现会暂停审查。
```jsonc
// 工具调用：ps_security_scan
{
"name": "ps_security_scan",
"arguments": {
"content": "const query = `SELECT * FROM users WHERE id = ${userId}`;\nconst API_KEY = 'sk-1234567890abcdef1234567890abcdef';"
}
}
```
```jsonc
// 响应：两个发现 — 一个关键（阻止），一个关键（阻止）
{
"findings": [
{
"patternId": "sql-injection",
"severity": "critical",
"match": "SELECT * FROM users WHERE id = ${userId}",
"line": 1,
"context": "const query = `SELECT * FROM users WHERE id = ${userId}`;",
"suggestion": "Use parameterized queries or prepared statements instead of template literals"
},
{
"patternId": "hardcoded-secret",
"severity": "critical",
"match": "API_KEY = 'sk-1234567890abcdef1234567890abcdef'",
"line": 2,
"context": "const API_KEY = 'sk-1234567890abcdef1234567890abcdef';",
"suggestion": "Move secrets to environment variables or a secrets manager"
}
],
"scannedAt": "2026-03-19T12:00:00.000Z",
"contentLength": 98,
"patternsChecked": 10,
"enforcement": {
"blocked": [
{ "patternId": "sql-injection", "severity": "critical" },
{ "patternId": "hardcoded-secret", "severity": "critical" }
],
"held": [],
"warned": [],
"logged": []
}
}
```
使用 `ps_security_gate` 代替 `ps_security_scan` 来强制执行策略 — 它会阻止关键问题，暂停高严重性问题，并对中等严重性问题发出警告：
```jsonc
// 工具调用：ps_security_gate — 扫描并强制执行
{
"name": "ps_security_gate",
"arguments": {
"content": "app.use(cors());\napp.listen(0.0.0.0, 3000);",
"action": "write_file"
}
}
// 响应：暂停审查（不安全默认值 = 高严重性）
{
"decision": "held",
"reason": "Security: 1 high-severity finding(s) held for review — insecure-defaults",
"scan": { "findings": [{ "patternId": "insecure-defaults", "severity": "high", "line": 1 }] }
}
```
## 工作原理：9 阶段验证管道
每个工具调用都会经过此管道。如果任何阶段失败，执行将被阻止。
```
Agent calls tool
│
├─ 1. Circuit Breaker ──── Halted agents blocked instantly (no further checks)
├─ 2. Frame Validation ─── Structural, semantic, and chain rule checks
├─ 3. Drift Prediction ─── Pre-flight behavioral anomaly detection
├─ 4. Hold Check ────────── Risky operations held for human approval
├─ 5. Interceptor ───────── Final permission gate (confidence thresholds)
├─ 6. Security Scan ─────── Scans write actions for vulnerabilities (see below)
├─ 7. Tool Execution ────── Only reached if all 6 pre-checks pass
├─ 8. Post-Audit ────────── Confirms behavior matched prediction
└─ 9. Immediate Action ──── Halts agent if critical drift detected post-execution
```
阶段 1-6 是 **预执行** — 如果任何检查失败，工具永远不会运行。阶段 8-9 是 **执行后** — 它们检测漂移并可以暂停智能代理以进行未来的调用。
## 安全扫描
当智能代理写入代码（`write_file`, `edit_file`, `create_file`, `patch_file`）时，内容会针对 10 个检测模式进行扫描，然后再执行。严重性决定了强制执行：
| 严重性 | 强制执行 | 它捕获的内容 |
|----------|-------------|-----------------|
| **关键** | **阻止** — 执行被拒绝 | SQL 注入 via 模板字符串、硬编码 API 密钥/密码/令牌 |
| **高** | **暂停** — 排队等待人工审查 | 安全相关的 TODO、日志记录敏感数据、不安全默认值 (`cors()`、`0.0.0.0`、`debug: true`) |
| **中等** | **警告** — 记录，继续执行 | 空 catch 块、对冲评论（“probably works”）、禁用的测试 |
| **低** | **记录** — 无强制执行 | `DROP TABLE`、`rm -rf`（标记以示 awareness） |
### 什么有效（已测试）
以下所有声明均有通过测试支持（5 个测试文件中的 104 个测试）：
- **模式检测有效。** 每个模式都经过测试，以确保真阳性和假阳性。例如：`api_key = "sk-1234567890abcdef"` 被捕获；`API_KEY = process.env.API_KEY` 不被捕获。SQL 注入捕获 `\`SELECT * FROM users WHERE id = ${id}\`` 但不捕获参数化查询 (`db.query("SELECT * FROM users WHERE id = ?", [id])`)。
- **严重性强制执行有效。** 关键发现阻止执行。高发现暂停审查。中等发现警告但允许。端到端通过拦截器管道测试。
- **仅扫描写入操作。** `read_file` 和其他非写入操作即使参数中包含漏洞代码，也会直接通过，不进行扫描。已测试。
- **运行时配置有效。** 可以通过 `ps_security_config` 启用/禁用模式和更改严重性。禁用模式立即停止触发。更改模式从中等到关键使其阻止而不是警告。端到端测试。
- **性能良好。** 100 行文件扫描在 10 毫秒内完成。已测试。
- **多个文件中的多个发现有效。** 一个文件中的 6 种不同漏洞类型正确分类到相应的严重性桶中。已测试。
### 什么还不工作
- ~~**高发现没有暂停队列集成。**~~ **已修复。** 高严重性安全发现现在通过 `security_finding` HoldReason 在 HoldManager 中创建真正的暂停。它们出现在 `ps_hold_list` 中，可以通过正常暂停流程批准/拒绝。
- **没有 `ps_execute` 上的自动扫描。** 安全扫描仅在拦截器的 `intercept()` 方法中针对直接工具调用触发。如果智能代理使用 `ps_execute`（受控执行路径），则仅当内部工具是写入操作且内容作为顶级参数传递时，扫描才会运行。嵌套参数结构可能会绕过扫描。**原因：** `ps_execute` 在其自己的参数模式中包装工具调用；扫描器检查 `proposedArgs.content`，而不是深入嵌套的字段。
- **没有基于文件路径的扫描。** 扫描器仅检查作为参数传递的内容。它无法扫描磁盘上已经存在的文件 — 它不读取文件系统。**原因：** 扫描器是一个纯函数，接受字符串。添加文件系统访问权限会更改安全模型。
- **模式基于正则表达式，而不是 AST 感知。** 模式使用正则表达式，这意味着它们无法理解代码结构。硬编码的机密位于测试fixture或注释中的 SQL 注入仍会触发。误报率从 25-70% 取决于模式（每个模式文档化）。**原因：** AST 解析将添加依赖项和复杂性。正则表达式快速且足够好，用于治理层暂停以供人工审查，而不是无声阻止。
- **部分持久性。** 暂停和断路器状态现在持久化到 SQLite (`data/governance.db`) 并在服务器重启后存活。但是，模式配置更改（启用/禁用、通过 `ps_security_config` 更改严重性）仅在内存中，并且在重启时重置。**原因：** 模式配置很轻，可以更改；完整的配置持久性需要单独的配置存储。
## MCP 工具（56 个）
### 核心治理
| 工具 | 何时调用 | 功能 |
|------|----------------|--------------|
| `ps_validate` | 执行任何智能代理操作之前 | 验证框架的所有规则而不执行 |
| `ps_validate_batch` | 一次检查多个操作时 | 批量验证以提高效率 |
| `ps_execute` | 智能代理想要执行工具调用时 | 完整管道：验证 -> 暂停检查 -> 执行 -> 审计 |
| `ps_execute_dry_run` | 预览将发生什么时 | 运行完整管道而不执行工具 |
### 人工审批暂停
| 工具 | 何时调用 | 功能 |
|------|----------------|--------------|
| `ps_hold_list` | 审查智能代理的待处理操作 | 列出所有等待人工审批的操作 |
| `ps_hold_approve` | 当暂停的操作应该继续时 | 批准并修改参数 |
| `ps_hold_reject` | 当暂停的操作应该被拒绝时 | 拒绝并提供原因 |
| `ps_hold_config` | 调整哪些操作需要审批时 | 配置暂停触发器和限 |
| `ps_hold_stats` | 监控暂停队列健康时 | 暂停队列统计 |
### 代理生命周期
| 工具 | 何时调用 | 功能 |
|------|----------------|--------------|
| `ps_state_get` | 检查智能代理正在执行什么 | 获取智能代理的活动框架和最后操作 |
| `ps_state_system` | 监控整体系统健康时 | 系统范围的统计信息 |
| `ps_state_halt` | 当智能代理必须立即停止时 | 触发断路器 - 阻止所有未来调用 |
| `ps_state_resume` | 当暂停的智能代理应该继续时 | 重置断路器 |
| `ps_state_reset` | 清除智能代理状态时 | 完全状态重置 |
| `ps_state_drift_history` | 调查行为变化时 | 漂移检测警报历史 |
### 委托
| 工具 | 何时调用 | 功能 |
|------|----------------|--------------|
| `ps_delegate` | 当智能代理创建子代理时 | 带有约束权限创建父/子委托 |
| `ps_delegate_revoke` | 撤销子代理的权限时 | 移除委托 |
| `ps_delegate_list` | 审计委托链时 | 列出活动委托 |
### 配置
| 工具 | 何时调用 | 功能 |
|------|----------------|--------------|
| `ps_config_set` | 运行时更改治理规则时 | 设置键值对 |
| `ps_config_get` | 读取当前配置时 | 获取当前配置 |
| `ps_config_activate` | 切换策略配置文件时 | 激活命名配置 |
| `ps_config_export` | 备份配置时 | 以 JSON 导出完整配置 |
| `ps_config_import` | 恢复配置时 | 从 JSON 导入配置 |
| `ps_confidence_set` | 调整验证严格程度时 | 设置置信度阈值 |
| `ps_confidence_get` | 检查当前阈值时 | 获取当前阈值 |
| `ps_confidence_bulk_set` | 重新配置多个阈值时 | 批量更新阈值 |
| `ps_feature_set` | 切换管道阶段时 | 启用/禁用特定检查 |
| `ps_feature_get` | 检查哪些阶段处于活动状态时 | 获取功能标志 |
### 符号注册表（实体跟踪）
| 工具 | 何时调用 | 功能 |
|------|----------------|--------------|
| `ps_symbol_create` | 注册新实体（公司、人员、系统）时 | 创建具有类型、元数据和标签的符号 |
| `ps_symbol_get` | 查找实体时 | 按 ID 检索 |
| `ps_symbol_update` | 实体数据发生变化时 | 更新元数据或标签 |
| `ps_symbol_list` | 按类型浏览实体时 | 列出并可选地过滤类型 |
| `ps_symbol_delete` | 删除实体时 | 按 ID 删除 |
| `ps_symbol_import` | 批量加载实体时 | 批量导入 |
| `ps_symbol_stats` | 监控注册表健康状况时 | 注册表统计信息 |
| `ps_symbol_format` | 显示实体时 | 格式化符号以供显示 |
| `ps_symbol_verify` | 确认实体数据当前有效时 | 标记符号为已验证 |
| `ps_symbol_list_unverified` | 审计过时数据时 | 列出需要验证的符号 |
| `ps_symbol_add_alternative` | 实体有别名时 | 添加替代标识符 |
### 安全强制
| 工具 | 何时调用 | 功能 |
|------|----------------|--------------|
| `ps_security_scan` | 检查代码是否存在漏洞时 | 扫描内容，返回按严重性分类的发现结果 |
| `ps_security_gate` | 对写入操作强制执行安全策略时 | 扫描 + 强制执行：阻止/暂停/警告/允许 |
| `ps_security_config` | 调整检测模式时 | 列出、启用、禁用、更改模式的严重性 |
### 审计
| 工具 | 何时调用 | 功能 |
|------|----------------|--------------|
| `ps_audit_get` | 审查发生的事情时 | 完整的审计轨迹，带有过滤器 |
## 架构
```
src/
├── gatekeeper/ # 8阶段验证流程（核心强制执行）
│ ├── index.ts # 流程协调器 + 代理驱逐策略
│ ├── validator.ts # 帧结构/语义/链验证
│ ├── interceptor.ts# 权限门控与置信度阈值
│ ├── hold-manager.ts# 人工介入的暂停队列
│ ├── resolver.ts # 帧解析与操作员覆盖
│ └── coverage.ts # 覆盖度置信度计算器
├── drift/ # 行为漂移检测
│ ├── circuit-breaker.ts # 每个代理的暂停/恢复
│ ├── baseline.ts # 行为基线比较
│ ├── tripwire.ts # 异常触发线
│ └── monitor.ts # 持续监控
├── security/ # 安全漏洞扫描
│ ├── patterns.ts # 10种检测模式（基于正则表达式）
│ └── scanner.ts # 扫描引擎 + 严重性分类
├── persistence/ # SQLite治理持久化
│ └── database.ts # 暂停、决策、熔断器（WAL模式）
├── symbols/ # SQLite支持的实体注册表（11种CRUD工具）
├── policies/ # 策略文件加载器 + 叠加系统
├── operator/ # 操作员配置
├── tools/ # MCP工具实现
│ ├── registry.ts # 29种核心工具
│ ├── ps_hold.ts # 5种暂停工具
│ └── ps_security.ts# 3种安全工具
├── handlers/ # 工具调度 + 元数据注册表
├── core/ # 日志、错误、结果模式
└── server.ts # MCP服务器入口点（stdio传输）
```
## 性能
PromptSpeak 为每次工具调用添加治理，延迟小于 1 毫秒。在 Apple M2 Pro、Node.js 22 和 Vitest 4.0 上进行基准测试：
### 延迟（预执行检查，1000 次迭代）
| 百分位 | 延迟 |
|-----------|---------|
| 平均值 | **0.164毫秒** |
| P95 | 0.368毫秒 |
| P99 | 1.183毫秒 |
| 完整执行路径 P95 | **0.074毫秒** |
### 吞吐量（并发操作）
| 操作 | 速率 |
|-----------|------|
| 熔断器检查（1000并发） | **6173次/秒** |
| 暂停创建 | **55556次/秒** |
| 暂停批准/拒绝 | **200000+次/秒** |
| 混合操作（暂停 + 暂停 + 允许） | **6818次/秒** |
### 压力测试
| 测试 | 结果 |
|------|--------|
| 1000个并发阻塞执行 | 162毫秒，总计，所有阻塞正确 |
| 100次快速暂停/恢复循环 | 100%正确的状态转换 |
| 500个代理，混合状态 | 250个阻塞，250个允许 - 零误判 |
| 持续负载下的内存（1000次操作） | **负增量**（-11.76 MB，GC回收） |
### 测试套件
| 指标 | 值 |
|--------|-------|
| 测试数量 | **829个测试**，跨33个文件 |
| 测试时长 | **1.11秒** 总计 |
| 类别 | 单元测试、集成测试、压力测试、安全测试、语法测试 |
## 需求
- Node.js >= 20.0.0
- TypeScript 5.3+（从源代码构建）
- 不需要外部服务 - SQLite用于符号和治理持久化
## 相关项目
- **[deeptrend](https://github.com/chrbailey/deeptrend)** - 面向自治代理的结构化AI趋势馈送。从14+个来源整理，通过LLM Counsel综合，每6小时发布为JSON Feed、RSS和`llms.txt`。设计用作代理监控流程的数据源。
## 隐私政策
[https://promptspeak.admin-as-a-service.com/privacy](https://promptspeak.admin-as-a-service.com/privacy)
PromptSpeak 不收集个人数据，无需遥测，并将所有治理数据存储在本地 SQLite 中。请在上述链接处查看完整政策。
## 数据处理条款
[https://promptspeak.admin-as-a-service.com/dpa](https://promptspeak.admin-as-a-service.com/dpa)
平台集成的标准数据处理条款（例如，Anthropic Connectors）。PromptSpeak 充当数据处理器；无子处理器，无外部数据传输。
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器