universal-db-mcp 0.1.0

package/EXAMPLES.md

@@ -0,0 +1,362 @@
+# 使用示例
+
+本文档提供 MCP 数据库万能连接器的详细使用示例。
+
+## 📋 目录
+
+- [MySQL 使用示例](#mysql-使用示例)
+- [PostgreSQL 使用示例](#postgresql-使用示例)
+- [Redis 使用示例](#redis-使用示例)
+- [Claude Desktop 配置示例](#claude-desktop-配置示例)
+- [常见使用场景](#常见使用场景)
+
+---
+
+## MySQL 使用示例
+
+### 基础配置（只读模式）
+
+```json
+{
+  "mcpServers": {
+    "mysql-db": {
+      "command": "npx",
+      "args": [
+        "universal-db-mcp",
+        "--type", "mysql",
+        "--host", "localhost",
+        "--port", "3306",
+        "--user", "root",
+        "--password", "your_password",
+        "--database", "myapp_db"
+      ]
+    }
+  }
+}
+```
+
+### 启用写入模式（谨慎使用）
+
+```json
+{
+  "mcpServers": {
+    "mysql-dev": {
+      "command": "npx",
+      "args": [
+        "universal-db-mcp",
+        "--type", "mysql",
+        "--host", "localhost",
+        "--port", "3306",
+        "--user", "dev_user",
+        "--password", "dev_password",
+        "--database", "dev_database",
+        "--danger-allow-write"
+      ]
+    }
+  }
+}
+```
+
+### 与 Claude 对话示例
+
+**用户**: 帮我查看 users 表的结构
+
+**Claude 会自动**:
+1. 调用 `get_table_info` 工具
+2. 返回表的列信息、主键、索引等
+
+**用户**: 统计最近 7 天注册的用户数量
+
+**Claude 会自动**:
+1. 理解需求
+2. 生成 SQL: `SELECT COUNT(*) FROM users WHERE created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)`
+3. 调用 `execute_query` 工具执行
+4. 返回结果
+
+---
+
+## PostgreSQL 使用示例
+
+### 基础配置
+
+```json
+{
+  "mcpServers": {
+    "postgres-db": {
+      "command": "npx",
+      "args": [
+        "universal-db-mcp",
+        "--type", "postgres",
+        "--host", "localhost",
+        "--port", "5432",
+        "--user", "postgres",
+        "--password", "your_password",
+        "--database", "myapp"
+      ]
+    }
+  }
+}
+```
+
+### 连接远程数据库
+
+```json
+{
+  "mcpServers": {
+    "postgres-prod": {
+      "command": "npx",
+      "args": [
+        "universal-db-mcp",
+        "--type", "postgres",
+        "--host", "db.example.com",
+        "--port", "5432",
+        "--user", "readonly_user",
+        "--password", "secure_password",
+        "--database", "production"
+      ]
+    }
+  }
+}
+```
+
+### 与 Claude 对话示例
+
+**用户**: 找出订单金额最高的 10 个客户
+
+**Claude 会自动**:
+1. 调用 `get_schema` 了解表结构
+2. 生成复杂的 JOIN 查询
+3. 执行并返回结果
+
+---
+
+## Redis 使用示例
+
+### 基础配置（无密码）
+
+```json
+{
+  "mcpServers": {
+    "redis-cache": {
+      "command": "npx",
+      "args": [
+        "universal-db-mcp",
+        "--type", "redis",
+        "--host", "localhost",
+        "--port", "6379"
+      ]
+    }
+  }
+}
+```
+
+### 带密码和数据库选择
+
+```json
+{
+  "mcpServers": {
+    "redis-session": {
+      "command": "npx",
+      "args": [
+        "universal-db-mcp",
+        "--type", "redis",
+        "--host", "localhost",
+        "--port", "6379",
+        "--password", "redis_password",
+        "--database", "1"
+      ]
+    }
+  }
+}
+```
+
+### 与 Claude 对话示例
+
+**用户**: 查看所有以 "user:" 开头的键
+
+**Claude 会执行**: `KEYS user:*`
+
+**用户**: 获取 user:1001 的信息
+
+**Claude 会执行**: `GET user:1001` 或 `HGETALL user:1001`（根据数据类型）
+
+---
+
+## Claude Desktop 配置示例
+
+### 同时连接多个数据库
+
+你可以在 Claude Desktop 中同时配置多个数据库连接：
+
+```json
+{
+  "mcpServers": {
+    "mysql-prod": {
+      "command": "npx",
+      "args": [
+        "universal-db-mcp",
+        "--type", "mysql",
+        "--host", "prod-db.example.com",
+        "--port", "3306",
+        "--user", "readonly",
+        "--password", "prod_password",
+        "--database", "production"
+      ]
+    },
+    "postgres-analytics": {
+      "command": "npx",
+      "args": [
+        "universal-db-mcp",
+        "--type", "postgres",
+        "--host", "analytics.example.com",
+        "--port", "5432",
+        "--user", "analyst",
+        "--password", "analytics_password",
+        "--database", "warehouse"
+      ]
+    },
+    "redis-cache": {
+      "command": "npx",
+      "args": [
+        "universal-db-mcp",
+        "--type", "redis",
+        "--host", "cache.example.com",
+        "--port", "6379",
+        "--password", "cache_password"
+      ]
+    }
+  }
+}
+```
+
+重启 Claude Desktop 后，你可以在对话中指定使用哪个数据库：
+
+- "在 MySQL 生产库中查询..."
+- "从 PostgreSQL 分析库获取..."
+- "检查 Redis 缓存中的..."
+
+---
+
+## 常见使用场景
+
+### 1. 数据分析
+
+**场景**: 快速分析业务数据
+
+```
+用户: 帮我分析最近一个月的销售趋势
+
+Claude 会:
+1. 查看 orders 表结构
+2. 按日期分组统计订单金额
+3. 生成趋势分析报告
+```
+
+### 2. 问题排查
+
+**场景**: 排查生产问题
+
+```
+用户: 为什么用户 ID 12345 无法登录？
+
+Claude 会:
+1. 查询 users 表找到该用户
+2. 检查 login_logs 表的最近记录
+3. 分析可能的原因（账号状态、密码错误次数等）
+```
+
+### 3. 数据迁移准备
+
+**场景**: 了解数据库结构以准备迁移
+
+```
+用户: 帮我生成所有表的结构文档
+
+Claude 会:
+1. 调用 get_schema 获取完整结构
+2. 整理成 Markdown 格式的文档
+3. 包含表名、列定义、索引、外键等信息
+```
+
+### 4. 性能优化建议
+
+**场景**: 优化慢查询
+
+```
+用户: 这个查询很慢，帮我优化：SELECT * FROM orders WHERE user_id = 123
+
+Claude 会:
+1. 查看 orders 表的索引情况
+2. 建议添加索引或修改查询
+3. 解释优化原理
+```
+
+### 5. Redis 缓存管理
+
+**场景**: 管理缓存数据
+
+```
+用户: 清理所有过期的会话缓存
+
+Claude 会:
+1. 查找所有 session: 开头的键
+2. 检查 TTL
+3. 在写入模式下执行清理（需要 --danger-allow-write）
+```
+
+---
+
+## 安全提示
+
+### ✅ 推荐做法
+
+1. **生产环境只读**: 生产数据库永远不要启用 `--danger-allow-write`
+2. **使用专用账号**: 为 MCP 创建权限受限的数据库账号
+3. **网络隔离**: 通过 VPN 或跳板机访问生产数据库
+4. **审计日志**: 定期检查 Claude Desktop 的操作日志
+
+### ❌ 避免做法
+
+1. 不要在生产环境启用写入模式
+2. 不要使用 root 或 admin 账号
+3. 不要在公共网络直接连接数据库
+4. 不要在配置文件中明文存储密码（考虑使用环境变量）
+
+---
+
+## 故障排查
+
+### 连接失败
+
+**错误**: `数据库连接失败`
+
+**解决方案**:
+1. 检查数据库服务是否运行
+2. 验证主机地址和端口
+3. 确认用户名和密码正确
+4. 检查防火墙规则
+
+### 权限不足
+
+**错误**: `Access denied` 或 `permission denied`
+
+**解决方案**:
+1. 确认数据库用户有足够权限
+2. MySQL: `GRANT SELECT ON database.* TO 'user'@'host';`
+3. PostgreSQL: `GRANT SELECT ON ALL TABLES IN SCHEMA public TO user;`
+
+### 写操作被拒绝
+
+**错误**: `操作被拒绝：当前处于只读安全模式`
+
+**解决方案**:
+- 这是安全特性，如需写入，添加 `--danger-allow-write` 参数
+- 仅在开发环境使用！
+
+---
+
+## 更多帮助
+
+- 查看 [README.md](./README.md) 了解项目概述
+- 查看 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解如何贡献
+- 提交 Issue: https://github.com/yourusername/universal-db-mcp/issues

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Universal DB MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# 🔌 MCP 数据库万能连接器
+
+> 让 Claude Desktop 直接连接你的数据库，用自然语言查询和分析数据
+
+[![npm version](https://img.shields.io/npm/v/universal-db-mcp.svg)](https://www.npmjs.com/package/universal-db-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🎯 为什么使用本项目
+
+作为开发者，你是否遇到过这些场景：
+
+- 📊 **临时数据分析**：想快速查看生产数据库的某些指标，但不想写 SQL？
+- 🔍 **问题排查**：需要跨多个表关联查询，但记不清表结构？
+- 🤖 **AI 辅助开发**：希望 Claude 能直接理解你的数据库结构，生成准确的查询？
+
+**MCP 数据库万能连接器** 通过 Model Context Protocol (MCP) 协议，让 Claude Desktop 成为你的数据库助手：
+
+✅ **自然语言查询** - 用中文描述需求，Claude 自动生成并执行 SQL
+✅ **智能表结构理解** - 自动获取数据库 Schema，提供精准建议
+✅ **多数据库支持** - MySQL、PostgreSQL、Redis 一键切换
+✅ **安全第一** - 默认只读模式，防止误操作删库
+✅ **开箱即用** - 无需复杂配置，一行命令启动
+
+## 🚀 快速开始
+
+### 前置要求
+
+- Node.js >= 20
+- Claude Desktop 应用
+- 至少一个数据库实例（MySQL/PostgreSQL/Redis）
+
+### 安装
+
+```bash
+npm install -g universal-db-mcp
+```
+
+或使用 npx 直接运行（无需安装）：
+
+```bash
+npx universal-db-mcp
+```
+
+### 配置 Claude Desktop
+
+编辑 Claude Desktop 配置文件：
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+添加以下配置：
+
+```json
+{
+  "mcpServers": {
+    "universal-db": {
+      "command": "npx",
+      "args": [
+        "universal-db-mcp",
+        "--type", "mysql",
+        "--host", "localhost",
+        "--port", "3306",
+        "--user", "root",
+        "--password", "your_password",
+        "--database", "your_database"
+      ]
+    }
+  }
+}
+```
+
+### 启动使用
+
+1. 重启 Claude Desktop
+2. 在对话中直接询问：
+   - "帮我查看 users 表的结构"
+   - "统计最近 7 天的订单数量"
+   - "找出消费金额最高的 10 个用户"
+
+Claude 会自动调用数据库工具完成查询！
+
+## 🛡️ 安全模式
+
+**默认情况下，本工具运行在只读模式**，会拒绝所有写入操作（DELETE、UPDATE、DROP、TRUNCATE）。
+
+如果你需要执行写入操作（请谨慎！），需要显式添加参数：
+
+```json
+{
+  "args": [
+    "universal-db-mcp",
+    "--danger-allow-write",
+    "--type", "mysql",
+    ...
+  ]
+}
+```
+
+⚠️ **警告**：启用写入模式后，Claude 可以修改你的数据库。请仅在开发环境使用，或确保你完全理解操作的后果。
+
+## 📖 支持的数据库
+
+| 数据库 | 类型参数 | 状态 |
+|--------|---------|------|
+| MySQL | `--type mysql` | ✅ 已支持 |
+| PostgreSQL | `--type postgres` | ✅ 已支持 |
+| Redis | `--type redis` | ✅ 已支持 |
+| MongoDB | `--type mongo` | 🚧 计划中 |
+| SQLite | `--type sqlite` | 🚧 计划中 |
+
+## 🔧 命令行参数
+
+```bash
+universal-db-mcp [选项]
+
+选项：
+  --type <db>              数据库类型 (mysql|postgres|redis)
+  --host <host>            数据库主机地址 (默认: localhost)
+  --port <port>            数据库端口
+  --user <user>            用户名
+  --password <password>    密码
+  --database <database>    数据库名称
+  --danger-allow-write     启用写入模式（危险！）
+  --help                   显示帮助信息
+```
+
+## 🏗️ 架构设计
+
+本项目采用模块化适配器模式，方便社区贡献新的数据库支持：
+
+```
+src/
+├── adapters/          # 数据库适配器
+│   ├── mysql.ts
+│   ├── postgres.ts
+│   └── redis.ts
+├── types/             # TypeScript 类型定义
+│   └── adapter.ts
+├── utils/             # 工具函数
+│   └── safety.ts      # 安全检查逻辑
+└── server.ts          # MCP 服务器主逻辑
+```
+
+## 🤝 贡献指南
+
+欢迎提交 Issue 和 Pull Request！
+
+如果你想添加新的数据库支持，只需：
+
+1. 在 `src/adapters/` 下实现 `DbAdapter` 接口
+2. 添加对应的数据库驱动依赖
+3. 更新 README 文档
+
+详见 [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+## 📄 开源协议
+
+MIT License - 自由使用，欢迎 Star ⭐
+
+## 🙏 致谢
+
+- [Model Context Protocol](https://modelcontextprotocol.io/) - Anthropic 提供的强大协议
+- 所有贡献者和使用者
+
+---
+
+**如果这个项目对你有帮助，请给个 Star ⭐ 支持一下！**

package/dist/adapters/mysql.d.ts

@@ -0,0 +1,41 @@
+/**
+ * MySQL 数据库适配器
+ * 使用 mysql2 驱动实现 DbAdapter 接口
+ */
+import type { DbAdapter, QueryResult, SchemaInfo } from '../types/adapter.js';
+export declare class MySQLAdapter implements DbAdapter {
+    private connection;
+    private config;
+    constructor(config: {
+        host: string;
+        port: number;
+        user?: string;
+        password?: string;
+        database?: string;
+    });
+    /**
+     * 连接到 MySQL 数据库
+     */
+    connect(): Promise<void>;
+    /**
+     * 断开数据库连接
+     */
+    disconnect(): Promise<void>;
+    /**
+     * 执行 SQL 查询
+     */
+    executeQuery(query: string, params?: unknown[]): Promise<QueryResult>;
+    /**
+     * 获取数据库结构信息
+     */
+    getSchema(): Promise<SchemaInfo>;
+    /**
+     * 获取单个表的详细信息
+     */
+    private getTableInfo;
+    /**
+     * 检查是否为写操作
+     */
+    isWriteOperation(query: string): boolean;
+}
+//# sourceMappingURL=mysql.d.ts.map

package/dist/adapters/mysql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.d.ts","sourceRoot":"","sources":["../../src/adapters/mysql.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,UAAU,EAIX,MAAM,qBAAqB,CAAC;AAG7B,qBAAa,YAAa,YAAW,SAAS;IAC5C,OAAO,CAAC,UAAU,CAAiC;IACnD,OAAO,CAAC,MAAM,CAMZ;gBAEU,MAAM,EAAE;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB;IAID;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB9B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAOjC;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAwC3E;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,UAAU,CAAC;IAwCtC;;OAEG;YACW,YAAY;IAuE1B;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAGzC"}