Remnus

Remnus

面向人类和 AI Agent 的开源 MCP 原生工作空间。

看板、数据库和页面可供 Claude、Cursor 及任何 AI Agent 通过 MCP 读取和编辑，也可供你使用。

---

Remnus 是什么？

Remnus 是一个以模型上下文协议（MCP）为基础构建的人类与 Agent 协作工作空间。工作空间中的每个页面、数据库和看板都可通过一流的 MCP 服务供 AI Agent 访问——编辑器可通过一键式 OAuth 2.1 (PKCE) 连接，无头 / CI Agent 则可使用限定范围的 bearer token。

与 Notion 的 MCP 集成不同，Remnus 从一开始就面向无头、CI/CD 和编码 Agent 工作流而设计。

原生支持 OKF 上下文，而非倾倒整个工作空间

Remnus 采用开放知识格式（OKF）的理念，将其作为可移植的知识契约。页面可以包含描述、类型、标签、来源、生命周期状态、信息新鲜度日期和与修订版本绑定的审核信号。OKF v0.2 导入 / 导出是数据交换层；可编辑的 Remnus 工作空间仍是规范数据源。

prepare_context MCP 工具会将具体任务转换为 Context Pack v2：根据 BM25 相关性、原生元数据、页面链接、信息新鲜度和可信度排序，并控制令牌预算。Smart 模式会针对有意义的工作自动推荐这种上下文优先的流程。Strict 模式还要求同一 Agent 在执行 Remnus MCP 修改前提供短期有效的 contextRunId。

这并不意味着 MCP 服务可以控制本地文件、Shell 命令或 Git。仓库级强制执行使用提供的 AGENTS.md 和 CLAUDE.md 片段。请阅读公开的上下文优先 MCP 指南和实现说明：Remnus 如何利用 OKF 为 AI Agent 提供更好的上下文。

功能

• 页面 — 支持斜杠命令、嵌套子页面和图标的 Markdown 编辑器
• 数据库 — 可自定义列，支持表格 / 看板 / 日历视图、筛选和排序
• 仪表板 — 实时状态屏幕（指标、图表、列表、嵌入式视图），Agent 可用几百个令牌的 JSON 构建，人类则可逐块编辑
• MCP 服务 — 通过无状态 Streamable HTTP 提供 28 个工具、7 个资源和 7 个提示词
• 原生支持 OKF 上下文 — 可移植的知识元数据、精确修订版本审核、Context Pack v2，以及 Smart / Strict MCP 策略
• Agent 身份验证 — 编辑器可使用一键式 OAuth 2.1 + PKCE（RFC 7591 动态注册），无头 Agent 可使用限定读写范围的个人访问令牌
• 多工作空间 — 邀请成员，支持基于角色的访问权限（所有者 / 成员 / 查看者）
• 桌面应用 — 基于 Tauri v2 的 Windows、macOS 和 Linux 版本
• 移动端 — 基于 Capacitor v8，支持 iOS 和 Android（加载 remnus.com）
• 国际化 — 英语、Türkçe、हिन्दी、Español、Français、Deutsch、中文、Русский

快速开始 — 自托管

本地开发

git clone https://github.com/Ranork/remnus-app.git
cd remnus-app
cp .env.example .env          # fill in AUTH_SECRET + OAuth credentials
npm install
npm run db:migrate
npm run dev

打开 http://localhost:3000。第一个注册的用户会自动升级为管理员。

Docker Compose（5 分钟完成设置）

如果你更喜欢使用 Docker 运行 Remnus：

1. 克隆代码仓库并进入其中：

   git clone https://github.com/Ranork/remnus-app.git
   cd remnus-app
   

2. 复制环境变量模板并填写必需的变量（尤其是 AUTH_SECRET 和 OAuth 凭据）：

   cp .env.example .env
   

3. 启动应用：

   docker compose up -d
   

4. 通过 http://localhost:3000 访问 Remnus。SQLite 数据库将通过 Docker 卷自动持久化。

部署

将 MCP 添加到编辑器

登录后，在侧边栏中打开 AI Agents 面板并点击 连接编辑器。系统会引导你完成所有受支持的编辑器（Cursor、VS Code、Claude Code、Codex、Windsurf 等）的配置。

从注册表安装

Remnus 已发布到 官方 MCP Registry（io.github.Ranork/remnus）和 Smithery，因此支持 MCP 的客户端和目录可以自动发现它。Smithery 支持在多种客户端（Claude、Cursor、VS Code、Codex、Windsurf 等）中一键安装——打开 Smithery 页面并点击 添加到工具箱，或使用 Smithery CLI 直接安装到客户端配置中：

npx -y smithery@latest mcp add ranorkk/remnus --client claude

将 --client 替换为 cursor、vscode、codex、windsurf 等。无论采用哪种方式，首次连接都会进行相同的 OAuth 2.1 登录，无需粘贴令牌。

推荐 — OAuth（无需令牌）： 将编辑器指向 MCP URL，并在首次连接时批准授权页面。编辑器会自动运行 OAuth 2.1 流程——无需复制任何内容。

{
  "mcpServers": {
    "remnus": {
      "type": "http",
      "url": "https://your-instance.com/api/mcp"
    }
  }
}

无头模式 / CI — 个人访问令牌： 在 AI Agents 面板中创建限定范围的令牌，并将其作为 bearer 请求头发送。

{
  "mcpServers": {
    "remnus": {
      "type": "http",
      "url": "https://your-instance.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

MCP 工具

工具	范围	描述
prepare_context	read	构建 Context Pack v2（BM25 + OKF 元数据 + 图），并返回一个短期有效的 contextRunId
search_workspace	read	对页面和数据库进行全文搜索
list_workspace	read	分页列出侧边栏项目
get_page	read	按 ID 获取页面、数据库行或仪表板（以其区块规范的形式）
get_pages	read	一次调用按 ID 获取多个页面/行（批量 get_page）
get_database_schema	read	获取数据库的列结构
query_database	read	使用筛选条件和分页查询行
list_members	read	列出工作区成员及其角色
query_audit_log	read	筛选 Agent 活动日志
get_changes_since	read	按时间戳或游标获取简洁的时间顺序变更动态
get_related_pages	read	获取页面的父级、子级、外链、反向链接、数据库同级项和源文件；或根据文件路径获取依赖该文件的页面
get_status	read	检查此连接：工作区、范围、令牌过期时间及应对方式
create_page	write	创建独立页面或数据库行，并设置图标
bulk_create_pages	write	一次调用最多创建 50 个页面或行，并通过 ref/parentRef 嵌套页面
update_page	write	更新标题、内容或属性
bulk_update_pages	write	一次调用更新多行
delete_page	write	删除页面、数据库、仪表板或行（需要 confirm: true）
bulk_delete_pages	write	一次调用最多删除 100 个页面/行/数据库（需要 confirm: true）
move_item	write	将项目移至新的父级
bulk_move_items	write	一次调用最多移动 100 个项目，可更改父级或将行移至其他数据库
create_database	write	创建带自定义结构、图标和视图的数据库
update_database_schema	write	添加或移除列
create_database_view	write	添加表格/看板/日历视图
update_database_view	write	重命名视图或修改其配置
delete_database_view	write	删除已保存的视图（需要 confirm: true）
create_dashboard	write	根据 JSON 区块创建实时仪表板；返回其 URL，以及可能渲染为空的区块的警告
update_dashboard	write	按区块 ID 修改仪表板——添加、更新、移除、重新排序
add_comment	write	向页面或行添加评论（Agent 评论只能追加）

技术栈

• 框架： Next.js 16.2.6（App Router）
• 数据库： 通过 Drizzle ORM + @libsql/client 使用 SQLite（兼容 Turso）
• 身份验证： Auth.js v5 — Google 和 GitHub OAuth
• 样式： Tailwind CSS + Lucide 图标
• 桌面端： Tauri v2（Rust）
• 移动端： Capacitor v8

参与贡献

请参阅 CONTRIBUTING.md。欢迎所有贡献——错误修复、新 MCP 工具、翻译和文档。

许可证

AGPL-3.0 — 可免费自托管和修改。SaaS 分支必须将其修改开源。