tgo-wiki 0.1.0

package/docs/mcp-usage.md

@@ -0,0 +1,631 @@
+# Agent Wiki MCP Usage
+
+Date: 2026-06-12
+
+## Purpose
+
+This guide shows how to run the Agent Wiki MCP server and call its public tools. It is written for agent clients that connect over stdio JSON-RPC.
+
+v2 supports local workspace initialization, stable wiki reads, isolated edit sessions, document ingestion, web ingestion, source reads, validation, diff, session commits, and fast-forward publish. v0 remains documented below as the historical baseline that later releases extend.
+
+## Local Setup
+
+Install Bun first; the published CLI runs TypeScript directly with the `bun` runtime:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+Install the CLI:
+
+```bash
+bun add -g tgo-wiki
+```
+
+Create a local wiki workspace:
+
+```bash
+workspace="$(mktemp -d)"
+tgo-wiki init --workspace "$workspace"
+```
+
+Inspect workspace status:
+
+```bash
+tgo-wiki status --workspace "$workspace"
+```
+
+From a source checkout before publishing, install dependencies with `bun install --frozen-lockfile` and replace `tgo-wiki` with `bun packages/server/src/cli.ts`.
+
+`init` prints:
+
+```json
+{
+  "workspaceRoot": "/tmp/example",
+  "stableCommit": "0123456789abcdef0123456789abcdef01234567"
+}
+```
+
+`status` prints the stable branch, commit, worktree, dirty flag, and session count:
+
+```json
+{
+  "workspaceRoot": "/tmp/example",
+  "repoPath": "/tmp/example/repo",
+  "branch": "wiki/stable",
+  "commit": "0123456789abcdef0123456789abcdef01234567",
+  "worktree": "/tmp/example/worktrees/stable",
+  "dirty": false,
+  "sessionCount": 0
+}
+```
+
+## Start the MCP Server
+
+Start a read-only server:
+
+```bash
+tgo-wiki mcp --workspace "$workspace" --role reader
+```
+
+Start a writer server:
+
+```bash
+tgo-wiki mcp --workspace "$workspace" --role writer
+```
+
+Start a publisher server:
+
+```bash
+tgo-wiki mcp --workspace "$workspace" --role publisher
+```
+
+The server speaks newline-delimited JSON-RPC over stdio. Each request or notification should be serialized as one JSON object followed by `\n`.
+
+## Initialize MCP
+
+Send `initialize`:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example-client","version":"0.0.0"}}}
+```
+
+Then send the initialized notification:
+
+```json
+{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
+```
+
+List tools:
+
+```json
+{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
+```
+
+Call a tool with:
+
+```json
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"wiki_read","arguments":{"path":"wiki/index.md","include_frontmatter":true}}}
+```
+
+Successful tool calls return `content` and `structuredContent`. Tool-level failures return `isError: true` and a typed error under `structuredContent.error`.
+
+## Roles
+
+`reader` can call:
+
+- `vfs_exec`
+- `wiki_read`
+- `wiki_channel_status`
+- `source_list`
+- `source_read`
+
+`writer` can call every reader tool plus:
+
+- `wiki_session_start`
+- `wiki_session_patch`
+- `wiki_session_validate`
+- `wiki_session_diff`
+- `wiki_session_commit`
+- `document_upload`
+- `document_parse`
+
+`publisher` and `admin` can call every reader/writer tool plus:
+
+- `web_fetch`
+- `wiki_publish_session`
+
+`web_fetch` is publisher/admin-only because it performs server-side network I/O. It rejects private, loopback, link-local, multicast, and reserved network targets by default, including redirects to those targets. Workspaces that intentionally fetch local or internal pages can add exact hostnames or IP literals to `web.allowedPrivateHosts`.
+
+## Tool Reference
+
+### `vfs_exec`
+
+Runs an allowed read-only VFS command against stable wiki content.
+
+Input:
+
+```json
+{"command":"pwd"}
+```
+
+Optional input:
+
+```json
+{"command":"cat wiki/index.md","ref":"stable"}
+```
+
+Output fields:
+
+- `stdout`
+- `stderr`
+- `exit_code`
+- `cwd`
+- `ref`
+
+### `wiki_read`
+
+Reads one stable Markdown page.
+
+Input:
+
+```json
+{"path":"wiki/index.md","include_frontmatter":true}
+```
+
+Output fields:
+
+- `path`
+- `ref`
+- `frontmatter`, when `include_frontmatter` is true
+- `content`
+- `sha`
+
+### `wiki_channel_status`
+
+Reports stable channel status.
+
+Input:
+
+```json
+{"channel":"stable"}
+```
+
+Output fields:
+
+- `channel`
+- `branch`
+- `commit`
+- `worktree`
+- `dirty`
+
+### `wiki_session_start`
+
+Creates an isolated edit session from stable by default.
+
+Input:
+
+```json
+{"purpose":"update the home page","agent_id":"example-agent"}
+```
+
+Output fields:
+
+- `session_id`
+- `branch`
+- `worktree`
+- `base_ref`
+- `base_commit`
+
+### `wiki_session_patch`
+
+Replaces a Markdown page in a session worktree. Full content replacement is required. Unified patch input is not supported. Direct writes to `sources/**` are rejected with `source_write_denied`; use ingestion tools such as `document_upload` plus `document_parse`, or `web_fetch`, to create source files.
+
+Input:
+
+```json
+{
+  "session_id": "SESSION_ID",
+  "path": "wiki/index.md",
+  "content": "---\ntitle: \"Home\"\nsummary: \"Entry point for the wiki.\"\ntags: [\"home\"]\nupdated: \"2026-06-11\"\n---\n\n# Home\n\nUpdated content.\n",
+  "reason": "refresh home page copy"
+}
+```
+
+Output fields:
+
+- `path`
+- `changed`
+- `sha_before`, when the file already existed
+- `sha_after`
+
+### `wiki_session_validate`
+
+Validates changed Markdown pages in a session, including optional `sources` frontmatter references when present.
+
+Input:
+
+```json
+{"session_id":"SESSION_ID"}
+```
+
+Optional focused validation:
+
+```json
+{"session_id":"SESSION_ID","paths":["wiki/index.md"]}
+```
+
+Output fields:
+
+- `ok`
+- `errors`
+- `warnings`
+
+### `wiki_session_diff`
+
+Shows committed and working diff for a session.
+
+Input:
+
+```json
+{"session_id":"SESSION_ID"}
+```
+
+Optional focused diff:
+
+```json
+{"session_id":"SESSION_ID","paths":["wiki/index.md"]}
+```
+
+Output fields:
+
+- `session_id`
+- `base_ref`
+- `diff`
+- `committed_diff`
+- `working_diff`
+- `changed_files`
+
+### `wiki_session_commit`
+
+Commits validated session changes on the session branch, including wiki pages and ingestion-generated source files.
+
+Input:
+
+```json
+{"session_id":"SESSION_ID","message":"docs: update home page"}
+```
+
+Output fields:
+
+- `commit`
+- `branch`
+- `changed_files`
+
+Committing a session branch does not publish or mutate stable content. Use `wiki_publish_session` as `publisher` or `admin` to fast-forward stable after commit.
+
+### `document_upload`
+
+Stores a raw document blob under workspace state outside git.
+
+Supported MIME types:
+
+- `application/pdf`
+- `text/markdown`
+- `text/x-markdown`
+- `text/plain`
+
+Input:
+
+```json
+{
+  "session_id": "SESSION_ID",
+  "file_name": "handbook.pdf",
+  "mime_type": "application/pdf",
+  "content_base64": "JVBERi0xLjQK"
+}
+```
+
+Markdown input:
+
+```json
+{
+  "session_id": "SESSION_ID",
+  "file_name": "plan.md",
+  "mime_type": "text/markdown",
+  "content_base64": "IyBQbGFuCg=="
+}
+```
+
+Output fields:
+
+- `document_id`
+- `blob_sha256`
+- `size`
+- `status`
+
+### `document_parse`
+
+Parses an uploaded document into git-tracked source files in a session worktree.
+
+Input:
+
+```json
+{"session_id":"SESSION_ID","document_id":"DOCUMENT_ID"}
+```
+
+Output fields:
+
+- `document_id`
+- `version`
+- `raw_markdown_path`
+- `metadata_path`
+- `status`
+- `warnings`
+
+The parsed source is written under `sources/<document_id>/raw.md`, with metadata in `sources/<document_id>/metadata.json`.
+
+For Markdown uploads, `raw.md` preserves the uploaded Markdown body. For plain text uploads, `document_parse` wraps the text in readable Markdown with a generated H1 and parser header. Source files still are not wiki pages and do not use wiki frontmatter.
+
+Command parser configuration:
+
+Workspace config can enable external command parsers under `documents.parsers`.
+
+```json
+{
+  "documents": {
+    "parsers": {
+      "marker": {
+        "enabled": true,
+        "command": "marker_single --output-format markdown -",
+        "supportedMimeTypes": ["application/pdf"],
+        "version": "marker-single",
+        "timeoutMs": 60000
+      }
+    }
+  }
+}
+```
+
+Command parser MVP rules:
+
+- The command runs locally where the MCP server runs.
+- The uploaded document bytes are written to stdin.
+- `TGO_DOCUMENT_ID`, `TGO_FILE_NAME`, `TGO_MIME_TYPE`, and `TGO_PARSED_AT` are provided as environment variables.
+- stdout must be Markdown and becomes `sources/<document_id>/raw.md`.
+- stderr is not written to `raw.md`; failures return `parse_failed`.
+- Shell syntax such as pipes and redirects is not supported.
+
+### `web_fetch`
+
+Fetches one public static HTML page into an open session as a raw source. Only `publisher` and `admin` roles can call this tool.
+
+Input:
+
+```json
+{
+  "session_id": "SESSION_ID",
+  "url": "https://example.com/docs"
+}
+```
+
+Output fields:
+
+- `source_id`
+- `version`
+- `raw_markdown_path`
+- `metadata_path`
+- `html_blob_sha256`
+- `status`
+- `title`, when available
+- `warnings`
+
+The original HTML blob is stored outside git under `state/web/blobs/sha256/<sha256>`. The generated source files are written into the session worktree under `sources/<source_id>/raw.md` and `sources/<source_id>/metadata.json`.
+
+The tool returns `source_id`, but the existing source APIs still use the `document_id` input name. Pass the returned `source_id` as `document_id` when calling `source_read`:
+
+```json
+{
+  "document_id": "web_20260613_ab12cd34ef567890",
+  "ref": "SESSION_ID"
+}
+```
+
+Use the same id in wiki page frontmatter `sources` when patching derived pages:
+
+```markdown
+---
+title: "Example Docs"
+summary: "Notes derived from the fetched web source."
+tags: ["web", "imported"]
+updated: "2026-06-13"
+sources:
+  - web_20260613_ab12cd34ef567890
+---
+
+# Example Docs
+
+The published page content should cite the fetched source id in frontmatter.
+```
+
+### `source_list`
+
+Lists ingestion-generated sources from stable or a session ref, including parsed documents and fetched web sources.
+
+Input:
+
+```json
+{"ref":"stable"}
+```
+
+Session ref input:
+
+```json
+{"ref":"SESSION_ID"}
+```
+
+Output fields:
+
+- `sources`
+
+### `source_read`
+
+Reads an ingestion-generated source file from stable or a session ref.
+
+Input:
+
+```json
+{"document_id":"DOCUMENT_ID","ref":"SESSION_ID"}
+```
+
+Stable input:
+
+```json
+{"document_id":"DOCUMENT_ID","ref":"stable"}
+```
+
+Output fields:
+
+- `document_id`
+- `ref`
+- `metadata`
+- `raw_markdown`
+
+### `wiki_publish_session`
+
+Fast-forwards stable to a committed clean session branch.
+
+Input:
+
+```json
+{"session_id":"SESSION_ID","channel":"stable","mode":"ff-only"}
+```
+
+Output fields:
+
+- `ok`
+- `channel`
+- `previous_commit`
+- `published_commit`
+
+## Complete v2 Web Ingestion Flow
+
+Start the server with `--role publisher` or `--role admin`, then initialize MCP.
+
+```text
+wiki_session_start
+web_fetch
+source_read with ref = session_id
+wiki_session_patch with frontmatter.sources citing returned source_id
+wiki_session_validate
+wiki_session_diff
+wiki_session_commit
+wiki_publish_session as publisher/admin
+source_read from stable
+```
+
+For separated duties, a writer can start the session, patch, validate, diff, and commit. A publisher or admin performs `web_fetch` and the final publish step.
+
+## Complete v1 Document Ingestion Flow
+
+Start the server with `--role publisher` or `--role admin`, then initialize MCP.
+
+```text
+wiki_session_start
+document_upload
+document_parse
+source_read with ref = session_id
+wiki_session_patch with frontmatter.sources
+wiki_session_validate
+wiki_session_diff
+wiki_session_commit
+wiki_publish_session as publisher/admin
+source_read from stable
+```
+
+For separated duties, a writer can perform upload, parse, patch, validate, diff, and commit; a publisher or admin performs the final publish step.
+
+## Historical v0 Writer Flow
+
+Start the server with `--role writer`, then initialize MCP.
+
+Read stable content:
+
+```json
+{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"wiki_read","arguments":{"path":"wiki/index.md","include_frontmatter":true}}}
+```
+
+Start a session:
+
+```json
+{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"wiki_session_start","arguments":{"purpose":"update home page"}}}
+```
+
+Use the returned `session_id`, then replace the page with complete Markdown content:
+
+```json
+{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"wiki_session_patch","arguments":{"session_id":"SESSION_ID","path":"wiki/index.md","content":"---\ntitle: \"Home\"\nsummary: \"Entry point for the wiki.\"\ntags: [\"home\"]\nupdated: \"2026-06-11\"\n---\n\n# Home\n\nUpdated content.\n","reason":"refresh home page copy"}}}
+```
+
+Validate:
+
+```json
+{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"wiki_session_validate","arguments":{"session_id":"SESSION_ID"}}}
+```
+
+Inspect diff:
+
+```json
+{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"wiki_session_diff","arguments":{"session_id":"SESSION_ID"}}}
+```
+
+Commit the session branch:
+
+```json
+{"jsonrpc":"2.0","id":15,"method":"tools/call","params":{"name":"wiki_session_commit","arguments":{"session_id":"SESSION_ID","message":"docs: update home page"}}}
+```
+
+After commit, `wiki_read` still reads stable. In the v0 historical flow there is no publish step, so committed session content remains isolated on the session branch.
+
+## Common Errors
+
+Permission denied:
+
+```json
+{
+  "isError": true,
+  "structuredContent": {
+    "error": {
+      "code": "permission_denied",
+      "message": "reader cannot use wiki_session_start"
+    }
+  }
+}
+```
+
+Common tool-level error codes:
+
+- `permission_denied`: the server role cannot call that tool.
+- `unsupported_channel`: a requested `ref`, `channel`, or publish mode is not supported.
+- `invalid_path`: the requested path is invalid or escapes the wiki root.
+- `validation_failed`: validation found errors before commit.
+- `source_write_denied`: session patch attempted to write under `sources/**`.
+- `session_dirty`: there are no session changes to commit, or the session state is not committable.
+- `session_not_found`: the session id does not refer to known session metadata.
+
+Schema-level input validation errors are returned by the MCP SDK as `isError: true` with text content. For example, sending a `patch` key to `wiki_session_patch` instead of `content` is rejected before the tool handler runs.
+
+## v0 Historical Scope
+
+v0 supported local workspace initialization, stable wiki reads, isolated edit sessions, validation, diff, and session commits. Publishing, rollback, search, ingestion, and QA tools were intentionally out of scope.
+
+These tools did not appear in `tools/list` for v0:
+
+- `wiki_publish_session`
+- `wiki_rollback`
+- `wiki_search`
+- document ingestion tools
+- web ingestion tools
+- QA or semantic search tools
+
+Use [v2-acceptance.md](./v2-acceptance.md) for the current release gate. Use [v1-acceptance.md](./v1-acceptance.md) and [v0-acceptance.md](./v0-acceptance.md) for historical acceptance policy.