内容
# 安全选择
**适用于 AI 代理的失败关闭、只读 SQL 和 NoSQL 数据库访问，基于 MCP。**
[](https://github.com/antonillos/safeselect/actions/workflows/verify.yml)
[]()
[]()
[]()
[]()
[](https://github.com/antonillos/homebrew-tap)
[](https://github.com/antonillos/asdf-safeselect)
[](LICENSE)
安全选择为 AI 代理提供了一种受限的数据库工具，适用于 SQL 和 NoSQL 系统：发现结构、检查数据、运行只读操作、诊断连接性和恢复陈旧连接，而无需获得写入访问权限。
大多数数据库 MCP 服务器都很容易将代理连接到数据库。安全选择旨在解决一个更难的问题：让代理在不将数据库变成无限制的工具表面情况下，检查生产环境中的数据。
> [!注意]
> 安全选择是一种用于代理访问的安全边界，而不是数据库权限的替代品。在可能的情况下，请使用最小特权的数据库用户；安全选择仍然在代理通过它连接时限制过多的凭证。
当前后端支持：PostgreSQL 和 MongoDB。
## 为什么选择安全选择？
安全选择故意比通用数据库 MCP 服务器更窄。它不是一个工具构建器、SQL 工作台或远程数据库网关。它是需要数据库可见性的代理的本地安全边界，而不是数据库权限。
| 安全选择优先考虑 | 这意味着什么 |
|---|---|
| 本地标准输入/输出传输 | 没有网络监听器或开放的 MCP 端口 |
| 只读工具 | 代理不会收到具有写入能力的数据库工具 |
| 与凭证无关的安全性 | 即使是 DBA 凭证也被限制在安全选择的只读工具表面 |
| 失败关闭强制执行 | 策略违规终止进程 |
| 机密隔离 | 密码存储在 Keychain 或环境变量中 |
| 项目范围的策略 | 每个存储库定义其自己的允许数据表面 |
| 嵌入式边车 | 一个已安装的二进制文件通过 Rust 策略访问 JDBC 和 MongoDB 驱动程序 |
## 什么使它与众不同？
| 通用数据库 MCP 服务器 | 安全选择 |
|---|---|
| 通常公开可配置的工具 | 公开固定的、只读的工具表面 |
| 可能支持远程 HTTP 传输 | 默认情况下使用本地 MCP 标准输入/输出 |
| 通常优化为广泛的后端覆盖 | 优化为可强制执行的策略和代理安全 |
| 通常依赖于最小特权的数据库用户 | 即使凭证过多，也强制执行只读行为 |
| 通常将连接设置分开 | 从 DBeaver、Docker Compose 和 MongoDB Compass 导入 |
| 可能记录查询以进行调试 | 在审计日志记录之前哈希查询文本 |
| 将安全故障视为可恢复的错误 | 失败关闭并终止 MCP 进程 |
产品承诺很简单：**代理可以查看，但不能修改**。即使配置的数据库用户是 DBA，代理仍然只接收安全选择的受限只读操作。
> [!提示]
> 当团队已经拥有 DBeaver、Docker Compose 或 MongoDB Compass 连接，并且需要在不重新设计数据库用户的情况下将它们暴露给代理时，这非常有用。
## 后端支持
| 后端 | 状态 | 工具 |
|---|---|---|
| PostgreSQL | 支持 | `list_tables`、`select`、`explain` |
| MongoDB | 支持 | 发现、查找、聚合、不同/计数、解释、性能分析、模式推断和匿名化固定件 |
## 架构
<p align="center">
<img src="docs/safeselect-architecture.svg" alt="安全选择架构" width="800">
</p>
代理通过 MCP 标准输入/输出与安全选择通信。安全选择在 Rust 中强制执行策略，存储项目文件之外的机密，并通过嵌入式 Java 边车访问数据库：用于 SQL 后端的 JDBC 和用于 MongoDB 的 MongoDB 驱动程序。Rust 到 Java 的通道是标准输入/输出上的 JSON 行：没有套接字，没有开放的端口。
## 快速入门
```bash
brew install antonillos/tap/safeselect
# 导入项目数据库
safeselect import-dbeaver ~/Downloads/dbeaver-export.zip
# 或：
# safeselect import-compose
# safeselect import-compass --path "$HOME/.config/MongoDB Compass"
# 验证环境
safeselect check --environment testing
# 为您的代理安装 MCP 条目
safeselect agent install opencode --environment testing
```
安全选择使用任何可用的 Java 17+ 运行时，而不是要求 Homebrew 的 `openjdk@17` 公式。如果 Java 丢失或太旧，请在运行数据库命令之前安装或选择 Java 17+ 运行时。
生成的 MCP 名称默认为 `safeselect-<project>-<environment>`。
生成的 MCP 条目是一个作用于一个项目和环境的标准输入/输出服务器：
```json
{
"mcpServers": {
"safeselect-myapp-testing": {
"command": "safeselect",
"args": ["serve", "--project", "/path/to/myapp", "--environment", "testing"]
}
}
}
```
参见 [AI 代理集成](docs/agents.md) 以获取客户端特定设置和手动配置。
## 代理工作流
代理应按以下顺序使用安全选择：
1. `database_info`
2. SQL 的 `list_tables` 或 NoSQL 的 `list_databases` / `list_collections`
3. `select` / `explain`，或与任务匹配的限定 MongoDB 读取工具
4. 当连接性陈旧时，`check`、`connect` 或 `reconnect`
查询响应包括 `row_count`、`byte_count`、`elapsed_ms` 和人类可读的 `elapsed` 值，以便代理可以推理结果大小和延迟。
## 安全模型
- **失败关闭**：安全违规终止 MCP 进程。
- **只读**：SQL 允许 `SELECT`、`EXPLAIN` 和 `WITH`；NoSQL 后端允许发现和只读文档读取。
- **作用域访问**：可以允许或拒绝模式、关系、数据库和集合。
- **硬限制**：行数、结果字节和超时强制执行。
- **机密隔离**：密码存储在 macOS Keychain 或环境变量中，而不是项目配置中。
- **驱动程序验证**：JDBC 驱动程序在使用前通过 SHA-256 进行检查。
- **审计跟踪**：查询文本在记录之前被哈希。
## MCP 工具
| 区域 | 工具 |
|---|---|
| SQL | `list_tables`、`select`、`explain` |
| MongoDB 读取 | `list_databases`、`list_collections`、`find_documents`、`aggregate_documents`、`distinct_documents`、`count_documents`、`explain_documents` |
| MongoDB 分析 | `profile_document_field`、`discover_document_schema`、`generate_document_fixture` |
| 连接 | `database_info`、`check`、`connect`、`disconnect`、`reconnect` |
| 配置 | `config_validate`、`config_show`、`config_set_password`、`config_rename_environment`、`config_delete_environment`、`config_reset` |
| 设置 | `import_compose`、`driver_list`、`driver_add`、`driver_download`、`agent_detect`、`agent_install`、`agent_status`、`agent_uninstall` |
当不存在 `.safeselect/` 目录时，`safeselect serve --environment <env>` 自动进入设置模式，并仅公开设置安全的工具。
> [!重要]
> 设置模式不公开查询工具。代理可以帮助导入和验证配置，然后再提供任何数据库检查工具。
## CLI 精华
| 命令 | 目的 |
|---|---|
| `safeselect serve --environment <env>` | 启动 MCP 服务器 |
| `safeselect check --environment <env>` | 验证配置、机密、隧道、边车和后端连接性 |
| `safeselect doctor --environment <env>` | 打印具有稳定代码的更深入的诊断信息 |
| `safeselect import-dbeaver <zip>` | 导入 DBeaver 连接 |
| `safeselect import-compose [--path <path>]` | 从 docker-compose 导入 |
| `safeselect import-compass [--path <path>]` | 导入 MongoDB Compass 连接 |
| `safeselect agent install <client> --environment <env>` | 安装 MCP 条目 |
| `safeselect config set-password --environment <env>` | 存储数据库密码 |
| `safeselect config set-ssh-password --environment <env>` | 存储 SSH 密码 |
| `safeselect uninstall` | 删除已安装的二进制文件、全局状态、审计数据和 Keychain 条目 |
使用 `safeselect --help` 或特定于命令的 `--help` 获取完整的 CLI。
交互式 OpenCode 安装允许您选择项目本地 JSON 配置，在适当时创建单独的 `.opencode/opencode.jsonc`，或使用全局配置。卸载检查发布安装程序和 Cargo 二进制文件位置。MongoDB Compass 导入支持 SSH 隧道 `mongodb+srv://` 连接，通过解析 SRV 目标并使用所需的 TLS 和直接连接选项重写本地端点。
## 配置
全局状态默认存储在 `~/.config/safeselect/` 中。项目策略存储在存储库根目录的 `.safeselect/` 中：
```text
<repo-root>/
└── .safeselect/
├── project.toml
└── environments/
└── <env>.toml
```
安全选择从当前目录向上遍历以查找 `.safeselect/`。在代理或脚本应针对特定存储库时，请使用 `--project <path>`。
## 支持的代理
- OpenCode：支持安装
- GitHub Copilot、Cursor、Windsurf、Claude Code、Codex、Gemini CLI：支持检测
## 从源代码构建
```bash
./install.sh
safeselect --version
```
要求：Rust 1.81+、Java 17+、Maven 3.8+。`sshpass` 是基于密码的 SSH 隧道的选项。
## 文档
- [安装指南](docs/install.md)
- [AI 代理集成](docs/agents.md)
- [安全模型](docs/security.md)
- [安全策略](SECURITY.md)
- [分发](docs/distribution.md)
- [变更日志](CHANGELOG.md)
发布说明从 `CHANGELOG.md` 生成。
## 许可证
MIT - 参见 [LICENSE](LICENSE)。
