MCP Rag

🚀 MCP - RAG：用於商業分析的智能AI編排

本項目是一個輕量級演示，展示瞭如何將 模型上下文協議（Model Context Protocol，MCP） 與 檢索增強生成（Retrieval - Augmented Generation，RAG） 相結合，為商業分析編排多智能體AI工作流。

🚀 快速開始

本項目展示瞭如何構建能夠實現以下功能的 智能AI系統：

1. 編排多個智能體：MCP服務器協調不同的專業工具。
2. 檢索商業知識：RAG提供上下文感知的信息檢索。
3. 進行統計分析：通過自然語言查詢實現自動化數據分析。
4. 保持模塊化：易於更換大語言模型（LLM）後端並添加新功能。

✨ 主要特性

• 基於MCP的協調：多個專業服務器協同工作。
• 商業分析工具：支持均值、標準差、相關性、線性迴歸等分析。
• RAG知識庫：包含商業術語、政策和分析指南。
• 模塊化設計：便於使用新工具進行擴展或更換LLM後端。
• 自然語言接口：可以提出如“第一季度的平均收入是多少？”這樣的問題。

📦 安裝指南

📋 前提條件

• Python 3.8及以上版本
• Google Gemini API密鑰（有免費套餐） - 用於未來的LLM集成
• 對MCP和RAG概念有基本瞭解

🛠️ 安裝步驟

1. 克隆倉庫：

   git clone https://github.com/ANSH-RIYAL/MCP-RAG.git
   cd MCP-RAG
   

2. 安裝依賴項：

   pip install -r requirements.txt
   

3. 設置環境變量： 使用Gemini API（默認）：

   export LLM_MODE="gemini"
   export GEMINI_API_KEY="your-gemini-api-key"
   

   使用自定義本地主機API：

   export LLM_MODE="custom"
   export CUSTOM_API_URL="http://localhost:8000"
   export CUSTOM_API_KEY="your-api-key"  # 可選
   

💻 使用示例

快速演示

運行演示腳本以查看兩個MCP服務器的實際運行情況：

python main.py

這將展示：

• 商業分析工具對示例數據的處理。
• RAG對商業術語的知識檢索。
• 系統如何協同工作。
• LLM與所選後端的集成。

LLM後端選擇

系統支持兩種LLM後端：

選項1：Google Gemini API（默認）

export LLM_MODE="gemini"
export GEMINI_API_KEY="your-gemini-api-key"
python main.py

選項2：自定義本地主機API

export LLM_MODE="custom"
export CUSTOM_API_URL="http://localhost:8000"
export CUSTOM_API_KEY="your-api-key"  # 可選
python main.py

自定義API要求：

• 必須支持與OpenAI兼容的聊天完成端點（/v1/chat/completions）。
• 應接受工具/函數調用格式。
• 預計在本地主機8000端口運行（可配置）。

對話場景

運行對話場景腳本以查看實際使用示例：

python test_scenarios.py

這將展示LinkedIn帖子場景，說明非技術用戶如何與系統交互。

商業分析工具

系統提供以下分析功能：

• 數據探索：獲取數據集信息和示例數據。
• 統計分析：計算均值、標準差並支持過濾。
• 相關性分析：查找變量之間的關係。
• 預測建模：使用線性迴歸進行預測。

RAG知識檢索

可通過以下方式訪問商業知識：

• 術語定義：查找商業概念。
• 政策信息：檢索公司程序。
• 分析指南：獲取數據解釋的上下文。

📚 詳細文檔

場景與用例

場景1：銷售分析

經理：“第一季度的平均收入是多少？”
MCP - RAG系統：
1. 分析服務器：calculate_mean(column='earnings', filter_column='quarter', filter_value='Q1-2024')
   → 收入均值：101666.67
2. RAG服務器：get_business_terms(term='earnings')
   → 收入：部門或公司在給定時期內產生的總收入
3. 回覆：“2024年第一季度的平均收入：101,667美元”

場景2：績效相關性

經理：“銷售額和費用之間的相關性是多少？”
MCP - RAG系統：
1. 分析服務器：calculate_correlation(column1='sales', column2='expenses')
   → 銷售額和費用之間的相關性：0.923
2. 回覆：“相關性：0.923（強正相關）”

場景3：預測建模

經理：“建立一個模型，根據銷售額和員工數量預測收入”
MCP - RAG系統：
1. 分析服務器：linear_regression(target_column='earnings', feature_columns=['sales', 'employees'])
   → 線性迴歸結果：
      目標：收入
      特徵：['sales', 'employees']
      截距：15000.00
      銷售額係數：0.45
      員工數量係數：1250.00
      決定係數（R²）：0.987
2. 回覆：“已創建模型，R² = 0.987”

場景4：商業知識

經理：“利潤率是什麼意思？”
MCP - RAG系統：
1. RAG服務器：get_business_terms(term='profit margin')
   → 利潤率：扣除費用後作為利潤保留的收入百分比，計算公式為 (收入 - 費用) / 收入
2. 回覆：“利潤率：扣除費用後作為利潤保留的收入百分比”

場景5：政策信息

經理：“預算分配政策是什麼？”
MCP - RAG系統：
1. RAG服務器：get_company_policies(policy_type='budget')
   → 預算分配：營銷部門佔總預算的25%，工程部門佔30%，銷售部門佔45%
2. 回覆：“預算分配：營銷部門25%，工程部門30%，銷售部門45%”

定製指南

為您的組織定製

步驟1：替換示例數據

1. 更新商業數據：將 data/sample_business_data.csv 替換為您的實際數據。
   • 確保分析工具使用的列是數值類型。
   • 添加用於過濾的分類列。
   • 包含用於趨勢分析的時間列。
2. 更新知識庫：將 data/business_knowledge.txt 替換為您組織的：
   • 商業術語和定義。
   • 公司政策和程序。
   • 分析指南和最佳實踐。

步驟2：添加自定義分析工具

需修改的文件：src/servers/business_analytics_server.py

1. 添加新工具：在 handle_list_tools() 函數（約第29行）中，將新工具添加到工具列表中：

   @server.list_tools()
   async def handle_list_tools() -> ListToolsResult:
       return ListToolsResult(
           tools=[
               # ... 現有工具 (calculate_mean, calculate_std, calculate_correlation, linear_regression) ...
               Tool(
                   name="your_custom_analysis",
                   description="Your custom analysis tool",
                   inputSchema={
                       "type": "object",
                       "properties": {
                           "parameter": {"type": "string"}
                       },
                       "required": ["parameter"]
                   }
               )
           ]
       )
   

2. 實現工具邏輯：在 handle_call_tool() 函數（約第140行）中，添加相應的處理程序：

   elif name == "your_custom_analysis":
       parameter = arguments["parameter"]
       # 此處添加您的自定義分析邏輯
       result = f"Custom analysis result for {parameter}"
       return CallToolResult(
           content=[TextContent(type="text", text=result)]
       )
   

步驟3：擴展RAG功能

需修改的文件：src/servers/rag_server.py

1. 添加新的知識源：修改 load_business_knowledge() 函數（約第25行）以包含：
   • 數據庫連接。
   • 文檔處理（PDF、Word文檔等）。
   • API集成（Salesforce、HubSpot等）。
2. 添加新的RAG工具：在 handle_list_tools() 函數（約第50行）中，添加新工具：

   Tool(
       name="your_custom_rag_tool",
       description="Your custom knowledge retrieval tool",
       inputSchema={
           "type": "object",
           "properties": {
               "query": {"type": "string"}
           },
           "required": ["query"]
       }
   )
   

3. 實現RAG工具邏輯：在 handle_call_tool() 函數（約第90行）中，添加處理程序：

   elif name == "your_custom_rag_tool":
       query = arguments["query"]
       # 此處添加您的自定義RAG邏輯
       result = f"Custom RAG result for {query}"
       return CallToolResult(
           content=[TextContent(type="text", text=result)]
       )
   

步驟4：集成LLM後端

需創建的文件：src/servers/llm_server.py（新文件） 系統已經包含一個靈活的LLM客戶端（src/core/llm_client.py），支持Gemini和自定義本地主機API。

1. 使用現有的LLM客戶端：src/core/gemini_rag_agent.py 中的 FlexibleRAGAgent 已經支持：
   • Google Gemini API。
   • 自定義本地主機API（與OpenAI兼容的格式）。
2. 創建自定義LLM服務器（可選）：如果您需要一個專門的MCP服務器來進行LLM操作：

   import asyncio
   from mcp.server import Server
   from mcp.server.stdio import stdio_server
   from mcp.types import Tool, TextContent, CallToolResult
   
   server = Server("llm-server")
   
   @server.list_tools()
   async def handle_list_tools():
       return ListToolsResult(
           tools=[
               Tool(
                   name="process_natural_language",
                   description="Convert natural language to tool calls",
                   inputSchema={
                       "type": "object",
                       "properties": {
                           "query": {"type": "string"}
                       },
                       "required": ["query"]
                   }
               )
           ]
       )
   
   @server.call_tool()
   async def handle_call_tool(name: str, arguments: dict):
       if name == "process_natural_language":
           query = arguments["query"]
           # 與OpenAI、Gemini或本地模型集成
           # 將自然語言轉換為適當的工具調用
           return CallToolResult(
               content=[TextContent(type="text", text=f"Processed: {query}")]
           )
   

3. 添加到requirements.txt：

   openai>=1.0.0
   google-genai>=0.3.0
   httpx>=0.24.0
   

步驟5：添加新的數據源

需修改的文件：src/servers/business_analytics_server.py 和 src/servers/rag_server.py

1. 數據庫連接器：添加連接以下數據庫的工具：
   • PostgreSQL、MySQL、SQLite。
   • MongoDB、Redis。
   • 數據倉庫（Snowflake、BigQuery）。
2. API集成：連接到商業系統：
   • CRM系統（Salesforce、HubSpot）。
   • 營銷平臺（Google Analytics、Facebook Ads）。
   • 財務系統（QuickBooks、Xero）。

當前工具實現

• 商業分析工具（src/servers/business_analytics_server.py）：
  • calculate_mean - 計算數值列的平均值。
  • calculate_std - 計算標準差。
  • calculate_correlation - 查找變量之間的關係。
  • linear_regression - 構建預測模型。
  • get_data_info - 獲取數據集信息。
• RAG工具（src/servers/rag_server.py）：
  • get_business_terms - 查找商業定義。
  • get_company_policies - 檢索政策信息。
  • search_business_knowledge - 進行通用知識搜索。
• LLM集成（src/core/llm_client.py）：
  • FlexibleRAGAgent - 支持Gemini和自定義本地主機API。
  • LLMClient - 處理兩個後端的API通信。
  • 工具調用和對話管理。

模塊化架構的好處

模塊化設計允許您：

• 交換組件：更換任何服務器而不影響其他服務器。
• 添加功能：插入新工具而無需重寫現有代碼。
• 獨立擴展：在不同的機器上運行不同的服務器。
• 根據用例定製：僅使用您需要的工具。

示例擴展

添加情感分析

需創建的文件：src/servers/sentiment_analysis_server.py

# 創建sentiment_analysis_server.py
@server.list_tool()
async def analyze_sentiment(text: str) -> CallToolResult:
    # 與情感分析API集成
    # 返回情感分數和見解

添加預測功能

需修改的文件：src/servers/business_analytics_server.py

# 添加到handle_list_tools()函數中
Tool(
    name="time_series_forecast",
    description="Forecast future values using time series analysis",
    inputSchema={
        "type": "object",
        "properties": {
            "column": {"type": "string"},
            "periods": {"type": "integer"}
        }
    }
)

添加文檔處理功能

需創建的文件：src/servers/document_processor_server.py

# 創建document_processor_server.py
@server.list_tool()
async def process_document(file_path: str) -> CallToolResult:
    # 從PDF、Word文檔等中提取文本
    # 添加到知識庫中

架構

項目結構

MCP - RAG/
├── data/
│   ├── sample_business_data.csv    # 用於分析的商業數據集
│   └── business_knowledge.txt      # RAG知識庫
├── src/
│   └── servers/
│       ├── business_analytics_server.py  # 統計分析工具
│       └── rag_server.py                 # 知識檢索工具
├── main.py                         # 演示和編排腳本
├── test_scenarios.py               # 對話場景
├── requirements.txt                # 依賴項
└── README.md                       # 本文件

關鍵組件

1. 商業分析服務器：提供統計分析工具的MCP服務器。
2. RAG服務器：用於商業知識檢索的MCP服務器。
3. 編排層：協調服務器和LLM（未來）。
4. 數據層：示例商業數據和知識庫。

配置

環境變量

示例數據

系統包含：

• 季度商業數據：四個季度的銷售、營銷、工程指標。
• 商業知識庫：術語、政策和分析指南。

用例

商業領導者

• 無代碼分析：用自然語言詢問商業數據相關問題。
• 快速洞察：無需技術專業知識即可獲得統計分析結果。
• 上下文感知報告：將數據分析與商業知識相結合。

數據團隊

• 模塊化架構：易於添加新的分析工具。
• LLM集成：可進行自然語言查詢處理。
• 可擴展框架：為特定需求構建自定義智能體。

AI工程師

• MCP協議：學習現代AI編排模式。
• RAG實現：瞭解知識檢索系統。
• 智能體設計：構建多智能體AI工作流。

未來增強功能

計劃功能

• [ ] LLM集成：連接Gemini、OpenAI或本地模型。
• [ ] 自然語言查詢：處理複雜的商業問題。
• [ ] 高級分析：時間序列分析、聚類、預測。
• [ ] Web界面：為非技術用戶提供用戶友好的儀表板。
• [ ] 即時數據：連接即時數據源。
• [ ] 自定義知識庫：上傳公司特定的文檔。

集成可能性

• 本地LLM API：使用 [Local LLM API](https://github.com/ANSH - RIYAL/local - llm - api) 運行開源模型。
• 數據庫連接器：連接SQL數據庫、數據倉庫。
• API集成：Salesforce、HubSpot、Google Analytics。
• 文檔處理：PDF、DOCX、電子郵件分析。

🤝 貢獻

這是構建智能AI系統的基礎，歡迎貢獻：

• 新的分析工具：添加統計方法、機器學習模型。
• 知識庫擴展：商業領域、特定行業的內容。
• LLM集成：支持不同的AI模型。
• 文檔：教程、用例、最佳實踐。

📄 許可證

本項目採用MIT許可證，您可以自由使用和修改以用於自己的項目！

🔗 相關項目

• [Local LLM API](https://github.com/ANSH - RIYAL/local - llm - api)：在本地運行開源大語言模型。
• MCP協議：官方文檔

準備好構建自己的智能AI系統了嗎？ 從這個基礎開始，根據您的特定需求進行擴展。模塊化設計使其易於添加新功能，同時保持清晰的架構。

#智能AI #MCP #RAG #商業分析 #開源AI