Mongtap

🚀 MongTap - 面向大语言模型的MongoDB MCP服务器

MongTap是一个模型上下文协议（MCP）服务器，它通过统计建模提供与MongoDB兼容的数据库功能。它允许像Claude这样的大语言模型使用自然语言创建、查询和管理数据库，而无需实际存储数据。

Demo视频链接（YouTube）：

作者：SmallMinds LLC Co

仓库地址：github.com/smallmindsco/MongTap
官网：smallminds.co
联系方式：andrew@smallminds.co

✨ 主要特性

• 🚀 MongoDB有线协议 - 与MongoDB驱动程序和工具完全兼容
• 🧠 统计建模 - 使用DataFlood技术即时生成逼真的数据
• 🔧 MCP集成 - 与Claude Desktop和其他支持MCP的大语言模型无缝协作
• 📊 自然语言 - 根据描述或样本数据训练模型
• ⚡ 高性能 - 每秒可生成20,000多个文档
• 🎯 零存储 - 数据通过统计方式生成，无需存储

📚 详细文档

• 生成控制参数 - 使用$seed和$entropy控制文档生成
• MCPB安装指南 - MCPB捆绑包安装指南

📦 安装指南

前提条件

• Node.js 20+
• Claude Desktop（用于MCP集成）
• 无需安装MongoDB！

快速开始

1. 克隆仓库：

git clone https://github.com/smallmindsco/MongTap.git
cd MongTap

2. 安装依赖（最少依赖）：

npm install

3. 测试安装：

node src/mcp/index.js

4. 启动MongoDB服务器（可选）：

node start-mongodb-server.js

Claude Desktop配置

要在Claude Desktop中使用MongTap，需要将其配置为MCP服务器。

1. 定位Claude Desktop配置文件

找到Claude Desktop的配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

2. 将MongTap添加到配置文件

编辑配置文件，并将MongTap添加到mcpServers部分：

{
  "mcpServers": {
    "mongtap": {
      "command": "node",
      "args": [
        "/absolute/path/to/MongTap/src/mcp/index.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    }
  }
}

重要提示：请将/absolute/path/to/MongTap替换为MongTap的实际安装路径。

3. 重启Claude Desktop

保存配置文件后，重启Claude Desktop使更改生效。

💻 使用示例

快速参考

工具	用途	主要特性
generateDataModel	创建统计模型	基于样本或描述
startMongoServer	启动MongoDB服务器	支持完整的有线协议
stopMongoServer	停止服务器实例	干净关机
listActiveServers	查看正在运行的服务器	监控所有实例
queryModel	生成文档	使用$seed和$entropy控制
trainModel	改进模型	增量学习
listModels	查看可用模型	本地模型清单
getModelInfo	获取模型详情	架构和统计信息

MCP工具参考

1. generateDataModel

描述：根据样本文档或文本描述创建用于数据生成的统计模型。 参数：

• name（必需）：模型名称
• description（可选）：数据结构的自然语言描述
• samples（可选）：用于训练模型的样本文档数组

示例：

generateDataModel({
  name: "users",
  description: "包含姓名、电子邮件、年龄和注册日期的用户资料"
})
// 或者使用样本
generateDataModel({
  name: "products",
  samples: [
    { name: "笔记本电脑", price: 999, category: "电子产品" },
    { name: "办公桌", price: 299, category: "家具" }
  ]
})

2. startMongoServer

描述：启动一个本地的、与MongoDB兼容的服务器，该服务器从统计模型生成数据。 参数：

• port（可选）：监听端口（0表示自动分配，默认值：27017）
• database（可选）：默认数据库名称（默认值："mcp"）

示例：

startMongoServer({ port: 27017, database: "myapp" })
// 返回：{ port: 27017, status: "running" }

3. stopMongoServer

描述：根据端口号停止正在运行的、与MongoDB兼容的服务器实例。 参数：

• port（必需）：要停止的服务器端口

示例：

stopMongoServer({ port: 27017 })
// 返回：{ success: true, message: "服务器已停止" }

4. listActiveServers

描述：获取所有当前正在运行的、与MongoDB兼容的服务器实例列表。 参数：无

示例：

listActiveServers()
// 返回：{ count: 2, servers: [
//   { port: 27017, database: "test", status: "running", uptime: 3600 },
//   { port: 27018, database: "dev", status: "running", uptime: 1800 }
// ]}

5. queryModel

描述：从统计模型生成文档，并可选择使用查询过滤器和生成控制参数。 参数：

• model（必需）：要查询的模型名称
• query（可选）：MongoDB风格的查询，包含特殊参数：
  • $seed：用于可重复生成的数字
  • $entropy：0 - 1之间的数字，用于控制随机程度
• count（可选）：要生成的文档数量（默认值：10）

示例：

queryModel({
  model: "users",
  query: { age: { $gte: 18 }, $seed: 42, $entropy: 0.3 },
  count: 5
})
// 返回5个始终一致生成的成年用户，随机性较低

6. trainModel

描述：使用额外的样本文档更新现有的统计模型，以提高生成质量。 参数：

• model（必需）：要训练的模型名称
• documents（必需）：用于训练的文档数组

示例：

trainModel({
  model: "products",
  documents: [
    { name: "鼠标", price: 29, category: "电子产品" },
    { name: "椅子", price: 199, category: "家具" }
  ]
})
// 返回：{ success: true, samplesAdded: 2, totalSamples: 4 }

7. listModels

描述：获取本地存储的所有可用统计模型列表。 参数：无

示例：

listModels()
// 返回：["users", "products", "orders", "inventory"]

8. getModelInfo

描述：检索特定统计模型的详细架构和统计信息。 参数：

• model（必需）：模型名称

示例：

getModelInfo({ model: "users" })
// 返回：{
//   name: "users",
//   schema: { type: "object", properties: { ... } },
//   sampleCount: 100,
//   lastUpdated: "2025-01-15T10:30:00Z",
//   fields: ["name", "email", "age", "signupDate"]
// }

MCP提示

MongTap包含针对常见数据库场景的预构建提示：

1. create_ecommerce_db

描述：创建一个包含产品、客户和订单的完整电子商务数据库。 用法：要求Claude “使用create_ecommerce_db提示” 即可立即设置完整的电子商务数据库结构。

2. create_user_profile

描述：创建一个包含身份验证和偏好设置的用户资料模型。 用法：非常适合快速设置用户管理系统。

3. analyze_model

描述：分析现有模型并提供其结构的见解。 用法：了解统计模型中的模式和分布。

4. generation_control

描述：了解如何使用$seed和$entropy参数进行受控生成。 用法：获取有关可重复和受控数据生成的详细信息。

MCP资源

MongTap提供用于监控的只读资源：

1. models://list

描述：所有训练过的DataFlood模型列表
类型：application/json
返回：模型名称和元数据数组

2. servers://status

描述：所有MongoDB服务器的状态
类型：application/json
返回：服务器端口、数据库和连接计数

3. models://{name}/schema

描述：获取特定模型的JSON架构
类型：application/json
返回：完整的JSON Schema定义

4. models://{name}/sample

描述：从模型获取样本数据
类型：application/json
返回：样本文档数组

5. docs://generation-control

描述：$seed和$entropy查询参数的文档
类型：text/markdown
返回：详细的使用指南

与Claude的示例对话

根据描述创建数据模型

你：创建一个包含姓名、电子邮件、年龄和注册日期的用户资料数据模型。
Claude：我将使用MongTap为你创建一个用户资料模型。
[使用generateDataModel工具]
我已创建了一个具有以下结构的用户资料模型：
- 姓名（字符串）
- 电子邮件（字符串，电子邮件格式）
- 年龄（整数，0 - 120）
- 注册日期（字符串，日期时间格式）
该模型现在可以生成逼真的用户数据。

启动MongoDB服务器

你：在端口27017上为我的应用程序启动一个MongoDB服务器。
Claude：我将为你启动一个MongoDB服务器。
[使用startMongoServer工具]
MongoDB服务器已成功启动：
- 端口：27017
- 数据库：test
- 连接字符串：mongodb://localhost:27017/test
你现在可以使用任何MongoDB客户端或驱动程序连接到该服务器。
该服务器支持通过查询中的$seed和$entropy参数进行高级生成控制。

生成样本数据

你：从我们创建的模型中生成100个用户资料。
Claude：我将为你生成100个用户资料。
[使用queryModel工具]
已生成100个用户资料。以下是一个示例：
1. { 姓名: "John Smith", 电子邮件: "john.smith@example.com", 年龄: 28, 注册日期: "2024-01-15T10:30:00Z" }
2. { 姓名: "Jane Doe", 电子邮件: "jane.doe@example.com", 年龄: 34, 注册日期: "2024-02-20T14:45:00Z" }
...
所有文档都遵循你的模型的统计模式。

根据样本数据训练模型

你：这里有一些产品样本。请根据它们训练一个模型：
- { 名称: "小工具", 价格: 19.99, 类别: "工具", 库存: 100 }
- { 名称: "小玩意儿", 价格: 29.99, 类别: "电子产品", 库存: 50 }
- { 名称: "小发明", 价格: 39.99, 类别: "工具", 库存: 75 }
Claude：我将根据你的样本训练一个产品模型。
[使用带有样本的generateDataModel工具]
模型训练成功！模型学习到：
- 名称：产品名称（字符串模式）
- 价格：范围19.99 - 39.99（数字分布）
- 类别："工具" 或 "电子产品"（枚举）
- 库存：范围50 - 100（整数分布）
该模型现在可以生成具有逼真变化的类似产品。

连接MongoDB客户端

MongTap服务器与MongoDB客户端完全兼容。通过Claude启动服务器后：

使用MongoDB Shell（mongosh）

mongosh "mongodb://localhost:27017/test"

使用Node.js MongoDB驱动程序

const { MongoClient } = require('mongodb');

async function connect() {
    const client = new MongoClient('mongodb://localhost:27017');
    await client.connect();
    
    const db = client.db('test');
    const collection = db.collection('users');
    
    // 插入操作触发模型训练
    await collection.insertMany([
        { name: 'Alice', age: 30 },
        { name: 'Bob', age: 25 }
    ]);
    
    // 查询操作从模型生成数据
    const users = await collection.find({}).toArray();
    console.log(users); // 统计生成的用户
    
    // 使用生成控制参数
    const consistentData = await collection.find({
        $seed: 12345,  // 一致的结果
        $entropy: 0.5  // 中等随机性
    }).toArray();
    
    await client.close();
}

使用Python（pymongo）

from pymongo import MongoClient

client = MongoClient('mongodb://localhost:27017/')
db = client['test']
collection = db['users']

# 插入操作训练模型
collection.insert_many([
    {'name': 'Alice', 'age': 30},
    {'name': 'Bob', 'age': 25}
])

# 查询操作从模型生成数据
for user in collection.find():
    print(user)  # 统计生成的用户
    
# 使用生成控制
for user in collection.find({'$seed': 12345, '$entropy': 0.3}):
    print(user)  # 一致的、低熵生成

高级用法

多个服务器实例

可以同时运行多个MongoDB服务器：

你：为开发、测试和预发布环境启动三个MongoDB服务器。
Claude：我将为你启动三个独立的MongoDB服务器。
[多次使用startMongoServer工具]
已启动3个MongoDB服务器：
1. 开发环境 - 端口：27017，数据库：dev
2. 测试环境 - 端口：27018，数据库：test  
3. 预发布环境 - 端口：27019，数据库：staging
每个服务器都维护自己的模型，并且可以独立访问。

模型持久化

模型会自动保存，并可以在不同会话中重复使用：

你：列出所有可用的模型。
Claude：[使用listModels工具]
可用的模型：
1. users - 包含姓名、电子邮件、年龄的用户资料
2. products - 包含定价的产品目录
3. orders - 订单管理系统
4. customers - 客户数据库
你可以查询这些模型中的任何一个或训练新的模型。

受限生成

生成具有特定约束和控制参数的数据：

你：使用种子12345生成50个年龄在25到35岁之间且结果一致的用户。
Claude：我将根据这些特定约束和种子控制生成用户。
[使用带有约束和生成参数的queryModel工具]
已生成50个结果一致的用户：
- 所有用户年龄在25 - 35岁之间  
- 使用种子12345进行可重复生成
- $entropy参数控制随机程度
- 相同的查询将始终返回相同的结果

配置选项

环境变量

• LOG_LEVEL - 日志级别（error、warn、info、debug、trace）
• MONGTAP_PORT - MCP服务器的默认端口（默认值：3000）
• MONGTAP_STORAGE - 模型存储路径（默认值：./welldb-models）
• MONGTAP_MAX_SERVERS - 最大并发MongoDB服务器数量（默认值：10）

MCP服务器模式

MCP服务器可以在不同模式下运行：

# 标准I/O模式（用于Claude Desktop）
node src/mcp/index.js

# TCP模式（用于网络访问）
node src/mcp/index.js tcp --port 3000

# 独立模式（用于测试）
node src/mcp/index.js standalone

🔧 技术细节

MongTap由三个主要组件组成：

1. DataFlood-JS - 从样本中学习的统计建模引擎
2. WellDB-Node - MongoDB有线协议实现
3. MCP服务器 - 大语言模型工具的集成层

┌─────────────────┐     MCP协议      ┌──────────────┐
│ Claude Desktop  │ ◄──────────────────► │  MCP服务器  │
└─────────────────┘                       └──────┬───────┘
                                                 │
                                                 ▼
┌─────────────────┐     MongoDB有线协议   ┌──────────────┐
│ MongoDB客户端  │ ◄──────────────────► │ WellDB-Node  │
└─────────────────┘                       └──────┬───────┘
                                                 │
                                                 ▼
                                          ┌──────────────┐
                                          │ DataFlood-JS │
                                          │  (建模)  │
                                          └──────────────┘

故障排除

Claude Desktop未显示MongTap工具

1. 检查配置文件路径是否正确
2. 确保MongTap的路径是绝对路径，而不是相对路径
3. 完全重启Claude Desktop
4. 查看日志：tail -f ~/Library/Logs/Claude/mcp-*.log（macOS）

MongoDB客户端无法连接

1. 验证服务器是否正在运行：在Claude中使用 "listActiveServers"
2. 检查端口是否被占用：lsof -i :27017
3. 确保防火墙允许本地连接
4. 尝试使用IP连接：mongodb://127.0.0.1:27017

模型生成似乎不正确

1. 提供更多样本数据以进行更好的训练
2. 在样本中使用一致的数据格式
3. 检查模型信息以查看学习到的模式
4. 如果需要，使用额外的约束重新训练

开发

运行测试

# 运行所有测试
npm test

# 运行特定测试套件
node test/mcp/test-mcp-server.js
node test/welldb-node/test-mongodb-server.js
node test/dataflood-js/test-inferrer.js

# 运行集成测试
node test/welldb-node/test-integration.js

项目结构

MongTap/
├── src/
│   ├── mcp/                 # MCP服务器实现
│   │   ├── mcp-server.js    # 核心MCP服务器
│   │   ├── prompt-analyzer.js # 提示的自然语言处理
│   │   └── server-manager.js # 多服务器管理
│   ├── welldb-node/         # MongoDB协议
│   │   ├── server/          # MongoDB服务器实现
│   │   └── storage/         # DataFlood存储适配器
│   └── dataflood-js/        # 统计建模
│       ├── schema/          # 架构推断
│       ├── generator/       # 文档生成
│       └── training/        # 模型训练
└── README.md               # 本文件

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

隐私政策

MongTap以隐私为基本原则进行设计：

数据收集

• 不收集个人数据 - MongTap不收集任何用户数据
• 无分析或跟踪 - 不收集使用统计信息
• 无外部连接 - 所有操作均在本地执行
• 无数据持久化 - 模型是统计表示，而非实际数据

数据存储

• 所有模型都存储在本地机器上
• 存储位置可通过mongtap.config.json完全配置
• 不使用云服务或外部存储
• 生成的数据是合成的，不代表真实信息

数据安全

• 仅本地操作确保数据不会离开你的机器
• 无需身份验证（无凭据可泄露）
• 开源代码允许进行全面的安全审计
• 输入验证可防止注入攻击

安全

MongTap实施了全面的安全措施：

• 输入验证：所有输入在处理前都会进行验证
• 错误处理：优雅的错误处理可防止信息泄露
• 无外部依赖：核心功能的依赖最少
• 本地操作：除非明确配置，否则无网络暴露
• 开源：完整的代码透明度便于进行安全审计

如需详细的安全信息，请参阅docs/SECURITY_AUDIT.md。

支持

• 问题反馈：GitHub Issues
• 文档：docs/
• 状态：DesignDocuments/STATUS.claude
• 联系方式：SmallMinds LLC Co - smallminds.co - andrew@smallminds.co

致谢

• DataFlood技术用于统计建模
• MongoDB提供协议规范
• Anthropic提供MCP协议
• Claude Desktop用于大语言模型集成

---

注意：MongTap通过统计方式生成数据，不存储实际数据。它非常适合开发、测试和演示目的，在这些场景中，你需要逼真的数据而无需实际存储的开销。