デスクトップアプリ — 操作マニュアル

md-business デスクトップアプリは、Markdown で書いた業務文書（適格請求書・基本設計書・ 検証シート・API / DB 設計書）を開き、文書種別ごとの専用プレビューを表示します。左側の Markdown を 編集すると、右側のプレビューがその場で更新されます。仕上がったら A4 PDF に出力できます。すべての処理は お使いの PC の中だけで完結し、アカウント登録も外部送信もありません。

1. インストールと初回起動

1. ダウンロードページからインストーラ（Windows .msi / macOS .dmg）を入手して実行します。
2. 初回起動時に「発行元不明」の警告が出ることがあります（現在コード署名は未対応のため）。 Windows は 「詳細情報」→「実行」、macOS は アプリを右クリック →「開く」 を 1 回行ってください。詳しくは「困ったときは」を参照。
3. 起動直後はサンプル文書がエディターに表示され、レイアウトをすぐ確認できます。これはプレビュー用で 保存はされません。実ファイルを扱うには、次の手順でフォルダを開きます。

2. 画面の構成

画面は 3 つの領域に分かれています。

• 上部バー — 中央にアプリ名（未保存の変更があるときは丸印が付きます）、右側に 保存・PDF・テーマ（ライト / ダーク）・ ヘルプ、およびウィンドウの最小化 / 最大化 / 閉じるボタン。
• 左レール — 開いたフォルダのファイルツリーと、変更されたファイルを示すソース管理欄。 ファイルをクリックすると開きます。
• 中央 — 左右 2 分割。左が Markdown エディター、右が プレビュー。間の仕切りをドラッグすると幅を変えられます。

3. フォルダと文書を開く

本アプリは、Markdown ファイルが入ったフォルダ単位で作業します（プロジェクトフォルダ・ 共有ドライブのフォルダ・Git 作業コピーなど）。

1. 左レールの「フォルダを開く」から、.md / .tsv ファイルのある フォルダを選びます。見つかった Markdown ファイルと TSV 検証シートがツリーに一覧表示されます。
2. ツリーのファイルをクリックするとエディターで開きます。右側のプレビューは、文書の schema: frontmatter から自動で選ばれます（次項参照）。
3. 開いたフォルダは記憶され、次回起動時に自動で開き直します。

4. ライブプレビューで編集する

左の Markdown エディターに入力すると、入力を止めた少し後に右のプレビューが再描画されます。カーソルを動かすと、 編集中の行に合わせてプレビューがスクロール追従します。

プレビューの種類は、文書先頭の frontmatter（--- で囲むブロック）内の schema: 行で 決まります。

frontmatter が無い / 書式が誤っていると、プレビューの代わりに注意書きが表示されます。先頭が --- で囲まれているか、schema: が設定されているかを確認してください。認識される schema が無い文書は、通常の Markdown プレビューにフォールバックします。

変更は保存ボタンまたは Ctrl / ⌘ + S で保存します。文書名の横の丸印は未保存の 変更があることを示します。

5. 請求書を作成する

1. 請求書のひな型（例: templates/invoice/standard-ja.md）を作業フォルダにコピーし、 2026-07-invoice-0001.md のように名前を付けます。
2. フォルダをアプリで開き、その新規ファイルをクリックします。右に請求書プレビューが表示されます。
3. frontmatter の項目（売り手・買い手・登録番号・明細・税率）を編集します。合計と税区分の内訳は入力に応じて プレビューで自動計算されます。該当しない値は空のままにしてください（ダッシュや「N/A」で埋めない）。
4. Ctrl / ⌘ + S で保存し、第 7 項の手順で PDF を出力して受け渡します。

6. 検証シートを記入する

検証シートは、右側が読み取り専用プレビューではなく編集可能なグリッドで開き、表計算のように 結果を直接記入できます。グリッドで開くのは、ファイル先頭にマジック行 #! md-business:test-spec-tsv/v1 がある カスタム TSV 形式の検証シートです （schema: test-spec/v1 の Markdown 検証シートは、グリッドではなく読み取りプレビューで開きます）。

新しい検証シートを作る

列の組み合わせを選ぶだけで、白紙から作れます。左レール右上の ＋（ルート直下に作る）か、 ツリーのフォルダを右クリック →「検証シートを新規作成」（そのフォルダの中に作る）を押すと、 次の 3 つを聞くダイアログが出ます。

• ひな形 — 用意されている列の組です。 試験ケース（項目 / 手順 / 期待結果）は手順どおり実施して結果を残す形、 観点表（分類 / 観点 / 確認方法）は確かめたい点を挙げて抜けを探す形です。 どちらも結果・実施日・担当・備考の列が付きます。
• ファイル名 — .tsv は省略できます（自動で付きます）。
• タイトル — 任意です。入れるとシート冒頭のタイトルになります。

作成するとそのままグリッドで開きます。同じ名前のファイルが既にある場合は上書きせず、理由をダイアログに 表示します。ひな型ファイルから始めたい場合は、これまでどおり templates/test-spec/standard-ja.tsv を作業フォルダにコピーしても構いません。

記入する

• セルをクリックして入力します。矢印キーでの移動、コピー / 貼り付けも表計算と同じ感覚で使えます。列型に応じて プルダウン / ラジオ / 日付・日時ピッカー / チェックボックスがインライン表示されます。
• グリッド上部の「全画面」切り替えでエディターを隠して記入に集中でき、Esc で 分割表示に戻ります。
• 編集内容は自動的に TSV へ書き戻されるので、Ctrl / ⌘ + S で他の文書と同じように 保存できます。

見たい行だけにする

行が増えると、直したい行までスクロールで探すことになります。グリッド上部の 「この値だけ」を押すと、選んでいるセルと同じ列・同じ値の行だけが表に残ります。 Ctrl / ⌘ + F で言葉を入れているときは「当たった行だけ」も出ます。 押すたびにさらに絞れます。

絞り込みはファイルに何も書きません。外した行は保存しても元の位置に残り、 提出物（コピー）にも全行が出ます。戻すときは「絞り込み解除」を押すか、 ファイルを開き直してください。控えにした行（表から外してファイルに残す方）とは別のものです。

絞っている間は、番号を自動で振る列（rowNumber()）は数え直しません。 表に出ている行だけで振り直すと、外している行を飛ばした番号がファイルに残ってしまうためです。

紙に出す

グリッド上部の「下見」を押すと、右ペインが印刷用の版面に切り替わります。この状態でだけ PDF / HTML / 画像の書き出しが有効になります。見出し行は 2 ページ目以降にも繰り返され、 控えにした行は紙にも出ません。切り替えてもファイルは書き換わりません（「グリッドへ戻る」で 表の編集に戻ります）。

行種別・列型の記法・エスケープ・保存規則など、TSV 検証シートの詳しい書式は カスタム TSV 検証シート仕様 を参照してください。

7. PDF を出力する

1. 文書を開き、右側にプレビューが表示されている状態にします。
2. 上部バーの PDF（または Ctrl / ⌘ + P）を押します。プレビューが A4 ページ として組まれた状態で、システムの印刷ダイアログが開きます。
3. 出力先に 「PDF として保存」を選んで保存します。プレビューと 1:1 の PDF になります。

PDF ボタンは、文書プレビューが表示されている間だけ有効です（グリッド編集中や Git 差分表示中は対象外）。 検証シートを PDF にするときは、グリッド上部の「下見」へ切り替えてから押します （第 6 項）。

8. Git で変更を管理する

開いたフォルダが Git 作業コピーの場合、左レールが変更ファイル（追加・変更・未追跡）を色で示します。ソース管理欄で 変更ファイルをクリックすると、右ペインがプレビューの代わりに差分表示に切り替わります。通常どおり 別のファイルを開けばプレビューに戻ります。commit の前に、自分が何を変更したかを正確に確認できます （commit は普段お使いの Git ツールで行ってください）。

共有リンクで同じ文書を見てもらう

同じリポジトリを各自が複製して使っている場合、ツリーのファイルを右クリック →「共有リンクをコピー」で md-business:// で始まるリンクが得られます。チャットやメールで渡すと、受け取った相手が押したときに 本アプリが起動（すでに起動していれば前面に出て）、同じ文書が開きます。

9. レイアウトとテーマ

• 分割幅の調整 — エディターとプレビューの間の仕切りをドラッグします。ダブルクリック （または仕切りにフォーカスして Enter / Home）で 50/50 に戻り、矢印キーで微調整できます。 設定した比率は記憶されます。
• ライト / ダークテーマ — 上部バーのテーマで切り替えます。プレビューも 同じテーマに追従します。

10. AI アシスタントとつなぐ（MCP）

アプリは起動と同時に、この PC の中だけで動く MCP サーバーを内蔵で立ち上げます。AI アシスタント（Claude Desktop など）をつなぐと、いま開いているフォルダの業務文書をアシスタントが 読み書きできるようになります。

つなぐ手順

• 右のサイドパネルを開き、MCP タブを選びます。
• 「接続設定を写す」を押します。AI クライアントの設定へそのまま貼れる JSON が クリップボードに入ります。
• AI クライアント（Claude Code / Claude Desktop / Cursor / Cline など）の MCP 設定へ貼ります。

写される内容は次の形です。

{
  "mcpServers": {
    "md-business": {
      "type": "http",
      "url": "http://127.0.0.1:ポート/mcp",
      "headers": { "Authorization": "Bearer トークン" }
    }
  }
}

既に設定を持っていてトークンだけを入れ替えたいときは、隣の「接続トークンを写す」を 使ってください。

接続先は次に起動しても変わりません

ポートとトークンはアプリの設定フォルダに保存され、次回以降も同じ値で立ち上がります。一度貼った 設定はそのまま使い続けられます。（保存済みのポートが他のソフトに使われていた場合だけ、 空いているポートへ移り、新しい値が保存されます。その場合は設定を貼り直してください。）

トークンを作り直したいときは、下記のファイルを消してからアプリを起動し直します。新しいトークンが 発行されるので、AI クライアント側の設定も貼り直してください。

• Windows: %APPDATA%\io.github.meta-taro.mdbusiness\mcp.json
• macOS: ~/Library/Application Support/io.github.meta-taro.mdbusiness/mcp.json

できること・届く範囲

つないだアシスタントは、業務文書の読み取り・検証・検索・作成・更新ができます。 アシスタントが書き込むと、アプリ側の一覧とプレビューも自動で追いつくので、操作は不要です。

検証シートは行ごとに編集できます。「3 行目の結果を OK にして実施日を入れて」のように 頼むと、その行だけが書き換わります。触っていない行はそのまま残るので、変更履歴に余計な差分が出ません。 列は名前で指定するため、列を並び替えても指示の仕方は変わりません。選択肢にない値も書き込めますが、 どのセルが書式に合っていないかは併せて返るので、書きかけのまま進めて後から直せます。

サーバーはこの PC のループバック（127.0.0.1）だけを受け付け、トークンが一致しない要求は 拒否するため、外部から届くことはありません。アシスタントが触れる範囲も アプリで開いているフォルダの中だけで、フォルダを切り替えると追従します。実行された操作は MCP タブに履歴として残るので、何が読み書きされたかを後から確認できます。

MCP は付加機能です。動かせない環境（Node ランタイムが見つからない場合など）でもアプリの他の機能は 通常どおり使えます。その場合は MCP タブに理由が表示されます。

11. アプリを更新する

起動時に新しいバージョンを自動確認するほか、ヘルプ →「更新を確認」からいつでも確認できます。 更新がある場合はダウンロード後に署名を検証してからその場で適用されるため、ダウンロードページから入れ直す 必要はありません。ヘルプのポップオーバーには現在のバージョン・キーボードショートカット・ライセンスも表示されます。

12. キーボードショートカット

検証グリッド

検証シート（TSV）をグリッドで開いているときは、表計算と同じ感覚のキー操作が使えます。

Home / End は行頭・行末へ、Ctrl（macOS は ⌘）を足すと表の左上・右下へ移動します。 Shift と併用すると、移動でなく選択範囲の伸長になります。

Ctrl + D は選択範囲の先頭行の値を下の行へ配ります。結果・実施日・担当のように 同じ値を何十行も入れる場面で、1 行目に入れてから下へ広げて押します。セルを 1 つだけ選んで 押した場合は、すぐ上のセルの値を引きます。画面下の「下へ埋める」ボタンも同じ動きです。

13. 困ったときは

初回起動で「発行元不明」の警告が出る

まだコード署名をしていないため、初回起動前に OS が警告します。Windows は「詳細情報」→「実行」、 macOS はアプリを右クリック（または Control + クリック）→「開く」を 1 回行えば、以降は通常どおり 起動します。未署名ビルドでは想定内の挙動で、ファイルの問題ではありません。

プレビューに文書でなく注意書きが出る

frontmatter を読み取れていません。ファイル先頭が --- の行で囲まれているか、第 4 項の 表にある正しい schema: 値が設定されているかを確認してください。

保存ボタンが押せない（グレーアウト）

保存は、実ファイルを開いていて未保存の変更があるときだけ有効です。フォルダを開く前に表示されるサンプルは保存 できません。先にフォルダとファイルを開いてください（第 3 項）。

検証シート以外を新規作成できない

アプリ内で新規作成できるのは検証シートです（第 6 項）。請求書や設計書は templates/ のひな型をフォルダにコピーして始めてください（第 3 項）。

質問・フィードバック

不具合の報告や質問は GitHub Issues へお寄せください。ソースコードは MIT ライセンスで github.com/meta-taro/md-business に公開しています。