1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@bestai

ClaudeにosFoundryのノートやシートを編集させるときの頼み方と確認ポイント

1
Posted at

この記事でやること

  • ノートまわりのMCPツールが何を必須にしているかを、curlとjqで確かめる
  • Claudeがノートを読めない・書けないときに、どこを順に見ればいいかを整理する
  • 人と同時に編集しても取りこぼしが出にくい頼み方を、そのまま使える形で置いておく

前提・環境

  • ClaudeのチャットにosFoundryのコネクタ（https://api.osfoundry.io/api/v1/external-mcp）を追加済み
  • 接続はワークスペース1つに対して承認済みで、プロジェクトに追加してある
  • 手元に curl と jq がある
  • 記事中のノート名、タブ名、担当者名は表示例

ノート用ツールの必須引数を確かめる

osFoundryのMCPエンドポイントの tools/list は、認証なしで叩けます。ノートとシートに関係するツールだけを抜き出し、読み取り専用かどうかと必須の引数を並べます。

list-note-tools.sh
curl -s -X POST https://api.osfoundry.io/api/v1/external-mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| jq -r '.result.tools[]
         | select(.name | test("note_|sheet"))
         | [.name, (.annotations.readOnlyHint | tostring), (.inputSchema.required | join(","))]
         | @tsv'

2026-11-06に叩いた結果です。

list_note_tabs          true   note_id
read_note_tab           true   note_id,tab_id
list_note_attachments   true   note_id,kind
create_note_tab         false  note_id,expected_version,idempotency_key,tab_type
add_note_source         false  note_id,expected_version,idempotency_key,title,url
edit_note_tab           false  note_id,tab_id,expected_version,idempotency_key,operation
read_sheet_range        true   note_id,tab_id,start_row,start_col,row_count,col_count

書き込みの3つは、どれも expected_version と idempotency_key が必須です。読み取りの4つにはどちらもありません。ここから、Claudeに頼むときに押さえておくことが3つ出てきます。

  • 書く前に必ず読ませる。expected_version は、タブを作るなら list_note_tabs、編集するなら read_note_tab が返したものを使う
  • タブは tab_id で指定させる。同じ種類のシートが1つのノートに何枚あってもよいので、名前や種類だけでは1枚に絞れない
  • シートは範囲で読ませる。read_sheet_range は開始行・開始列・行数・列数が必須で、1回に返すのは最大100×100セル

1つのツールの中身まで見る

edit_note_tab は、operation によって使う引数が変わります。名前で絞ってスキーマを出すと、どの値を取るかが分かります。

... | jq '.result.tools[]
          | select(.name == "edit_note_tab")
          | {operation: .inputSchema.properties.operation.enum,
             sheet_args: (.inputSchema.properties | {sheet_id, start_row, start_col, values} | map_values(.type)),
             scopes: .securitySchemes[0].scopes}'

{
  "operation": ["replace_text", "replace_tab_data", "slide_add", "slides_add_outline", "sheet_set_range"],
  "sheet_args": { "sheet_id": "string", "start_row": "integer", "start_col": "integer", "values": "array" },
  "scopes": ["osfoundry:write"]
}

シートのセルを書き換えるときは sheet_set_range に、開始行・開始列と、行の配列の配列を values として渡します。範囲を指定して書くので、シート全体を送り直す必要はありません。スコープも分かれていて、読み取りの4つはどれも osfoundry:read、書き込みの3つは osfoundry:write を宣言しています。書き込み側の3つは readOnlyHint: false で、接続のToolsで個別にオン・オフできます。

そのまま使える頼み方

Claudeのチャットに、ノート名とタブ名を出して頼みます。最後の2行が、同時編集のときに効いてきます。

prompt.txt
osFoundryの「Q3ローンチ」ノートで作業して。
1. list_note_tabs でタブ一覧を取って、「Owners」シートと「Brief」タブのIDを確認する
2. OwnersシートのA1:D12を read_sheet_range で読む
3. Briefタブを read_note_tab で読み、未完了の項目すべてに担当を書き込む
4. 「ローンチ状況」というスライドタブを足して、担当者ごとに1枚にする
書き込みがバージョンの不一致で拒否されたら、そのタブを読み直して、
今の内容の上に同じ変更をやり直してから書き込んで。

最後の指示は省いても構いませんが、明示しておくと安心です。拒否されたときにバージョンの値だけ新しくして、古いテキストを送り直すと、その間に人が足した行が消えてしまいます。読み直したうえで変更を当て直すように頼んでおけば、Claudeの変更と人の追記の両方が残ります。

Claudeが書き込みの前にツール実行の許可を求めてきたら、それはClaude側の確認です。osFoundry側では、そのノートへの編集権限が呼び出しのたびに確かめられます。

読めない・書けないときに見るところ

上から順に確認すると早いです。

1. ノートが接続のプロジェクトに入っているか

ノートを開き、右側のパネルの「設定」タブ → 「設定」を見ます。プロジェクト未設定なら「プロジェクトに追加」が出ているので、Claudeの接続が入っているプロジェクトを選びます。

2. ノートがワークスペースに同期されているか

この端末にしかないノートはクラウドに実体がないので、接続からは見えません。

3. 書き込みのツールがオンになっているか

鍵アイコン → Connected でClaudeの接続を選び、Toolsを見ます。読み取りだけ使えて書けないときは、edit_note_tab、create_note_tab、add_note_source のチェックが外れていないかを確認します。しばらく読み取り専用にしたいときは、逆にこの3つを外してSave toolsを押せば済みます。

4. 自分にそのノートの編集権限があるか

Claudeの書き込みは、接続を承認した人の権限で動きます。閲覧しかできないノートなら、ツールがオンでも edit_note_tab は通りません。ノートの「Access」タブで確認します。

5. ノートや接続を動かしていないか

接続が入っていないプロジェクトへノートを移した、接続からプロジェクトを外した、Revoke connectionを押した。このどれかをすると、Claudeの次の呼び出しから届かなくなります。前に発行したトークンで開いたままにはなりません。

よくある疑問

最初の書き込みが拒否されたのは失敗ですか

いいえ。Claudeが読んだあとで誰かがノートを保存すると、古いバージョンを名乗った書き込みは受け付けられません。マージもされません。テキスト全体を送る replace_text では、2つの版のどちらが意図なのかをサーバーが決められないからです。読み直して書き直すのが正しい流れで、ツール呼び出しの中にそのまま見えます。

人が別のタブを触っていても、Claudeの書き込みは読み直しになりますか

なります。バージョンはタブ単位ではなくノート単位です。シートを読んでBriefを書く、といったタブをまたぐ作業で、途中で変わったシートの値をもとにBriefを書いてしまわないための仕組みです。読み直しは1回で済みます。

人のほうの編集がClaudeに上書きされることはありますか

デスクトップアプリの保存も、どのリビジョンから編集を始めたかを一緒に送ります。下でノートが変わっていれば、人の編集はローカルの下書きとして残り、同期の競合として知らせます。どちらか一方が黙って消えることはありません。

返事が途切れて、同じタブが2枚できることはありますか

create_note_tab には専用の idempotency_key が付きます。同じキーで呼び直しても、2枚目は作られず、最初に作ったタブが返ります。

タブの種類ごとに使う操作は決まっていますか

決まっています。edit_note_tab の operation は次のとおりです。

タブ operation
ノート・Markdown replace_text
スライド slide_add、slides_add_outline
シートのセル指定 sheet_set_range
そのほかの対応タブ replace_tab_data

create_note_tab が新しく作れるのはスライドとシートのタブです。既存タブの中身を置き換えるものではありません。

添付ファイルの中身は読めますか

list_note_attachments が返すのはFilesとSourcesのメタデータだけで、中身やダウンロードリンクは返しません。出典を足したいときは add_note_source でHTTP/HTTPSのURLを渡します。

まとめ

  • 書き込みツールは expected_version と idempotency_key が必須なので、Claudeには「読んでから書く」「拒否されたら読み直して当て直す」を頼んでおく
  • 届かないときは、プロジェクト、同期、Tools、編集権限、接続の状態の順に見る
  • 拒否と読み直しは、同時編集を守るための正常な流れ

スライドタブがノートのほかのタブとどう並ぶかはノートのスライド機能のページに、ノートの以前の状態を残して戻す仕組みはノートのバージョン管理のページにあります。

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?