使用说明

哨兵-MCP拦截器

一个用于模型上下文协议（MCP）的透明、故障开放的可观察性侧车。
Sentinel提供身份, 排序，以及正直代理人担保↔ 工具交互-无需修改执行或与代理耦合。

Sentinel无形地位于LLM客户端和MCP工具之间，充当 被动、无阻塞水龙头 进入实时代理流量。它不会改变请求。它不会阻止处决。它不强加政策。

相反，Sentinel在MCP流量流动时进行观察，重建一个 规范事件流，并将其暴露于实时可视化和持久审计日志中。

结果：
你终于可以 看看你的代理人做了什么，按什么顺序做，然后相信记录 -即使代理本身是一个黑匣子。

🚀 立即尝试（30秒）

# 1. Install Sentinel
curl -fsSL https://raw.githubusercontent.com/EngramAI-io/sentinel/main/install.sh | sh

# 2. Run Sentinel in front of any MCP server
<your-mcp-client> sentinel run -- <your-mcp-server>

# For example:
node mcp_client.js sentinel run --audit-log test_audit.jsonl -- node mcp_server.js

# 3. Open the dashboard
# http://localhost:3000

⚠️ 项目状态
Sentinel正在积极开发中。实施了核心架构和保证，并正在进行硬化、用户体验抛光、文档和扩展验证工具的工作。
鼓励早期采用者和审稿人提供反馈。

Sentinel是什么（不是什么）

哨兵是：

透明MCP侧车
标准事件记录器
实时可观测性层
可加密验证的审计漏洞

Sentinel不是：

执行引擎
政策执行者
工具经纪人
速率限制器
重播控制器

代理和工具继续运行 一模一样 有或没有哨兵。

哨兵vs MCP官方检查员

专题	MCP官方检查员	哨兵
主要用途	独立工具测试	观察在线客服使用工具
集成	独立的web UI	工作流程中的透明sidecar
排序	隐式/未定义	规范的、单调的事件排序
相关性	仅按请求	会话、跟踪和跨度连续性
可审计性	无	仅附加已签名的可选加密日志
故障模式	停止可见性	失败打开：执行继续

哨兵为何存在

LLM代理隐式推理。
工具调用异步发生。
故障经常出现之后原因。

传统的伐木方式已经崩溃。

Sentinel的存在是为了提供 可观测性保证 代理系统隐含地依赖于但很少正式化。

使用Sentinel，您可以获得：

代理活动的单一有序历史记录
请求→ 跨工具的响应相关性
按方法划分的延迟和错误可见性
您可以稍后回放和验证的持久日志
使因果关系可见的实时图表

思考 Chrome 开发者工具 - 要不是 代理工具链.

🛡 Sentinel的核心保证

Sentinel提供 可选的非侵入性保证 围绕代理交互。
启用后，这些保证支持调试、审计和安全分析。
当不存在时，代理继续正常运行，但这些属性会丢失。

1.会话标识和跟踪连续性

保证：
每个观察到的代理操作都可以归因于会话和执行跟踪。

Sentinel提供：

稳定 session_id 和 trace_id 在跑步的一生中
根据请求 span_id 根据请求↔ 响应相关性
跨工具和错误的一致归因

没有它：
日志变得支离破碎，推理变得不透明。

2.规范有序事件流

保证：
存在一个单一的、一致的、可回放的代理活动历史。

Sentinel提供：

单调、全局有序的事件流
仅附加语义
与挂钟时间无关的稳定事件ID

关键属性：
订购来源于 哨兵边界观测，而不是时间戳。

没有它：
事件是存在的，但顺序是模糊的，信任会受到侵蚀。

3.遥测的密码完整性

保证：
观察到的代理行为在事后没有被篡改。

Sentinel提供：

哈希链，只追加审计记录
Ed25519数字签名
静止时可选加密
离线验证工具

重要提示：
密码学适用 仅用于遥测永远不要被处决。

为什么这些保证很重要

物业	已回答问题
身份	谁做了什么？
顺序	按什么顺序？
诚信	我们能相信记录吗？

这些共同构成了所需的最小基础 严重可观测性 -而不执行政策或约束代理人。

设计理念

观察，永远不要决定
记录，永不执行
故障打开，未关闭
信任来自可见性，而不是控制

✨ 核心功能

📡 透明MCP侧车

将Sentinel放在任何MCP服务器前，即可立即获得深入的可见性——无需更改代码、重写或修补。

⚡ 零拷贝、亚毫秒代理

Sentinel拦截JSON-RPC流量，而不缓冲或篡改有效载荷。真正通过，开销<1ms。

🧠 实时交互式图形

每次工具调用都会变成一个发光的边缘。
每个响应都会更新节点统计信息。
错误脉冲为红色。
高延迟呼叫发热。

🔐 内置PII Redaction

敏感区域被清除仅在可观测性输出中。
原始MCP流量永远不会被修改。

💥 未结保函

如果UI崩溃或WebSocket掉线， 您的MCP管道继续保持稳定.

🖥️ 克劳德桌面就绪

一个命令可以修补Claude Desktop，同时保留自动备份。

🏗 建筑

图案： 透明侧车（T-Tap）
哲学： 故障打开
技术栈： Rust（Tokio）•TypeScript•React•React Flow•WebSockets

                  ┌──────────────┐
                  │   LLM Agent  │
                  └──────┬───────┘
                         │
            responses ▲  │   ▼ requests
                         │
                  MCP (JSON-RPC over stdio)
                         │
            responses ▲  │   ▼ requests
                         │
                  ┌──────────────────┐
                  │     Sentinel     │  ← observe only (fail-open)
                  │  • parse MCP     │
                  │  • order events  │
                  │  • emit telemetry│
                  └──────┬───────────┘
                         │
            responses ▲  │   ▼ requests
                         │
                  unchanged MCP stream
                         │
            responses ▲  │   ▼ requests
                         │
                  ┌──────────────────┐
                  │   MCP Server /   │
                  │       Tools      │
                  └──────────────────┘

💎 完整功能列表

零拷贝stdin/stdout MCP传递
典型事件排序
会话/跟踪/span相关性
WebSocket事件总线
完整的JSON-RPC解析
每种方法的延迟和错误度量
交互式力定向图
紧急恢复和安全停机
用于工具集成的NDJSON审计日志

🚀 快速安装

选项1：卷曲安装（推荐）

Linux/macOS：

curl -fsSL https://raw.githubusercontent.com/EngramAI-io/sentinel/main/install.sh | sh

自定义安装目录：

INSTALL_DIR=$HOME/.local/bin curl -fsSL https://raw.githubusercontent.com/EngramAI-io/sentinel/main/install.sh | sh

选项2:Windows（PowerShell）

iwr https://raw.githubusercontent.com/EngramAI-io/sentinel/main/install.ps1 -UseBasicParsing | iex

选项3：下载预构建二进制文件

下载适用于您平台的最新版本：

下载后（仅限Linux/macOS）：

chmod +x sentinel-*
sudo mv sentinel-* /usr/local/bin/sentinel

📖 使用与文档

安装Sentinel后，请参阅以下内容的完整使用指南：

使用MCP服务器运行Sentinel
WebSocket身份验证
审计日志记录和加密
Claude桌面集成
常见部署模式
故障排除

👉 阅读完整指南： 📄 `docs/USAGE.md`

📚 从源代码手动构建

步骤1：安装先决条件

1.1安装铁锈和货物

在Windows上：

按照以下说明下载并运行Rust安装程序 https://www.rust-lang.org/tools/install
按照安装提示进行操作（建议使用默认设置）
安装后重新启动终端/PowerShell
验证安装：
```
rustc --version
cargo --version
```
您应该看到以下版本 rustc 1.70.0 或更高，以及 cargo 1.70.0 或更高。
如果你是 Windows Linux子系统（WSL） 用户，在终端中运行以下命令，然后按照屏幕上的说明安装Rust。

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

在macOS上：

# Install using Homebrew
brew install rust

# Or use rustup (recommended)
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version

在Linux上：

# Install using rustup (recommended)
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
source $HOME/.cargo/env

# Verify installation
rustc --version
cargo --version

1.2安装Node.js和npm

在Windows上：

从下载Node.js https://nodejs.org/
选择LTS版本（推荐18.x或更高版本）
运行安装程序并按照提示操作
验证安装：
```
node --version
npm --version
```
你应该看看 v18.x.x Node.js或更高版本，以及 9.x.x 或者对于npm更高。

在macOS上：

# Using Homebrew
brew install node

# Verify installation
node --version
npm --version

在Linux上：

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# Install Node.js using nvm
nvm install node

# Verify installation
node --version
npm --version

步骤2：克隆并导航到项目

# If you haven't already cloned the repository
git clone https://github.com/EngramAI-io/sentinel.git
cd sentinel

# Or if you're already in the project directory, verify you're in the right place
# You should see Cargo.toml and a frontend/ directory

步骤3：构建前端

导航到前端目录：
```
cd frontend/my-react-flow-app
```
安装前端依赖项：
```
npm install
```
这将下载并安装所有必需的包（React、React Flow、Vite、TypeScript等）
构建生产前端：
```
npm run build
```
这会编译TypeScript，捆绑React应用程序，并输出到 frontend/dist/ 目录。
返回到项目根目录：
```
cd ..
```

步骤4：构建Rust二进制文件

构建发布版本（优化）：
```
cargo build --release
```
注：第一次构建可能需要5-10分钟，因为它编译了所有依赖项。后续构建将更快。
验证二进制文件是否已创建：
- 窗户： target\release\sentinel.exe
- macOS/Linux： target/release/sentinel

（可选）测试二进制文件是否运行：

# Windows
.\target\release\sentinel.exe --help

# macOS/Linux
./target/release/sentinel --help

步骤5：本地测试

选项A：使用开发版本运行（建议用于测试）

在一个终端中，使用MCP服务器运行哨兵代理：
```
cargo run -- run -- npx -y @modelcontextprotocol/server-filesystem
```
这将：
- 启动哨兵代理
- 启动MCP文件系统服务器
- 在端口3000上启动HTTP/WebSocket服务器
打开浏览器并导航到：
```
http://localhost:3000
```
您应该看到仪表板上显示：
- 力导向图可视化
- 中心的“Agent”节点
- 发出MCP请求时出现的工具节点

要使用其他MCP服务器进行测试：

# SQLite server example
cargo run -- run -- npx -y @modelcontextprotocol/server-sqlite path/to/database.db

# Custom Python server example
cargo run -- run -- python -m my_mcp_server

选项B：使用发布二进制文件运行

使用您构建的发布二进制文件：

# Windows
.\target\release\sentinel.exe run -- npx -y @modelcontextprotocol/server-filesystem

# macOS/Linux
./target/release/sentinel run -- npx -y @modelcontextprotocol/server-filesystem

打开http://localhost:3000在浏览器中

步骤6：验证一切正常

检查仪表板负载： 您应该看到可视化界面
检查WebSocket连接： 图表应该是交互式的
检查日志： 寻找 sentinel_debug.jsonl 在调试日志的项目目录中
测试交互性： 点击节点查看详细的JSON-RPC有效载荷

故障排除

问题： cargo: command not found

解决方案：安装Rust后重新启动终端，或手动添加 ~/.cargo/bin 到你的路径

问题： npm: command not found

解决方案：安装Node.js后重新启动终端，或验证Node.js是否在PATH中

问题：前端构建失败

解决方案：确保你在 frontend/ 目录并运行 npm install 第一

问题：端口3000已在使用中

解决方案：使用端口3000终止进程，或在代码中修改端口

问题： cargo build 链接器错误失败（Windows）

解决方案：从安装Microsoft C++构建工具 https://visualstudio.microsoft.com/visual-cpp-build-tools/

问题：构建后找不到二进制文件

解决方案：检查构建是否成功完成。寻找 target/release/sentinel （或 .exe 在Windows上）

为Claude Desktop安装

# Install sentinel for a specific MCP server
./target/release/sentinel install filesystem

# The config is automatically updated and backed up
# Your Claude Desktop will now use sentinel as a proxy

要还原原始配置，请执行以下操作：

# Config backup is at: ~/.config/claude-desktop/claude_desktop_config.json.backup (Unix)
# or %APPDATA%/Claude/claude_desktop_config.json.backup (Windows)

项目结构

sentinel/
├── src/
│   ├── audit.rs             # Audit log writer and lifecycle management
│   ├── audit_crypto.rs      # Signing, hashing, and encryption logic for tamper-evident logs
│   ├── config.rs            # Claude Desktop config helper  
│   ├── decrypt_audit_log.rs # Signing, hashing, and encryption logic for tamper-evident logs
│   ├── events.rs            # Event logging structures
│   ├── keygen.rs            # Offline audit log verification and decryption
│   ├── main.rs              # CLI and orchestration
│   ├── panic.rs             # Panic recovery
│   ├── proxy.rs             # Zero-copy stdio proxy
│   ├── protocol.rs          # JSON-RPC structures
│   ├── parser.rs            # NDJSON streaming parser
│   ├── session.rs           # Request/response correlation
│   ├── server.rs            # HTTP/WebSocket server
│   └── redaction.rs         # PII redaction
└── frontend/                # React dashboard
    └── src/
        ├── App.tsx
        ├── components/
        │   ├── Graph.tsx
        │   └── NodeDetails.tsx
        └── hooks/
            └── useWebSocket.ts

发展

前端开发

cd frontend
npm install
npm run dev

这将在开发模式（非嵌入式）下运行前端。要连接到正在运行的哨兵实例，请在中更新WebSocket URL src/hooks/useWebSocket.ts.

构建嵌入前端

cd frontend
npm run build
# Output goes to frontend/dist/ which gets embedded into the binary

使用示例

示例：MCP文件系统服务器

# Development (no auth)
cargo run -- run -- npx -y @modelcontextprotocol/server-filesystem

# Production (with auth)
cargo run -- run --ws-token "secret123" --ws-bind "127.0.0.1:3000" -- npx -y @modelcontextprotocol/server-filesystem

示例：MCP SQLite服务器

cargo run -- run --ws-token "$SENTINEL_WS_TOKEN" -- npx -y @modelcontextprotocol/server-sqlite path/to/database.db

示例：带有审核日志记录的自定义服务器

# First generate keys
cargo run -- keygen --out-dir ./keys
cargo run -- recipient-keygen --out-dir ./keys

# Run with full audit logging and encryption
cargo run -- run \
  --signing-key-b64-path ./keys/signing_key.b64 \
  --encrypt-recipient-pubkey-b64-path ./keys/recipient_pub.b64 \
  --audit-log ./audit.jsonl \
  --ws-token "secret123" \
  -- python -m my_mcp_server

仪表盘

仪表板显示：

代理节点 （中）：法学硕士客户
工具节点 （卫星）：MCP服务器及其方法
边缘：主动通信路径
颜色:
- 黄色=待处理请求
- 绿色=成功响应
- 红色=错误响应

单击任何节点查看详细的JSON-RPC有效载荷。

调试

审计日志已写入 sentinel_audit.jsonl （可通过以下方式配置 --audit-log)
恐慌日志转到 sentinel_panic.log
配置备份是通过以下方式自动创建的 .backup 扩展
控制台输出显示：
- ✅ 成功指示器（绿色复选标记）
- ❌ 错误指示器（红色X标记）
- 🔒 安全状态（锁图标）
- ⚠️ 警告（三角警示牌）
- 📝 检查点和审计事件

安全

🔒 内置安全功能

Sentinel的设计遵循安全第一原则：

认证

WebSocket令牌身份验证：使用基于令牌的身份验证保护您的可观察性端点
环境变量支持：设置 SENTINEL_WS_TOKEN 避免在命令历史记录中暴露令牌
自动报警：Sentinel在生产环境中未经身份验证运行时发出警告

# Secure mode (recommended)
./sentinel run --ws-token "your-secret-token-here" -- npx @modelcontextprotocol/server-filesystem

# Using environment variable (recommended for production)
export SENTINEL_WS_TOKEN="your-secret-token-here"
./sentinel run -- npx @modelcontextprotocol/server-filesystem

# Connect from browser/client
ws://localhost:3000/ws?token=your-secret-token-here

可配置的网络绑定

自定义绑定地址：控制WebSocket服务器监听的位置
生产准备就绪：绑定到特定接口或使用Unix套接字

# Localhost only (default - most secure)
./sentinel run --ws-bind "127.0.0.1:3000" -- your-mcp-server

# All interfaces (use with authentication!)
./sentinel run --ws-bind "0.0.0.0:3000" --ws-token "secret" -- your-mcp-server

# Custom port
./sentinel run --ws-bind "127.0.0.1:8080" -- your-mcp-server

PII补救措施

API密钥、令牌、电子邮件在可视化前自动清除
原始MCP流量为从不修改-编辑仅适用于可观察性数据
基于正则表达式的检测，具有多种模式类型：
- api_key, apikey, access_token, secret_key
- OpenAI风格 sk-* 钥匙
- 电子邮件地址
- 持有者代币

加密审计日志记录

Ed25519数字签名：每个检查点都经过加密签名
ChaCha20-Poly1305加密：审计日志的可选端到端加密
篡改证据链：哈希链事件防止追溯修改
可验证日志：独立验证 sentinel verify 命令

# Generate signing keypair
./sentinel keygen --out-dir ./keys

# Generate encryption keypair (optional)
./sentinel recipient-keygen --out-dir ./keys

# Run with audit logging
./sentinel run \
  --signing-key-b64-path ./keys/signing_key.b64 \
  --encrypt-recipient-pubkey-b64-path ./keys/recipient_pub.b64 \
  --audit-log ./audit.jsonl \
  -- your-mcp-server

# Verify audit log integrity
./sentinel verify \
  --log ./audit.jsonl \
  --pubkey-b64-path ./keys/signing_pubkey.b64 \
  --decrypt-recipient-privkey-b64-path ./keys/recipient_priv.b64

优雅地关闭

信号处理：CTRL+C触发优雅关机
冲洗保证：退出前，所有审核日志都会刷新到磁盘
超时保护：10秒超时可防止挂起关机
无数据丢失：事件缓冲区已完全耗尽

安全依赖关系

固定版本：所有依赖项都使用特定版本（无通配符）
最新安全补丁：tokio钨酸盐0.24，所有CVE已修补
内存安全：零的纯Rust实现 unsafe 块
加密库：RustCrypto审计实施

错误处理

详细日志记录：用于调试的全面错误信息
用户友好的消息：通用错误消息防止信息泄露
打开代理失败：即使可观察性失败，MCP流量也会继续
恐慌恢复：自定义紧急处理程序可防止崩溃影响MCP管道

安全最佳实践

始终使用身份验证 在生产环境中
绑定到本地主机 除非你需要远程访问
启用审核日志加密 适用于敏感环境
定期旋转按键 使用keygen命令
监控日志 未经授权的访问尝试
保持Sentinel更新 获取最新的安全补丁

安全披露

发现安全问题？请发送电子邮件至security@engramai.io（或您的联系人）而不是公开问题。

配置备份

在进行任何修改之前，会自动创建配置备份
备份位置：
- Linux/macOS: ~/.config/claude-desktop/claude_desktop_config.json.backup
- 视窗: %APPDATA%\Claude\claude_desktop_config.json.backup

许可证

麻省理工学院

使用说明

哨兵-MCP拦截器

🚀 立即尝试（30秒）

Sentinel是什么（不是什么）

哨兵vs MCP官方检查员

哨兵为何存在

🛡 Sentinel的核心保证

1.会话标识和跟踪连续性

2.规范有序事件流

3.遥测的密码完整性

为什么这些保证很重要

设计理念

✨ 核心功能

📡 透明MCP侧车

⚡ 零拷贝、亚毫秒代理

🧠 实时交互式图形

🔐 内置PII Redaction

💥 未结保函

🖥️ 克劳德桌面就绪

🏗 建筑

💎 完整功能列表

🚀 快速安装

选项1：卷曲安装（推荐）

选项2:Windows（PowerShell）

选项3：下载预构建二进制文件

📖 使用与文档

👉 阅读完整指南： 📄 docs/USAGE.md

📚 从源代码手动构建

步骤1：安装先决条件

1.1安装铁锈和货物

1.2安装Node.js和npm

步骤2：克隆并导航到项目

步骤3：构建前端

步骤4：构建Rust二进制文件

步骤5：本地测试

选项A：使用开发版本运行（建议用于测试）

选项B：使用发布二进制文件运行

步骤6：验证一切正常

故障排除

为Claude Desktop安装

项目结构

发展

前端开发

构建嵌入前端

使用示例

示例：MCP文件系统服务器

示例：MCP SQLite服务器

示例：带有审核日志记录的自定义服务器

仪表盘

调试

安全

🔒 内置安全功能

认证

可配置的网络绑定

PII补救措施

加密审计日志记录

优雅地关闭

安全依赖关系

错误处理

安全最佳实践

安全披露

配置备份

许可证

相关 MCP

Kubernetes集群管理MCP服务

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

👉 阅读完整指南： 📄 `docs/USAGE.md`