universal-db-mcp 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# 贡献指南
+
+感谢你对 MCP 数据库万能连接器的关注！我们欢迎所有形式的贡献。
+
+## 🤝 如何贡献
+
+### 报告 Bug
+
+如果你发现了 Bug，请在 [GitHub Issues](https://github.com/yourusername/universal-db-mcp/issues) 中提交，并包含：
+
+- 详细的问题描述
+- 复现步骤
+- 预期行为 vs 实际行为
+- 环境信息（操作系统、Node.js 版本、数据库版本）
+
+### 提交功能建议
+
+我们欢迎新功能建议！请先在 Issues 中讨论，确保该功能符合项目方向。
+
+### 提交代码
+
+1. **Fork 本仓库**
+2. **创建特性分支**: `git checkout -b feature/amazing-feature`
+3. **编写代码**: 遵循下面的代码规范
+4. **提交更改**: `git commit -m '添加某某功能'`
+5. **推送分支**: `git push origin feature/amazing-feature`
+6. **创建 Pull Request**
+
+## 📝 代码规范
+
+- 使用 TypeScript 严格模式
+- 关键架构决策需要添加中文注释
+- 用户可见的消息必须使用简体中文
+- 遵循现有的代码风格
+
+## 🔌 添加新数据库支持
+
+如果你想添加新的数据库支持（如 MongoDB、SQLite），请按以下步骤：
+
+1. 在 `src/adapters/` 下创建新文件（如 `mongodb.ts`）
+2. 实现 `DbAdapter` 接口
+3. 在 `src/index.ts` 中添加对应的 case 分支
+4. 更新 `README.md` 的支持列表
+5. 添加相应的 npm 依赖
+
+### 示例结构
+
+```typescript
+// src/adapters/mongodb.ts
+import type { DbAdapter, QueryResult, SchemaInfo } from '../types/adapter.js';
+
+export class MongoDBAdapter implements DbAdapter {
+  async connect(): Promise<void> {
+    // 实现连接逻辑
+  }
+
+  async disconnect(): Promise<void> {
+    // 实现断开连接逻辑
+  }
+
+  async executeQuery(query: string, params?: unknown[]): Promise<QueryResult> {
+    // 实现查询逻辑
+  }
+
+  async getSchema(): Promise<SchemaInfo> {
+    // 实现获取结构逻辑
+  }
+
+  isWriteOperation(query: string): boolean {
+    // 实现写操作检测
+  }
+}
+```
+
+## ✅ 提交前检查清单
+
+- [ ] 代码通过 TypeScript 编译 (`npm run build`)
+- [ ] 关键逻辑添加了中文注释
+- [ ] 用户可见消息使用简体中文
+- [ ] 更新了相关文档
+- [ ] 测试了基本功能
+
+## 📄 许可证
+
+提交代码即表示你同意将代码以 MIT 许可证开源。
+
+## 💬 联系方式
+
+如有疑问，欢迎在 Issues 中讨论或联系维护者。
+
+---
+
+再次感谢你的贡献！🎉

package/DEPLOYMENT.md

@@ -0,0 +1,411 @@
+# 部署指南
+
+本文档介绍如何将 MCP 数据库万能连接器部署到不同环境。
+
+## 📦 发布到 NPM
+
+### 准备工作
+
+1. **注册 NPM 账号**
+   ```bash
+   npm adduser
+   ```
+
+2. **更新 package.json**
+
+   确保以下字段正确：
+   ```json
+   {
+     "name": "universal-db-mcp",
+     "version": "0.1.0",
+     "description": "MCP 数据库万能连接器 - 让 Claude Desktop 直接连接你的数据库",
+     "repository": {
+       "type": "git",
+       "url": "https://github.com/yourusername/universal-db-mcp.git"
+     },
+     "keywords": [
+       "mcp",
+       "model-context-protocol",
+       "claude",
+       "database",
+       "mysql",
+       "postgresql",
+       "redis"
+     ]
+   }
+   ```
+
+3. **构建项目**
+   ```bash
+   npm run build
+   ```
+
+4. **测试本地安装**
+   ```bash
+   npm pack
+   npm install -g ./universal-db-mcp-0.1.0.tgz
+   universal-db-mcp --help
+   ```
+
+### 发布
+
+```bash
+# 发布到 NPM
+npm publish
+
+# 如果是第一次发布，可能需要验证邮箱
+# 如果包名已被占用，需要修改 package.json 中的 name
+```
+
+### 版本管理
+
+```bash
+# 补丁版本（bug 修复）
+npm version patch  # 0.1.0 -> 0.1.1
+
+# 次要版本（新功能）
+npm version minor  # 0.1.0 -> 0.2.0
+
+# 主要版本（破坏性更改）
+npm version major  # 0.1.0 -> 1.0.0
+
+# 发布新版本
+npm publish
+```
+
+---
+
+## 🐳 Docker 部署
+
+### 创建 Dockerfile
+
+```dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+# 复制 package 文件
+COPY package*.json ./
+
+# 安装依赖
+RUN npm ci --only=production
+
+# 复制源代码
+COPY . .
+
+# 构建
+RUN npm run build
+
+# 设置入口点
+ENTRYPOINT ["node", "dist/index.js"]
+```
+
+### 构建镜像
+
+```bash
+docker build -t universal-db-mcp:latest .
+```
+
+### 运行容器
+
+```bash
+# MySQL 示例
+docker run -it \
+  universal-db-mcp:latest \
+  --type mysql \
+  --host host.docker.internal \
+  --port 3306 \
+  --user root \
+  --password password \
+  --database mydb
+
+# 使用环境变量
+docker run -it \
+  -e DB_TYPE=mysql \
+  -e DB_HOST=host.docker.internal \
+  -e DB_PORT=3306 \
+  -e DB_USER=root \
+  -e DB_PASSWORD=password \
+  -e DB_NAME=mydb \
+  universal-db-mcp:latest
+```
+
+---
+
+## 🔧 本地开发部署
+
+### 从源码安装
+
+```bash
+# 克隆仓库
+git clone https://github.com/yourusername/universal-db-mcp.git
+cd universal-db-mcp
+
+# 安装依赖
+npm install
+
+# 构建
+npm run build
+
+# 全局链接（用于开发）
+npm link
+
+# 现在可以直接使用
+universal-db-mcp --help
+```
+
+### 开发模式
+
+```bash
+# 监听文件变化，自动重新编译
+npm run dev
+```
+
+### 在 Claude Desktop 中使用本地版本
+
+编辑 Claude Desktop 配置文件，使用本地路径：
+
+```json
+{
+  "mcpServers": {
+    "local-db": {
+      "command": "node",
+      "args": [
+        "/path/to/universal-db-mcp/dist/index.js",
+        "--type", "mysql",
+        "--host", "localhost",
+        "--port", "3306",
+        "--user", "root",
+        "--password", "password",
+        "--database", "test"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 🌐 企业内网部署
+
+### 场景：通过跳板机访问数据库
+
+1. **在跳板机上安装**
+   ```bash
+   ssh jumphost
+   npm install -g universal-db-mcp
+   ```
+
+2. **配置 SSH 隧道**
+   ```bash
+   # 本地机器执行
+   ssh -L 3306:db-server:3306 user@jumphost -N
+   ```
+
+3. **Claude Desktop 配置**
+   ```json
+   {
+     "mcpServers": {
+       "prod-db": {
+         "command": "npx",
+         "args": [
+           "universal-db-mcp",
+           "--type", "mysql",
+           "--host", "localhost",
+           "--port", "3306",
+           "--user", "readonly",
+           "--password", "secure_password",
+           "--database", "production"
+         ]
+       }
+     }
+   }
+   ```
+
+### 场景：使用 VPN 连接
+
+1. **连接企业 VPN**
+
+2. **直接配置内网地址**
+   ```json
+   {
+     "mcpServers": {
+       "internal-db": {
+         "command": "npx",
+         "args": [
+           "universal-db-mcp",
+           "--type", "postgres",
+           "--host", "10.0.1.100",
+           "--port", "5432",
+           "--user", "analyst",
+           "--password", "password",
+           "--database", "analytics"
+         ]
+       }
+     }
+   }
+   ```
+
+---
+
+## 🔐 安全最佳实践
+
+### 1. 使用专用数据库账号
+
+**MySQL**:
+```sql
+-- 创建只读用户
+CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'secure_password';
+GRANT SELECT ON mydb.* TO 'mcp_readonly'@'%';
+FLUSH PRIVILEGES;
+```
+
+**PostgreSQL**:
+```sql
+-- 创建只读用户
+CREATE USER mcp_readonly WITH PASSWORD 'secure_password';
+GRANT CONNECT ON DATABASE mydb TO mcp_readonly;
+GRANT USAGE ON SCHEMA public TO mcp_readonly;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;
+```
+
+### 2. 使用环境变量存储密码
+
+创建 `.env` 文件（不要提交到 Git）：
+```bash
+DB_PASSWORD=your_secure_password
+```
+
+修改 Claude Desktop 配置使用环境变量：
+```json
+{
+  "mcpServers": {
+    "secure-db": {
+      "command": "bash",
+      "args": [
+        "-c",
+        "source ~/.env && npx universal-db-mcp --type mysql --host localhost --port 3306 --user root --password $DB_PASSWORD --database mydb"
+      ]
+    }
+  }
+}
+```
+
+### 3. 网络隔离
+
+- 使用防火墙限制数据库访问
+- 仅允许特定 IP 连接
+- 使用 SSL/TLS 加密连接
+
+### 4. 审计日志
+
+定期检查 Claude Desktop 的日志：
+
+**macOS**: `~/Library/Logs/Claude/`
+**Windows**: `%APPDATA%\Claude\logs\`
+
+---
+
+## 📊 监控和日志
+
+### 启用详细日志
+
+MCP 服务器的日志输出到 stderr，可以通过 Claude Desktop 查看。
+
+### 自定义日志记录
+
+如果需要更详细的日志，可以修改源码添加日志记录：
+
+```typescript
+// src/server.ts
+console.error(`[${new Date().toISOString()}] 执行查询: ${query}`);
+```
+
+---
+
+## 🚀 性能优化
+
+### 1. 连接池（未来改进）
+
+当前版本使用单一连接，未来可以添加连接池支持：
+
+```typescript
+// 使用 mysql2 连接池
+const pool = mysql.createPool({
+  host: config.host,
+  port: config.port,
+  user: config.user,
+  password: config.password,
+  database: config.database,
+  connectionLimit: 10,
+});
+```
+
+### 2. 查询缓存
+
+对于频繁查询的 schema 信息，可以添加缓存：
+
+```typescript
+private schemaCache: SchemaInfo | null = null;
+private schemaCacheTime: number = 0;
+private CACHE_TTL = 60000; // 1 分钟
+
+async getSchema(): Promise<SchemaInfo> {
+  const now = Date.now();
+  if (this.schemaCache && now - this.schemaCacheTime < this.CACHE_TTL) {
+    return this.schemaCache;
+  }
+
+  this.schemaCache = await this.fetchSchema();
+  this.schemaCacheTime = now;
+  return this.schemaCache;
+}
+```
+
+---
+
+## 🐛 故障排查
+
+### 问题：Claude Desktop 无法连接
+
+**检查步骤**:
+1. 验证配置文件格式正确（JSON 语法）
+2. 重启 Claude Desktop
+3. 查看 Claude Desktop 日志
+4. 手动测试命令：
+   ```bash
+   npx universal-db-mcp --type mysql --host localhost --port 3306 --user root --password password --database test
+   ```
+
+### 问题：数据库连接超时
+
+**解决方案**:
+1. 检查数据库服务是否运行
+2. 验证网络连接
+3. 检查防火墙规则
+4. 增加连接超时时间（需要修改源码）
+
+### 问题：权限错误
+
+**解决方案**:
+1. 确认数据库用户权限
+2. 检查数据库访问控制列表
+3. 验证用户名和密码
+
+---
+
+## 📚 更多资源
+
+- [使用示例](./EXAMPLES.md)
+- [贡献指南](./CONTRIBUTING.md)
+- [GitHub Issues](https://github.com/yourusername/universal-db-mcp/issues)
+- [Model Context Protocol 文档](https://modelcontextprotocol.io/)
+
+---
+
+## 🎉 部署成功！
+
+完成部署后，你就可以在 Claude Desktop 中使用自然语言查询数据库了！
+
+如有问题，欢迎提交 Issue 或参与讨论。