研究助理MCP服务器-部署在EC2上
由 BINATI A分析
一种模型上下文协议(MCP)服务器,使用向量嵌入和语义搜索提供智能研究数据管理。此服务器使您能够使用部署在AWS EC2上的ChromaDB和OpenAI嵌入来保存、组织和检索研究内容。
截图
特性
- 基于矢量的存储:使用ChromaDB通过语义嵌入存储研究内容
- 语义搜索:使用基于相似性检索的自然语言查询您的研究数据
- 主题组织:将研究组织到单独的基于主题的数据库中
- 重复检测:使用内容哈希进行自动重复数据删除
- RESTful API:使用FastMCP的流式HTTP传输的基于HTTP的MCP服务器
- OpenAI嵌入:使用OpenAI的文本嵌入3-small模型进行高质量的语义搜索
可用工具
服务器通过MCP协议公开了五个强大的工具:
- 保存_研究_数据 -将研究内容保存到矢量数据库
- search_research_data -通过保存的研究进行语义搜索
- list_research主题 -查看所有可用的研究主题
- delete_research_topic -删除主题及其数据
- get_topic_info -获取特定主题的详细信息
建筑```
Research Assistant MCP Server
├── FastMCP Server (streamable-http transport)
├── ChromaDB (Vector Database)
├── OpenAI Embeddings (text-embedding-3-small)
└── LangChain (Document Processing)
## 先决条件
- Python 3.13+
- OpenAI API密钥(在这里买一个)
- AWS EC2实例(用于部署)
## 安装
### 本地设置
1. **克隆仓库**```bash
git https://github.com/CyprianFusi/mcp-research-server-on-EC2.git
cd mcp-research-server-on-EC2
- 使用uv安装依赖项```bash
pip install uv
uv sync
或者使用pip:```bash
pip install -r requirements.txt
- 配置环境变量
创建 .env 项目根目录中的文件:```bash
OPENAI_API_KEY=your_openai_api_key_here
替换 `your_openai_api_key_here` 使用来自的实际OpenAI API密钥 OpenAI平台.
1. **运行服务器**```bash
python server.py
AWS EC2部署
步骤1:启动EC2实例
- 启动Amazon Linux 2或Amazon Linux 2023 EC2实例
- 配置安全组以允许:
- SSH(端口22)
- 自定义TCP(如果暴露在外部,则为MCP服务器提供端口) - 下载您的密钥对(.pem文件)
步骤2:连接到EC2
从Windows:```bash
ssh -i "your-key.pem" ec2-user@your-ec2-public-dns
**从macOS/Linux:**```bash
chmod 400 your-key.pem
ssh -i "your-key.pem" ec2-user@your-ec2-public-dns
步骤3:安装Anaconda
按照中的设置指南进行操作 anaconda_setup.md:```bash
Update system
sudo yum update -y
Download Anaconda
curl -O https://repo.anaconda.com/archive/Anaconda3-2025.06-0-Linux-x86_64.sh
Install Anaconda
bash Anaconda3-2025.06-0-Linux-x86_64.sh
Add to PATH
export PATH="/home/ec2-user/anaconda3/bin:$PATH"
echo 'export PATH="/home/ec2-user/anaconda3/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Initialize conda
conda init bash
source ~/.bashrc
#### 步骤4:设置MCP服务器```bash
# Clone your repository
git clone https://github.com/CyprianFusi/mcp-research-server-on-EC2.git
cd mcp-research-server-on-EC2
# Install dependencies
pip install uv
uv sync
# Configure environment variables
echo "OPENAI_API_KEY=your_openai_api_key_here" > .env
# Important: Replace 'your_openai_api_key_here' with your actual OpenAI API key
nano .env # Edit the file to add your real API key
# Run the server
python server.py
步骤5:作为后台服务运行(可选)
创建systemd服务文件:```bash
sudo nano /etc/systemd/system/mcp-research.service
添加以下内容:```ini
[Unit]
Description=Research Assistant MCP Server
After=network.target
[Service]
Type=simple
User=ec2-user
WorkingDirectory=/home/ec2-user/mcp-research-server-on-EC2
Environment="OPENAI_API_KEY=your_openai_api_key_here"
ExecStart=/home/ec2-user/anaconda3/bin/python server.py
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
重要提示: 替换 your_openai_api_key_here 在服务文件中使用您的实际OpenAI API密钥。
启用并启动服务:```bash
sudo systemctl daemon-reload
sudo systemctl enable mcp-research
sudo systemctl start mcp-research
sudo systemctl status mcp-research
## 配置
服务器使用以下默认配置(在中定义 `server.py`):```python
EMBED_MODEL = "text-embedding-3-small"
API_URL = "https://api.openai.com/v1/embeddings"
CHROMA_DB_ROOT = "./research_chroma_dbs"
环境变量
以下环境变量为 必需的:
OPENAI_API_KEY:用于访问嵌入的OpenAI API密钥API
创建 .env 项目根目录中的文件:```bash
OPENAI_API_KEY=sk-...your-key-here
服务器使用 `python-dotenv` 从中自动加载环境变量 `.env` 文件。
## 用法
### 工具:save_research_data
将研究内容保存到矢量数据库。
**参数:**
- `content` (List\[str\]):要保存的文本内容列表
- `topic` (str,可选):用于组织数据的主题名称(默认值:“default”)
**例子:**```json
{
"content": [
"Machine learning is a subset of artificial intelligence...",
"Neural networks are inspired by biological neurons..."
],
"topic": "machine_learning"
}
退货:```
Successfully saved 2 new documents to topic: machine_learning (skipped 0 duplicates)
### 工具:search_research_data
使用语义相似性搜索已保存的研究。
**参数:**
- `query` (str):搜索查询
- `topic` (str,可选):要搜索的主题(默认值:“default”)
- `max_results` (int,可选):返回的最大结果数(默认值:5)
**例子:**```json
{
"query": "What is deep learning?",
"topic": "machine_learning",
"max_results": 3
}
退货:```
Result 1 (Similarity: 0.892):
Deep learning is a subset of machine learning...
==================================================
Result 2 (Similarity: 0.845):
Neural networks with multiple layers...
==================================================
### 工具:列表_搜索_主题
列出所有可用的研究主题。
**退货:**```
Topic: machine_learning (15 documents)
Topic: python_programming (8 documents)
Topic: cloud_computing (12 documents)
工具:get_topic_info
获取有关研究主题的详细信息。
参数:
topic(str):主题名称
例子:```json
{
"topic": "machine_learning"
}
**退货:**```
Topic Information: machine_learning
- ChromaDB Collection: research_machine_learning
- Document Count: 15
- Hash Records: 15
- Database Path: /path/to/research_chroma_dbs/machine_learning
- Embedding Model: text-embedding-3-small
- OPENAI URL: https://api.openai.com/v1/embeddings
工具:delete_research_topic
删除研究主题及其所有数据。
参数:
topic(str):要删除的主题名称
例子:```json
{
"topic": "old_research"
}
**退货:**```
Successfully deleted topic: Old Research
项目结构```
8_Deploy_MCP_Server_on_EC2/
├── server.py # Main MCP server implementation
├── pyproject.toml # Project dependencies
├── uv.lock # Locked dependencies
├── anaconda_setup.md # EC2 Anaconda installation guide
├── .env # Environment configuration
├── .python-version # Python version specification
├── research_chroma_dbs/ # ChromaDB storage (created at runtime)
│ ├── topic1/
│ ├── topic2/
│ └── ...
└── asserts/ # UI screenshots
├── ui_1.png
├── ui_2.png
└── ...
## 依赖项
关键依赖关系来自 `pyproject.toml`:
- `fastmcp>=2.13.2` -MCP服务器框架
- `chromadb>=1.3.5` -矢量数据库
- `langchain>=1.1.3` -文档处理框架
- `langchain-chroma>=1.0.0` -ChromaDB集成
- `langchain-openai>=1.1.1` -OpenAI嵌入集成
- `langchain-core>=1.1.2` -核心LangChain功能
- `mcp[cli]>=1.23.2` -MCP CLI工具
- `python-dotenv` -环境变量管理
## 故障排除
### OpenAI API关键问题
**问题:** `Error: OpenAI API key not found` 或 `AuthenticationError`
**解决方案:**```bash
# Verify .env file exists and contains your API key
cat .env
# Should output:
# OPENAI_API_KEY=sk-...
# If not, create the .env file:
echo "OPENAI_API_KEY=your_actual_key_here" > .env
对于EC2部署:
- 确保
.env文件在工作目录中 - 或者,在systemd服务文件中设置环境变量
- 验证API密钥在 OpenAI平台
OpenAI API利率限制
问题:
RateLimitError: Rate limit exceeded
解决方案:
- 减少一次嵌入的文档数量
- 升级您的OpenAI API计划以获得更高的费率限制
- 使用指数回退实现重试逻辑(内置于langchain openai中)
ChromaDB权限错误
问题:
Permission denied when accessing research_chroma_dbs/
解决方案:```bash
Fix permissions
chmod -R 755 research_chroma_dbs/
On EC2, ensure ec2-user owns the directory
sudo chown -R ec2-user:ec2-user research_chroma_dbs/
```
网络连接问题
问题:
Error: Cannot connect to OpenAI API
解决方案:
- 验证互联网连接:
curl https://api.openai.com - 检查防火墙设置是否允许出站HTTPS连接
- 在EC2上,确保安全组允许到OpenAI API的出站流量
- 验证没有代理设置干扰连接
EC2连接超时
问题: 无法连接到EC2实例
解决方案:
- 检查安全组是否允许从您的IP进行SSH(端口22)
- 验证实例是否正在运行
- 确保.pem文件具有正确的权限:
chmod 400 your-key.pem - 使用正确的用户名:
ec2-user适用于亚马逊Linux
性能注意事项
- 嵌入生成:OpenAI API调用通常在每个文档100-500ms内完成
- 搜索速度:对于文档数\<10000的数据库,语义搜索通常为亚秒级
- 存储ChromaDB将嵌入内容存储在磁盘上;每份文档约1KB的计划
- API成本:OpenAI的text-embedding-3-small每100万代币售价0.02美元(非常划算)
- 速率限制:免费级别:3 RPM,级别1:500 RPM,级别2:5000 RPM
- 批处理:对于大型数据集,考虑批处理文档以优化API的使用
安全说明
- 默认情况下,服务器在本地主机上运行
- 对于生产部署,实施适当的身份验证
- 使用适当的安全组保护您的EC2实例
- 关键的:从不承诺
.env对版本控制具有敏感凭据的文件 - 添加
.env给你的.gitignore文件 - 定期旋转OpenAI API密钥
- 使用特定于环境的API密钥(用于开发和生产的单独密钥)
- 监控您的OpenAI API使用情况仪表板以了解意外活动
- 在EC2上,使用IAM角色和AWS Secrets Manager进行生产部署(建议使用.env文件)
贡献
欢迎投稿!拜托:
- 分叉存储库
- 创建要素分支
- 进行更改
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-有关详细信息,请参阅许可证文件。
支持
对于问题和疑问:
- 在GitHub上打开一个问题
- 检查现有问题的解决方案
- 查看 MCP文件
致谢
- FastMCP -MCP服务器框架
- ChromaDB -矢量数据库
- 开放人工智能 -嵌入API
- LangChain -LLM应用框架
基于模型上下文协议构建,用于智能研究管理。
