exp-llm-mcp-rag

# LLM-MCP-RAG 实验项目 > This project is a Python implementation of [KelvinQiu802/llm-mcp-rag](https://github.com/KelvinQiu802/llm-mcp-rag), used for learning and practicing LLM, MCP, and RAG technologies. > > The author of this project has a demonstration video at https://www.bilibili.com/video/BV1dcRqYuECf/ > > It is strongly recommended to browse its README first. This repository has made slight adjustments and naming adjustments to some logic! ## 项目简介 This project is an experimental project based on Large Language Models (LLM), Model Context Protocol (MCP), and Retrieval-Augmented Generation (RAG). It demonstrates how to build an AI assistant system that can interact with external tools and utilize retrieval-augmented generation techniques. ### 核心功能 - LLM calls based on the OpenAI API - LLM interaction with external tools via MCP (Model Context Protocol) - Implementation of a vector search-based RAG (Retrieval-Augmented Generation) system - Support for file system operations and web content retrieval ## 系统架构 ```mermaid graph TD A[用户] -->|提问| B[Agent] B -->|调用| C[LLM] C -->|生成回答/工具调用| B B -->|工具调用| D[MCP 客户端] D -->|执行| E[MCP 服务器] E -->|文件系统操作| F[文件系统] E -->|网页获取| G[网页内容] H[文档/知识库] -->|嵌入| I[向量存储-内存形式] B -->|查询| I I -->|相关上下文| B ``` ## 主要组件 ```mermaid classDiagram class Agent { +mcp_clients: list[MCPClient] +model: str +llm: AsyncChatOpenAI +system_prompt: str +context: str +init() +cleanup() +invoke(prompt: str) } class MCPClient { +name: str +command: str +args: list[str] +version: str +init() +cleanup() +get_tools() +call_tool(name: str, params: dict) } class AsyncChatOpenAI { +model: str +messages: list +tools: list[Tool] +system_prompt: str +context: str +chat(prompt: str, print_llm_output: bool) +get_tools_definition() +append_tool_result(tool_call_id: str, tool_output: str) } class EembeddingRetriever { +embedding_model: str +vector_store: VectorStore +embed_query(query: str) +embed_documents(document: str) +retrieve(query: str, top_k: int) } class VectorStore { +items: list[VectorStoreItem] +add(item: VectorStoreItem) +search(query_embedding: list[float], top_k: int) } class ALogger { +prefix: str +title(text: str, rule_style: str) } Agent --> MCPClient Agent --> AsyncChatOpenAI Agent ..> EembeddingRetriever EembeddingRetriever --> VectorStore Agent ..> ALogger AsyncChatOpenAI ..> ALogger ``` ## 快速开始 ### 环境准备 1. Ensure that Python 3.12 or later is installed 2. Clone this repository 3. Copy `.env.example` to `.env` and fill in the necessary configuration information: - `OPENAI_API_KEY`: OpenAI API key - `OPENAI_BASE_URL`: OpenAI API base URL, be sure to keep the '/v1' at the end (default is 'https://api.openai.com/v1') - `DEFAULT_MODEL_NAME`: (Optional) Default model name (default is "gpt-4o-mini") - `EMBEDDING_KEY`: (Optional) Embedding model API key (default is $OPENAI_API_KEY) - `EMBEDDING_BASE_URL`: (Optional) Embedding model API base URL, such as Silicon-based flow API or OpenAI-compatible API (default is $OPENAI_BASE_URL) - `USE_CN_MIRROR`: (Optional) Whether to use the Chinese mirror, set any value (such as '1') to true (default is false) - `PROXY_URL`: (Optional) Proxy URL (such as "http(s)://xxx") for `fetch` (mcp-tool) to use a proxy ### 安装依赖 ```bash # 使用 uv 安装依赖 uv sync ``` ### 运行示例 This project uses the `just` command tool to run different examples: ```bash # 查看可用命令 just help ``` ## RAG 示例流程 ```mermaid sequenceDiagram participant User as 用户 participant Agent as Agent participant LLM as LLM participant ER as EmbeddingRetriever participant VS as VectorStore participant MCP as MCP客户端 participant Logger as ALogger User->>Agent: 提供查询 Agent->>Logger: 记录操作日志 Agent->>ER: 检索相关文档 ER->>VS: 查询向量存储 VS-->>ER: 返回相关文档 ER-->>Agent: 返回上下文 Agent->>LLM: 发送查询和上下文 LLM-->>Agent: 生成回答或工具调用 Agent->>Logger: 记录工具调用 Agent->>MCP: 执行工具调用 MCP-->>Agent: 返回工具结果 Agent->>LLM: 发送工具结果 LLM-->>Agent: 生成最终回答 Agent-->>User: 返回回答 ``` ## 项目结构 - `src/augmented/`: Main source code directory - `agent.py`: Agent implementation, responsible for coordinating LLM and tools - `chat_openai.py`: OpenAI API client encapsulation - `mcp_client.py`: MCP client implementation - `embedding_retriever.py`: Embedding retriever implementation - `vector_store.py`: Vector store implementation - `mcp_tools.py`: MCP tool definitions - `utils/`: Utility functions - `info.py`: Project information and configuration - `pretty.py`: Unified log output system - `rag_example.py`: RAG example program - `justfile`: Task execution configuration file ## 学习资源 - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/): Learn about the MCP protocol - [OpenAI API 文档](https://platform.openai.com/docs/api-reference): OpenAI API Reference - [RAG (Retrieval-Augmented Generation)](https://arxiv.org/abs/2005.11401): RAG Technology Paper