Refactor: Update MCP API documentation and authentication

Co-authored-by: jxxghp <jxxghp@qq.com>

README.md

@@ -30,6 +30,8 @@
 
 API文档：https://api.movie-pilot.org
 
+MCP工具API文档：详见 [docs/mcp-api.md](docs/mcp-api.md)
+
 本地运行需要 `Python 3.12`、`Node JS v20.12.1`
 
 - 克隆主项目 [MoviePilot](https://github.com/jxxghp/MoviePilot) 

docs/mcp-api.md

@@ -12,7 +12,7 @@ MoviePilot的智能体工具已通过HTTP API暴露，可以通过RESTful API调
 
 获取所有可用的MCP工具列表。
 
-**认证**: 需要API KEY，从 URL 查询参数中获取 `apikey=xxx`，或请求头中获取 `X-API-KEY`
+**认证**: 需要API KEY，在请求头中添加 `X-API-KEY: <api_key>` 或在查询参数中添加 `apikey=<api_key>`
 
 **响应示例**:
 ```json
@@ -46,7 +46,7 @@ MoviePilot的智能体工具已通过HTTP API暴露，可以通过RESTful API调
 
 调用指定的MCP工具。
 
-**认证**: 需要Bearer Token
+**认证**: 需要API KEY，在请求头中添加 `X-API-KEY: <api_key>` 或在查询参数中添加 `apikey=<api_key>`
 
 **请求体**:
 ```json
@@ -84,7 +84,7 @@ MoviePilot的智能体工具已通过HTTP API暴露，可以通过RESTful API调
 
 获取指定工具的详细信息。
 
-**认证**: 需要Bearer Token
+**认证**: 需要API KEY，在请求头中添加 `X-API-KEY: <api_key>` 或在查询参数中添加 `apikey=<api_key>`
 
 **路径参数**:
 - `tool_name`: 工具名称
@@ -114,7 +114,7 @@ MoviePilot的智能体工具已通过HTTP API暴露，可以通过RESTful API调
 
 获取指定工具的参数Schema（JSON Schema格式）。
 
-**认证**: 需要Bearer Token
+**认证**: 需要API KEY，在请求头中添加 `X-API-KEY: <api_key>` 或在查询参数中添加 `apikey=<api_key>`
 
 **路径参数**:
 - `tool_name`: 工具名称
@@ -138,128 +138,93 @@ MoviePilot的智能体工具已通过HTTP API暴露，可以通过RESTful API调
 }
 ```
 
-## 使用示例
+## MCP客户端配置
 
-### 使用curl调用工具
+MoviePilot的MCP工具可以通过HTTP协议在支持MCP的客户端中使用。以下是常见MCP客户端的配置方法：
 
-```bash
+### Claude Desktop (Anthropic)
-# 1. 获取访问令牌（通过登录API）
-TOKEN=$(curl -X POST "http://localhost:3001/api/v1/login/access-token" \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "username=admin&password=your_password" | jq -r '.access_token')
 
-# 2. 列出所有工具
+在Claude Desktop的配置文件中添加MoviePilot的MCP服务器配置：
-curl -X GET "http://localhost:3001/api/v1/mcp/tools" \
-  -H "Authorization: Bearer $TOKEN"
 
-# 3. 调用工具
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
-curl -X POST "http://localhost:3001/api/v1/mcp/tools/call" \
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-  -H "Authorization: Bearer $TOKEN" \
+
-  -H "Content-Type: application/json" \
+```json
-  -d '{
+{
-    "tool_name": "query_subscribes",
+  "mcpServers": {
-    "arguments": {
+    "moviepilot": {
-      "status": "all",
+      "command": "npx",
-      "media_type": "all"
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-http",
+        "http://localhost:3001/api/v1/mcp"
+      ],
+      "env": {
+        "X-API-KEY": "your_api_key_here"
+      }
     }
-  }'
+  }
-
+}
-# 4. 获取工具详情
-curl -X GET "http://localhost:3001/api/v1/mcp/tools/add_subscribe" \
-  -H "Authorization: Bearer $TOKEN"
 ```
 
-### 使用Python调用
+**注意**: 如果MCP HTTP服务器不支持环境变量传递API Key，可以使用查询参数方式：
 
-```python
+```json
-import requests
+{
-
+  "mcpServers": {
-# 配置
+    "moviepilot": {
-BASE_URL = "http://localhost:3001/api/v1"
+      "command": "npx",
-TOKEN = "your_access_token"
+      "args": [
-HEADERS = {"Authorization": f"Bearer {TOKEN}"}
+        "-y",
-
+        "@modelcontextprotocol/server-http",
-# 1. 列出所有工具
+        "http://localhost:3001/api/v1/mcp?apikey=your_api_key_here"
-response = requests.get(f"{BASE_URL}/mcp/tools", headers=HEADERS)
+      ]
-tools = response.json()
-print(f"可用工具数量: {len(tools)}")
-
-# 2. 调用工具
-tool_call = {
-    "tool_name": "add_subscribe",
-    "arguments": {
-        "title": "流浪地球",
-        "year": "2019",
-        "media_type": "电影"
     }
+  }
 }
-response = requests.post(
-    f"{BASE_URL}/mcp/tools/call",
-    headers=HEADERS,
-    json=tool_call
-)
-result = response.json()
-print(f"执行结果: {result['result']}")
-
-# 3. 获取工具Schema
-response = requests.get(
-    f"{BASE_URL}/mcp/tools/add_subscribe/schema",
-    headers=HEADERS
-)
-schema = response.json()
-print(f"工具Schema: {schema}")
 ```
 
-### 使用JavaScript/TypeScript调用
+### Cursor IDE
 
-```typescript
+在Cursor的设置中添加MCP服务器配置：
-const BASE_URL = 'http://localhost:3001/api/v1';
-const TOKEN = 'your_access_token';
 
-// 列出所有工具
+```json
-async function listTools() {
+{
-  const response = await fetch(`${BASE_URL}/mcp/tools`, {
+  "mcpServers": {
-    headers: {
+    "moviepilot": {
-      'Authorization': `Bearer ${TOKEN}`
+      "url": "http://localhost:3001/api/v1/mcp",
+      "headers": {
+        "X-API-KEY": "your_api_key_here"
+      }
     }
-  });
+  }
-  return await response.json();
 }
-
-// 调用工具
-async function callTool(toolName: string, arguments: Record<string, any>) {
-  const response = await fetch(`${BASE_URL}/mcp/tools/call`, {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${TOKEN}`,
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify({
-      tool_name: toolName,
-      arguments: arguments
-    })
-  });
-  return await response.json();
-}
-
-// 使用示例
-const result = await callTool('query_subscribes', {
-  status: 'all',
-  media_type: 'all'
-});
-console.log(result);
 ```
 
+### 其他支持MCP的客户端
+
+对于其他支持MCP协议的客户端，可以按照以下方式配置：
+
+1. **服务器地址**: `http://your-moviepilot-host:3001/api/v1/mcp`
+2. **认证方式**: 在HTTP请求头中添加 `X-API-KEY: <your_api_key>` 或在URL查询参数中添加 `apikey=<your_api_key>`
+3. **支持的端点**:
+   - `GET /tools` - 列出所有工具
+   - `POST /tools/call` - 调用工具
+   - `GET /tools/{tool_name}` - 获取工具详情
+   - `GET /tools/{tool_name}/schema` - 获取工具参数Schema
+
+### 获取API Key
+
+API Key可以在MoviePilot的系统设置中生成和查看。请妥善保管您的API Key，不要泄露给他人。
+
 ## 认证
 
-所有MCP API端点都需要认证。支持以下认证方式：
+所有MCP API端点都需要认证。**仅支持API Key认证方式**：
 
-1. **Bearer Token**: 在请求头中添加 `Authorization: Bearer <token>`
+- **请求头方式**: 在请求头中添加 `X-API-KEY: <api_key>`
-2. **API Key**: 在请求头中添加 `X-API-KEY: <api_key>` 或在查询参数中添加 `apikey=<api_key>`
+- **查询参数方式**: 在URL查询参数中添加 `apikey=<api_key>`
 
-获取Token的方式：
+**获取API Key**: 在MoviePilot系统设置中生成和查看API Key。请妥善保管您的API Key，不要泄露给他人。
-- 通过登录API: `POST /api/v1/login/access-token`
-- 通过API Key: 在系统设置中生成API Key
 
 ## 错误处理
 
@@ -267,7 +232,7 @@ API会返回标准的HTTP状态码：
 
 - `200 OK`: 请求成功
 - `400 Bad Request`: 请求参数错误
-- `401 Unauthorized`: 未认证或Token无效
+- `401 Unauthorized`: 未认证或API Key无效
 - `404 Not Found`: 工具不存在
 - `500 Internal Server Error`: 服务器内部错误