mcp-database-server AGENTS.md

MCP Database Server — AI 助手指南

项目概述

这是一个基于 Model Context Protocol (MCP) 的数据库服务器，通过 MCP 工具和资源接口让 AI 客户端（如 Claude）与多种数据库交互。

• npm 包名: @executeautomation/database-server（或发布为 @pixel2012/mcp-database-server）
• GitHub: https://github.com/pixel2012/mcp-database-server
• 入口文件: src/index.ts → 编译为 dist/src/index.js
• MCP SDK: @modelcontextprotocol/sdk v1.9.0
• 许可: MIT

构建与运行

命令	用途
npm run build	编译 TypeScript
npm run dev	编译并立即运行
npm run watch	监听模式编译
npm run clean	删除 dist/
npm run example	运行示例脚本

部署方式

本地直接运行

node dist/src/index.js <sqlite-path>
node dist/src/index.js --mysql --host <host> --database <db> --user <user> --password <pass>

集成到 mcp-gateway / Claude Desktop

方式一：本地路径（适合开发调试）

{
  "mcpServers": {
    "mysql-db": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-database-server/dist/src/index.js",
        "--mysql", "--host", "10.60.5.47",
        "--database", "dify_db", "--port", "3306",
        "--user", "root", "--password", "xjgc@1234"
      ]
    }
  }
}

方式二：发布到 npm（推荐，启动快有缓存）

# 修改 package.json 中的 name 字段后发布
npm publish

{
  "command": "npx",
  "args": ["-y", "@yourname/mcp-database-server", "--mysql", ...]
}

方式三：GitHub 直拉（推代码即用，无需发布）

{
  "command": "npx",
  "args": ["-y", "github:pixel2012/mcp-database-server", "--mysql", ...]
}

npx 会自动 clone → npm install（触发 prepare 脚本自动 npm run build）→ 运行。首次启动较慢，后续有缓存。

Docker 部署

docker build -t mcp-database-server .
docker run --rm -i mcp-database-server /path/to/database.db

项目结构

src/
├── index.ts                  # 入口：CLI 参数解析、MCP 服务器初始化
├── db/
│   ├── adapter.ts            # DbAdapter 接口 + 工厂函数
│   ├── index.ts              # 数据库工具函数（init, dbAll, dbRun 等）
│   ├── sqlite-adapter.ts     # SQLite 实现
│   ├── sqlserver-adapter.ts  # SQL Server 实现
│   ├── postgresql-adapter.ts # PostgreSQL 实现
│   └── mysql-adapter.ts      # MySQL 实现（含 AWS IAM 认证）
├── handlers/
│   ├── toolHandlers.ts       # MCP 工具列表分发
│   └── resourceHandlers.ts   # MCP 资源列表与读取
├── tools/
│   ├── queryTools.ts         # read_query, write_query, export_query
│   ├── schemaTools.ts        # create_table, alter_table, drop_table, list_tables, describe_table
│   └── insightTools.ts       # append_insight, list_insights
└── utils/
    └── formatUtils.ts        # CSV/JSON 格式化、错误/成功响应