Fusebase MCP Server

Fusebase MCP服务器

一 主控程序 服务器，让AI助手管理您的 保险丝座 （以前称为Nimbus Note）工作区——页面、文件夹、任务、标签、文件、成员等。

注： Fusebase没有公共REST API。此服务器使用具有基于cookie的身份验证的反向工程内部端点。

✨ 特性

• 63工具 跨内容、任务、成员、组织管理员、门户、数据库、文件、指南等
• 双层制度 --默认加载21个核心工具；42种按需扩展工具
• 自动身份验证重试 --检测401/403并自动刷新会话
• 加密的秘密 --静态加密存储的Cookie（AES-256-GCM）
• 版本检查 --来自GitHub的内置更新检测
• API日志记录 --记录所有调试请求

🚀 快速开始

先决条件

• 18+
• A. 保险丝座 账户

1.安装

选项A——从GitHub安装（推荐）：

npm install -g github:ryan-haver/fusebase-mcp

这会自动安装依赖项，编译TypeScript，并下载Chromium进行身份验证。

选项B--手动克隆和构建：

git clone https://github.com/ryan-haver/fusebase-mcp.git
cd fusebase-mcp
npm install

npm install 自动构建项目并通过以下方式安装Playwright的Chromium prepare 和 postinstall 脚本。

2.配置

复制 .env.example 到 .env 并设置您的Fusebase详细信息：

cp .env.example .env

FUSEBASE_HOST=yourorg.nimbusweb.me     # Your org's Fusebase hostname
FUSEBASE_ORG_ID=your_org_id            # Found in Fusebase URL or API responses

在哪里可以找到这些： 登录Fusebase→ 请查看URL栏。您的主机名是 .nimbusweb.me.组织ID显示在API请求中（打开浏览器DevTools→ 网络选项卡→ 寻找 /v2/api/ 请求：

3.身份验证

运行auth脚本以安全地捕获会话Cookie：

npx tsx scripts/auth.ts

这将打开一个浏览器窗口→ 登录Fusebase→ Cookie会自动捕获并保存 加密的 到 data/cookie.enc.

无头模式： 首次登录后，您可以在没有浏览器窗口的情况下重新进行身份验证： ``bash npx tsx scripts/auth.ts --headless ``

4.连接到您的AI助手

添加到您的MCP客户端配置中。示例：

Gemini CLI — mcp_config.json

{
  "fusebase": {
    "command": "node",
    "args": ["/path/to/fusebase-mcp/dist/index.js"],
    "env": {
      "FUSEBASE_HOST": "yourorg.nimbusweb.me",
      "FUSEBASE_ORG_ID": "your_org_id"
    }
  }
}

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "fusebase": {
      "command": "node",
      "args": ["/path/to/fusebase-mcp/dist/index.js"],
      "env": {
        "FUSEBASE_HOST": "yourorg.nimbusweb.me",
        "FUSEBASE_ORG_ID": "your_org_id"
      }
    }
  }
}

VS Code Copilot — settings.json

{
  "mcp": {
    "servers": {
      "fusebase": {
        "command": "node",
        "args": ["/path/to/fusebase-mcp/dist/index.js"],
        "env": {
          "FUSEBASE_HOST": "yourorg.nimbusweb.me",
          "FUSEBASE_ORG_ID": "your_org_id"
        }
      }
    }
  }
}

注： 替换 /path/to/fusebase-mcp 使用克隆仓库的实际路径。在Windows上，使用双反斜杠： "C:\\path\\to\\fusebase-mcp\\dist\\index.js".

5.验证

问你的AI助手：

*“列出我的Fusebase工作区”*

如果它有效，你就准备好了！ 🎉

🔧 工具层

服务器使用 核心/扩展层系统 为了优化代理上下文的使用：

启用扩展工具：

• 期中：让你的AI使用 set_tool_tier 随着 tier: "all"
• 始终打开：添加 FUSEBASE_TOOLS=all 到你的 .env

核心工具（21）

扩展工具（42）

启用 set_tool_tier(tier: "all"):

• 内容突变: delete_page, update_page_content
• 文件和附件: get_page_attachments, list_files, get_file_count, upload_file, download_attachment
• 标签和标记: get_labels, get_note_tags
• 活动和评论: get_activity_stream, get_comment_threads
• 任务（高级）: get_task_description, get_task_count, get_task_usage
• 组织: get_org_usage, get_org_limits, get_usage_summary, get_org_permissions, get_org_features, get_ai_usage
• 工作区: get_workspace_detail, get_workspace_emails, get_workspace_info
• 导航与人工智能: get_navigation_menu, get_mention_entities, list_agents, get_recently_updated_notes
• 数据库: get_database_data, list_databases, get_database_entity, create_database, add_database_row, list_all_databases, get_database_detail, update_database, delete_database, get_dashboard_detail, delete_dashboard, update_view, set_view_representation
• 传送门: list_portals, get_portal_pages

🔐 安全

• 磁盘上没有明文秘密 --Cookie使用AES-256-GCM使用机器范围的密钥进行加密
• 自动刷新 --过期的会话将通过Playwright透明地刷新
• .env 被忽视了 --凭据从不进入版本控制
• 通过env var创建Cookie --可选通过 FUSEBASE_COOKIE 在加密存储不可用的环境中，在MCP配置中

🗂️ 项目结构

src/
  index.ts              → MCP server (63 tools, stdio transport, tier system)
  client.ts             → HTTP client (cookie auth, 401 auto-retry, logging)
  crypto.ts             → AES-256-GCM encryption for secrets at rest
  types.ts              → TypeScript interfaces for API responses
  content-schema.ts     → Content block IR (25+ block types)
  markdown-parser.ts    → Markdown → ContentBlock[] converter
  token-builder.ts      → ContentBlock → Y.js token builder
  yjs-ws-writer.ts      → Y.js WebSocket writer (write + read via WS sync)
  yjs-html-decoder.ts   → Y.js document → HTML decoder (20+ block types)
  guide-loader.ts       → Guide search index (231 guides, 17 sections)
scripts/
  auth.ts               → Capture session cookies via Playwright
  scrape-guides.ts      → Scrape FuseBase help guides into markdown + NLM sync
  test-regression.ts    → Comprehensive write→read regression test (20 checks)
  test-guide-tools.ts   → Guide loader integration test (13 checks)
  discover.ts           → Crawl Fusebase UI to discover API endpoints
docs/
  guides/               → 231 FuseBase guides across 17 sections (auto-scraped)
data/                   → (gitignored) Cookie store, API logs, workspace cache

🗺️ 路线图

看 未实施_观点.md 对于36个已发现但未实现的API端点，按值划分优先级：

• 自动化 --ActivePieces流/运行管理（11个端点）
• 数据库 --实体/表CRUD（3个端点）
• AI助手 --线程和偏好管理

🤝 贡献

1. 分叉回购
2. 创建要素分支
3. 跑 npm run build 验证TypeScript是否编译成功
4. 提交PR

📄 许可证

麻省理工学院