db-mcp 使用说明

项目简介

db-mcp 是一个以 MCP 为核心的后端服务器，专门为 LLM 客户端提供标准化的数据库上下文服务。它托管资源、注册并执行工具、并定义可渲染的提示模板，支持通过 JSON-RPC 与客户端通信，具备会话管理、能力声明，以及多种传输协议支持（如标准输入输出、HTTP/SSE）。当前实现提供对 SQLite 的两种后端模式（Native 与 WASM），并内建 OAuth 2.1 鉴权。

主要功能点

MCP 栈：符合 MCP 协议的请求/响应处理与 JSON-RPC 通信（支持初始化、工具调用、资源获取等流程）。
资源、工具、提示的统一管理：8 个资源、122 个 Native 工具（102 个 WASM 版本），以及 10 个提示模板（Prompts）。
传输层多样化：stdio、HTTP（含 SSE 流通知）等传输，支持有状态会话和无状态服务模式。
安全与认证：内置 OAuth 2.1 实现，Token 验证、作用域控制、基于资源与工具的细粒度权限。
Tool Filtering：灵活的工具筛选机制，支持快捷方式、分组与自定义工具集合，便于在 IDE/环境中控制工具集规模。
SQL/数据库安全：通过 WHERE 子句安全校验、标识符校验与防注入策略，确保工具对数据库的访问安全。
深度集成的测试覆盖：全面的单元测试与集成测试覆盖核心组件与安全策略。

安装步骤

克隆代码库并安装依赖
运行构建：npm run build
启动服务器（两种后端模式任选其一）：
- Native 后端（better-sqlite3，特性最全，适合生产环境）： node dist/cli.js --transport stdio --sqlite-native ./database.db
- WASM 后端（sql.js，跨平台、无需本地编译）： node dist/cli.js --transport stdio --sqlite ./database.db
如需使用 HTTP/SSE 传输，使用 npm/编排的 HTTP 传输命令启动并监听端口（如 3000），并结合 OAuth 配置使用。

服务器配置（MCP 客户端需要的最低信息）

说明：MCP 客户端需要配置一个描述服务器的 JSON 信息，包含服务器名称、启动命令与参数等，以便建立连接。下面给出“示意性的配置描述”，以帮助理解具体字段的含义；实际使用时请按客户端专用 JSON 配置格式提供，确保与服务器启动参数相符。

serverName（服务器名称）: db-mcp-sqlite
command（启动命令）: node
args（启动参数数组）: ["dist/cli.js", "--transport", "stdio", "--sqlite-native", ":memory:", "--tool-filter", "starter"]

参数注释：

serverName 指定 MCP 服务器在客户端侧的标识名称，便于区分不同服务器实例。
command 指定启动服务器的可执行文件，这里通常是 node，用于运行 dist/cli.js。
args 指定启动时的参数，包含传输类型、数据库后端选择、数据库路径以及工具筛选等配置，确保客户端初始化时能正确建立会话并加载合适的工具集。注：MCP 客户端不需要任何实现细节，仅需要知道服务器名称与启动参数的组合，以便在客户端侧发起初始化请求。

基本使用方法

通过快速测试：构建后直接运行 dist/cli.js，选择网络传输或标准输入输出，确保数据库文件或内存数据库可用。
使用 OAuth 的场景：在 HTTP 传输模式下启用 OAuth，提供授权服务器、JWKS、客户端信息等，客户端在获取到 Bearer Token 后即可发起带鉴权的 MCP 请求。
Tool Filtering 与资源访问：通过配置 toolFilter 和资源/提示定义，控制 LLM 客户端可访问的工具与数据源，确保安全且高效的上下文提供。
监控与调试：利用 server_health、server_info、list_adapters 等内置工具查询服务器状态与已注册的适配器信息，结合日志系统对运行状态进行诊断。

db-mcp - SQLite MCP Server