尤里西亚之书 API

一个对开发者和 AI 代理友好的《尤里西亚之书》API。提供全文搜索、结构化内容访问，以及涵盖 197 篇论文中 14,500 多个段落的音频 URL。

API 端点

交互式文档可在 /docs (Swagger UI) 查看。OpenAPI 规范位于 /openapi.json。

SDK

官方 TypeScript SDK 可在 npm 上获取：

npm install @urantia/api    # Typed client for all endpoints
npm install @urantia/auth   # OAuth client for accounts.urantiahub.com

请参阅 urantia.dev/sdks 获取文档。

段落 ID 格式

API 接受三种引用格式——从字符串中自动检测：

搜索

curl -X POST https://api.urantia.dev/search \
  -H "Content-Type: application/json" \
  -d '{"q": "Universal Father", "limit": 10, "type": "and"}'

搜索模式：and（所有词，默认）、or（任意词）、phrase（精确匹配）。可选过滤器：paperId, partId。

音频

段落包含一个 audio 字段——一个按模型和语音键入的嵌套对象，如果没有音频则为 null：

{
  "audio": {
    "tts-1-hd": {
      "nova": { "format": "mp3", "url": "https://audio.urantia.dev/tts-1-hd-nova-3:119.1.5.mp3" },
      "echo": { "format": "mp3", "url": "https://audio.urantia.dev/tts-1-hd-echo-3:119.1.5.mp3" }
    }
  }
}

可用的模型和语音因段落而异。专用的 /audio/:paragraphId 端点仅返回给定段落的音频数据。

缓存

响应包含 Cache-Control 标头。Cloudflare 的 CDN 通过 s-maxage 在边缘进行缓存：

面向 AI 代理

推荐流程：

1. GET /toc — 理解书籍结构

2. POST /search — 查找相关段落

3. GET /paragraphs/:ref/context?window=3 — 获取周围上下文

4. GET /papers/:id — 阅读完整论文

MCP 服务器

该 API 在 https://api.urantia.dev/mcp 包含一个内置的 MCP 服务器——连接 Claude Desktop、Cursor 或任何 MCP 客户端以访问：

• 13 个工具 — 搜索、段落查找、论文导航、实体浏览、音频

• 2 个资源模板 — urantia://paper/{id} (markdown) 和 urantia://entity/{id}

• 2 个提示词模板 — study_assistant, comparative_theology

通过 Smithery 一键安装。

身份验证

公共端点无需授权。用户端点 (/me/*) 需要 JWT。OAuth 流程：

1. 通过 POST /auth/apps (管理员) 或在 accounts.urantiahub.com/developer 自助注册应用

2. 用户在 accounts.urantiahub.com 登录

3. 通过 POST /auth/token 将授权码交换为访问令牌

4. 将令牌作为 Authorization: Bearer <token> 传递

访问令牌是有效期为 7 天的 HS256 JWT。基于浏览器的应用支持 PKCE。

可观测性

• 日志记录： 通过 @logtail/edge 使用 BetterStack — 带有请求元数据的结构化 JSON 日志

• 错误跟踪： 全局错误处理程序将堆栈跟踪发送到 BetterStack

• 健康检查： GET /health — 验证数据库连接

• 正常运行时间： BetterStack 正常运行时间监控

技术栈

• 运行时： Bun (开发) / Cloudflare Workers (生产)

• 框架： Hono + @hono/zod-openapi

• 数据库： Supabase (PostgreSQL + pgvector)

• ORM： Drizzle

• 可观测性： BetterStack (日志记录、正常运行时间)

开发

# Install dependencies
bun install

# Set up environment
cp .env.example .env
# Edit .env with your Supabase DATABASE_URL

# Push schema to database
bun run db:push

# Set up full-text search (run after db:push)
bun scripts/run-fts-setup.ts

# Generate audio manifest (requires ../urantia-hub-api)
bun run generate-manifest

# Seed database from urantia-papers-json
bun run seed

# Start dev server (hot reload)
bun run dev

服务器默认在 http://localhost:3000 运行。

部署

部署到 Cloudflare Workers。首次设置：

npx wrangler login
npx wrangler secret put DATABASE_URL
# paste your Supabase connection string (use pooler port 6543)

npx wrangler secret put APP_JWT_SECRET
# paste a 64-byte hex secret: node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

npx wrangler secret put ADMIN_USER_IDS
# comma-separated Supabase user UUIDs for admin access

部署：

bun run deploy

数据

内容来源于 urantia-papers-json — 197 篇论文、1,626 个章节、14,500 多个段落，通过 audio.urantia.dev 提供音频叙述。

许可证

本项目采用 MIT 许可证 授权。

免责声明

这是一个由 Adams Technologies LLC 发起的独立社区项目。它与尤里西亚基金会（Urantia Foundation）无关，未得到其认可或关联。《尤里西亚之书》的原始英文文本属于公有领域（Michael Foundation v. Urantia Foundation, 10th Cir. 2003）。所有对“Urantia”的使用均为识别主题的提名性合理使用。