@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 24 or newer is required. Authenticated GitHub Release tarballs are maintainer mirrors, not the public installation channel.

Install

The npm command installs the released package, with the 21-tool authoring inventory documented here. Version 0.2.0 and later also contain eight restricted Kanban tools in a separate profile, described in Kanban agent connections. Their live-client, OAuth and native acceptance remain unverified.

ZUDOTEXT_MCP_VERSION=0.2.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:

Configuration

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 default authoring registry contains exactly 21 unique names:

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"

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.

See also

• MCP integration — user setup and operating guidance.

• Agent task recipes — intent-shaped recipes for driving a workspace from Claude Code or Codex.

• Local Agent Authoring — security, scope, history, asset, and resource-policy decisions.

Restricted Kanban connections

This capability ships in package 0.2.0 and later, and needs a configured matching Worker and a restricted PAT. Remote OAuth access is not enabled on the hosted service yet, and live-client, OAuth and native acceptance remain unverified.

The default authoring profile has 21 tools and uses its workspace-bound authoring PAT, workspace ID, and password. It does not register Kanban tools. The separate ZUDOTEXT_MCP_PROFILE=kanban profile exposes exactly 8 tools listed below. It requires its own server-restricted Kanban credential, an active grant for selected boards, and an explicit temporary unlock in the first-party connection screen. A document/asset/agent PAT cannot call these routes; adding Kanban scopes to that PAT does not provision a grant. Use separate MCP client entries and credentials when both profiles are needed.

• list_kanban_boards: approved boards only.

• get_kanban_board: ordered column IDs with columnLabels, observed revision and bounded cards; follow nextOffset until null.

• get_kanban_card: stable card identity or a revision-bound file reference.

• create_kanban_card: create a card and membership atomically.

• update_kanban_card: explicit title/body/labels/priority/due only; preserve other fields.

• move_kanban_card: required observed source column and revision; conditional claim has one winner.

• archive_kanban_card: archive with membership atomically.

• restore_kanban_card: restore into an existing column.

get_kanban_board returns ordered stable IDs in columns and an effective columnLabels map from each ID to its display label (configured label, or the ID as fallback). Match the user's intended label to this map, then send the returned ID in create/move/restore column and the observed ID in move expectedColumn. Never send a display label as an ID or assume labels are unique; resolve an ambiguous match before writing.

Every mutation requires the exact expectedRevision from a fresh read and a stable idempotencyKey. Retry a lost response with the identical request; a changed payload under the same key fails. On VERSION_CONFLICT, reread and reconsider intent. Never attach a fresh revision to a stale body. Reads never repair identities; missing identities use {fileId,version} until an explicit mutation initializes the target. Unknown format/source failures make zero writes.

Configure the restricted profile with ZUDOTEXT_SERVER_URL and an explicitly provisioned Kanban-only ZUDOTEXT_PAT. It does not read or prompt for a workspace password, create legacy key sessions, or register generic note, search, history, asset, local-path or AI inference tools. Keep credentials in the client/host secret facility, outside prompts and recipes. For Codex Cloud, a domain-scoped network secret can authorize the HTTPS adapter at POST /api/v1/kanban/tools/<tool_name> with the same JSON arguments; arbitrary hosted custom MCP availability is not assumed.

The first-party connection screen owns login, selected boards, and a separate explicit temporary unlock. Connections start locked. WORKSPACE_LOCKED or KEY_SESSION_EXPIRED means return there to unlock, not retry OAuth. Refresh never creates or extends the memory-only lease (at most 24 hours; eviction may end it sooner). Workspace-wide keys are temporarily held by the server; board restrictions are server authorization, not cryptographic board isolation. A dedicated agent workspace narrows key custody. Direct board editing is independent of built-in Workspace AI consent and never grants agent:invoke.

Remote HTTPS MCP exposes exactly these eight tools at /api/v1/kanban/mcp, with explicit OAuth deployment configuration and the same canonical audience intentionally accepted by the eight REST routes. Actual ChatGPT, Codex CLI, Claude Code and Codex Cloud account acceptance remains a separate live check; SDK/protocol tests do not establish those clients' readiness. Generic TODO, mindmap, timeline, schedule-query and asset operations retain their existing gaps.

Restricted client setup and acceptance

Kanban agent connections covers source-build setup for ChatGPT, Codex CLI/IDE, Claude Code and hosted environments, the separate optional tunnel, and outstanding live-client/native checks. The feature ships in npm 0.2.0 and later; that release is not evidence of live-client or native acceptance. The portable routine in Agent task recipes (MCP) reads, conditionally claims, reports actual results and completes work without implying a scheduler.

Restricted TODO connections (unreleased)

The separate ZUDOTEXT_MCP_PROFILE=todo TODO profile exposes exactly 7 tools listed below, for existing zudo-text TODO documents (type: todo frontmatter, ## TODO / ## DONE sections, <!-- id: … --> item identities). It needs its own server-restricted TODO credential: a grant for exact selected documents (todo:read / todo:write), an explicit temporary unlock, and a TODO-only ZUDOTEXT_PAT. A Kanban credential cannot call these tools and a TODO credential cannot call Kanban, generic note, search, history, checkpoint, asset or agent routes. Moving, deleting or recreating an approved document ends the grant for it. The unlock carries workspace-wide keys; the per-document limit is server authorization, not separate document encryption.

• list_todo_documents(): approved TODO documents only, with title and revision.

• get_todo_document(documentId, offset?, limit?): items (id, title, body, done, section, index, notify) and the whole-document revision; follow nextOffset until null.

• create_todo_item(documentId, expectedRevision, idempotencyKey, title, body?): append an open item with a new persisted identity.

• update_todo_item(documentId, expectedRevision, idempotencyKey, itemId, title?, body?): explicit title/body replacement only.

• set_todo_item_done(documentId, expectedRevision, idempotencyKey, itemId, done): complete or reopen; repeating the current state is a no-op.

• reorder_todo_item(documentId, expectedRevision, idempotencyKey, itemId, toIndex): move within the item's section.

• initialize_todo_item_ids(documentId, expectedRevision, idempotencyKey): append identities to items that have none.

Every mutation edits only the targeted item's bytes and keeps frontmatter, notifications, extra sections and every other item byte-for-byte; content the tool cannot edit that way is refused with zero writes (UNSUPPORTED_FORMAT), as are duplicate identities. Reads never normalize or assign identity: an item with id: null is reachable only after initialize_todo_item_ids. Retry a lost response with the identical request; a changed payload under the same key fails. On VERSION_CONFLICT (the whole document changed), reread and reconsider intent. There is no delete or archive tool.

Remote HTTPS MCP serves the same 7 tools at /api/v1/kanban/todo/mcp, and the seven REST routes at /api/v1/kanban/todo/tools/<tool_name> intentionally accept that same canonical audience. A remote client discovers it from /.well-known/oauth-protected-resource/api/v1/kanban/todo/mcp and authorizes on the same issuer with resource set to that URL and todo:read (add todo:write only when edits are needed). The resource alone selects the TODO family: a Kanban token, a TODO token on Kanban, a mixed kanban:*/todo:* request and a resource-less TODO request are all refused. Consent selects exact TODO documents, is read-only unless edit permission is chosen, and connects locked; unlock it in Settings → External Connections. Refresh can only narrow scopes and never unlocks, extends the lease or changes the documents. Actual client account acceptance remains a separate live check.

Captured document identity

Canonical notes have a permanent noteId UUID and display number; their paths can change. After read_note, retain the returned noteIdentity.noteId, noteIdentity.locationRevision, and body version. Supply these as noteId, expectedLocationRevision, and expectedVersion for update, delete, move, or restore, together with a caller-stable idempotencyKey. Do not substitute a newer version or the current occupant of an old path when retrying. Locate the same UUID and review the new body before authorizing a different edit. Reads and history reads accept noteId to reject a reused path.

Creating a Note Tray note requires a newly minted UUID in noteId and a stable idempotencyKey; omit expectedVersion. Keep the UUID, key, destination and exact body across an uncertain response or process restart. The server assigns the permanent display number. An ordinary root/internal document stays unregistered: its read returns a separate fileId, passed as expectedFileId with the captured version for mutations. Never pass an ordinary file ID as a note UUID or supply both identity fields. A workspace that still needs enrollment must be opened in the current app; there is no path-only creation fallback.

stash_log additionally requires the captured createdAt ISO UTC timestamp, noteId, and idempotencyKey. Reuse the entire tuple and original content on retry. It changes a filename suffix only after a definite collision; uncertain responses retain the original attempt. Read/write/stash results expose identity metadata in structuredContent as well as readable text.

Search results retain structuredContent.documents: the path, file ID, body version and optional canonical note identity captured for each matched body. Carry the matched noteId (or ordinary fileId as expectedFileId) into subsequent reads/history. A moved or reused path must never select a different result silently.