MCP Vectorizer

MCP矢量器

一个连接到MCP（模型上下文协议）服务器的生产就绪系统，使用OpenAI嵌入对客户数据进行矢量化，并将其存储在ChromaDB中以实现语义搜索功能。

🚀 特性

• MCP集成：连接到MCP服务器以获取客户数据
• 智能矢量化：使用OpenAI嵌入来创建语义表示
• 矢量存储器：将嵌入内容存储在ChromaDB中，以实现快速相似性搜索
• REST API：提供用于搜索和检索客户的HTTP端点
• 元数据：保留客户属性以供过滤和分析
• 生产就绪：包括错误处理、日志记录和配置管理

🏗️ 建筑

MCP Server → MCP Client → Embedding Service → Vector Storage → REST API
     ↓            ↓              ↓              ↓            ↓
Customer Data → Descriptions → Embeddings → ChromaDB → Search Results

📋 先决条件

• Node.js 16+
• Docker（用于ChromaDB）
• OpenAI API密钥
• 正在运行MCP服务器

🔧 安装

1. 克隆存储库

   git clone 
   cd mcp-vectorizer

1. 安装依赖项

   npm install

1. 设置环境变量

   cp .env.example .env
   # Edit .env with your configuration

1. 启动ChromaDB

   docker run -p 8001:8000 chromadb/chroma

⚙️ 配置

创建一个 .env 包含以下变量的文件：

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here

# ChromaDB Configuration  
CHROMA_HOST=localhost
CHROMA_PORT=8001
CHROMA_COLLECTION_NAME=mcp_customers

# MCP Server Configuration
MCP_SERVER_URL=http://localhost:8080/mcp
MCP_TENANT_ID=development

# API Configuration
API_PORT=3000

🚀 用法

1.处理客户数据

# Process customers from your MCP server
npm run vectorize

# Or use the main vectorizer class
node src/examples/process-customers.js

2.启动API服务器

npm start

3.寻找客户

# Search via API
curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{"query": "high-value wine club member", "limit": 5}'

# Get customer by ID
curl http://localhost:3000/customers/customer-id-here

📊 API终点

健康检查

GET /health

搜索客户

POST /search
Content-Type: application/json

{
  "query": "customer description or search terms",
  "limit": 10,
  "filters": {
    "isActiveClubMember": true
  }
}

按ID获取客户

GET /customers/:id

🧪 测试

# Run with mock data
npm run test:mock

# Run integration tests
npm test

🏗️ 项目结构

mcp-vectorizer/
├── src/
│   ├── api/           # REST API endpoints
│   ├── mcp/           # MCP client and communication
│   ├── vectorizer/    # Embedding generation
│   ├── storage/       # ChromaDB integration
│   └── examples/      # Usage examples
├── config/            # Configuration files
├── docs/             # Documentation
└── package.json

🔄 发展

添加新数据源

1. 扩展 MCPClient 类在 src/mcp/client.js
2. 更新中的转换函数 src/vectorizer/transformer.js
3. 在存储层中添加新的元数据字段

自定义嵌入

修改 src/vectorizer/embedding.js 致：

• 使用不同的嵌入模型
• 自定义文本预处理
• 添加特定于域的转换

🚨 故障排除

常见问题

1. ChromaDB连接失败

- 确保Docker正在运行 - 检查端口8001是否可用 - 验证.env中的CHROMA_HOST和CHROMA_PORT

1. OpenAI API错误

- 验证OPENAI_API_KEY是否有效 - 检查费率限制和配额 - 确保有足够的API信用

1. MCP服务器连接问题

- 验证MCP_SERVER_URL是否正确 - 检查MCP服务器是否正在运行 - 验证租户ID是否存在

📈 扩展

对于生产部署：

1. 数据库：使用具有适当存储的持久ChromaDB
2. API：部署在负载平衡器后面
3. 处理：对大型数据集实施批处理
4. 监控：添加指标和日志记录
5. 安全：实施身份验证和速率限制

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🆘 支持

如有疑问或问题：

• 在存储库中创建问题
• 检查故障排除部分
• 查看中的示例 src/examples/