Merge pull request #2 from tzuhsiang/mcp_agent

Mcp agent

Author: tzuhsiang

README.md

@@ -1,12 +1,13 @@
 # 📚 LibriFlow - 個人圖書管理系統
 
-一個基於 **FastAPI**、**Vue.js 3** 和 **PostgreSQL** 的全端圖書管理應用，使用 **Docker Compose** 進行容器化部署。
+一個基於 **FastAPI**、**Vue.js 3** 和 **PostgreSQL** 的全端圖書管理應用，整合 **AI Agent** 與 **MCP (Model Context Protocol)** 技術，提供智能化的語音/文字互動管理功能。
 
 ![LibriFlow UI](imgs/UI.png)
 
 ## 🌟 功能特色
 
 - ✨ **現代化 UI** - 使用 Vue 3 Composition API 和 Tailwind CSS 打造美觀的響應式介面
+- 🤖 **AI 智慧助理** - 內建交談式 Agent，可透過自然語言進行書籍管理操作
 - 📖 **完整的 CRUD 操作** - 新增、查看、更新和刪除書籍
 - ⭐ **互動式評分系統** - 點擊星星直接為書籍評分，即時回饋
 - 📊 **閱讀狀態追蹤** - 視覺化的狀態標籤（未讀、閱讀中、已完成）
@@ -15,14 +16,29 @@
 - 🐳 **Docker 部署** - 一鍵啟動所有服務
 - 🔄 **RESTful API** - 完整的後端 API，自動生成 Swagger 文件
 
+## 🤖 AI 讀書助理
+
+本專案整合了基於 **Pydantic AI** 與 **MCP Server** 的智能助理，使用者可以透過右下角的對話視窗與 Agent 互動。
+
+![LibriFlow Agent UI](imgs/AGENT-UI.png)
+
+### 支援功能
+- **新增書籍**：「幫我新增一本《原子習慣》，作者是詹姆斯·克利爾」
+- **查詢書籍**：「列出我目前正在閱讀的書」
+- **修改狀態**：「把《原子習慣》標記為已讀完」
+- **修改評分**：「給《哈利波特》打 5 顆星」
+- **自動同步**：Agent 操作完成後，畫面會自動更新顯示最新資料
+
 ## 🏗️ 技術架構
 
 ### 後端 (Backend)
 - **框架**: FastAPI (Python 3.12+)
+- **AI Agent**: Pydantic AI
+- **工具協定**: Model Context Protocol (MCP) by Anthropic
+- **LLM**: Azure OpenAI (GPT-4o)
 - **ORM**: SQLAlchemy
 - **資料驗證**: Pydantic
 - **資料庫**: PostgreSQL 15
-- **API 文件**: Swagger UI (自動生成)
 
 ### 前端 (Frontend)
 - **框架**: Vue.js 3 (Composition API)
@@ -32,15 +48,15 @@
 
 ### 部署 (Deployment)
 - **容器化**: Docker & Docker Compose
-- **網路**: Docker Bridge Network
-- **資料持久化**: Docker Volumes
 
 ## 📁 專案結構
 
 ```
 libray_implement/
-├── backend/                 # FastAPI 後端
-│   ├── main.py             # 應用主入口與路由
+├── backend/                 # FastAPI 後端 & AI Agent
+│   ├── main.py             # 應用主入口與路由 (含 Chat Endpoint)
+│   ├── agent.py            # Pydantic AI Agent 定義
+│   ├── mcp_server.py       # MCP Server 工具實作
 │   ├── models.py           # SQLAlchemy 資料庫模型
 │   ├── schemas.py          # Pydantic 資料驗證模型
 │   ├── database.py         # 資料庫連線配置
@@ -50,18 +66,15 @@ libray_implement/
 ├── frontend/               # Vue.js 前端
 │   ├── src/
 │   │   ├── components/     # Vue 組件
-│   │   │   ├── BookForm.vue    # 新增書籍表單（摺疊式面板）
+│   │   │   ├── ChatWindow.vue  # AI 對話視窗組件
+│   │   │   ├── BookForm.vue    # 新增書籍表單
 │   │   │   └── BookList.vue    # 書籍清單展示
 │   │   ├── App.vue         # 主頁面
-│   │   ├── main.js         # 應用入口
-│   │   └── style.css       # Tailwind CSS 樣式
-│   ├── package.json        # npm 依賴配置
-│   ├── vite.config.js      # Vite 配置
+│   │   └── ...
 │   └── Dockerfile          # 前端容器映像檔
 ├── envs/                   # 環境變數配置
-│   ├── .env                # 環境變數設定檔
+│   ├── .env                # 環境變數設定檔 (含 Azure OpenAI Key)
 │   └── .env.example        # 環境變數範例檔
-├── imgs/                   # 專案截圖
 ├── docker-compose.yml      # 多容器編排定義
 └── README.md              # 專案說明文件
 ```
@@ -84,7 +97,13 @@ cd libray_implement
 2. **配置環境變數**
 ```bash
 cp envs/.env.example envs/.env
-# 根據需要修改 envs/.env 中的配置
+```
+**重要**：請編輯 `envs/.env`，填入您的 **Azure OpenAI** 相關金鑰，以啟用 AI 功能：
+```env
+AZURE_OPENAI_API_KEY=your_key
+AZURE_OPENAI_ENDPOINT=your_endpoint
+AZURE_OPENAI_API_VERSION=2024-02-15-preview
+AZURE_DEPLOYMENT_NAME=gpt-4o
 ```
 
 3. **啟動所有服務**
@@ -94,99 +113,48 @@ docker compose up --build
 
 ### 訪問應用
 
-啟動成功後，可以訪問：
-
 - 🌐 **前端界面**: http://localhost:5173
 - 🔧 **後端 API**: http://localhost:8000
 - 📚 **API 文件**: http://localhost:8000/docs
 
-![API Documentation](imgs/doc.png)
-
 ## 📊 資料庫 Schema
 
-**books 表**
-
-| 欄位名 | 類型 | 約束 | 說明 |
-|--------|------|------|------|
-| id | Integer | Primary Key, Autoincrement | 書籍 ID |
-| title | String | Not Null | 書名 |
-| author | String | Not Null | 作者 |
-| status | String | Default: 'unread' | 閱讀狀態 (unread/reading/finished) |
-| rating | Integer | Default: 0, Min: 0, Max: 5 | 評分 |
+| 欄位名 | 類型 | 說明 |
+|--------|------|------|
+| id | Integer | Primary Key |
+| title | String | 書名 |
+| author | String | 作者 |
+| status | String | unread / reading / finished |
+| rating | Integer | 0-5 |
 
 ## 🔌 API 端點
 
+包含標準 RESTful API 與 Chat API：
+
 | 方法 | 路徑 | 說明 |
 |------|------|------|
-| GET | `/books` | 取得所有書籍清單 |
-| GET | `/books/{id}` | 取得單一書籍 |
+| POST | `/chat` | 與 AI Agent 對話 |
+| GET | `/books` | 取得書籍清單 |
 | POST | `/books` | 新增書籍 |
-| PUT | `/books/{id}` | 更新書籍資訊 |
-| DELETE | `/books/{id}` | 刪除書籍 |
-| GET | `/docs` | Swagger UI 文件 |
-
-## 🎨 UI 功能
-
-### 新增書籍 (優化)
-- **摺疊式面板設計**，保持介面整潔
-- 點擊展開輸入表單，新增或取消後自動收合
-- 完整欄位支援：書名、作者、狀態、評分
-
-### 書籍清單 (優化)
-- **卡片式展示**：美觀的陰影與圓角設計
-- **互動式評分**：滑鼠懸停預覽星星，點擊即時更新
-- **視覺化狀態標籤**：
-  - 📕 未讀 (灰色背景)
-  - 📖 閱讀中 (藍色背景)
-  - ✅ 已完成 (綠色背景)
-- **空狀態引導**：當無書籍時顯示友善的提示圖示
-- **即時響應**：操作後無需重整頁面
-- **一鍵刪除**：支援確認對話框防止誤刪
-
-### 統計儀表板
-- 總書籍數
-- 閱讀中書籍數
-- 已完成書籍數
-
-## 🛠️ 開發
-
-### 停止服務
-```bash
-docker compose down
-```
+| ... | ... | ... |
 
-### 查看日誌
-```bash
-docker compose logs -f
-```
+## 🛠️ 開發與除錯
 
-### 僅重建特定服務
+- 查看後端日誌 (包含 Agent 思考過程)：
 ```bash
-docker compose up --build backend
-docker compose up --build frontend
-```
-
-## 🌐 Proxy 設定
-
-如果您的網路環境需要使用 proxy，已在 `envs/.env` 中配置：
-
-```env
-HTTP_PROXY=http://{proxy_ip:port}
-HTTPS_PROXY=https://{proxy_ip:port}
-NO_PROXY=localhost,127.0.0.1,db,backend,frontend
+docker compose logs -f backend
 ```
 
-## 📝 授權
+## 授權
 
 MIT License
 
-## 👨‍💻 作者
+## 作者
 
 tzuhsiang
 
-## 🙏 致謝
+## 致謝
 
-- FastAPI - 現代化 Python Web 框架
-- Vue.js - 漸進式 JavaScript 框架
-- Tailwind CSS - 實用優先的 CSS 框架
-- PostgreSQL - 強大的開源關聯式資料庫
+- Pydantic AI
+- Model Context Protocol (MCP)
+- FastAPI, Vue.js, PostgreSQL

PROMPT_SPEC.md SPEC.mdPROMPT_SPEC.md renamed to SPEC.md

@@ -76,3 +76,7 @@ rating	Integer	Min: 1, Max: 5, Default: 0
 
 
 
+
+
+
+

PROMPT_SPEC_2.md SPEC_2.mdPROMPT_SPEC_2.md renamed to SPEC_2.md

@@ -0,0 +1,16 @@
+在既有專案做以下修改
+
+1. 建立一個新的 mcp server，參考後端，提供以下功能：
+    - 新增書籍
+    - 刪除書籍
+    - 修改評價
+    - 修改閱讀狀態
+    - 列出書籍
+2. 建立一個新的 Agent，註冊 mcp server 的工具
+3. 在UI介面新增一個對話視窗，用Agent來與使用者互動
+    - 視窗尺寸需放大
+    - 支援重置對話功能
+    - Agent 操作完成後需自動更新頁面列表
+4. 使用envs/.env的設定檔，設定azure openai api key
+5. 使用 docker compose 來管理所有開發套件
+

SPEC_3.md

@@ -0,0 +1,86 @@
+import os
+import asyncio
+from dataclasses import dataclass
+from mcp import StdioServerParameters, ClientSession
+from mcp.client.stdio import stdio_client
+from pydantic_ai import Agent, RunContext
+import nest_asyncio
+
+# Apply nest_asyncio to allow nested event loops if needed
+nest_asyncio.apply()
+
+@dataclass
+class McpDeps:
+    session: ClientSession
+
+# Initialize Agent
+# Ensure env vars for Azure OpenAI are set (AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION)
+# The model name is passed in the constructor.
+agent = Agent(
+    f'azure:{os.getenv("AZURE_DEPLOYMENT_NAME", "gpt-4o")}',
+    deps_type=McpDeps,
+    system_prompt="""
+    你是一個圖書管理助理。
+    你可以協助使用者新增、查詢、修改、刪除書籍。
+    
+    支援的功能：
+    - 新增書籍 (add_book)
+    - 刪除書籍 (delete_book)
+    - 修改評價 (update_book_rating)
+    - 修改閱讀狀態 (update_book_status)
+    - 列出書籍 (list_books)
+    
+    書籍狀態 (status) 只能是以下之一：unread (未讀), reading (閱讀中), finished (已讀)。
+    
+    請使用提供的工具執行操作。請用繁體中文回答。
+    """
+)
+
+@agent.tool
+async def list_books(ctx: RunContext[McpDeps], limit: int = 20, offset: int = 0) -> str:
+    """列出書籍清單"""
+    result = await ctx.deps.session.call_tool("list_books", arguments={"limit": limit, "offset": offset})
+    return result.content[0].text
+
+@agent.tool
+async def add_book(ctx: RunContext[McpDeps], title: str, author: str, status: str = "unread", rating: int = 0) -> str:
+    """新增書籍 (status: unread, reading, finished)"""
+    result = await ctx.deps.session.call_tool("add_book", arguments={
+        "title": title, "author": author, "status": status, "rating": rating
+    })
+    return result.content[0].text
+
+@agent.tool
+async def delete_book(ctx: RunContext[McpDeps], book_id: int) -> str:
+    """刪除書籍"""
+    result = await ctx.deps.session.call_tool("delete_book", arguments={"book_id": book_id})
+    return result.content[0].text
+
+@agent.tool
+async def update_book_rating(ctx: RunContext[McpDeps], book_id: int, rating: int) -> str:
+    """修改書本評價 (0-5)"""
+    result = await ctx.deps.session.call_tool("update_book_rating", arguments={"book_id": book_id, "rating": rating})
+    return result.content[0].text
+
+@agent.tool
+async def update_book_status(ctx: RunContext[McpDeps], book_id: int, status: str) -> str:
+    """修改閱讀狀態 (unread, reading, finished)"""
+    result = await ctx.deps.session.call_tool("update_book_status", arguments={"book_id": book_id, "status": status})
+    return result.content[0].text
+
+async def process_message(user_message: str):
+    server_script = os.path.join(os.path.dirname(__file__), "mcp_server.py")
+    
+    server_params = StdioServerParameters(
+        command="python",
+        args=[server_script],
+        env=os.environ.copy()
+    )
+
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            
+            deps = McpDeps(session=session)
+            result = await agent.run(user_message, deps=deps)
+            return result.output

backend/agent.py

@@ -75,5 +75,26 @@ def delete_book(book_id: int, db: Session = Depends(get_db)):
     return None
 
 
+class ChatRequest(schemas.BaseModel): # schemas usually has Pydantic models, or standard import
+    message: str
+
+class ChatResponse(schemas.BaseModel):
+    reply: str
+
+import agent
+
+@app.post("/chat", response_model=ChatResponse)
+async def chat_endpoint(request: ChatRequest):
+    """跟 Agent 對話"""
+    # Simply call the agent function. 
+    # Note: agent.process_message spawns a subprocess each time. 
+    # For a high traffic app this is bad, but for this task/demo it's fine.
+    try:
+        reply = await agent.process_message(request.message)
+        return ChatResponse(reply=reply)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
 if __name__ == "__main__":
     uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)