AI导哈

MCP协议学习沙盒

一个用于学习模型上下文协议（MCP）的小型沙盒，集成MongoDB Atlas向量搜索、Voyage嵌入和可选的Gemini生成功能。

  • by samuelIkoli
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 samuelIkoli/mcp-mongodb

使用说明

MCP MongoDB+Voyage+Gemini游乐场

一个用于学习模型上下文协议（MCP）的小型沙箱，包括MongoDB Atlas矢量搜索、Voyage嵌入和可选的Gemini生成。TBH，我觉得我不小心又创造了RAG。它包括：

  • 直接节点客户端流：在Voyage中嵌入查询→ $vectorSearch 在Atlas上→ （可选）双子座回答。
  • MCP服务器接线：启动MongoDB MCP服务器并调用工具（例如。， listDatabases)通过VS Code Chat或附带的CLI示例。
  • 用于嵌入演示和矢量搜索种子的实用脚本。

这里有什么

  • src/index.ts -语义搜索+（可选）RAG风格的Gemini答案。
  • src/mcpClientExample.ts –通过stdio生成MongoDB MCP服务器并调用的最小JSON-RPC客户端 listDatabases.
  • src/tests/generateEmbeddings.ts –快速Voyage嵌入POST示例。
  • src/tests/mcpVectorDemo.ts –带有嵌入和运行的种子示例文档 $vectorSearch.
  • package.json 脚本–构建、搜索和MCP服务器运行程序。

先决条件

  • 节点18+（用22.x测试）。
  • 互联网访问MongoDB Atlas、Voyage嵌入API和（可选）Gemini API。
  • 带有样本数据集的Atlas集群(sample_mflix)或者你自己的数据。

环境变量

创建一个 .env 在项目根中。关键值：

DB_URI=mongodb+srv://<user>:<password>@<cluster>/?appName=Cluster0
DB_PASSWORD=<password_if_DB_URI_contains_<db_password>>
DB_NAME=sample_mflix
COLLECTION_NAME=embedded_movies

# Vector search
VECTOR_INDEX_NAME=plot_embeddings
VECTOR_PATH=plot_embedding          # matches the 1536-d field in sample_mflix
VECTOR_LIMIT=5
VECTOR_CANDIDATES=200

# Embeddings
VOYAGE_API_KEY=...
VOYAGE_MODEL=voyage-code-2          # 1536-d to match VECTOR_PATH

# Generation (optional)
GEMINI_API_KEY=...
GEMINI_MODEL=gemini-1.5-flash-latest

安装和构建

npm install
npm run build

运行语义搜索（以及可选的Gemini答案）

npm run search -- "easy company in wwii"

这将查询嵌入Voyage中，运行 $vectorSearch 在你的 plot_embeddings 索引，打印排名的点击量，如果 GEMINI_API_KEY 设置后，返回一个简洁的Gemini答案，引用检索到的项目。

MCP服务器：启动和试运行

  • 启动只读MCP服务器（使用 DB_URI, VOYAGE_API_KEY):
    npm run mcp:start
  • 试运行以列出启用的工具，而不提供服务：
    npm run mcp:dryrun

VS代码聊天+MCP

  1. 打开聊天视图（语音气泡）→ “模型上下文协议：连接服务器”。
  2. 选择 mongodb 进入 ~/Library/Application Support/Code/User/mcp.json.
  3. 提供 MDB_MCP_CONNECTION_STRING （完整的Atlas URI）和可选 MDB_MCP_VOYAGE_API_KEY.
  4. 问聊天：“调用列表数据库”或“运行向量搜索…”——工具通过MCP执行，而不是本地驱动程序。

CLI MCP客户端示例

npm run build
node dist/mcpClientExample.js

这会通过stdio生成MCP服务器并发出问题 initialize + tools/call → listDatabases，打印JSON-RPC响应。

嵌入/演示脚本

  • npm run embeddings –点击Voyage并打印嵌入长度/结果。
  • npm run demo –播种一个很小的KB，确保一个向量索引，然后运行 $vectorSearch.

尺寸说明

  • 提供的Atlas索引 plot_embeddings 有两个字段：
    • plot_embedding （1536调光）-使用 VOYAGE_MODEL=voyage-code-2 或任何1536-d型号。
    • plot_embedding_voyage_3_large （2048调暗）-需要2048-d型号；当前密钥/模型集可能不会产生2048-d向量。
  • 如果切换型号，请对齐 VECTOR_PATH、索引定义和嵌入维度。

故障排除

  • PlanExecutor错误：向量未被索引为向量：字段/路径不匹配--设置 VECTOR_PATH 指向索引为的字段 vector.
  • 尺寸不匹配：确保嵌入模型维度与索引匹配 numDimensions.
  • MCP连接问题：验证 DB_URI （带密码） npx mongodb-mcp-server@latest 可以接入互联网。

许可证

麻省理工学院（项目级）。依赖关系遵循其各自的许可证。

相关 MCP