Desktop app — user guide

The md-business desktop app opens business documents written as Markdown (invoices, design specs, test sheets, API and database designs), shows a purpose-built preview for each document type, and lets you edit the Markdown on the left while the preview updates live on the right. When a document looks right, export it to an A4 PDF. Everything runs locally on your machine — no account, no upload.

1. Install and first launch

1. Download the installer from the download page (Windows .msi / macOS .dmg) and run it.
2. On the first launch you may see an "unknown publisher" warning because the build is not yet code-signed. On Windows choose More info → Run anyway; on macOS right-click the app → Open once. See Troubleshooting for details.
3. The app opens with a sample document shown in the editor so you can see the layout right away. This sample is a preview only — it is not saved anywhere. Open a folder (next section) to work on real files.

2. The window at a glance

The window has three areas:

• Top bar — the app title in the center (with a dot when there are unsaved changes), and on the right: Save, PDF, Theme (light/dark), Help, and the window minimize / maximize / close controls.
• Left rail — the file tree of the folder you opened, and a source-control section that marks changed files. Click a file to open it.
• Center — a split view: the Markdown editor on the left and the preview on the right. Drag the divider between them to change the balance.

3. Open a folder and a document

The app works on a folder of Markdown files (a project folder, a shared drive folder, or a Git working copy).

1. Use Open folder in the left rail and pick the folder that holds your .md / .tsv files. The tree fills with every Markdown file and TSV test sheet it finds.
2. Click any file in the tree to open it in the editor. The preview on the right is chosen automatically from the document's schema: front-matter (see the next section).
3. The folder you opened is remembered, so the next time you launch the app it reopens it for you.

4. Edit with live preview

Type in the Markdown editor on the left. A moment after you stop typing, the preview on the right re-renders. As you move the cursor, the preview scrolls to follow the line you are editing.

The preview is selected from the schema: line in the document's front-matter (the block fenced by --- at the top of the file):

If the front-matter is missing or malformed, the preview shows a note instead of a rendered document — check that the top block is fenced by --- and that schema: is set. Documents without a recognized schema fall back to a plain Markdown preview.

Save your changes with the Save button or Ctrl / ⌘ + S. A dot next to the document title means there are unsaved changes.

5. Create an invoice

1. Copy an invoice template (for example templates/invoice/standard-ja.md) into your working folder and rename it, e.g. 2026-07-invoice-0001.md.
2. Open the folder in the app and click the new file. The invoice preview appears on the right.
3. Edit the front-matter fields (seller, buyer, registration number, line items, tax rate). The totals and tax breakdown update in the preview as you type. Leave a value empty when it does not apply — do not fill blanks with dashes or "N/A".
4. Save with Ctrl / ⌘ + S, then export a PDF (section 7) to hand off.

6. Fill in a test sheet

A test sheet opens in an editable grid on the right instead of a read-only preview, so you can fill in results directly like a spreadsheet. The grid opens for a custom TSV test sheet — a file whose first line is the magic line #! md-business:test-spec-tsv/v1 (a schema: test-spec/v1 Markdown test sheet opens as a read-only preview, not the grid).

Create a new test sheet

You can start from scratch by picking a set of columns. Press the + button at the top right of the left rail (creates the file at the top of the open folder), or right-click a folder in the tree → "New test sheet" (creates it inside that folder). A dialog asks for three things.

• Template — a ready-made set of columns. Test cases (item / steps / expected result) is for running through steps and recording what happened; Viewpoints (category / viewpoint / how to check) is for listing what you want to confirm and spotting gaps. Both add result, date, owner and notes columns.
• File name — you can leave out .tsv; it is added for you.
• Title — optional. If you fill it in, it becomes the title at the top of the sheet.

The new sheet opens in the grid straight away. If a file with the same name already exists, nothing is overwritten and the dialog tells you why. You can still start from a template file instead by copying templates/test-spec/standard-ja.tsv into your working folder.

Fill it in

• Click a cell and type to edit it; use the arrow keys and copy / paste to move around, the same as a spreadsheet. Depending on the column type, a dropdown / radio / date or datetime picker / checkbox is shown inline.
• Use the Fullscreen toggle above the grid to hide the editor while you work through cases, and press Esc to return to the split view.
• Your edits are written back into the TSV automatically, so Ctrl / ⌘ + S saves the sheet like any other document.

For the full format — line kinds, column-type notation, escaping, and save rules — see the custom TSV test-sheet specification.

7. Export to PDF

1. Open the document so its preview is showing on the right.
2. Press PDF in the top bar (or Ctrl / ⌘ + P). The system print dialog opens with the preview laid out as A4 pages.
3. Choose Save as PDF as the destination and save. The PDF matches the preview one-to-one.

The PDF button is active only while a document preview is on screen (not during grid editing or a Git diff).

8. Track changes with Git

If the folder you opened is a Git working copy, the left rail marks changed files (added, modified, untracked) with color. Click a changed file in the source-control section to see its diff in the right pane instead of the preview; open any file normally to return to the preview. This lets you review exactly what you changed before committing with your usual Git tool.

9. Layout and theme

• Resize the split — drag the divider between the editor and preview. Double-click it (or press Enter / Home while it is focused) to reset to 50/50; use the arrow keys for fine adjustment. Your ratio is remembered.
• Light / dark theme — click Theme in the top bar to switch. The preview follows the same theme.

10. Connect an AI assistant (MCP)

The app starts a built-in MCP server that runs only on your own machine. Connect an AI assistant (Claude Desktop, for example) and it can read and write the business documents in the folder you currently have open.

How to connect

• Open the side panel on the right and select the MCP tab.
• Click Copy connection settings. This puts a JSON snippet on the clipboard that you can paste straight into an AI client.
• Paste it into the MCP settings of your AI client (Claude Code, Claude Desktop, Cursor, Cline, …).

The copied snippet looks like this.

{
  "mcpServers": {
    "md-business": {
      "type": "http",
      "url": "http://127.0.0.1:port/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

If you already have the settings in place and only want to swap the token, use Copy access token next to it.

The connection stays the same across restarts

The port and token are stored in the app's configuration folder and reused the next time the app starts, so settings you paste once keep working. (Only if the stored port is taken by another program does the app move to a free one and store the new value — paste the settings again in that case.)

To issue a new token, delete the file below and restart the app. A fresh token is generated, so paste the settings into your AI client again.

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

What it can do, and how far it reaches

A connected assistant can read, validate, search, create and update business documents. When it writes, the file list and preview in the app follow along on their own — you do not have to refresh anything.

Test sheets are edited row by row. Ask for something like "mark row 3 as OK and fill in today's date" and only that row changes — rows it did not touch stay exactly as they were, so your history shows the edit and nothing else. Columns are addressed by name, so reordering them does not change how you phrase the request. Values outside the allowed choices are still written, but you get back which cells do not match the format, so you can leave a sheet half-filled and fix it later.

The server only accepts loopback connections (127.0.0.1) and rejects requests whose token does not match, so nothing outside your machine can reach it. The assistant can only touch the folder you have open in the app, and it follows along when you switch folders. Every tool call is listed in the MCP tab, so you can review what was read or written afterwards.

MCP is an optional extra. If it cannot run (for example, no Node runtime is installed), the rest of the app keeps working as usual and the MCP tab shows the reason.

11. Update the app

The app checks for a newer version on startup, and you can check any time from Help → Check for update. When an update is available it is downloaded, verified against a signature, and applied in place — you do not need to reinstall from the download page. The Help popover also shows the current version, the keyboard shortcuts, and the license.

12. Keyboard shortcuts

13. Troubleshooting

"Unknown publisher" warning on first launch

The build is not code-signed yet, so the OS warns before the first run. Windows: click More info, then Run anyway. macOS: right-click (or Control-click) the app → Open once; after that it launches normally. This is expected for an unsigned build and does not indicate a problem with the file.

The preview shows a note instead of the document

The front-matter could not be read. Make sure the very top of the file is a block fenced by --- lines and that it contains a valid schema: value from the table in section 4.

The Save button is greyed out

Save is available only when a real file is open and it has unsaved changes. The sample shown before you open a folder cannot be saved — open a folder and a file first (section 3).

I can't create anything other than a test sheet

Test sheets are the document type you can create inside the app (section 6). For invoices and specs, copy a template from templates/ into your folder to start a new document (section 3).

Questions and feedback

Report issues or ask questions on GitHub Issues. The full source is available under the MIT license at github.com/meta-taro/md-business.