MCP 接入指南

LifeFrame MCP Server 基于 Model Context Protocol (MCP)，允许 AI 助手直接调用照片管理、AI 点评、地理位置和数据分析等功能。

🚀 快速开始

1. 获取 API Key

登录 LifeFrame
进入「设置」→「API 密钥」
点击「创建新密钥」
输入密钥名称（如 "Claude Desktop"）
选择权限范围和速率限制层级
复制生成的 API Key（格式：lfmcp_...）

⚠️ 重要：API Key 只会在创建时显示一次，请妥善保管！

2. 配置客户端

根据您使用的 AI 客户端，按照以下步骤配置：

Claude Desktop：编辑配置文件添加 MCP 服务器
Cursor：在设置中添加 MCP 服务器
其他客户端：使用 HTTP 客户端调用 JSON-RPC 接口

3. 开始使用

配置完成后，重启客户端，即可在对话中使用 LifeFrame 的功能：

你：帮我列出最近上传的照片
AI：[调用 list_photos 工具] 我找到了您最近上传的 10 张照片...

🔧 Claude Desktop 配置

Claude Desktop 是 Anthropic 官方的桌面应用，支持 MCP 协议。

配置步骤

找到配置文件位置：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
编辑配置文件：

{
  "mcpServers": {
    "life-frame": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-http",
        "--url",
        "https://your-domain.com/api/mcp"
      ],
      "env": {
        "LIFE_FRAME_API_KEY": "lfmcp_your_api_key_here"
      }
    }
  }
}

重启 Claude Desktop
验证连接：

在 Claude Desktop 中输入：

你能帮我列出 LifeFrame 中的照片吗？

高级配置

{
  "mcpServers": {
    "life-frame-pro": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-http",
        "--url",
        "https://your-domain.com/api/mcp"
      ],
      "env": {
        "LIFE_FRAME_API_KEY": "lfmcp_your_pro_api_key_here",
        "NODE_ENV": "production"
      },
      "disabled": false
    }
  }
}

💻 Cursor 配置

Cursor 是一个支持 MCP 的代码编辑器，配置简单且功能强大。

配置步骤

打开 MCP 配置文件

Cursor 的 MCP 配置文件位于：
- macOS/Linux: ~/.cursor/mcp.json
- Windows: %USERPROFILE%\.cursor\mcp.json
编辑配置文件

在 mcpServers 对象中添加 LifeFrame 服务器：
```
{
  "mcpServers": {
    "life-frame-local-dev": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/api/mcp",
      "headers": {
        "Authorization": "Bearer lfmcp_your_api_key_here"
      }
    }
  }
}
```
配置说明：
- life-frame-local-dev: 服务器名称（可自定义）
- type: 必须设置为 "streamableHttp" 以支持流式响应
- url: MCP 服务器地址
  - 开发环境：http://localhost:3001/api/mcp
  - 生产环境：https://your-domain.com/api/mcp
- headers: 认证信息
  - Authorization: Bearer + 空格 + 你的 API Key
重启 Cursor

配置完成后，完全退出并重新启动 Cursor。
验证连接

在 Cursor 的 AI Chat 中输入：
```
@life-frame-local-dev 列出我的照片
```
如果连接成功，你会看到 AI 调用 MCP 工具并返回结果。

生产环境配置

如果要连接到生产环境的服务器：

{
  "mcpServers": {
    "life-frame-prod": {
      "type": "streamableHttp",
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "Authorization": "Bearer lfmcp_your_pro_api_key_here"
      }
    }
  }
}

多环境配置

同时配置开发环境和生产环境：

{
  "mcpServers": {
    "life-frame-local": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/api/mcp",
      "headers": {
        "Authorization": "Bearer lfmcp_dev_key_here"
      }
    },
    "life-frame-prod": {
      "type": "streamableHttp",
      "url": "https://your-domain.com/api/mcp",
      "headers": {
        "Authorization": "Bearer lfmcp_prod_key_here"
      }
    }
  }
}

使用时可以通过 @life-frame-local 或 @life-frame-prod 来选择不同的环境。

📡 其他客户端配置

使用 HTTP 客户端

如果您使用自定义的 agent 客户端，可以直接调用 JSON-RPC 接口：

curl -X POST https://your-domain.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lfmcp_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Python 示例

import requests
import json

url = "https://your-domain.com/api/mcp"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer lfmcp_your_api_key_here"
}

# 列出可用工具
response = requests.post(
    url,
    headers=headers,
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list"
    }
)

print(response.json())

JavaScript/TypeScript 示例

const response = await fetch('https://your-domain.com/api/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer lfmcp_your_api_key_here'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/list'
  })
})

const data = await response.json()
console.log(data)

🛠️ 可用工具

📸 照片工具（6 个）

工具名	说明	权限
`list_photos`	列出照片（支持分页、筛选）	`photos:read`
`get_photo`	获取单张照片详情（含 EXIF）	`photos:read`
`update_photo`	更新照片元数据	`photos:write`
`delete_photo`	删除照片	`photos:write`
`batch_update_photos`	批量更新照片	`photos:write`
`search_photos`	智能搜索照片	`photos:read`

🤖 AI 工具（5 个）

工具名	说明	权限
`review_photo`	AI 照片点评	`ai:review`
`generate_content`	生成旅行内容	`ai:generate`
`list_assistants`	列出 AI 助手	`ai:read`
`get_assistant`	获取助手详情	`ai:read`
`apply_ai_suggestion`	应用 AI 建议	`ai:write`, `photos:write`

🗺️ 位置工具（6 个）

工具名	说明	权限
`geocode`	地理编码（地址 → 坐标）	`locations:read`
`reverse_geocode`	反向地理编码（坐标 → 地址）	`locations:read`
`get_locations`	获取地点列表	`locations:read`
`update_photo_location`	更新照片位置	`locations:write`, `photos:write`
`batch_update_locations`	批量更新位置	`locations:write`, `photos:write`
`get_map_footprint`	获取地图足迹	`locations:read`

📊 分析工具（5 个）

工具名	说明	权限
`get_statistics`	获取统计数据	`analytics:read`
`get_photo_aggregations`	照片聚合分析	`analytics:read`
`create_export_job`	创建导出任务	`analytics:export`
`get_export_job_status`	查询导出任务状态	`analytics:read`
`download_export`	下载导出文件	`analytics:export`

💡 使用示例

示例 1：列出照片

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_photos",
    "arguments": {
      "limit": 10,
      "offset": 0,
      "city": "北京"
    }
  }
}

示例 2：AI 照片点评

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "review_photo",
    "arguments": {
      "photoId": "cmxxx...",
      "style": "professional"
    }
  }
}

示例 3：地理编码

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "geocode",
    "arguments": {
      "address": "北京市朝阳区",
      "provider": "amap"
    }
  }
}

🔐 权限说明

权限范围（Scopes）

Scope	说明
`photos:read`	读取照片信息
`photos:write`	修改/删除照片
`ai:read`	读取 AI 助手信息
`ai:review`	使用 AI 点评功能
`ai:generate`	使用 AI 内容生成
`ai:write`	应用 AI 建议
`locations:read`	读取位置信息
`locations:write`	修改位置信息
`analytics:read`	读取统计数据
`analytics:export`	导出数据

速率限制

套餐层级	请求限制	Token/月
FREE	100/小时	10K
PRO	1000/小时	500K
ENTERPRISE	无限制	5M

🔧 故障排查

认证失败

错误：Unauthorized: Invalid API key

解决方案：

检查 API Key 是否正确（格式：lfmcp_...）
确认 API Key 未过期
验证 API Key 是否已激活

速率限制

错误：Rate limit exceeded

解决方案：

等待 1 小时后重试
升级到 PRO 或 ENTERPRISE 套餐
优化请求频率

权限不足

错误：Insufficient scope

解决方案：

检查 API Key 的权限范围
重新创建包含所需权限的 API Key

连接超时

错误：Request timeout

解决方案：

检查网络连接
确认服务器地址正确
尝试使用 VPN

调试技巧

测试 API 连接：

# 健康检查
curl https://your-domain.com/api/mcp

# 列出工具
curl -X POST https://your-domain.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lfmcp_your_api_key_here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

📚 参考资源

📝 更新日志

v1.0.0 (2026-04-04)

✅ 初始版本发布
✅ 22 个 MCP 工具
✅ 完整的认证和速率限制

On this page