Content
# Tool List
> This project is a Python implementation based on [KelvinQiu802/llm-mcp-rag](https://github.com/KelvinQiu802/llm-mcp-rag), used for learning and practicing LLM, MCP, and RAG technologies.
>
> The project author has a demonstration video, see https://www.bilibili.com/video/BV1dcRqYuECf/
>
> It is strongly recommended to browse its README; this repository has made some adjustments and naming changes to the logic!
## Project Introduction
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 technology.
### Core Features
- Large Language Model (LLM) invocation based on OpenAI API
- Interaction between LLM and external tools through MCP (Model Context Protocol)
- Implementation of RAG (Retrieval-Augmented Generation) system based on vector retrieval
- Support for file system operations and webpage content retrieval
## System Architecture
```mermaid
graph TD
A[User] -->|Question| B[Agent]
B -->|Call| C[LLM]
C -->|Generate Response/Tool Call| B
B -->|Tool Calls| D[MCP Client]
D -->|Execute| E[MCP Server]
E -->|File System Operations| F[File System]
E -->|Webpage Retrieval| G[Webpage Content]
H[Documents/Knowledge Base] -->|Embedding| I[Vector Store - In-Memory]
B -->|Query| I
I -->|Relevant Context| B
```
## Main Components
```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_calls_id: str, tool_output: str)
}
class EmbeddingRetriever {
+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 ..> EmbeddingRetriever
EmbeddingRetriever --> VectorStore
Agent ..> ALogger
AsyncChatOpenAI ..> ALogger
```
## Quick Start
### Environment Preparation
1. Ensure Python 3.12 or higher 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, note 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 Si基流动's API or compatible OpenAI format API (default is $OPENAI_BASE_URL)
- `USE_CN_MIRROR`: (optional) whether to use Chinese mirror, set any value (like '1') to true (default is false)
- `PROXY_URL`: (optional) proxy URL (like "http(s)://xxx"), used for `fetch` (mcp-tool) to go through the proxy
### Install Dependencies
```bash
# Install dependencies using uv
uv sync
```
### Run Examples
This project uses the `just` command tool to run different examples:
```bash
# View available commands
just help
```
## RAG Example Process
```mermaid
sequenceDiagram
participant User as User
participant Agent as Agent
participant LLM as LLM
participant ER as EmbeddingRetriever
participant VS as VectorStore
participant MCP as MCP Client
participant Logger as ALogger
User->>Agent: Provide query
Agent->>Logger: Record operation log
Agent->>ER: Retrieve relevant documents
ER->>VS: Query vector store
VS-->>ER: Return relevant documents
ER-->>Agent: Return context
Agent->>LLM: Send query and context
LLM-->>Agent: Generate response or tool calls
Agent->>Logger: Record tool calls
Agent->>MCP: Execute tool calls
MCP-->>Agent: Return tool results
Agent->>LLM: Send tool results
LLM-->>Agent: Generate final response
Agent-->>User: Return response
```
## Project Structure
- `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 run configuration file
## Learning Resources
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/): Learn about MCP protocol
- [OpenAI API Documentation](https://platform.openai.com/docs/api-reference): OpenAI API reference
- [RAG (Retrieval-Augmented Generation)](https://arxiv.org/abs/2005.11401): RAG technology paper
