Content
# Douban Movie MCP (Model Control Panel)
This is a Douban Movie recommendation MCP service designed for large language models, which helps the model to obtain movie data, search for movies, and get movie recommendations.
## Features
- Get movie details: Retrieve detailed information based on movie ID
- Search for movies: Search for movies based on keywords
- Movie recommendations: Get movie recommendations based on user preferences (genre, tags, year, etc.)
- Built-in API documentation: Access complete API documentation via the browser
- Client examples: Provide interactive browser demos and client examples in various programming languages
## Tech Stack
- TypeScript
- Node.js
- Express
- pnpm
## Quick Start
### Install Dependencies
```bash
pnpm install
```
### Configure Environment Variables
Create a `.env` file and set the relevant environment variables:
```
PORT=3000
DOUBAN_API_BASE_URL=https://api.douban.com/v2
DOUBAN_API_KEY=your_douban_api_key
LOG_LEVEL=info
```
> Note: This project currently uses mock data and can run without a real Douban API key.
### Run in Development Mode
```bash
pnpm dev
```
### Build the Project
```bash
pnpm build
```
### Run in Production
```bash
pnpm start
```
## Documentation and Client Examples
After starting the service, you can access various resources via the following URLs:
- API Information: `http://localhost:3000/`
- API Documentation: `http://localhost:3000/docs`
- Client Examples: `http://localhost:3000/demo`
## Client Example Code
### Node.js Client
```javascript
const axios = require('axios');
// Base URL configuration
const API_BASE_URL = 'http://localhost:3000/api';
// Search for movies
async function searchMovies(keyword, start = 0, count = 10) {
const response = await axios.get(`${API_BASE_URL}/search`, {
params: { q: keyword, start, count }
});
return response.data;
}
// Get movie details
async function getMovieDetail(movieId) {
const response = await axios.get(`${API_BASE_URL}/movie/${movieId}`);
return response.data;
}
// Get movie recommendations
async function getRecommendations(params = {}) {
const response = await axios.post(`${API_BASE_URL}/recommend`, params);
return response.data;
}
```
### Python Client
```python
import requests
# Base URL configuration
API_BASE_URL = 'http://localhost:3000/api'
# Search for movies
def search_movies(keyword, start=0, count=10):
response = requests.get(
f"{API_BASE_URL}/search",
params={"q": keyword, "start": start, "count": count}
)
response.raise_for_status()
return response.json()
# Get movie details
def get_movie_detail(movie_id):
response = requests.get(f"{API_BASE_URL}/movie/{movie_id}")
response.raise_for_status()
return response.json()
# Get movie recommendations
def get_recommendations(params=None):
if params is None:
params = {}
response = requests.post(f"{API_BASE_URL}/recommend", json=params)
response.raise_for_status()
return response.json()
```
More detailed client example code can be found in the `examples` directory.
## API Interface Description
### Get Movie Details
```
GET /api/movie/:id
```
#### Parameters:
- `id`: Movie ID
#### Example Response:
```json
{
"code": 200,
"message": "success",
"data": {
"id": "1234",
"title": "Mock Movie 1234",
"original_title": "Mock Movie 1234",
"year": "2023",
"genres": ["Drama", "Sci-Fi"],
"rating": {
"max": 10,
"average": 8.5,
"stars": "45",
"min": 0
},
"summary": "This is a mock movie summary...",
// Other fields...
}
}
```
### Search for Movies
```
GET /api/search?q=keyword&start=0&count=20
```
#### Parameters:
- `q`: Search keyword (required)
- `start`: Pagination starting position (optional, default 0)
- `count`: Number of items per page (optional, default 20)
#### Example Response:
```json
{
"code": 200,
"message": "success",
"data": {
"count": 10,
"start": 0,
"total": 50,
"subjects": [
// Movie list...
]
}
}
```
### Movie Recommendations
```
POST /api/recommend
```
#### Request Body:
```json
{
"genres": ["Drama", "Sci-Fi"],
"tags": ["Mystery", "Space"],
"year_range": "2010-2023",
"rating_range": "7-10",
"limit": 5
}
```
#### Parameter Description:
- `genres`: Array of movie genres (optional)
- `tags`: Array of tags (optional)
- `year_range`: Year range (optional, format: "start year-end year")
- `rating_range`: Rating range (optional, format: "min rating-max rating")
- `limit`: Limit on the number of returned items (optional, default 10)
#### Example Response:
```json
{
"code": 200,
"message": "success",
"data": [
// Recommended movie list...
]
}
```
## Large Model Call Example
Here is an example of how a large model might call this MCP:
```
User: "Please recommend some high-rated sci-fi movies"
Large Model:
[Call MCP API]
POST /api/recommend
Body: {"genres": ["Sci-Fi"], "rating_range": "8-10", "limit": 5}
[After getting the results]
"Here are some high-rated sci-fi movie recommendations:"
1. "Mock Movie 0" (8.7) - 2018
2. "Mock Movie 1" (9.2) - 2020
3. "Mock Movie 2" (8.5) - 2021
4. "Mock Movie 3" (8.9) - 2019
5. "Mock Movie 4" (9.0) - 2022
```
## Logging System
The project integrates a simple logging system, which can be controlled via the environment variable `LOG_LEVEL`:
- `error`: Only show error messages
- `warn`: Show warnings and error messages
- `info`: Show information, warnings, and error messages (default)
- `debug`: Show all log messages, including debug information
## Notes
- This project currently uses mock data and does not rely on a real Douban API
- To integrate with the real Douban API, you need to apply for the relevant API key and modify the service implementation accordingly
## Contribution
Feel free to submit issues and improvement suggestions!
## License
ISC
