Roam Research MCP

🚀 Roam 研究服务器 API ドキュメント

Roam Research サーバーは、Roam Research のダイアグラムとやり取りするための強力な API を提供しています。このサーバーは Model Context Protocol (MCP) を実装しており、開発者がプログラムで Room 研究データにアクセスし操作することを可能にします。

このドキュメントでは、サーバーが提供する様々なツールとその機能、パラメータ、入出力形式、エラー処理メカニズムについて詳細に説明します。

🚀 クイックスタート

Roam Research サーバーの API を使うことで、Roam Research のデータにアクセスし操作することができます。以下では、提供されている各ツールの概要と使用方法を説明します。

✨ 主な機能

ツールの概要

1. ブロックマッチ検索

文字列内容を使って特定のブロックを検索します。

use_roam_search {
  "string": "検索する文字列",
  "page_title_uid": "ページタイトルまたは UID（オプション）"
}

機能説明

• 指定されたページ内で、指定された文字列を含むブロックを検索します。
• 部分一致と複数行一致をサポートしています。
• 一致するブロックの詳細情報（内容、UID、ページタイトルを含む）を返します。

2. ページ検索

ページタイトルに基づいて検索します。

use_roam_page_search {
  "string": "検索するページタイトル",
  "exact_match": boolean（オプション、デフォルト：false）
}

機能説明

• 曖昧検索と完全一致モードをサポートしています。
• 一致するページの基本情報（UID とタイトルを含む）を返します。
• 大文字と小文字を区別するかどうかを指定できます。

3. ページ内容取得

UID を使ってページ内容を取得します。

use_roam_page_get {
  "page_title_uid": "ページタイトルまたは UID"
}

機能説明

• 指定されたページの完全な内容構造を返します。
• すべての入れ子になったブロックとそれらの関係を含みます。
• 複雑な階層構造の解析をサポートしています。

4. ブロック作成

ページ内に新しいブロックを作成します。

use_roam_create_block {
  "page_title_uid": "対象ページのタイトルまたは UID",
  "string": "挿入する文字列内容"
}

機能説明

• 指定された位置に新しいブロックを挿入することをサポートしています。
• 一意の UID を自動生成できます。
• 新しく作成されたブロックの情報を返します。

5. ブロック更新

既存のブロックの内容を更新します。

use_roam_update_block {
  "block_uid": "更新するブロックの UID",
  "string": "新しい文字列内容"
}

機能説明

• 部分更新と完全置換をサポートしています。
• 更新後のブロック情報を返します。
• バージョン管理情報を含みます。

6. ブロック削除

指定されたブロックを削除します。

use_roam_delete_block {
  "block_uid": "削除するブロックの UID"
}

機能説明

• 誤削除を防止する安全な削除メカニズムがあります。
• 削除確認情報を返します。
• 一括削除操作をサポートしています。

Datalog クエリインターフェイス

Roam のクエリエンジンに直接アクセスします。

use_roam_query {
  "query": "Datalog クエリ文",
  "inputs": []
}

機能説明

• 完全な Datalog クエリ機能をサポートしています。
• 集約関数と文字列操作を含みます。
• 結果セットの構造化データを返します。

🔧 技術詳細

エラー処理

サーバーは包括的なエラー処理メカニズムを提供しています。

• 設定エラー：
  • API キーまたはチャート名が欠落している。
  • 環境変数の設定問題。
• API エラー：
  • 認証失敗。
  • 無効なリクエスト。
  • 操作失敗。
• ツール固有のエラー：
  • ページが見つからない（大文字と小文字を区別する検索）。
  • 内容でブロックが見つからない。
  • タグ形式が無効。
  • 必須パラメータが欠落している。

各エラーレスポンスには以下が含まれます。

• MCP 標準エラーコード
• 詳細なエラーメッセージ
• 解決策の提案（適用可能な場合）

開発ガイド

サーバー実装の詳細

サーバーは Node.js と Express フレームワークに基づいて構築されており、TypeScript を使って型安全な開発が行われています。主な依存モジュールは以下の通りです。

• @roamjs/core - Roam の核心機能ライブラリ
• express - Web アプリケーションフレームワーク
• typescript - 静的型付けサポート

プロジェクト構造

src/
├── server.ts - メインサーバーファイル
├── routes/ - ルートモジュール
│   ├── blocks.ts - ブロック関連のルート
│   └── pages.ts - ページ関連のルート
├── middleware/ - ミドルウェア
│   ├── auth.ts - 認証ミドルウェア
│   └── errorHandling.ts - エラー処理ミドルウェア
└── types/ - 型定義ファイル

開発環境の設定

以下の依存関係が必要です。

• Node.js 14+
• TypeScript 4.0+
• @roamjs/core 5.x
• Express 4.x

💻 使用例

新しいブロックを作成する

const response = await fetch('/api/create-block', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "page_title_uid": "My Page",
    "string": "New block content"
  })
});

Datalog をクエリする

const response = await fetch('/api/query', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "query": "SELECT * FROM blocks WHERE content LIKE '%test%'"
  })
});

見つからないページを処理する

try {
  const response = await fetch('/api/search-page', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      "string": "NonExistentPage"
    })
  });
} catch (error) {
  console.error('エラー:', error);
}

📄 ライセンス

本ドキュメントでは、Roam Research サーバー API の機能と使用方法を詳細に説明しました。開発者はこれらのインターフェイスを通じて、Roam 研究データとの高度なやり取りを実現できます。さらなるサポートや質問については、当社の技術チームにお問い合わせください。