@takazudo/zudotext-mcp

@takazudo/zudotext-mcp is the official local stdio MCP server for one encrypted zudo-text cloud workspace. It exposes documents, versions, checkpoints, changes, five narrow asset operations, and optional delegation to the cloud AI assistant.

This page is the authoritative distribution, install/configuration, exact-tool inventory, and release reference. For operating workflow, use MCP integration; for design and safety policy, use Local Agent Authoring.

The package is public on npm while its source repository remains private. Node.js 22.19 or newer is required. Authenticated GitHub Release tarballs are maintainer mirrors, not the public installation channel.

Install

ZUDOTEXT_MCP_VERSION=0.1.1
npm install --global "@takazudo/zudotext-mcp@${ZUDOTEXT_MCP_VERSION}"
zudotext-mcp --version

The last command must print the version that was installed. The tarball ships two executables:

Command	Purpose
`zudotext-mcp`	Start the stdio MCP server.
`zudotext-mcp-install-skill`	Install, update, or byte-check the official authoring skill for one harness.

Configuration

Variable	Required	Contract
`ZUDOTEXT_SERVER_URL`	yes	Sync-server origin.
`ZUDOTEXT_PAT`	yes	Prefer a PAT bound to this workspace with the four narrow document/asset scopes.
`ZUDOTEXT_WORKSPACE_ID`	yes	The one workspace exposed by this process.
`ZUDOTEXT_WORKSPACE_PASSWORD_FILE`	one password source	Recommended absolute path to a file you create, containing only the workspace password; protect it with `chmod 600`.
`ZUDOTEXT_WORKSPACE_PASSWORD`	one password source	Inline environment value; easier but more exposed.
neither password variable	one password source	Prompt from the external process's controlling OS shell through `/dev/tty`, without echo. This is not the retired in-app terminal.
`ZUDOTEXT_WORKSPACE_SALT`	no	Debug override only; normal startup reads workspace metadata.
`ZUDOTEXT_AGENT_URL`	no	Agent-server origin for `ask_zudo_agent`.
`ZUDOTEXT_MCP_LOG_LEVEL`	no	`debug`, `info`, `warn`, `error`, or `silent`; logs use stderr.

Before using ZUDOTEXT_WORKSPACE_PASSWORD_FILE, create the file yourself with a trusted editor, write only the workspace password, and run chmod 600 /absolute/path/to/workspace-password. The process never writes the workspace password to disk. stdout is reserved for MCP framing; logs are redacted and written to stderr.

Exact tool inventory

The assembled registry contains exactly 21 unique names:

Family	Tools
Document reads	`list_notes`, `read_note`, `search_notes`
Document writes	`write_note`, `stash_log`
Lifecycle	`delete_note`, `move_note`
Session and history	`begin_authoring_session`, `list_note_versions`, `read_note_version`, `restore_note_version`, `list_checkpoints`, `get_checkpoint_summary`, `get_checkpoint_restore_manifest`
Changes	`what_changed`
Assets	`list_assets`, `get_asset_usage`, `download_asset`, `upload_asset`, `create_asset_folder`
Cloud agent	`ask_zudo_agent`

There is no registered checkpoint note-state tool. Checkpoint rollback uses the restore manifest and normal per-document tools. Assets are outside document history/checkpoints/changes and expose no narrow rename, move, delete, replace, or recursive-delete operation.

Install the official authoring skill

The release carries behaviorally equivalent Claude Code and Codex skills.

# User scope
zudotext-mcp-install-skill --harness claude-code
zudotext-mcp-install-skill --harness codex

# Repository scope (absolute repository root required)
zudotext-mcp-install-skill --harness claude-code --project "$PWD"
zudotext-mcp-install-skill --harness codex --project "$PWD"

Harness	User destination	Repository destination	Explicit invocation
Claude Code	`$CLAUDE_CONFIG_DIR/skills/zudotext-authoring/SKILL.md`, falling back to `~/.claude/skills/zudotext-authoring/SKILL.md`	`.claude/skills/zudotext-authoring/SKILL.md`	`/zudotext-authoring`
Codex	`$HOME/.agents/skills/zudotext-authoring/SKILL.md`	`.agents/skills/zudotext-authoring/SKILL.md`	`$zudotext-authoring` or `/skills`

Update the npm package first, then replace and verify the matching artifact:

zudotext-mcp-install-skill --harness claude-code --update
zudotext-mcp-install-skill --harness claude-code --check
zudotext-mcp-install-skill --harness codex --update
zudotext-mcp-install-skill --harness codex --check

Without --update, an existing skill is never overwritten. --check is read-only and byte-exact. Owner edits to the skill's destructive defaults make the check fail intentionally; back them up before an update and reapply them afterward. Do not install these files under .zudotext/skills/, which belongs to the separate in-app inline-AI skill format.

Package and release shape

The package's only runtime dependencies are the MCP SDK and Zod. Its private workspace crypto/path dependencies are development dependencies inlined into the distributable JavaScript by tsup, so an installed tarball has no unresolved @takazudo/* runtime import.

Release verification performs a clean build, npm pack, installation into a temporary prefix, installed zudotext-mcp --version, the exact 21-tool inventory smoke, tarball-content checks, private-import checks, and byte checks for both packaged skills.