内容
n-mcp (Node)
一款用于查询数据库的简单托管的 **模型上下文MCP）服务器**，适用于 AI 代理（如 Claude、Cursor、Windsurf、VS Code、Zed 等）。
它只做一件事：让代理 **安全地探索和查询** 您指定的数据库 — 其安全性委托给最基元（静态 JSON 文件和数据库自身的只读事务），身份验证服务器或脆弱的 SQL 解析。
> 这是 [db-conn](https://github.com/ync/db-conn-mcp) （最初为 Python）的 **Node/TypeScript** 端口。、相同的工具、相同的安全模型 — 发布到 npm 以便您可以使用 `npx`/`npm` 而不是 `pipx`/`pip` 运行。
> 仅支持 PostgreSQL**。所有特定于数据库的代码 `Dialect` 接口后面，因此稍后添加 MySQL 只需添加一个新文件。
---
## 为什么
- **读取始终为读取**。`read` 数据库在原生只读运行每个查询，并且读取工具只接受单个只读语句（`/`WITH`/`VALUES`/`TABLE`/`SHOWEXPLAIN`）— 因此代理无法插入写入或 `SET … READ WRITE` 以翻转获得硬性、特的保证，无论如何都有效，请将 DSN 指向读数据库角色**（请参阅 [使用只读角色只读角色-最强保证)）。
- **无**。DSN/密码永远不会被任何工具记录或连接失败以 **净化诊断**（类别 + 返回，从不返回包含主机和凭证的原始回溯 **分级写入安全性**。写入在服务器端受到限制：`mode`（硬性，原生）→ `yolo`数据库信任）→ `user_consent`（显操作批准）。
- **零摩擦设置**。交互式向导注册您的数据库并将服务器注入到您的 AI 客户端配置中 — 适用于 8 种流行的客户端，每种格式各不相同。
---
## 安装
需要 **Node.js 18+**。
```bash
# 运行而无需安装（推荐试用）：
npx @idle-sync/db-conn-mcp setup
# 或全局安装db-conn-mcp` 位于您的 PATH 中：
npm install -g @idle-sync/db-conn-mcp
```
`db-conn-mcp` 命令。
---
## 快速入门
```bash
db-conn-mcp setup
```
向导会询问：. **范围** —（`~/.db-mcp/connections.json`）或存储库（`./connections.json`）。
2.名称** — 例如 `prod`. **DSN** — 例如 `postgresql://user:pass@host:5432/db。
4. **模式** — `read`（推荐）或 `write`。
5客户端注入** — 选择的检测到的 MCP 例如 `1,3` 或 `all`）。
然后它会写入您的配置并（可选）注册服务器到您选择的 AI中。重启/客户端后，工具即可使用。
> **取消是安全的**。在任何提示下按 Ctrl+C，什么都不会被---
## 配置
单一真实来源是 **`connections.json`**以下顺序解析（优先匹配1. `--config/to/connections.json`
2. `./connections.json`（范围）
3. `~/.db-conn-mcp.json`（全局范围）
```json
{
"connections": [
{ " "prod", "ds "postgresql://…",": "read" },
"name": "dev", "dsn": "postgresql", "mode": "write", "yolo": ]
}
```
| 字段 | 必需 | 含义 |
| ---------- | --------------------------------------------------------------- |
` | 是 代理用来选择数据库的符。 |
| `dsn` | 是 连接字符串。**秘密**任何工具都不会 |
| `mode 是 | `read `write`。绝对的、原生的安全边界。| `yolo 否（默认 `false 如果为 `true`，则为此数据库跳过每次写入的同意提示。 |
> `connections.json` 被该项目的 `.gitignore` 忽略 — 永远不要提交真正的 DSN。
---
## 安全模型
写入通过三个关卡，**按顺序**：
1. **`mode`（硬性，原生）**。如果数据库不是 `"mode": "write"`，则写入被拒绝 — 连接无论如何都在 PostgreSQL 会话级别以只读方式打开，因此被阻止两次。`yolo`user_consent` **永远** 不能使 `read` 数据库。
2. **`yolo`（持久信任）**。对于具有 `yolo: true` 的 `write` 数据库，写入无需进行。
3. **`user`（每个操作）**。否则，代理必须模式，显示确切的 SQL，获取您的“是”，并重新调用 `user_consent=true`。
在原生只读事务中运行，**且** `execute_read_query接受单个只读`SELECT`/`WITH`/`VALUES`/`TABLESHOW`/`EXPLAIN该允许列表阻止 `SET SESSION CHARACTERISTICS READ WRITE` 以翻转会话，或在读取时附加 DELETE …` — 不涉及 SQL 解析，只需关键词检查和驱动程序的单命令协议。
> **注意（Node）：** node-postgres在设置了预名称时，才通过单命令扩展协议运行查询 — 空仍使用多语句简单，读取工具将其命名预备语句发出的 `; DELETE … PostgreSQL 在解析时`无法在预中插入多个命令`原始 asyncpg 的行为 使用只读角色（保证）
上述应用级检查是纵深防御。**最强** 边界权边界：使用 角色连接，该角色**无法**写入，因此即使上述所有层都被绕过，写入也会失败。为每个数据库创建角色并为 `read` 连接使用其 DSN：
```sql
CREATE ROLE agent_ro LOGIN PASSWORD '…';
GRANT CONNECT ON DATABASE mydb TO agent_ro;
GRANT USAGEEMA public TO agentGRANT SELECT ON ALL TABLES IN SCHEMA public TO agentALTER DEFAULT PRIVILE SCHEMA public GR ON TABLES TO agent_ro;
```
这是您关心的的推荐设置。
---
## MCP 工具
服务器暴露 **10 种工具** 和 **1 个提示**:
| 工具 | 类型 | 描述 |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `list_databases` | 探索 | 配置的数据库（名称，模式，yolo — DSN**）。| `list_tables` | 探索 | 数据库中的表和视图。 |
| `get_table_schema | 探索 | 表的列，类型，主键/外键。 |
| `sample_table_rows` | 表的第一 N默认为 10）。 |
| `find_columns | 搜索 跨表按名称查找列（模糊，不区分大小写 |
| `search | 搜索 | 在哪些表中模糊）；返回表命中 + 示例。传递=[…]` 以。 |
| `execute_read_query` | 执行 | 在只读事务中运行单个只读语句（`/`WITH`/… |
| `execute_write | 执行 | 运行变更 — 由上述安全模型 |
| `set_yolo_mode` | 配置 | 为一个数据库启用/禁用 `yolo`）。 |
| `check_database` | | 测试一个数据库（或所有数据库）→ `OK净化诊断。**提示：** `troubleshoot_connection` — 可发现的完整连接问题检查清单（主机/端口，防火墙，`sslmode` `localhost`，数据库名称大小写，连接池限制，…）。
---
## CLI 参考
`db-concp` 既是服务器又是管理工具。
| 命令 功能 |
- | --------------------------------------------------------------------- |
db-conn-mcp` | 通过 **stdio**（默认 MCP 客户端使用）。 |
| `db-conn-mcp --transport http` | 改用 **Streamable HTTP**（`http://127.0.0.1:8000/mcp`）。 |
| `db-conn-mcp setup` | 引导设置；显示状态 + 配置后操作菜单。 |
| `db-conn-mcp status` | 列出配置的数据库和已注入服务器的客户端。 |
| `db-conn-mcp add` | 添加另一个数据库连接。 |
| `db-conn-mcp clients` | 将服务器注入检测到的 MCP 客户端。 |
| `db-conn-mcp clients --remove` | 从选择的客户端中卸载服务器。 |
| `db-conn-mcp check [name]` 探测连接性（退出 `0` 表示全部正常，`2` 表示不可达）。 |
| `db-conn-mcp remove <name>` | 删除一个连接。 |
| `db-conn-mcp reset` | 删除 **所有** 连接（删除 `connections.json`）— 重新开始。 |
| `db-conn-mcp yolo <name> on\|off` | 为一个数据库切换 `yolo`。 |
| `db-conn-mcp -v` / `--version` | 打印已安装的版本并退出。 |
`--config <path>` 在任何子命令之前或之后都有效。
> 原始 Python 服务器的 `--transport http` 使用 SSE（在 MCP SDK 中已弃用）。此端口使用 **Streamable HTTP**，即当前标准，在同一角色下。`stdio` 是 MCP 客户端使用的， unchanged。
---
## 连接 AI 客户端
`db-mcp setup或 `db-conn clients`）自动检测并写入以下客户端的正确配置：
**Claude Desktop · Cursor · Windsurf · Agy（Antigravity）· Claude Code · Cline · VS Code · Zed**
手动连接？使用向导的绝对路径（以便客户端可以找到它，无论 PATH 如何）。对于 `mcpServers` 样式的客户端（Claude Desktop，Cursor，Windsurf，…）：
```json
{
"mcpServers": {
"db-conn-mcp": {
"command": "db-conn-mcp",
"args": ["--config", "/absolute/pathnections.json"]
}
}
}
```
> 如果 `db-conn-mcp` 不在客户端的 PATH 中，请改用解释器`"command": "/abs/path/to/node", "args":abs/path/to/dist/cli.js", "--config", "`。`setup`/`clients` 命令自动这个问题。
VS Code（`servers` `"type": "stdio"`）和 Zed（`context_servers`，嵌套 `command`）使用不同的格式 — 向导也处理这些。
---
## 提供商说明
- **Railway / 托管 Postgres 通过公共代理：** 使用 ** 连接 URL（ 的 `DATABASE_PUBLIC_URL`，而不是内部 `*.railway.internal`追加 **`?sslmode=require`** — 这些代理需要 SSL 和自签名证书，`sslmode=require` 在不接受。
---
## 开发
```bash
git://github.com/Idle-Sync/db-conn-mcp-node
cd db-conn-mcp-node
npm install
npm run typecheck sc，无输出
npm run format:check #
npm test est（154 个测试）
npm run build 译到 dist/
```
分为单一用途的层（`config`、`models`、`dialects/`、`safety`、`diagnostics`、`handlers`
