docs/API.md

API 文档

本文档详细描述了饭否 MCP 服务器提供的所有工具函数。

认证方式

环境变量方式（PyPI 包）

使用环境变量传递认证信息：

• FANFOU_API_KEY - 饭否应用的 API Key
• FANFOU_API_SECRET - 饭否应用的 API Secret
• FANFOU_OAUTH_TOKEN - OAuth Token（推荐）
• FANFOU_OAUTH_TOKEN_SECRET - OAuth Token Secret（推荐）
• FANFOU_USERNAME - 饭否用户名（首次使用）
• FANFOU_PASSWORD - 饭否密码（首次使用）

HTTP 头方式（SSE 服务）

使用 HTTP 头传递认证信息，支持多用户隔离：

• X-Fanfou-Api-Key - 饭否应用的 API Key
• X-Fanfou-Api-Secret - 饭否应用的 API Secret
• X-Fanfou-OAuth-Token - OAuth Token（推荐）
• X-Fanfou-OAuth-Token-Secret - OAuth Token Secret（推荐）
• X-Fanfou-Username - 饭否用户名（首次使用）
• X-Fanfou-Password - 饭否密码（首次使用）

认证相关

generate_oauth_token

生成 OAuth Token

功能:

• 使用用户名密码生成 OAuth Token
• 用于后续免密登录，避免重复输入用户名密码

前提条件:

• 环境变量方式：需要设置 FANFOU_USERNAME 和 FANFOU_PASSWORD 环境变量
• HTTP 头方式：需要传递 X-Fanfou-Username 和 X-Fanfou-Password 头部

返回:

• 包含 OAuth Token 信息的字典
• 控制台会显示详细的 Token 信息和使用说明

时间线相关

get_home_timeline

获取当前用户首页关注用户及自己的饭否时间线

功能:

• 调用饭否 API 的 /statuses/home_timeline.json 接口获取当前用户的首页时间线
• 包含用户关注的所有人的最新消息
• 注：通常用户询问「我的饭否」时，指的是该时间线，除非用户明确指出「某个用户的饭否」

参数:

• count (int, 可选): 获取数量，默认 5 条
• max_id (str, 可选): 返回列表中内容最新 ID，用于分页获取更早的内容

返回:

• 首页时间线列表，包含以下字段：
  • 饭否内容: 饭否消息内容（HTML 格式）
    • 转发：以「转@」开头，后跟用户链接，如 转@<a href="https://fanfou.com/~FgPOFSnmkW8" class="former">kingcos</a>，其中 href 中的是用户 ID，inner Text 是被转发用户的显示名称，一条饭否可能有多个转发
    • 话题：以「#」包围，如 #<a href="/q/%E6%AD%A3%E5%9C%A8%E6%92%AD%E6%94%BE">正在播放</a>#，其中 q/ 后面的是话题名，一条饭否可能有多个话题
    • 审核状态：如果内容末尾显示「【审核中】」，表示该内容正在审核中
  • 发布 ID: 消息的唯一标识符
  • 发布时间: 消息发布时间
  • 发布者: 发布者的用户名
  • 发布者 ID: 发布者的用户 ID
  • 图片链接: 如果包含图片，则提供图片链接

get_user_timeline

根据用户 ID 获取某个用户发表内容的时间线

功能:

• 调用饭否 API 的 /statuses/user_timeline.json 接口获取指定用户的时间线
• 当提供搜索关键词时，会调用 /search/user_timeline.json 接口进行搜索

参数:

• user_id (str, 可选): 用户 ID，如果为空则获取当前用户时间线
• max_id (str, 可选): 返回列表中内容最新 ID，用于分页获取更早的内容
• count (int, 可选): 获取数量，默认 5 条
• q (str, 可选): 搜索关键词，如果为空则获取普通用户时间线；如果不为空则搜索该用户包含该关键词的消息

返回:

• 用户时间线列表，包含以下字段：
  • 饭否内容: 饭否消息内容（HTML 格式）
    • 转发：以「转@」开头，后跟用户链接，如 转@<a href="https://fanfou.com/~FgPOFSnmkW8" class="former">kingcos</a>，其中 href 中的是用户 ID，inner Text 是被转发用户的显示名称，一条饭否可能有多个转发
    • 话题：以「#」包围，如 #<a href="/q/%E6%AD%A3%E5%9C%A8%E6%92%AD%E6%94%BE">正在播放</a>#，其中 q/ 后面的是话题名，一条饭否可能有多个话题
    • 审核状态：如果内容末尾显示「【审核中】」，表示该内容正在审核中
  • 发布 ID: 消息的唯一标识符
  • 发布时间: 消息发布时间
  • 发布者: 发布者的用户名
  • 发布者 ID: 发布者的用户 ID
  • 图片链接: 如果包含图片，则提供图片链接

get_public_timeline

获取公开时间线

功能:

• 调用饭否 API 的 /statuses/public_timeline.json 接口获取饭否全站最新的公开消息
• 这些是所有用户可见的公开饭否内容
• 当提供搜索关键词时，会调用 /search/public_timeline.json 接口进行搜索

参数:

• count (int, 可选): 获取数量，默认 5 条
• max_id (str, 可选): 返回列表中内容最新 ID，用于分页获取更早的内容
• q (str, 可选): 搜索关键词，如果为空则获取普通公开时间线；如果不为空则搜索包含该关键词的公开消息

返回:

• 公开时间线列表，包含以下字段：
  • 饭否内容: 饭否消息内容（HTML 格式）
    • 转发：以「转@」开头，后跟用户链接，如 转@<a href="https://fanfou.com/~FgPOFSnmkW8" class="former">kingcos</a>，其中 href 中的是用户 ID，inner Text 是被转发用户的显示名称，一条饭否可能有多个转发
    • 话题：以「#」包围，如 #<a href="/q/%E6%AD%A3%E5%9C%A8%E6%92%AD%E6%94%BE">正在播放</a>#，其中 q/ 后面的是话题名，一条饭否可能有多个话题
    • 审核状态：如果内容末尾显示「【审核中】」，表示该内容正在审核中
  • 发布 ID: 消息的唯一标识符
  • 发布时间: 消息发布时间
  • 发布者: 发布者的用户名
  • 发布者 ID: 发布者的用户 ID
  • 图片链接: 如果包含图片，则提供图片链接

用户和内容相关

get_user_info

获取用户信息

功能:

• 调用饭否 API 的 /users/show.json 接口获取指定用户的详细信息
• 如果 user_id 为空，则获取当前登录用户的信息

参数:

• user_id (str, 可选): 用户 ID，如果为空则获取当前用户信息

返回:

• 用户信息字典，包含以下字段：
  • 用户 ID: 用户的唯一标识符
  • 用户名: 用户名
  • 位置: 用户所在位置
  • 性别: 用户性别
  • 生日: 用户生日
  • 描述: 用户个人描述
  • 头像: 用户头像链接
  • 链接: 用户个人网站链接
  • 是否加锁: 账号是否受保护
  • 粉丝数: 被关注数量
  • 朋友数: 互相关注数量
  • 收藏数: 收藏的消息数量
  • 发布数: 发布的消息数量
  • 照片数: 发布的照片数量
  • 是否关注: 当前用户是否关注该用户
  • 注册时间: 账号注册时间
  • 最新状态: 用户最新发布的消息信息（包含发布时间、发布 ID、发布内容）

get_status_info

获取某条饭否内容的具体信息

功能:

• 调用饭否 API 的 /statuses/show/id.json 接口获取指定饭否内容的详细信息

参数:

• status_id (str, 必需): 饭否内容的 ID

返回:

• 饭否内容的详细信息字典，包含以下字段：
  • 饭否内容: 消息文本内容（HTML 格式）
    • 转发：以「转@」开头，后跟用户链接，如 转@<a href="https://fanfou.com/~FgPOFSnmkW8" class="former">kingcos</a>，其中 href 中的是用户 ID，inner Text 是被转发用户的显示名称，一条饭否可能有多个转发
    • 话题：以「#」包围，如 #<a href="/q/%E6%AD%A3%E5%9C%A8%E6%92%AD%E6%94%BE">正在播放</a>#，其中 q/ 后面的是话题名，一条饭否可能有多个话题
    • 审核状态：如果内容末尾显示「【审核中】」，表示该内容正在审核中
  • 发布 ID: 消息的唯一标识符
  • 发布时间: 消息发布时间
  • 发布者: 发布者的显示名称
  • 发布者 ID: 发布者的用户 ID
  • 是否收藏: 当前用户是否收藏了该消息
  • 是否是自己: 是否是当前用户发布的消息
  • 发布位置: 消息发布的地理位置
  • 回复信息: 如果是回复消息，包含被回复的状态 ID、用户 ID 和用户名
  • 图片链接: 如果包含图片，则提供图片链接

互动相关

manage_favorite

管理饭否内容的收藏状态

功能:

• 调用饭否 API 的 /favorites/create/id.json 或 /favorites/destroy/id.json 接口
• 可以收藏或取消收藏指定的饭否内容
• 内置二次确认机制，防止误操作
• 重要：AI助手不能自动确认操作，必须等待用户明确指示

参数:

• status_id (str, 必需): 饭否内容的 ID
• action (str, 必需): 操作类型，"create" 表示收藏，"destroy" 表示取消收藏
• confirm (bool, 可选): 是否确认操作，默认为 False

返回: 首次调用时（confirm=False）:

• 确认信息字典，包含以下字段：
  • 需要确认: 是否需要用户确认
  • 内容预览: 要操作的内容预览（最多50字）
  • 发布时间: 内容的发布时间
  • 发布 ID: 内容的 ID
  • 发布者: 内容的发布者
  • 当前收藏状态: 当前的收藏状态
  • 操作类型: 要执行的操作（收藏/取消收藏）
  • ⚠️ 重要提示: 操作的提醒信息
  • 确认提示: 如何进行确认的说明
  • 🚫 绝对禁止: AI助手不能自动确认的提醒

确认操作时（confirm=True）:

• 操作结果字典，包含以下字段：
  • 是否收藏: 操作后的收藏状态
  • 操作结果: 操作是否成功的描述信息
  • 操作类型: 执行的具体操作（收藏/取消收藏）

使用流程:

1. 首次调用：manage_favorite("status_id", "action") - 显示内容预览和确认提示
2. 用户必须明确表示要操作：用户看到预览后，必须明确说"确认收藏"或"确认取消收藏"
3. 确认操作：只有在用户明确确认后，AI才会调用 manage_favorite("status_id", "action", confirm=True)

安全机制:

• 🛡️ 双重保护：首次调用只显示预览，不执行操作
• 🚫 AI限制：AI助手被明确禁止自动确认操作
• 👤 用户控制：只有用户明确表示要操作时，AI才会执行
• ⚠️ 状态检查：自动检查当前收藏状态，避免重复操作

manage_friendship

管理用户关注状态

功能:

• 调用饭否 API 的 /friendships/create.json 或 /friendships/destroy.json 接口
• 可以关注或取消关注指定用户
• 在执行关注操作前，会先调用 get_user_info 查询目标用户信息
• 智能处理受保护账号的关注申请
• 内置二次确认机制，防止误操作
• 重要：AI助手不能自动确认操作，必须等待用户明确指示

参数:

• user_id (str, 必需): 目标用户的 ID
• action (str, 必需): 操作类型，"create" 表示关注，"destroy" 表示取消关注
• confirm (bool, 可选): 是否确认操作，默认为 False

返回: 首次调用时（confirm=False）:

• 确认信息字典，包含以下字段：
  • 需要确认: 是否需要用户确认
  • 用户预览: 要操作的用户预览信息（用户名、用户ID、是否受保护、粉丝数、发布数、个人描述）
  • 当前关注状态: 当前的关注状态
  • 操作类型: 要执行的操作（关注/取消关注）
  • ⚠️ 重要提示: 操作的提醒信息
  • 特殊情况: 如果是受保护账号，会包含相关提示
  • 确认提示: 如何进行确认的说明
  • 🚫 绝对禁止: AI助手不能自动确认的提醒

确认操作时（confirm=True）:

• 操作结果字典，包含以下字段：
  • 是否关注: 操作后的关注状态
  • 操作结果: 操作是否成功的描述信息
  • 操作类型: 执行的具体操作（关注/取消关注/关注申请）
  • 用户信息: 目标用户的基本信息（用户名、用户ID、是否受保护）
  • 特殊情况: 如果是受保护账号的关注申请，会包含相关提示

使用流程:

1. 首次调用：manage_friendship("user_id", "action") - 显示用户预览和确认提示
2. 用户必须明确表示要操作：用户看到预览后，必须明确说"确认关注"或"确认取消关注"
3. 确认操作：只有在用户明确确认后，AI才会调用 manage_friendship("user_id", "action", confirm=True)

安全机制:

• 🛡️ 双重保护：首次调用只显示预览，不执行操作
• 🚫 AI限制：AI助手被明确禁止自动确认操作
• 👤 用户控制：只有用户明确表示要操作时，AI才会执行
• ⚠️ 状态检查：自动检查当前关注状态，避免重复操作

特殊情况:

• 当目标用户账号受保护（protected）时，关注操作将变为申请关注
• 系统会自动检测并处理这种情况，返回相应的提示信息
• 申请关注需要对方确认后才能生效

发布相关

publish_status

发布饭否内容（仅文字）

功能:

• 调用饭否 API 的 /statuses/update.json 接口发布纯文字内容
• 支持最多140字的文字内容发布
• 内置二次确认机制，防止误发布
• 重要：AI助手不能自动确认发布，必须等待用户明确指示

参数:

• status (str, 必需): 要发布的文字内容（最多140字）
• confirm (bool, 可选): 是否确认发布，默认为 False

返回: 首次调用时（confirm=False）:

• 确认信息字典，包含以下字段：
  • 需要确认: 是否需要用户确认
  • 内容预览: 要发布的内容预览
  • 字数统计: 当前字数和限制（如：50/140）
  • 操作类型: 发布饭否
  • ⚠️ 重要提示: 发布的提醒信息
  • 确认提示: 如何进行确认的说明
  • 🚫 绝对禁止: AI助手不能自动确认的提醒

确认发布时（confirm=True）:

• 发布结果字典，包含以下字段：
  • 发布 ID: 新发布消息的唯一标识符
  • 发布时间: 消息发布时间
  • 发布结果: 发布是否成功的描述信息
  • 重要提示: 关于审核的提醒信息

使用流程:

1. 首次调用：publish_status("内容") - 显示内容预览和确认提示
2. 用户必须明确表示要发布：用户看到预览后，必须明确说"确认发布"或类似的话
3. 确认发布：只有在用户明确确认后，AI才会调用 publish_status("内容", confirm=True)

安全机制:

• 🛡️ 双重保护：首次调用只显示预览，不执行发布
• 🚫 AI限制：AI助手被明确禁止自动确认发布
• 👤 用户控制：只有用户明确表示要发布时，AI才会执行
• ⚠️ 内容验证：自动进行字数统计和内容验证

注意事项:

• 发布成功后需要等待审核才能在时间线中显示
• 内容不能为空且不能超过140字
• 系统会自动进行内容验证
• AI助手绝对不会自动执行发布操作

publish_photo

发布饭否内容（文字+图片）

功能:

• 调用饭否 API 的 /photos/upload.json 接口发布带图片的内容
• 支持文字+单张图片的组合发布（最多一张图片）
• 支持从网络 URL 自动下载图片
• 内置二次确认机制，防止误发布
• 重要：AI助手不能自动确认发布，必须等待用户明确指示

参数:

• status (str, 必需): 要发布的文字内容（最多140字）
• photo_url (str, 必需): 图片的网络 URL 地址
• confirm (bool, 可选): 是否确认发布，默认为 False

返回: 首次调用时（confirm=False）:

• 确认信息字典，包含以下字段：
  • 需要确认: 是否需要用户确认
  • 内容预览: 要发布的内容预览
  • 字数统计: 当前字数和限制（如：50/140）
  • 图片链接: 图片的 URL 地址
  • 操作类型: 发布带图片的饭否
  • ⚠️ 重要提示: 发布的提醒信息
  • URL 提示: 图片 URL 格式检查结果
  • 确认提示: 如何进行确认的说明
  • 🚫 绝对禁止: AI助手不能自动确认的提醒

确认发布时（confirm=True）:

• 发布结果字典，包含以下字段：
  • 发布 ID: 新发布消息的唯一标识符
  • 发布时间: 消息发布时间
  • 发布结果: 发布是否成功的描述信息
  • 重要提示: 关于审核的提醒信息

使用流程:

1. 首次调用：publish_photo("内容", "图片URL") - 显示内容和图片预览以及确认提示
2. 用户必须明确表示要发布：用户看到预览后，必须明确说"确认发布"或类似的话
3. 确认发布：只有在用户明确确认后，AI才会调用 publish_photo("内容", "图片URL", confirm=True)

安全机制:

• 🛡️ 双重保护：首次调用只显示预览，不执行发布
• 🚫 AI限制：AI助手被明确禁止自动确认发布
• 👤 用户控制：只有用户明确表示要发布时，AI才会执行
• ⚠️ 内容验证：自动进行字数统计、内容验证和图片URL检查

支持的图片格式:

• JPEG: https://example.com/image.jpg
• PNG: https://example.com/image.png
• GIF: https://example.com/image.gif
• BMP: https://example.com/image.bmp
• WebP: https://example.com/image.webp

注意事项:

• 发布成功后需要等待审核才能在时间线中显示
• 文字内容不能为空且不能超过140字
• 图片下载后大小不能超过5MB
• 系统会自动从 URL 下载图片并上传到饭否
• 支持 HTTP 和 HTTPS 协议
• 下载超时时间为30秒
• 系统会自动检测图片的 MIME 类型
• AI助手绝对不会自动执行发布操作

delete_status

删除饭否内容

功能:

• 调用饭否 API 的 /statuses/destroy.json 接口删除指定的饭否内容
• 只能删除自己发布的内容
• 内置二次确认机制，防止误删
• 重要：AI助手不能自动确认删除，必须等待用户明确指示

参数:

• status_id (str, 必需): 要删除的饭否内容的 ID
• confirm (bool, 可选): 是否确认删除，默认为 False

返回: 首次调用时（confirm=False）:

• 确认信息字典，包含以下字段：
  • 需要确认: 是否需要用户确认
  • 内容预览: 要删除的内容预览（最多50字）
  • 发布时间: 内容的发布时间
  • 发布 ID: 内容的 ID
  • ⚠️ 重要警告: 删除操作的警告信息
  • 确认提示: 如何进行确认的说明
  • 🚫 绝对禁止: AI助手不能自动确认的提醒

确认删除时（confirm=True）:

• 删除结果字典，包含以下字段：
  • 删除 ID: 被删除消息的 ID
  • 删除结果: 删除是否成功的描述信息
  • 重要提示: 关于删除操作的提醒信息

使用流程:

1. 首次调用：delete_status("status_id") - 显示内容预览和确认提示
2. 用户必须明确表示要删除：用户看到预览后，必须明确说"确认删除"或类似的话
3. 确认删除：只有在用户明确确认后，AI才会调用 delete_status("status_id", confirm=True)

安全机制:

• 🛡️ 双重保护：首次调用只显示预览，不执行删除
• 🚫 AI限制：AI助手被明确禁止自动确认删除操作
• 👤 用户控制：只有用户明确表示要删除时，AI才会执行删除
• ⚠️ 警告提示：每次都会显示删除不可逆的警告

注意事项:

• 只能删除自己发布的饭否内容
• 删除操作不可逆，请谨慎操作
• 删除成功后，内容将立即从时间线中消失
• 需要提供准确的饭否内容 ID
• 系统会自动检查内容所有权，非本人内容无法删除
• 内容预览会自动移除HTML标签，便于阅读
• AI助手绝对不会自动执行删除操作