使用说明
📚 MoodReads——基于MCP的情绪图书推荐器
“告诉我你的感受，我会找到符合你内心的故事。”
MoodReads是一个 基于MCP的人工智能代理 根据您的喜好推荐书籍 当前情绪和氛围，而不仅仅是类型关键字。
你会说这样的话：
“我感到情绪疲惫，想和家人一起度过一个充满希望的幻想。”
系统：
- 解读你的心情，
- 构建智能搜索查询，
- 调用MCP工具 开放式库API,
- 对推荐进行排名和解释，
- 您可以选择获取您选择的任何书籍的详细信息。
🧭 高层项目概述
- 接口：您从启用MCP的客户端（例如Cursor）聊天。
- 脑：担任“情绪图书馆员”的法学硕士。
- 工具 （MCP）：
search_books_by_query(query, limit)→ 从开放图书馆查找候选书籍。get_book_details(book_id)→ 获取丰富的元数据、描述、主题等。
- 真相的来源：开放图书馆的免费公开图书目录API。
- 目标：地图 情感+共鸣→ 故事建议 以透明、工具驱动、可重复的方式。
🧩 系统架构
graph TD
U[User: Mood Input] --> C[MCP Client]
C --> LLM[LLM: Mood Librarian]
LLM --> S[MCP Server]
subgraph "MCP Layer"
S --> T1[Tool: Search Books]
S --> T2[Tool: Get Details]
end
T1 --> OL[Open Library API]
T2 --> OL
OL --> T1
OL --> T2
T1 --> S
T2 --> S
S --> LLM
LLM --> C
C --> U[Recommendations]
🔁 端到端请求流
sequenceDiagram
participant User
participant Client as MCP Client
participant LLM
participant Server as MCP Server
participant SearchTool
participant DetailsTool
participant OpenLib as Open Library API
User->>Client: "I feel emotionally tired, want soft hopeful fantasy"
Client->>LLM: Forward message + tools
LLM->>LLM: Parse mood → extract tone, genre, vibes
LLM->>Server: call search_books_by_query
Server->>SearchTool: Invoke tool
SearchTool->>OpenLib: GET /search.json
OpenLib-->>SearchTool: Book list
SearchTool-->>Server: Results
Server-->>LLM: Tool result
LLM->>LLM: Rank books by mood fit
LLM->>Client: Recommendations + explanations
Client->>User: Show recommendations
Note over User,LLM: User requests more details
User->>Client: "Tell me more about book #1"
Client->>LLM: Forward request
LLM->>Server: call get_book_details
Server->>DetailsTool: Invoke tool
DetailsTool->>OpenLib: GET /works/{id}.json
OpenLib-->>DetailsTool: Metadata
DetailsTool-->>Server: Details
Server-->>LLM: Book info
LLM->>Client: Summary with emotional themes
Client->>User: Human-friendly explanation
🔍 内部流动：情绪→ 查询→ Tools
flowchart TD
A["User mood input<br>tired, need soft hopeful fantasy"] --> B[LLM: Parse Mood]
B --> C[Extract Features<br>mood, genre, trope, pacing]
C --> D[Build Query<br>cozy fantasy found family hopeful gentle]
D --> E[Call Search Tool]
E --> F[Receive Book List]
F --> G[Rank by Vibe Match]
G --> H[Return Top Recommendations]
H --> I{User Wants Details?}
I -->|Yes| J[Call Details Tool]
I -->|No| K[Continue Conversation]
🧠 工具概述
🔎 search_books_by_query 签字：
async def search_books_by_query(query: str, limit: int = 5) -> Dict[str, Any]
Used by the LLM to search Open Library using a mood/genre/trope-rich string.
返回示例：
{
"query": "cozy fantasy found family hopeful",
"total_found": 123,
"books": [
{
"id": "/works/OL22082778W",
"title": "Heartsong",
"author": "T.J. Klune",
"first_publish_year": 2019,
"subjects": ["Fantasy", "Romance", "LGBTQ+", "Found family"],
"edition_count": 12
}
]
}
📖 get_book_details 签字：
async def get_book_details(book_id: str) -> Dict[str, Any]
Takes the id returned by search_books_by_query (e.g. /works/OL22082778W) and fetches rich metadata from the Open Library works API.
返回示例：
{
"id": "/works/OL22082778W",
"title": "Heartsong",
"description": "A cozy, found-family fantasy...",
"subjects": ["Fantasy", "Queer", "Friendship", "Found family"],
"first_publish_date": "2019",
"covers": [1234567],
"links": [],
"raw": { "full Open Library payload" }
}
🧱 组件体系结构
flowchart LR
subgraph ClientSide[Client Side]
U[User]
CUR[Cursor / MCP Client]
MODEL[LLM: Mood Librarian]
end
subgraph ServerSide[Server Side]
subgraph MCPServer[MCP Server]
SFILE[Python Server]
TSEARCH[Search Tool]
TDETAILS[Details Tool]
HTTPX[HTTP Client]
end
ENV[uv + venv]
end
subgraph External[External Services]
OL[Open Library API]
end
U --> CUR
CUR --> MODEL
MODEL <--> MCPServer
SFILE --> TSEARCH
SFILE --> TDETAILS
TSEARCH --> HTTPX
TDETAILS --> HTTPX
HTTPX --> OL
ENV --- MCPServer
⚙️ 运行时视图
graph LR
subgraph Runtime
A[Start MCP Client] --> B[Load Config]
B --> C[Spawn MCP Server]
C --> D[Register Tools]
D --> E[Start Chat Session]
E --> F[LLM Receives Tools]
F --> G[Tool Calls]
G --> H[Final Recommendations]
end
🛠 技术栈
| Layer | Technology |
|--------------------|--------------------------------------|
| AI Orchestration | MCP (Model Context Protocol) |
| Agent Client | Cursor (MCP-enabled IDE) |
| Backend | Python, FastMCP |
| HTTP Client | httpx |
| Book Catalog | Open Library API |
| Environment | uv + virtualenv (.venv) |
🚀 快速开始
- 克隆和安装
git clone https://github.com/your-username/moodreads-mcp.git
cd moodreads-mcp
- 运行MCP服务器（用于开发/检查）
uv run mcp dev src/mood_reads_server.py
# Opens MCP Inspector where you can test both tools
- 光标配置（MCP） 在光标MCP设置中：
{
"mcpServers": {
"mood-reads": {
"command": "C:/path/to/.venv/Scripts/python.exe",
"args": [
"C:/path/to/repo/src/mood_reads_server.py"
]
}
}
}
💡 示例提示
"I feel drained and need something gentle, soft, and warm with found family."
"Give me dark academia with mystery and slow-burn romance."
"Tell me more about the first book you recommended; fetch detailed info."
🗺 路线图
User preference learning (remember what you liked)
Scoring & ranking model for better match quality
Web UI or Streamlit app
Integration with other book APIs (Goodreads/StoryGraph style)
📝 许可证
MIT — free to use, modify, and extend.
❤️ 鸣谢
Open Library for book metadata.
MCP ecosystem for tool-based AI patterns.
