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通過統計方式生成數據，不存儲實際數據。它非常適合開發、測試和演示目的，在這些場景中，你需要逼真的數據而無需實際存儲的開銷。