ORANO MCP Server

ORANO MCP 服务

一个个人只读 MCP（Model Context Protocol）服务，可让用户自己的 AI Agent（ChatGPT、Claude、Cursor、Ollama）将其 ORANO 图书馆作为有依据的上下文来读取。

**注意：**此公开仓库包含文档、MCP 服务清单和参考实现。生产环境中的 MCP 服务作为经过身份验证的端点运行，挂载在 ORANO 后端的 /mcp 路径上（FastAPI + Postgres + pgvector）。有关实时端点和身份验证流程，请参阅 ORANO 产品网站。

什么是 ORANO？

ORANO 将保存的 Reels、TikToks、YouTube Shorts 和参考资料转化为结构化项目 — 包括摘要、关键要点、排序后的任务、研究背景和学习路线图。现已在 iOS App Store 上架（App Store 页面）。

个人只读 MCP 服务可让用户自己的 AI Agent 读取这些上下文，这是 ORANO 的差异化优势。

暴露的 MCP 工具

ORANO MCP 服务暴露以下工具：

工具	描述
list_projects	列出用户的项目，并可选择按状态筛选（active、completed、skipped、archived）。
get_project	返回单个项目的完整结构化理解内容，以及摘要、任务、资源、研究和路线图。
get_project_context	仅返回所请求的上下文字段（summary、overview、caption、transcript、visual_context、links、tasks、roadmap、source 或 raw_source），输出格式为结构化内容、Markdown 或文本。
search_library	按标题、摘要、来源标题或 URL 搜索用户的项目。
read_memory_facts	返回经过整理的记忆事实（偏好、技能、目标），并附带置信度和时效性信号。
get_pending_handoffs	检索从 ORANO 应用明确发送给目标 Agent 的项目。每次读取时都会确认一条交接，因此并发轮询不会重复获取。

身份验证

• **机制：**Bearer 个人 API 密钥，作用域为 orano:read。
• **不使用 OAuth。**只能手动创建密钥（参见 landing/mcp-access.html）。
• **每位用户的调用额度：**每 60 分钟 240 次调用。
• **每位用户可启用的密钥上限：**10 个。

MCP 服务清单（server.json）

规范的 MCP 服务清单遵循官方 MCP server.json 架构：

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/server.json",
  "name": "io.github.infotik/orano-mcp-server",
  "displayName": "ORANO",
  "description": "Personal, read-only MCP server that exposes the user's ORANO library (projects, tasks, research, roadmaps, memory facts) as tools for their own AI agent.",
  "version": "0.1.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/infotik/orano-mcp-server"
  },
  "homepage": "https://oranoai.com/mcp",
  "categories": [
    "knowledge-management",
    "personal-assistant",
    "productivity",
    "second-brain"
  ],
  "tools": [
    { "name": "list_projects", "description": "List the user's ORANO projects with optional status filters." },
    { "name": "get_project", "description": "Return a single project's full structured understanding." },
    { "name": "get_project_context", "description": "Return only the requested context fields (summary, overview, transcript, visual_context, links, tasks, roadmap, source, raw_source)." },
    { "name": "search_library", "description": "Search the user's projects by title, summary, source title, or URL." },
    { "name": "read_memory_facts", "description": "Return curated memory facts with confidence and freshness signals." },
    { "name": "get_pending_handoffs", "description": "Retrieve acknowledged-once projects explicitly sent from the ORANO app to a target agent." }
  ],
  "transports": [
    { "type": "http", "endpoint": "https://orano-ai-backend-1037939693300.us-central1.run.app/mcp/" }
  ],
  "authentication": {
    "type": "bearer",
    "scope": "orano:read",
    "user_specific": true,
    "rate_limit": "240 calls / 60 minutes / user"
  }
}

参考实现（Python）

生产服务作为 ORANO 后端（FastAPI + SQLAlchemy + pgvector）的一部分运行。参考实现模式如下：

from mcp.server.fastmcp import FastMCP
from mcp.server.auth.settings import AuthSettings
from mcp.server.auth.provider import AccessToken

mcp = FastMCP(
    name="orano",
    auth=AuthSettings(issuer_url="https://orano-ai-backend-1037939693300.us-central1.run.app", required_scopes=["orano:read"]),
)

@mcp.tool()
async def list_projects(status: str | None = None) -> list[dict]:
    """List the user's ORANO projects."""
    ...

@mcp.tool()
async def get_project(project_id: str, fields: list[str] | None = None) -> dict:
    """Return a single project's full structured understanding."""
    ...

# ... plus get_project_context, search_library, read_memory_facts,
# get_pending_handoffs

完整的生产服务（787 行代码 + 290 行身份验证/握手辅助代码）位于 ExecutionOSBackend/app/mcp_server.py，属于 ORANO 私有后端仓库。要将完整的生产代码开源，需要把 SQLAlchemy 模型和摄取服务提取到一个公开软件包中；这已列入产品路线图，但尚未完成。

使用方法

最终用户：

1. 从 App Store 安装 ORANO iOS 应用。
2. 登录，至少保存一个 Reel/TikTok/YouTube Short，以生成你的第一个项目。
3. 打开“设置”→“MCP 访问”→“创建新密钥”（作用域为 orano:read）。
4. 将你的 AI Agent（ChatGPT、Claude、Cursor、Ollama）连接到个人 MCP 端点，并将密钥用作 Bearer 令牌。

隐私与信任

• MCP 服务为只读。它不会写入项目、来源、任务、记忆或账户数据。
• 唯一的状态变更是 get_pending_handoffs：确认一条由应用触发、排队等待发送的交付，并设置其交付时间戳。
• 不承诺提供 Agent 写入权限；也没有一键式 OAuth 流程。

许可证

MIT — 详见 LICENSE。

链接

• 产品网站
• MCP 概览
• MCP 访问流程
• App Store 页面
• 演示文稿

配置指南

• Claude Code：使用一条 claude mcp add --transport http 命令，或使用包含环境变量密钥的 .mcp.json
• Cursor：使用包含 url 和 Authorization: Bearer ${env:ORANO_MCP_KEY} 的 mcp.json
• 在 ChatGPT、Claude 或 Cursor 中使用已保存视频的三种方式
• 机器可读的连接详情：https://oranoai.com/mcp.json