wyrd-scribe

wyrd-scribe

wyrd-scribe は、明示的に許可した1つのフォルダー内に、来歴スタンプ付きの Markdown ページを作成する Tier-A MCP サーバーです。Tier A は作成のみ可能です。新しいページを作成し、その系譜レコードを追記できますが、ページの上書き、名前変更、削除はできず、系譜を照会するツールも公開しません。

インストールと設定

npm install -g wyrd-scribe でインストールします。 実行ファイルは wyrd-scribe です。既定では Stdio を使用するため、MCP クライアントの設定から直接起動できます。

{
  "command": "wyrd-scribe",
  "args": ["--grant", "/absolute/path/to/folder"]
}

許可するフォルダーは、代わりに WYRD_GRANT で指定することもできます。明示的に指定した --grant 引数は WYRD_GRANT より優先されます。WYRD_SCRIBE_TIER で Tier を選択でき、指定がない場合は A が既定値です。Tier B では overwrite_page が追加されます。Tier C は認識されますが、利用できません。

HTTP と HTTPS

HTTP は --http <port> または --http <host>:<port> を指定した場合にのみ起動します。ポートだけを指定すると 127.0.0.1 にバインドされます。--http 127.0.0.1:0 を指定すると、システムが空いているループバックポートを選び、実際のエンドポイントを stderr に出力します。具体的な非ループバックアドレスを指定する場合は、--http-public と有効な TLS 素材も必要です。どちらかがない場合、リッスンを開始する前に起動を拒否します。ルートは POST /mcp です。

Reader トークンとは別に、wyrd-mcp token で新しい Scribe トークンを生成します。トークンの指定元は WYRD_WRITE_TOKEN または --write-token-file <absolute-path> のいずれか一方のみです。トークンは、32バイトをエンコードした、パディングなしの正規形式の base64url でなければなりません。トークンファイルの末尾には、LF または CRLF を1つだけ付けることができます。POSIX では、グループやその他のユーザーがアクセスできない設定にする必要があります。Scribe は WYRD_READ_TOKEN を読み取りません。

WYRD_WRITE_TOKEN=<Scribe-token> wyrd-scribe --grant /absolute/path/to/vault --http 127.0.0.1:8788

ネットワークアクセスの場合は、wyrd-mcp cert --host <hostname-or-IP> で証明書を生成し、具体的なインターフェイスアドレスを設定します。証明書はクライアントから信頼されており、クライアントが使用するホスト名または IP をカバーしている必要があります。証明書の生成方法とプラットフォームでの信頼設定手順については、Reader の README を参照してください。

WYRD_WRITE_TOKEN=<Scribe-token> wyrd-scribe --grant /absolute/path/to/vault --http 192.168.1.20:8788 --http-public --tls-cert /absolute/path/to/wyrd-cert.pem --tls-key /absolute/path/to/wyrd-key.pem

すべてのリクエストで Authorization: Bearer <Scribe-token> が必要です。Origin が存在する場合は、起動時に開示された許可済み Origin と完全に一致している必要があります。HTTP リクエストボディの上限は、エンコードされた JSON エンベロープを含めて 1 MiB です。Stdio にはこの上限はありません。すでに受け付けられた書き込みは、クライアントが切断しても完了します。また、正常なシャットダウンでは、タイムアウトを設けずに、ページと台帳への追記が完了するまで待機します。引用する各ソースは、すべて同じ許可済みフォルダー内に存在する必要があります。ファイアウォール、VPN、コンテナ、仮想マシンのルーティングによって、バインドしたアドレスが外部からアクセス可能になる場合があります。Scribe は起動時にアドレスを一度だけ確認します。

write_page

Tier A では、次の正確な入力形式で write_page を公開します。

{
  "path": "Notes/new-page.md",
  "content": "Page text\n",
  "derived_from": [
    {
      "source": "Sources/source.md",
      "spans": [
        { "offset": 0, "length": 9 },
        { "quote": "source text" },
        { "offset": 0, "length": 9, "quote": "source te" }
      ]
    }
  ]
}

path と各 derived_from[].source は、許可済みフォルダーからの相対パスです。各スパンは、バイト単位の offset と正のバイト数の length、空でない一意に出現する quote、または3つすべてのフィールドのいずれかを正確に指定します。3つすべてのフィールドを指定した場合、バイト列と引用文が一致している必要があります。不明な入力キーは拒否されます。

許可済みフォルダーには、あらかじめ .wyrd/ ディレクトリが存在している必要があります。Scribe はこのディレクトリを作成しません。最初の書き込みが可能になった時点で、次の形式の .wyrd/scribe.json を生成します。

{
  "schema": "wyrd.scribe/v1",
  "vault_id": "a server-minted UUID v4",
  "write_frontmatter": false
}

write_frontmatter の既定値は false です。作成するページに wyrd_lineage キーを含めるには、ボルトの設定で true にします。

結果と復旧

呼び出しが成功すると、まずページが作成され、その後、LF で終端された JSON レコードが 1 件 .wyrd/lineage.jsonl に追記されます。ページ作成後に台帳への追記に失敗した場合、ページは保持されます。結果は PAGE_WRITTEN_LEDGER_FAILED となり、作成されたページの情報と根本原因の cause が含まれ、保持されたバイト数が報告される場合もあります。修復または再試行する前に、保持されたページと台帳を確認してください。同じページパスでの再試行は作成専用であり、EXISTS を返して拒否されます。

台帳の各行は wyrd.lineage/v1 オブジェクトで、event: "page_written"、サーバーが発行する event_id、recorded_at、書き込み元の wyrd-scribe とバージョン、Vault UUID、作成されたページのパスと SHA-256 コンテンツ識別情報、および sources 配列を含みます。各ソースには、許可されたフォルダーからの相対パスとコンテンツ識別情報が含まれます。各スパンには、バイトオフセットと長さ、保存された引用テキスト、バイト数、引用全体の SHA-256、および保存されたテキストが切り詰められているかどうかが記録されます。

フロントマターへの投影が有効な場合、作成されたページには、1 行の JSON を含む wyrd_lineage キーが 1 つ追加されます。この投影には、スキーマ、イベント、イベント ID、タイムスタンプ、書き込み元、Vault、およびソースが含まれます。ページの識別情報とページコンテンツのハッシュは意図的に省略されます。完全な台帳レコードとの紐付けには event_id が使われます。

セキュリティ境界と制限

許可されたフォルダーへの読み取りと書き込みは、すべて wyrd-fence を経由します。包含保証、ハードリンクの制限、残存するファイルシステムの競合状態、および復旧時の影響については、Fence のセキュリティ境界と制限に関する正式な説明で定義されています。Scribe は、直接指定された Arc/ の対象も拒否します。Tier A ではページを新規作成のみできます。Tier B では、期待される SHA-256 が一致する場合に限り、ページを置き換えられます。これらの制御は、範囲を限定したファイルシステム境界であり、オペレーティングシステムのサンドボックスではありません。

プライバシーとデータフロー

サーバーはデフォルトで stdio を使用し、--http を指定した場合にのみネットワークリスナーを開きます。許可されたフォルダー内で、Vault の設定と引用元のソースバイトを読み取ります。Tier A では、新しいページ、必要に応じて新規作成する設定、およびリネージ台帳を書き込みます。Tier B では、ページの置き換えも可能です。接続された MCP クライアントは、ツールのメタデータと、リネージおよび復旧情報を含む構造化された結果または拒否情報を受け取ります。初期化手順では、許可されたフォルダーの正規絶対パスも開示されます。Scribe は、引用されていないソースファイルの内容を返しません。

ソースからのビルドとテスト

ワークスペースのルートから実行します。

npm install
npm --workspace wyrd-fence run build
npm --workspace wyrd-mcp run build
npm --workspace wyrd-scribe test

このパッケージの test ライフサイクルでは、Scribe のテストスイートを実行する前に、Reader の前提条件となるビルドを実行します。

リリースノート

0.2.1 — 2026-10-19

wyrd-fence の正確な依存バージョンを 0.4.0 に更新します。Scribe ツールの動作に変更はありません。

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。