TGO Wiki

TGO Wiki is a Bun-first TypeScript implementation of the Agent Wiki MCP surface. It gives an agent a local git-backed wiki workspace, stable read tools, isolated edit sessions for Markdown changes, v1 document ingestion that turns uploaded source documents into git-tracked wiki sources, and v2 web ingestion that fetches static HTML pages into citable sources.

v2 Current Scope

v2 extends the v1 local git/worktree/session/validation/commit/publish/source surface with static web ingestion:

• Fetch one public http: or https: HTML page into an open session with web_fetch as publisher or admin.
• Store original HTML blobs outside git under workspace state.
• Convert fetched HTML into raw Markdown source files under sources/<source_id>/.
• Read web sources from stable or from an active session ref.
• Validate optional wiki page sources frontmatter against returned web source IDs.
• Commit wiki pages and web source files together on a session branch.
• Fast-forward publish committed clean sessions as publisher or admin.

Typical v2 MCP flow:

wiki_session_start
web_fetch
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

v1 Scope

v1 extends the v0 local git/worktree/session/validation/commit/MCP surface with document ingestion and stable publishing:

• Upload source document blobs into workspace state outside git. Supported input MIME types are application/pdf, text/markdown, text/x-markdown, and text/plain.
• Parse uploaded documents into session worktree files under sources/<document_id>/.
• Configure external command parsers that read document bytes from stdin and emit Markdown on stdout.
• Read source files from stable or from an active session ref.
• Validate optional wiki page sources frontmatter against parsed source IDs.
• Commit wiki pages and source files together on a session branch.
• Fast-forward publish committed clean sessions as publisher or admin.

Typical v1 MCP flow:

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

v0 Scope

v0 is the historical baseline that v1 builds on. Supported in v0:

• Initialize and inspect a local wiki workspace.
• Start an MCP server over stdio.
• Read stable wiki content.
• Run read-only VFS commands against stable content.
• Create isolated edit sessions.
• Replace Markdown pages in a session.
• Validate, diff, and commit session branches.
• Enforce reader and writer tool permissions.

Out of scope in v0:

• Publish and rollback tools.
• Search, document ingestion, web ingestion, and QA tools.
• Remote git or pull request integration.
• Web UI.

Quick Start

Install Bun first; the published CLI runs TypeScript directly with the bun runtime:

curl -fsSL https://bun.sh/install | bash

Install the CLI:

bun add -g tgo-wiki

After installation, the tgo-wiki command is available on your PATH:

workspace="$HOME/.tgo-wiki/default"
tgo-wiki init --workspace "$workspace"
tgo-wiki status --workspace "$workspace"
tgo-wiki mcp --workspace "$workspace" --role reader

npm install -g tgo-wiki also works when bun is already installed and available on PATH.

For one-off usage without a global install:

bunx tgo-wiki status --workspace "$workspace"

Source Checkout

Install dependencies from a source checkout:

bun install --frozen-lockfile

Run the release-readiness gate:

bun run release:check

Run the executable MCP stdio example:

bun run example:mcp

The example creates a temporary workspace, starts the MCP server, lists tools, reads wiki/index.md, runs a writer session flow, commits the session branch, and cleans up the temporary workspace.

Run the packaging smoke before handoff or release checks:

bun run smoke:pack

The packed smoke creates a tarball with bun pm pack, installs that tarball into a temporary consumer project, runs the installed tgo-wiki bin for init and status, starts MCP through the installed bin, and checks initialize plus tools/list.

For a faster local check without packing, run:

bun run smoke:cli

CLI

Create a wiki workspace:

workspace="$(mktemp -d)"
tgo-wiki init --workspace "$workspace"

Inspect workspace status:

tgo-wiki status --workspace "$workspace"

Start the MCP server as a reader:

tgo-wiki mcp --workspace "$workspace" --role reader

Start the MCP server as a writer:

tgo-wiki mcp --workspace "$workspace" --role writer

From a source checkout before publishing, replace tgo-wiki with bun packages/server/src/cli.ts.

MCP Tools

Reader tools:

• vfs_exec
• wiki_read
• wiki_channel_status
• source_list
• source_read

Writer tools:

• wiki_session_start
• wiki_session_patch
• wiki_session_validate
• wiki_session_diff
• wiki_session_commit
• document_upload
• document_parse

Publisher and admin tools:

• web_fetch
• wiki_publish_session

web_fetch rejects private, loopback, link-local, multicast, and reserved network targets by default. Workspace config can explicitly allow private hosts with web.allowedPrivateHosts when local or internal fixtures are intentional. publisher and admin roles can publish committed clean sessions. v0 did not expose publish or rollback behavior; see the v0 docs for that historical scope.

Documentation

• MCP usage guide
• v2 acceptance gate
• v1 acceptance gate
• v0 acceptance gate
• v0 delivery checklist
• Changelog

Development

Default unit and integration checks:

bun run check

Independent black-box tests:

bun run test:blackbox

Full v0 verification:

bun run verify:v0

Full v1 verification:

bun run verify:v1

Full v2 verification:

bun run verify:v2

Release-readiness check:

bun run release:check

Packaging smoke commands:

bun run smoke:pack
bun run smoke:cli

GitHub Actions runs the default checks, black-box tests, and packed CLI smoke as separate jobs.