Atomic Writer MCP Server

Atomic Writer MCP サーバー

MCP（Model Context Protocol）サーバーとして実装された、安全でアトミックなファイル操作サービスです。このサーバーは、MCP プロトコルを通じて安全かつトランザクション対応のファイル操作を提供します。

開発の動機

LLM（大規模言語モデル）が助けようとして、誤ってコンテンツを削除してしまった経験はありませんか？よくある、もどかしい体験です。AI が自信満々にファイルを変更した後で、大切なコンテンツを削除してしまったことに気づくのです。

私は、Obsidian のノートで特につらい経験をした後、このシステムを開発しました。AI がノートの管理を支援する連携機能を開発していたとき、AI が操作の影響に気づかないまま、ノートのコンテンツの半分を意図せず消してしまうことがあるとわかりました。

これをきっかけに、設計段階から破壊的な操作を防ぐ、安全性を最優先にしたファイル操作システム Atomic Writer を開発しました。

• 新しいコンテンツは追記のみ可能で、上書きはできません
• ファイルを作成できるのは、そのファイルが存在せず、空である場合のみです
• すべての操作が記録され、ロールバックできます
• ファイルの整合性が常に監視され、検証されます

もともとは意図しない AI の変更から保護するために構築されましたが、Atomic Writer はファイルの安全性が何より重要なあらゆる状況で利用できます。次のような用途に最適です。

• ファイルを変更する必要がある AI 連携
• 共同編集システム
• 重要なデータの管理
• データの偶発的な損失を防ぐことが不可欠なあらゆるアプリケーション

機能

コアファイル操作

• コンテンツを検証しながらファイルを作成、書き込み
• 整合性を確認しながらファイルを読み取り
• ファイルを新しい場所へアトミックに移動
• ゴミ箱ディレクトリを使用した安全なファイル削除
• ファイルへのコンテンツの追記と先頭への挿入

テキスト操作

• テキストの最初の一致またはすべての一致を置換
• 指定した行番号にコンテンツを挿入
• 指定した行を削除
• 指定した行、または検索語の前後のコンテキストを読み取り

安全機能

• すべての操作をアトミックに実行し、ジャーナルに記録
• ファイルの整合性を検証
• 変更前に自動バックアップ
• 削除したファイル用のゴミ箱ディレクトリ
• 競合を防止するロック管理
• 操作のロールバック機能
• 外部ファイルの自動連携：
  • システム外で作成されたファイルを検出
  • 初回アクセス時に整合性の追跡を初期化
  • 既存の操作とシームレスに連携

システム操作

• システムの状態を監視
• ファイル操作履歴
• ロック管理
• ジャーナルからファイルを復旧
• 外部ファイルに対応した整合性検証
• 未追跡ファイルの追跡を自動的に初期化

インストール

1. リポジトリをクローンします
2. 依存関係をインストールします：npm install
3. プロジェクトをビルドします：npm run build
4. MCP ホストの設定でサーバーを設定します

MCP サーバーの設定

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "atomic-writer": {
      "command": "node",
      "args": [
        "/absolute/path/to/atomic-writer/build/index.js",
        "/absolute/path/to/base/directory"
      ]
    }
  }
}

重要：2 番目の引数（"/absolute/path/to/base/directory"）は必須で、Atomic Writer がファイルを保存、管理する場所を指定します。このディレクトリには、システムファイル（ジャーナル、ロックなど）をすべて格納する .atomic-writer サブディレクトリが作成されます。

または、2 番目の引数を指定する代わりに、環境変数 BASE_DIR を設定できます。

設定ファイルの場所：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

利用可能なツール

このサーバーは、次の MCP ツールを提供します。

ファイル操作

• write-file：新しいファイルを作成、または空のファイルに書き込み
• read-file：整合性を検証しながらファイルを読み取り
• delete-file：ファイルをゴミ箱ディレクトリに移動
• move-file：ファイルをアトミックに移動または名前変更
• append-content：ファイルにコンテンツを追記
• prepend-content：ファイルの先頭にコンテンツを挿入

テキスト操作

• replace-content: テキストの最初の出現箇所を置換します
• replace-all-content: テキストのすべての出現箇所を置換します
• insert-content-at-line: 指定した行番号に内容を挿入します
• delete-line: 指定した行を削除します
• read-lines: 指定した行番号の内容を読み取ります
• read-around: 検索語の前後の行を読み取ります

システムツール

• verify-integrity: ファイルの整合性を確認し、外部ファイルの追跡を開始します
• get-status: システムの状態を取得します
• recover-file: ジャーナルから復元します
• get-file-history: 操作履歴を表示します
• get-lock-status: ファイルのロック状態を確認します
• force-release-lock: 解除できなくなったロックを解除します
• rollback-operation: 変更をロールバックします

エラーコード

操作は標準化されたエラーコードを返します。

• FILE_NOT_FOUND: ファイルが存在しません
• INVALID_PATH: パスが無効です
• EMPTY_CONTENT: 内容が空です
• LINE_OUT_OF_BOUNDS: 行番号が無効です
• FILE_LOCKED: ファイルがロックされています
• INTEGRITY_ERROR: チェックサムの検証に失敗しました

ディレクトリ構成

base/
  ├── files/    # Managed files
  ├── journal/  # Operation journal
  ├── locks/    # File locks
  ├── trash/    # Deleted files
  └── temp/     # Temporary files

開発

• npm run build: TypeScript コードをビルドします
• npm run test: テストスイートを実行します
• npm run lint: リンターを実行します

セキュリティ

• すべての操作はアトミックに実行され、ジャーナルに記録されます
• 操作中はファイルがロックで保護されます
• チェックサムによってコンテンツの整合性が検証されます
• 削除したファイルは完全に削除せず、ゴミ箱に移動します
• 必要に応じて操作をロールバックできます
• 外部ファイルは自動的に整合性保護の対象になります