内容
# 类型安全模型上下文协议（MCP）SQLite 桥接
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://vitest.dev/)
[](https://github.com/aj-jhaveri/mcp-sqlite-bridge/actions/workflows/ci.yml)
[](LICENSE)
一个干净、模块化的模型上下文协议（MCP）服务器，通过类型安全、验证的工具，使 AI 代理能够安全地与本地 SQLite 数据库交互。该服务器使用 TypeScript、Zod 和 Vitest 构建，演示了现代 AI 工程模式，包括代理友好的错误反馈环路和运行时安全控制。
---
## 为什么 MCP 很重要
大型语言模型（LLM）是强大的推理器，但缺乏对动态、实时私有数据的访问。**模型上下文协议（MCP）**，由 Anthropic 开源，建立了一个标准化的双边协议，使 AI 代理能够与数据源、本地文件系统和开发环境交互。
与其为每个自定义应用程序设计单片 API 集成，开发人员通过 MCP 暴露资源和工具。标准化的客户端（例如 Claude Desktop）立即发现这些工具，使代理能够动态、安全、本地地检索上下文、调用函数和检查系统环境。
---
## 架构
该项目实现了一个模块化、分层架构，以解耦传输协议、参数验证、存储库查询层和数据库驱动程序。
```mermaid
graph TD
Client[AI 客户端，例如 Claude Desktop] <-->|JSON-RPC 2.0 over Stdio| Transport[Stdio 传输]
Transport <-->|MCP 协议 SDK| Server[MCP 服务器路由器]
Server <-->|错误格式化中间件| Middleware[错误处理程序]
Server <-->|Zod 模式验证| Schemas[验证层]
Schemas <-->|解析参数| Handlers[工具处理程序]
Handlers <-->|存储库操作| Repository[存储库层]
Repository <-->|参数化查询| Database[(SQLite: mcp_database.db)]
```
### 请求流程
1. **AI 客户端：** 通过标准输入（`stdin`）发出 `tools/call` RPC 命令。
2. **MCP 协议层：** 解码 JSON-RPC 有效载荷并将参数路由到注册的工具模式。
3. **验证层：** 根据严格的 Zod 定义评估参数。
4. **错误拦截器：** 如果验证失败，自定义中间件拦截器清理并编译 Zod 问题为扁平、易读的错误字符串。
5. **工具处理程序：** 接收验证的 TypeScript 对象并将操作调用委托给存储库层。
6. **存储库层：** 抽象查询边界，直接在数据库驱动程序上执行参数化操作。
7. **SQLite 驱动程序：** 安全地写入更改或获取记录，保持数据操作隔离。
---
## 可用工具
服务器根据当前权限范围配置公开以下工具：
| 工具名称 | 操作 | 参数 | 描述 |
| :--- | :--- | :--- | :--- |
| `query_data_source` | **读取** | `category: string` | 检索与请求的类别/领域（例如 `headcount`、`internal_metrics`）匹配的记录。 |
| `add_database_record` | **创建** | `category`、`key_name`、`status`、`detail_one?`、`detail_two?` | 在数据库表中插入新记录。*（在只读模式下禁用）* |
| `update_database_record` | **更新** | `id`、`category?`、`key_name?`、`status?`、`detail_one?`、`detail_two?` | 通过其唯一 ID 修改现有数据库行。*（在只读模式下禁用）* |
---
## 代理反馈环路（自我纠正）
标准工具模式通常返回包含复杂 JSON 数组的原始 Zod 模式验证错误。当发送到 AI 代理时，这种原始格式会导致混淆并增加对话漂移。
该服务器拦截验证错误并将它们格式化为干净、人类可读的字符串：
```text
输入验证错误：字段 'category'：预期字符串，收到数字；字段 'status'：预期字符串，收到未定义
```
当 LLM 客户端接收到此反馈时，它会准确识别哪些字段无效或缺失，并在不需要用户干预的情况下在后续回合中自动纠正它们。
---
## 安全模型
在向自主代理操作公开数据存储时，安全性至关重要：
1. **SQL 注入防护：** 处理程序中的每个查询都是完全参数化的。处理程序使用 SQLite 参数绑定（`?`）严格绑定原始客户端值，防止恶意有效载荷更改 SQL 语句结构。
2. **访问控制（READ_ONLY 模式）：** 服务器支持可配置的只读安全边界。启用时，变异工具（`add_database_record`、`update_database_record`）不会被注册或公开。
3. **本地主权：** 服务器完全通过 `StdioServerTransport` 在本地环路上运行，防止远程数据泄漏并尊重主机权限边界。
---
## 开发
### 1. 安装
安装依赖项：
```bash
npm install
```
### 2. 配置
在本地 `.env` 文件中配置数据库路径和权限：
```env
DB_PATH=mcp_database.db
READ_ONLY=false
```
### 3. 构建和运行
将 TypeScript 源代码编译为 JavaScript：
```bash
npm run build
```
运行演示工具查询、添加和更新的独立演示：
```bash
npm run demo
```
### 4. 与 Claude Desktop 集成
将此服务器配置添加到您的 `claude_desktop_config.json`（位于 `~/Library/Application Support/Claude/claude_desktop_config.json`，适用于 macOS）：
*（注意：在生产中，建议使用标准 `node` 运行编译后的代码，以防止转换器工具状态输出污染 `stdout` 流。）*
```json
{
"mcpServers": {
"slake-data-tools": {
"command": "node",
"args": [
"/absolute/path/to/mcp-server/dist/server.js"
]
}
}
}
```
### 5. 运行测试
运行全面的 Vitest 测试套件，验证 CRUD 操作、Zod 格式化、安全边界和 SQL 注入净化：
```bash
npm test
```
---
## 扩展服务器
要公开新的表或数据库操作：
1. **Zod 验证和类型：** 在 [src/tools/schemas.ts](file:///Users/aj/mcp-server/src/tools/schemas.ts) 中添加相应的模式定义。在 [src/types/database.ts](file:///Users/aj/mcp-server/src/types/database.ts) 中的 TypeScript 类型将自动推断。
2. **存储库层：** 更新 [src/db/repository.ts](file:///Users/aj/mcp-server/src/db/repository.ts) 中的 `IMetricsRepository` 接口和实现，添加新的数据库查询逻辑。
3. **数据库处理程序：** 在 [src/tools/handlers.ts](file:///Users/aj/mcp-server/src/tools/handlers.ts) 中编写高级别事务包装器，调用存储库。
4. **注册：** 在 [src/tools/index.ts](file:///Users/aj/mcp-server/src/tools/index.ts) 中连接处理程序并注入存储库。
---
## 路线图
针对企业代理环境的未来改进：
* **多数据库驱动程序接口：** 通过公共数据库抽象工厂模式支持 PostgreSQL 和 MySQL 驱动程序。
* **粒度基于角色的访问控制：** 细粒度 API 密钥权限或角色范围，将客户端会话映射到不同的表边界。
* **事务确认：** 安全的 webhook 回调系统，允许人类在循环中验证后再提交高价值数据库修改。
* **可观察性拦截器：** OpenTelemetry 跟踪支持，跟踪工具调用持续时间、错误率和系统资源指标。
