Growi Smart Save

Smart Save: GROWI Content Save Workflow

Save content to GROWI by finding the best destination, confirming with the user, and creating the page.

Workflow

Step 1: Get destination candidates

Produce a small set of candidate destination directories for the document. There are two ways to get them. The default is the server's suggest-path tool (Step 1a). The Vault local-grep mode (Step 1b) is strictly opt-in: it is noticeably slower (typically 1–2 minutes of grepping and reading) but more accurate, so use it only when the user asked for it.

Step 1a — Server suggest-path (default). Call the suggest-path tool.

• Input: The full content body (the text to be saved)
• Output: An array of destination suggestions (see "Understanding the server response" below)

Step 1b — Vault local-grep discovery (opt-in). Find the candidates by grepping a local clone of the wiki yourself. Use this instead of Step 1a only when both hold:

1. The user asked for it. They explicitly want higher-accuracy placement and accept that it takes longer — e.g. "use the Vault", "take your time and find the right place", "accuracy over speed". Do not switch to this mode on your own judgement; the server path stays the default even when a Vault clone is available.

2. A GROWI Vault clone is reachable. Get or refresh the clone with the MCP server's own vault-sync command:

   npx @growi/mcp-server vault-sync --app-name <name>
   

   One command clones on first use and refreshes afterwards, picks the cache directory itself, and resolves the instance's URL and credential from the same configuration the MCP server uses — so you never handle a token. It prints the app name, the base URL and the clone directory; check that the base URL is the instance this save is for. A non-zero exit means Vault is not usable: tell the user briefly and use Step 1a instead. See references/vault-clone-access.md for prerequisites, other ways to invoke it, and what the exit codes mean. The first clone downloads the whole wiki, so on a large wiki it dominates the wait.

Before starting, check that the command can run at all (node --version — it needs Node.js, the same as the MCP server) and only then tell the user this takes a minute or two, so a missing prerequisite does not cost them the wait. Then discover candidate shelves by grepping the clone — see references/vault-grep-discovery.md (the method: grep the document's concrete tokens, follow where hits cluster, confirm by reading sibling pages, converge on 1–3 parent directories). Judge content fit, not path-string similarity. This mode is worth the wait because you are a stronger reasoner than the server's path agent, and a real grep over raw Markdown hits the exact tokens (slugs, dates, IDs) that decide the right shelf.

The output is 1–3 candidate directory paths (each ending in /), the same shape Step 1a returns.

Whichever path produced the candidates, the rest of the workflow is identical.

Step 2: Present options to the user

Show the candidate destinations from Step 1. Always add a "specify path manually" option — this is your responsibility, not part of any tool response.

• From Step 1a (server), each candidate has a label and description — show them as-is.
• From Step 1b (Vault grep), you found the candidates yourself, so write a one-line reason for each (why this shelf fits — the sibling pages that confirm it), playing the role description plays for server results. Lead with the shelf you judged best.

Example presentation:

1. Save as memo — Save to your personal memo area
2. Save near related pages — Related pages like "How to use React Hooks" exist nearby
3. Specify path manually

Step 3: Decide on a page name

After the user selects a destination:

1. Propose a page name based on the content. If Step 1b discovery showed a naming convention at the chosen shelf, follow it — when the sibling pages use a fixed label (e.g. every feature folder's spec is named 仕様-Specification-) or a consistent pattern, match it rather than inventing a content-derived title. The destination's existing names are the strongest hint for what this page should be called.
2. Let the user confirm or modify
3. Combine directory path + page name into the final path
   • Example: /Tech Notes/React/ + Jotai vs Redux → /Tech Notes/React/Jotai vs Redux

The destination is always a directory (ends with /). You are responsible for proposing the page name portion. (When the destination came from Step 1b, make sure the directory is the decoded GROWI page path, not the on-disk percent-encoded filename — see references/vault-grep-discovery.md.)

Step 4: Confirm visibility (grant)

Before saving, confirm the page's visibility with the user. The grant value at a directory is an upper limit — a constraint, not a recommendation — and the user must never be allowed to pick a visibility that exceeds it. How you know the limit depends on which Step 1 path produced the candidate:

When the candidate came from Step 1a (server). The suggestion carries a grant upper limit. Present up to 3 options based on it:

1. Inherit from parent page — use the destination's grant value as-is
2. Only me — grant 4 (Only-me)
3. Anyone with the link — grant 2 (Anyone-with-the-link)

How should the page visibility be set?
1. Inherit from parent page (Public)
2. Only me
3. Anyone with the link

Do NOT silently default to the upper limit. Always ask unless the only option is Only-me.

When the candidate came from Step 1b (Vault grep). You discovered the path from the clone, so you do not have the grant upper limit in hand. The rule above still applies: inheriting from the parent is saving at the upper limit, so choosing it for the user would be exactly the silent default the rule forbids — a personal note filed under a Public shelf would become a public page without anyone being asked. Ask the same question, with the inherit option described without a level (you don't know it yet):

How should the page visibility be set?
1. Inherit from parent page (same visibility as the destination)
2. Only me
3. Anyone with the link

• Option 1 → omit grant when saving. GROWI applies the closest ancestor's visibility, which by construction cannot exceed the limit.
• Options 2 and 3 → pass that grant. If it would exceed the destination's limit GROWI rejects it server-side; relay the error and re-ask rather than guessing the limit yourself.
• If you would rather not offer an option that will be rejected, resolve the destination with getPage → getPageInfo first to read the limit, then use the Step 1a table above.

Step 5: Save the page

Use the page creation tool to save:

• path: The combined path from Step 3
• body: The content to save
• grant: The visibility confirmed in Step 4 — omit it when the user chose "inherit from parent page", so GROWI applies the destination's own visibility

Understanding the server response (Step 1a)

When candidates come from the suggest-path tool, each suggestion contains:

Vault-grep candidates (Step 1b) are just directory paths you discovered; you supply the reason-to-show yourself (Step 2), and you ask about visibility without knowing the limit (Step 4).

Grant constraints

The grant value is the upper limit of what can be set at that directory — a constraint, not a recommendation.

When saving, the selected grant must not exceed this limit. See Step 4 for how to present options to the user.

Fallback behavior

The discovery method degrades gracefully — the user can always save, whatever is available:

• Vault mode was requested but the clone is not reachable (Vault disabled or not bootstrapped on the instance, no local Node.js or git, no GROWI configuration reachable, clone/fetch error — any non-zero exit from vault-sync) → tell the user briefly that Vault is not usable and use the server suggest-path tool (Step 1a) instead. Do not block the save.
• suggest-path tool fails or is unavailable → offer manual path input.
• Server candidates look weak (all memo type, or none fit the document) → present what you have plus the manual input option; don't force a poor pick. If a Vault clone is reachable, you may additionally offer — once — to re-discover with the slower, more accurate Vault grep mode (Step 1b); run it only if the user accepts.
• Always ensure the user can save their content regardless of which discovery path worked.