使用说明

具有RAG和历史维护功能的AI MCP代理

一个强大的人工智能代理系统，将模型上下文协议（MCP）工具与检索增强生成（RAG）和对话历史维护相结合，用于智能、上下文感知的交互。

🌟 特性

核心能力

✅ RAG（检索增强生成） -使用FAISS矢量存储进行上下文感知问答
✅ 对话历史 -基于会话的聊天记忆，用于多回合对话
✅ 历史感知检索 -使用对话上下文自动重新表述问题
✅ MCP工具集成 -连接到任何兼容MCP的工具服务器
✅ 多种操作模式 -代理模式（带工具）或仅RAG模式
✅ 会话管理 -支持多个并发对话
✅ CLI接口 -易于使用的命令行界面

受生产系统启发

此实现借鉴了生产级系统的概念，如DosiBridge/dosi发动机的RAG实现：

基于会话的历史管理（类似于多租户方法）
使用LangChain进行历史感知检索
模块化架构，易于扩展

🚀 快速开始

安装

# Clone or download the repository
cd mcp-server

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Add your OPENAI_API_KEY to .env

基本用法

# Run default demo with examples
python ai_mcp_dynamic.py

# Ask a simple question
python ai_mcp_dynamic.py --query "What is DosiBlog?"

# Start a conversation with history
python ai_mcp_dynamic.py --query "Hi, I'm Alice" --session-id alice
python ai_mcp_dynamic.py --query "What's my name?" --session-id alice

# Use RAG-only mode (faster, no MCP tools)
python ai_mcp_dynamic.py --mode rag --query "Tell me about DosiBlog"

🐳 Docker支持

Docker快速入门

# Build the image
docker build -t mcp-server:latest .

# Run the container
docker run -d -p 8000:8000 \
  -e OPENAI_API_KEY=your-api-key \
  -v $(pwd)/config:/app/config:ro \
  mcp-server:latest

使用Docker Compose

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

自动化Docker Hub发布

该项目包括GitHub Actions工作流，该工作流自动构建Docker镜像并将其推送到Docker Hub：

推到 main/master 分支
版本标签（例如。， v1.0.0)
手动触发

安装说明：

将机密添加到GitHub： DOCKER_HUB_USERNAME 和 DOCKER_HUB_ACCESS_TOKEN
看 .github/SETUP.md 有关详细的设置指南

有关更多Docker文档，请参阅医生.md.

📚 文档

文档	描述
快速启动.md	入门指南
MCP_USAGE.md	MCP服务器集成
RAG_历史_指南.md	详细的RAG和历史文件
快速引用.md	快速参考卡

💡 用法示例

示例1：多回合对话

# Turn 1: Introduction
python ai_mcp_dynamic.py --session-id user1 \
  --query "I'm interested in web development with Node.js"

# Turn 2: Follow-up (remembers context)
python ai_mcp_dynamic.py --session-id user1 \
  --query "What projects use these technologies?"

# Turn 3: Another follow-up
python ai_mcp_dynamic.py --session-id user1 \
  --query "Can you tell me more about DosiBlog?"

# View conversation history
python ai_mcp_dynamic.py --show-history --session-id user1

示例2：带有工具的代理

# Agent can use both MCP tools and RAG
python ai_mcp_dynamic.py \
  --query "Calculate 25 * 4 and tell me about DosiBlog"

# Follow-up using history
python ai_mcp_dynamic.py \
  --query "What was that number again?"

示例3：仅RAG模式

# Faster queries without tool overhead
python ai_mcp_dynamic.py --mode rag \
  --query "What technologies does DosiBlog use?"

python ai_mcp_dynamic.py --mode rag \
  --query "When was it started?"

示例4：会话管理

# View all active sessions
python ai_mcp_dynamic.py --show-history

# View specific session
python ai_mcp_dynamic.py --show-history --session-id user1

# Clear a session
python ai_mcp_dynamic.py --clear-history --session-id user1

🏗️ 建筑

┌────────────────────────────────────────────────────────┐
│                   User Interface (CLI)                  │
└────────────────────────────────────────────────────────┘
                          ↓
┌────────────────────────────────────────────────────────┐
│              ConversationHistoryManager                 │
│  • Session-based storage (Dict[session_id → history])  │
│  • Message persistence and retrieval                    │
│  • Multi-session support                                │
└────────────────────────────────────────────────────────┘
                          ↓
┌────────────────────────────────────────────────────────┐
│                 EnhancedRAGSystem                       │
│  • FAISS vector store for similarity search             │
│  • OpenAI embeddings for semantic understanding         │
│  • History-aware retriever (reformulates questions)     │
│  • Context retrieval from knowledge base                │
└────────────────────────────────────────────────────────┘
                          ↓
┌────────────────────────────────────────────────────────┐
│            Agent Executor (Optional)                    │
│  • MCP tool integration                                 │
│  • Multi-tool orchestration                             │
│  • Tool selection and execution                         │
└────────────────────────────────────────────────────────┘
                          ↓
┌────────────────────────────────────────────────────────┐
│                  LLM (GPT-4o)                          │
│  • Natural language understanding                       │
│  • Response generation                                  │
│  • Context-aware answers                                │
└────────────────────────────────────────────────────────┘

🔄 历史感知检索的工作原理

系统使用对话上下文自动重新制定后续问题：

User: "What is DosiBlog?"
AI: "DosiBlog is a web development project..."

User: "Who created it?"
       ↓ (System reformulates using history)
      "Who created DosiBlog?"
AI: "DosiBlog was created by Abdullah Al Sazib."

User: "What technologies does it use?"
       ↓ (System reformulates using history)
      "What technologies does DosiBlog use?"
AI: "DosiBlog uses Node.js, Express, and MongoDB."

📊 命令行选项

python ai_mcp_dynamic.py [OPTIONS]

Query Options:
  --query, -q TEXT          Query to send to the agent
  --mode, -m {agent,rag}    Operating mode (default: agent)
  
Session Management:
  --session-id, --sid TEXT  Session ID for conversation history (default: default)
  --show-history            Show conversation history for session
  --clear-history           Clear conversation history for session
  
MCP Configuration:
  --add-server, -s JSON     Add MCP server as JSON: '{"name":"Name","url":"https://..."}'
  
Help:
  --help                    Show help message and examples

🎯 用例

1.客户支持聊天机器人

# Each customer gets their own session
python ai_mcp_dynamic.py --sid customer_123 \
  --query "I have a problem with my order"
  
# Follow-up in same session maintains context
python ai_mcp_dynamic.py --sid customer_123 \
  --query "Can you help me with that?"

2.教育助理

# Student learning session
python ai_mcp_dynamic.py --sid student_alice --mode rag \
  --query "Explain Node.js"
  
python ai_mcp_dynamic.py --sid student_alice --mode rag \
  --query "How is it different from Python?"

3.技术文件问答

# Query your documentation
python ai_mcp_dynamic.py --mode rag \
  --query "How do I set up the development environment?"

🔧 配置

环境变量

创建一个 .env 文件：

# Required
OPENAI_API_KEY=your-api-key-here

# Optional MCP servers (JSON array)
MCP_SERVERS=[{"name":"MyServer","url":"https://example.com/mcp"}]

MCP服务器配置

创建 mcp_servers.json:

[
  {
    "name": "Calculator",
    "url": "https://example.com/mcp/calculator"
  },
  {
    "name": "WeatherAPI",
    "url": "https://example.com/mcp/weather",
    "headers": {
      "Authorization": "Bearer YOUR_TOKEN"
    }
  }
]

🆚 比较：ai_mcp_dynamic与dosi发动机

功能	ai_mcp_dynamic	dosi发动机
向量存储	FAISS（内存中）	Weaviate（持久）
嵌入	OpenAI	拥抱脸
LLM	OpenAI GPT-4o	双子座/DeepSeek/奥利马
历史	内存中会话	内存中多租户
流媒体	❌ 还没有✅ 异步流媒体
持久性	❌ 仅在内存中	✅ 编织数据库
工具	✅ MCP集成	❌ 无外部工具
命令行界面	✅ 完整CLI	❌ 无CLI
用例	开发/测试	生产聊天机器人

🔮 未来的增强功能

[]持久存储（PostgreSQL、Redis、Weaviate）
[]流式响应以获得更好的用户体验
[]会话到期和清理
[]上下文窗口管理
[]多个矢量存储后端
[]Web API（FastAPI/Flask）
[]Docker容器化
[]混合搜索（关键字+语义）
[]文档上传和索引
[]先进的RAG技术（重新排序、查询扩展）

🤝 贡献

欢迎投稿！需要改进的地方：

持久层 -添加历史数据库后端
流媒体 -实现异步流式响应
更多矢量存储 -支持松果、ChromaDB等。
web界面 -构建web UI
文档 -更多示例和教程

📝 需求

langchain
langchain-core
langchain-community
langchain-openai
langchain-mcp-adapters
openai
faiss-cpu
python-dotenv
mcp

看 requirements.txt 查看完整列表。

🐛 故障排除

常见问题

问题：“RAG系统不可用”

# Solution: Install FAISS
pip install faiss-cpu

问题：“未找到对话历史记录”

# Solution: Check session ID or start new conversation
python ai_mcp_dynamic.py --show-history --sid your-session-id

问题：“上下文不包括最近的消息”

# Solution: Verify using same session ID
python ai_mcp_dynamic.py --sid consistent-id --query "Your question"

问题：“找不到OpenAI API密钥”

# Solution: Set environment variable
export OPENAI_API_KEY="your-key-here"
# Or add to .env file

📄 许可证

本项目按原样提供，用于教育和发展目的。

🙏 致谢

灵感来自DosiBridge/dosi引擎的RAG和历史实现
基于LangChain框架构建
使用OpenAI的GPT-4o和嵌入
用于工具集成的MCP协议

📞 支持

详细文档：

看 RAG_历史_指南.md 了解技术细节
看快速引用.md 用于命令示例
检查 MCP_USAGE.md 用于MCP集成

由以下材料制成❤️ 为开发人员构建上下文感知的AI代理