collabnotes

collabnotes

collabnotes は HackMD の共同編集ノートを扱います。認証済みユーザーのプロフィール、チーム、閲覧履歴を読み取り、チームノートと個人ノートを一覧表示し、どちらのノートも作成、更新、削除できます。ユーザーが提供する個人用 API トークンを使って、公開されている HackMD API v1 に代わってアクセスします。

このパッケージは、元の HackMD MCP サーバーで文書化されているツールセット全体（12 個のツール）を網羅した、クリーンルームでの再実装です。

サービスとの通信方法

すべてのツールで HackMD API トークンが必要です。

export HACKMD_API_TOKEN="your token"
# Optional override (default: https://api.hackmd.io/v1)
export HACKMD_API_URL="https://api.hackmd.io/v1"

トークンが設定されていない場合、リクエストを行う前に、HACKMD_API_TOKEN を示すエラーが返され、すべての呼び出しが失敗します。

リクエストには Authorization: Bearer HACKMD_API_TOKEN が含まれます。チームパスやノート ID などのパスセグメントは URL エンコードされます。レスポンスは解析済みの JSON として返されます。削除呼び出しと空のレスポンスボディは、関連する ID を含む {"status": "ok", ...} として解決され、上流の HTTP エラーはステータスとボディとともに報告されます。HackMD API の作成／更新権限フィールドはこのツール仕様の対象外です。そのため、作成時に送信されるのは title と content のみで、更新時に送信されるのは content のみです。

インストール

npx @reneturcios/collabnotes list_user_notes '{}'

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/collabnotes

コンテナーはデフォルトで MCP サーバーとして起動します。CLI として使うには、CLI 引数を渡してください。

CLI

CLI はツールに対応しており、各ツールに 1 つずつサブコマンドが用意されています。引数は単一の JSON オブジェクトとして渡します。

collabnotes get_user_info '{}'
collabnotes list_teams '{}'
collabnotes get_history '{}'
collabnotes list_team_notes '{"teamPath":"my-team"}'
collabnotes create_team_note '{"teamPath":"my-team","title":"Spec","content":"# Spec"}'
collabnotes update_team_note '{"teamPath":"my-team","noteId":"abc","content":"# v2"}'
collabnotes delete_team_note '{"teamPath":"my-team","noteId":"abc"}'
collabnotes list_user_notes '{}'
collabnotes get_note '{"noteId":"abc"}'
collabnotes create_note '{"title":"Note","content":"# Note"}'
collabnotes update_note '{"noteId":"abc","content":"# v2"}'
collabnotes delete_note '{"noteId":"abc"}'
collabnotes --version

終了コード：成功時は 0、API エラーまたは検証エラー時は 1（問題の内容が示されます）、使用方法のエラー時は 2 です。

MCP サーバー

1 つの実行ファイルで、どちらの用途にも対応します。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/collabnotes mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "collabnotes": {
      "command": "npx",
      "args": ["-y", "@reneturcios/collabnotes", "mcp"],
      "env": { "HACKMD_API_TOKEN": "your token" }
    }
  }
}

ツール

ツール	入力	機能
get_user_info	（なし）	認証済み HackMD ユーザーの情報を取得します。（GET /me）
list_teams	（なし）	認証済みユーザーが所属するチームを一覧表示します。（GET /teams）
get_history	（なし）	認証済みユーザーのノート閲覧履歴を取得します。（GET /history）
list_team_notes	teamPath（必須）	チームに属するノートを一覧表示します。
create_team_note	teamPath、title、content（すべて必須）	チームに新しいノートを作成します。
update_team_note	teamPath、noteId、content（すべて必須）	チームノートの内容を更新します。
delete_team_note	teamPath、noteId（必須）	チームノートを削除します。
list_user_notes	（なし）	認証済みユーザー自身のノートを一覧表示します。（GET /notes）
get_note	noteId（必須）	ID を指定して単一のノートを取得します。
create_note	title、content（必須）	新しい個人ノートを作成します。
update_note	noteId、content（必須）	個人ノートの内容を更新します。
delete_note	noteId（必須）	個人ノートを削除します。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。