Seojeom MCP Server

Local-first MCP server for Claude/Codex project wiki and graph workflows.

Preview status This package is published and installable today, but it is still a preview release rather than a stable general-availability product. Tool behavior, playbooks, packaging, and release automation may change between versions while the standalone MCP workflow is being stabilized.

What It Does

• connects Claude or Codex to a project-local wiki under <projectRoot>/wiki
• reads and edits a local graph snapshot under .seojeom/graph/*
• prepares deterministic graph workflows, runbooks, sessions, and playbooks
• supports both direct local mutation and proposal/review flows

Who It Is For

• writers who want local continuity tracking instead of a remote-only SaaS workflow
• worldbuilding-heavy projects that benefit from wiki + graph side by side
• Korean webnovel or long-form creative writing projects that need reusable authoring context

60-Second Claude Quickstart

Option 1: Claude Code CLI

claude mcp add seojeom -- npx -y @seojeom/mcp-server \
  --project-root . \
  --project-id demo-project \
  --graph-authority local-snapshot \
  --approval-mode prompt

Option 2: Claude Desktop (GUI)

1. Open Claude Desktop settings → Developer → Edit Config.
2. Add the entry below to claude_desktop_config.json. Replace <project-root> with the absolute path to your novel/worldbuilding directory and pick a short project id.
3. Completely quit and restart Claude Desktop.

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "seojeom": {
      "command": "npx",
      "args": [
        "-y",
        "@seojeom/mcp-server",
        "--project-root", "<project-root>",
        "--project-id",   "<project-id>",
        "--graph-authority", "local-snapshot",
        "--approval-mode",   "prompt"
      ]
    }
  }
}

If npx fails to resolve inside Claude Desktop (Windows), add "env": { "APPDATA": "C:\\Users\\<you>\\AppData\\Roaming\\" } to the server entry. See the Claude Desktop local-server docs for full troubleshooting.

Option 3: Have the server print the exact command first

npx -y @seojeom/mcp-server \
  --print-claude-onboarding \
  --project-root . \
  --project-id demo-project

Recommended first calls after install

1. seojeom_get_claude_mcp_onboarding
2. seojeom_list_graph_playbooks
3. seojeom_prepare_graph_playbook with a focus node and preset such as document_entity, repair_state, or atomic_decomposition

One-click install (MCPB bundle, preview)

A Desktop Extension (.mcpb) bundle manifest is included at manifest.json and validated via @anthropic-ai/mcpb. Once a seojeom-mcp-<version>.mcpb file is attached to a GitHub release, double-clicking it will install the server into Claude Desktop without editing any config. Build with:

npm install --omit=dev --package-lock=false
npx @anthropic-ai/mcpb pack

By default mcpb pack writes mcp-server.mcpb in this directory. Rename it if you want a versioned release asset name before attaching it to GitHub Releases.

The MCPB bundle only asks the user for project_root and project_id at install time; no JSON editing is required.

Package Contract

• primary public surface: seojeom-mcp CLI / npx -y @seojeom/mcp-server
• primary transport: stdio
• optional desktop/launcher path: loopback HTTP sidecar
• expected runtime: Node >=20.20.0

Tool Namespace

All MCP tools exposed by this package share the seojeom_* prefix (e.g. seojeom_list_graph_playbooks, seojeom_get_claude_mcp_onboarding, seojeom_prepare_graph_playbook). Package branding, bin, CLI alias, and tool namespace all align on seojeom.

Current limitation

This package is not local-authority complete yet.

• local graph authority is snapshot + proposal queue + scene store, not an embedded graph DB
• proposal apply still only supports the proposal item kinds currently emitted by the standalone queue (create_node, create_edge)
• embedded graph DB, richer packet validation parity, and broader graph intelligence workflows remain follow-up work
• graph chat, auto-fill orchestration, and web-search still remain separate higher-level workflows; seojeom_analyze_graph_gaps only covers deterministic local review
• desktop sidecar still defaults wiki and graph authority to api-bridge for launcher compatibility

Maintainer Note

• canonical public repository: https://github.com/seojeom/seojeom-mcp
• package metadata points there for repository, homepage, and issue tracking
• MCP Registry identifier target: io.github.seojeom/seojeom-mcp
• License: MIT (see LICENSE)
• planned CI entrypoint: .github/workflows/mcp-server-release.yml
• planned publish mode: GitHub Actions Trusted Publishing + npm publish --provenance
• current caveat: this workflow is prepared locally, but it does not become live until the public repo above actually exists
• registry submission prep helper: pnpm -C apps/desktop run prep:mcp-server-registry-submission -- --output-dir artifacts/mcp-server-registry-submission
• latest local packet path: apps/desktop/artifacts/mcp-server-registry-submission/
• release bundle now embeds the same packet under apps/desktop/artifacts/mcp-server-release/registry-submission/
• GitHub publication prep helper: pnpm -C apps/desktop run prep:mcp-server-github-publication -- --output-dir artifacts/mcp-server-github-publication
• public launch handoff helper: pnpm -C apps/desktop run prep:mcp-server-public-launch-handoff -- --output-dir artifacts/mcp-server-public-launch-handoff
• latest public launch handoff: apps/desktop/artifacts/mcp-server-public-launch-handoff/
• release bundle also embeds github-publication/ and public-launch-handoff/ under apps/desktop/artifacts/mcp-server-release/

Current scope

• stdio standalone entry for claude mcp add ... -- npx @seojeom/mcp-server
• existing desktop-owned loopback HTTP entry for the Tauri launcher sidecar
• wiki, graph, proposal, and project tools from the desktop MCP baseline
• standalone wiki tools default to local filesystem authority under <projectRoot>/wiki
• standalone graph tools default to local snapshot authority under <projectRoot>/.seojeom/graph/*
• standalone wiki-first buildout prep can combine orphan inventory, graph-bound wiki targets, and ordered next-tool phases into one deterministic packet before graph-side decomposition
• standalone graph read tools can opt into local snapshot authority from .seojeom/graph/canonical-slice.json
• standalone graph context bundling can assemble prompt-ready local graph facts around a focus node
• standalone graph gap analysis can inspect local snapshot structure without upstream API calls
• standalone graph workflow preparation can combine context, gaps, and next-tool recommendations for Claude/Codex
• standalone graph research preparation can decide when to reuse local wiki, create wiki notes, or escalate to external research
• standalone graph runbook preparation can sequence local review, documentation, research prep, and graph edit steps into one ordered session plan
• standalone graph session preparation can turn that runbook into a Claude-ready prompt contract with grounding rules and ordered tool calls
• standalone focused graph sessions can narrow the contract to wiki documentation, packet repair, or relation fill-in work
• standalone graph playbooks can wrap those focused sessions into named presets such as document, repair, relation fill-in, or research-document-link
• standalone graph playbook catalog can tell Claude which preset to pick and provide a starter prompt before any graph call
• standalone Claude onboarding helper can emit the exact claude mcp add command and the first MCP calls to make after install
• standalone graph proposal tools can use a local proposal queue at .seojeom/graph/proposal-sets.json
• standalone graph scene tools can use a local scene store at .seojeom/graph/scenes.json
• standalone local graph apply supports approved create_node and create_edge proposals against the canonical snapshot
• standalone direct graph mutation tool can apply local create/update/delete node, create/update/delete edge, create/update packet, and patch_node_timeline operations against the canonical snapshot

Standalone usage

node dist/standalone.js \
  --project-root . \
  --project-id demo-project \
  --graph-authority local-snapshot \
  --approval-mode prompt

Claude install example:

claude mcp add seojeom -- npx -y @seojeom/mcp-server \
  --project-root . \
  --project-id demo-project \
  --graph-authority local-snapshot \
  --approval-mode prompt

Standalone mode defaults --wiki-authority to local-filesystem, so wiki create/read/search tools operate on markdown files inside the selected project root.

When both local wiki authority and --graph-authority local-snapshot are enabled, seojeom_prepare_wiki_graph_buildout becomes the deterministic wiki-first entrypoint for missing-doc/buildout work. It reports orphan inventory, ready atomic-decompose targets, blocked pages that still need root binding, and the ordered phases that should run before graph packets are applied.

When --graph-authority local-snapshot is enabled, graph read tools load a canonical graph slice from one of:

• .seojeom/graph/canonical-slice.json
• .seojeom/canonical-graph-slice.json

Use --graph-slice-path <path> to point at an explicit snapshot file.

In the same local-snapshot mode, seojeom_propose_node, seojeom_propose_edge, seojeom_list_proposal_sets, seojeom_decide_proposal_set, and supported seojeom_apply_proposal_set flows operate on .seojeom/graph/proposal-sets.json and .seojeom/graph/canonical-slice.json without upstream API calls.

That same local mode also enables seojeom_list_graph_scenes, seojeom_get_default_graph_scene, seojeom_read_graph_scene, seojeom_create_graph_scene, and seojeom_save_graph_scene against .seojeom/graph/scenes.json.

seojeom_apply_graph_mutation also runs fully local in local-snapshot mode for direct node/edge editing, packet upserts, and timeline patching. Packet mutations are currently supported for node types that already have local packet descriptors (character, organization); unsupported node types return GRAPH_MUTATION_INVALID.

seojeom_build_graph_context is a read-only local helper that bundles nearby nodes, edges, packets, and a prompt-ready promptContext block around an optional focus node. It is meant to reduce Claude/Codex round trips before using the local proposal or mutation tools.

seojeom_analyze_graph_gaps is a read-only local tool that inspects the canonical snapshot for structural and snapshot-derived issues such as missing core node types, orphan nodes, weak character hubs, unresolved foreshadowing, missing state packets, and empty summaries. When local wiki authority is present and the focus node already owns a wiki page, it can also flag missing_atomic_coverage from wiki decomposition signals that come from headings, markdown tables, bullet lists, and consequence markers. That means character pages can suggest missing aggregate coverage (for example motivation/voice/behavior detail) and event pages can suggest missing event-causal atoms (for example beats, state deltas, or knowledge facts) even when the section heading itself is generic. It does not call LLM workflows; the intended flow is to let Claude/Codex read these findings and then use the existing local proposal or mutation tools directly.

seojeom_prepare_graph_workflow is a deterministic coordinator helper. It combines local graph context and local gap findings, then returns recommended next actions with preferred MCP tools and argument hints. That now includes aggregate-first repair hints for wiki-detected persona decomposition gaps, while keeping event-causal decomposition on the node/edge proposal path. It is intended to replace some of the “what should I call next?” work that the old web graph chat/review flow handled implicitly.

When local wiki authority is enabled too, seojeom_prepare_graph_workflow includes related local wiki page matches for the focus node and can recommend seojeom_write_wiki when graph entities are still undocumented in the local wiki.

seojeom_prepare_graph_research is a local-first research planner. It surfaces existing local wiki pages to read, suggests local wiki creation when documentation is missing, and only then prepares external search queries for researchable node types such as locations, organizations, items, and world rules.

seojeom_prepare_graph_runbook is a deterministic session helper built on top of the workflow and research tools. It returns an ordered step list with preferred MCP tools, argument hints, and stop conditions so Claude/Codex can follow one local-first sequence instead of deciding the choreography from scratch on every turn.

seojeom_prepare_graph_session is the Claude-facing contract helper on top of the runbook. It returns grounding rules, an ordered toolSequence, an operatorBrief, and a copyablePrompt so a local-first graph editing session can start with one deterministic packet instead of rebuilding the tool choreography by hand.

seojeom_prepare_graph_focused_session narrows that contract for common work modes. Today it supports wiki_documentation, packet_repair, relation_fill_in, and atomic_decomposition, so Claude/Codex can start from a smaller task-specific tool sequence instead of post-filtering the full session plan. The atomic_decomposition mode now keeps local wiki capture plus aggregate-first mutation and node/edge proposal steps in the same bounded packet.

seojeom_prepare_graph_playbook sits one level above focused sessions. It returns named presets such as document_entity, repair_state, fill_relations, research_document_then_link, and atomic_decomposition, with phased session blocks, approval checkpoints, verification steps, and a handoff prompt that is easier to paste into a Claude operator loop. The atomic_decomposition preset now starts with a dedicated Wiki-first Buildout Prep phase that runs seojeom_prepare_wiki_graph_buildout before any graph-side packet review, then resolves orphan/root-binding backlog if needed, and only then moves into graph packet work. When grouped packets exist after that, the remaining playbook phases split into primary_atomic_packets and followup_atomic_packets instead of flattening both into one generic phase. The returned approval checkpoints are packet-aware too: primary-node approval gates now explicitly block dependent follow-up edge packets, and follow-up edge approval gates now require the matching primary packet to be approved, applied, or intentionally deferred first. Verification steps are packet-aware as well, so the playbook explicitly checks that primary packets resolve before follow-up packets are treated as complete and that follow-up packets preserve the intended sequence, causality, or aftermath linkage. The handoff prompt is packet-aware too, telling operators to finish primary node packets and local grounding first, then run follow-up edge packets only after the matching primary packet is resolved. The phase summaryLine now carries the same split as a one-line read model, while operatorBrief and copyablePrompt repeat it in imperative form so the Claude/Codex operator can read the current packet responsibility without reconstructing it from the checklist or surrounding playbook prose.

seojeom_list_graph_playbooks is the lightweight discovery entrypoint for Claude. It lists the available playbook presets, explains when to use each one, and emits a starter prompt that tells Claude to call seojeom_prepare_graph_playbook with the right preset and focus node. The atomic_decomposition row now also carries a grouped-packet phase hint and a starter prompt reminder that primary node packets come before dependent follow-up edge packets once the playbook expands.

The same atomic workflow now has first-class MCP resource and prompt surfaces too. The server exposes a static seojeom://graph/schema/atomic-decomposition-policy resource, plus resource templates for seojeom://graph/gaps/{focusNodeId}, seojeom://graph/context/{focusNodeId}, and seojeom://wiki/atomic-decomposition-map/{pageRef}. Those resources let Claude/Codex pull deterministic schema, gap, context, and section-candidate data before choosing a mutation path. The atomic map now carries evidence modes too (heading, table, list, body) plus evidenceSummary, taxonomyHints, and recommendedTool, so downstream prompts can tell whether a candidate came from an explicit heading, a beat table, a consequence ledger, or body/list markers and then route straight to aggregate mutation or node-first proposal work. The current event taxonomy hints distinguish at least relationship_delta, inventory_delta, knowledge_marker, observation, and recognition subclasses. seojeom_prepare_graph_workflow now consumes those subtype hints too: event-focused missing_atomic_coverage findings no longer stop at one generic state_delta or knowledge_fact action. They can emit subtype-specific seojeom_propose_node packets such as relationship_delta, inventory_delta, observation, and recognition, each with dedicated argumentsHint payload shapes (relationshipDelta.*, inventoryDelta.*, observation.*, recognition.*). Those same packets now also carry subtype-aware followupEdgesHint rows, so downstream operators know which edge proposals should immediately follow node creation, for example caused_by + modifies for state deltas or acquired_at + knows_fact for knowledge facts. Beat packets now carry sequential edge guidance too when the wiki evidence came from a sequence table: contains_beat back to the parent event, before links around neighboring beats, and triggers links toward the downstream consequence atom. The workflow surface itself now groups those downstream edge packets explicitly as followupActionHints, and the runbook/session layers preserve that grouping as packetGroupId, packetRole, and packetLabel metadata. Focused sessions and playbooks can now tell operators when they are on a primary atomic node packet versus a dependent follow-up edge packet, instead of flattening everything into one undifferentiated proposal list. Claude/Codex no longer has to reconstruct either the node payload or the next edge choreography from freeform prompt text alone.

The prompt catalog also exposes atomic_decompose_wiki_page, decompose_character_page, decompose_event_page, and repair_atomic_coverage. These prompts are thin operator wrappers over the same local-first workflow: read the atomic policy/context/gap/map resources first, then call seojeom_prepare_graph_playbook with atomic_decomposition.

seojeom_get_claude_mcp_onboarding is the install/start entrypoint. It returns the exact claude mcp add command, the equivalent direct seojeom-mcp command, the recommended flags, and the first two MCP calls Claude should make after install. It now also exposes an install.summary line plus a recommendedFlagsHint, and that summary, the recommended-flags hint, the first-call catalog rationale, first-call selectionHint, second-call rationale, starter prompt, and command-line comment hints all point out that atomic_decomposition can expand into grouped primary_atomic_packets and followup_atomic_packets, so the operator sees that packet ordering before the first playbook call. The second onboarding call now defaults to atomic_decomposition when a focus node is present and still carries argumentsHintVariants, including both the explicit atomic_decomposition variant and a document_entity fallback variant for documentation-only cases. Without a focus node, the onboarding payload falls back to document-first selection/default hints, the starter prompt keeps the same document-first tone, install.summary does the same, and recommendedFlagsHint now keeps grouped atomic packet ordering conditional instead of presenting it as the default path.

Maintainer Release Verification

pnpm -C apps/desktop run smoke:mcp-server-release-prep
pnpm -C apps/desktop run smoke:mcp-server-release-verify
pnpm -C apps/desktop run smoke:mcp-server-release-verify-tarball-helper
pnpm -C apps/desktop run smoke:mcp-server-release-verify-published-helper
pnpm -C apps/desktop run smoke:mcp-server-release-verify-published-claude-helper
pnpm -C apps/desktop run smoke:mcp-server-release-powershell-helpers
pnpm -C apps/desktop run smoke:mcp-server-release-bundle-inspector
pnpm -C apps/desktop run smoke:mcp-server-release-bundle-portability
pnpm -C apps/desktop run smoke:mcp-server-release-publish-readiness-helper
pnpm -C apps/desktop run smoke:mcp-server-release-publish-helper
pnpm -C apps/desktop run smoke:mcp-server-release-complete-after-auth
pnpm -C apps/desktop run smoke:mcp-server-release-local-claude-self-check
pnpm -C apps/desktop run smoke:mcp-server-release-self-check
pnpm -C apps/desktop run smoke:mcp-server-release-postpublish-helper
pnpm -C apps/desktop run smoke:mcp-server-release-evidence-capture
pnpm -C apps/desktop run smoke:mcp-server-release-evidence-inspector
pnpm -C apps/desktop run smoke:mcp-server-package-tarball
pnpm -C apps/desktop run smoke:mcp-server-tarball-install

smoke:mcp-server-release-prep runs the release prep script end to end and verifies that it emits 00-START-HERE.md, release-manifest.json, release-notes.md, checksums.txt, publish-checklist.md, release-bundle-readme.md, plus bash and PowerShell helper scripts for publish and verification with the expected install commands, publish commands, tarball checksum, and portable relative-path helper content.

smoke:mcp-server-release-verify takes a generated release manifest, verifies the packed tarball source end to end, and then reruns the same verifier in --source published mode with mocked registry/onboarding overrides so the repo-side release verifier contract is covered without a real npm publish. It also locks the structured failure JSON returned for corrupted tarballs and malformed published onboarding payloads.

smoke:mcp-server-release-verify-tarball-helper moves the generated bundle and runs verify-tarball-release.sh --json, proving that the direct tarball verifier now supports structured success output after the bundle moves and returns structured failure JSON when the tarball is corrupted.

smoke:mcp-server-release-verify-published-helper moves the generated bundle and runs verify-published-release.sh --json with mocked registry/onboarding overrides, proving that the direct postpublish verifier can be executed from a moved bundle without touching the live npm registry and returns structured failure JSON when the onboarding payload is malformed.

smoke:mcp-server-release-verify-published-claude-helper moves the generated bundle and runs verify-published-claude-proof.sh --json with a tarball-backed npm exec --package override, proving that the postpublish Claude add/tool-call helper itself can execute from a moved bundle and returns structured failure JSON when the Claude CLI is unavailable.

smoke:mcp-server-release-powershell-helpers does the same coverage pass for *.ps1 helpers when pwsh or powershell is available. On non-PowerShell hosts it returns a structured skip result instead of failing the release smoke suite.

smoke:mcp-server-release-bundle-inspector moves the generated bundle and runs inspect-release-bundle.sh --json, proving that the bundle can self-report missing helpers, tarball/checksum integrity, and the next recommended command without relying on the repo checkout.

smoke:mcp-server-release-bundle-portability moves the generated release bundle to a different directory and runs verify-tarball-release.sh from there, proving that the helper scripts resolve the tarball relative to the bundle instead of relying on the original output path.

smoke:mcp-server-release-publish-readiness-helper moves the generated bundle and runs inspect-publish-readiness.sh --json, proving that the bundle can distinguish registry reachability, npm auth state, and version collision before the actual publish attempt. It also locks the structured failureStep: "npm-auth" and recommendedCommand: "npm adduser" path used on unauthenticated hosts.

smoke:mcp-server-release-publish-helper moves the generated bundle and runs publish-release.sh --dry-run --json, proving that the publish helper accepts extra npm flags and still resolves the tarball relative to the moved bundle.

smoke:mcp-server-release-complete-after-auth moves the generated bundle and runs complete-release-after-auth.sh --json with auth-ready and published-package override seams, proving that the post-auth one-shot path can execute inspect-publish-readiness -> prepublish-self-check -> publish-release --dry-run -> postpublish-self-check -> refresh-release-status from a moved bundle and end with a green status payload.

smoke:mcp-server-release-local-claude-self-check moves the generated bundle and runs local-claude-self-check.sh --json, proving that the one-shot local Claude proof entrypoint now runs bundle inspection before delegating to verify-local-claude-proof and still returns one structured payload after the bundle has moved.

smoke:mcp-server-release-evidence-capture moves the generated bundle and runs capture-release-evidence.sh --json, proving that the bundle can write a shareable evidence/ directory with summary.json, SUMMARY.md, raw helper outputs, the expected prepublish failure steps, and the tarball-backed postpublish Claude proof in one pass after the bundle has moved.

smoke:mcp-server-release-status-refresh moves the generated bundle and runs refresh-release-status.sh --json, proving that the bundle can recapture the latest evidence, reopen it immediately, summarize the diagnosis, and surface both the next command and the followup command in one pass after the bundle has moved.

smoke:mcp-server-release-evidence-inspector moves the generated bundle, captures a fresh evidence pack, then runs inspect-release-evidence.sh --json, proving that the bundle can reopen evidence/LATEST.json, surface the current blocking step, summarize the diagnosis, and point the operator at the next command without manually browsing the timestamped evidence directory.

smoke:mcp-server-release-self-check moves the generated bundle and runs prepublish-self-check.sh --json, proving that the one-shot prepublish entrypoint now runs bundle inspection, publish readiness inspection, tarball verification, and publish dry-run in sequence after the bundle has moved and returns one structured JSON envelope.

smoke:mcp-server-release-postpublish-helper moves the generated bundle and runs postpublish-self-check.sh --json with mocked registry/onboarding overrides plus the tarball-backed published-Claude override seam, proving that the one-shot postpublish entrypoint now runs bundle inspection before delegating to both verify-published-release and verify-published-claude-proof and still returns one structured payload after the bundle has moved.

smoke:mcp-server-package-tarball checks that npm pack emits the expected scoped tarball and that the published package includes runtime files (dist, bin, README.md, server.json) while excluding src and tsconfig inputs.

smoke:mcp-server-registry-submission-prep builds a local MCP Registry submission packet from package.json, registry-server.json, and the release workflow, then verifies that the expected registry path, copied registry-format server.json, and human-readable summary all line up before an actual registry PR is opened.

smoke:mcp-server-github-publication-prep builds a local public-repo publication packet from package metadata and the release workflow, then verifies that the repo guard, required file set, and human-readable publication summary all line up before the public seojeom/seojeom-mcp repository is made reachable.

smoke:mcp-server-public-launch-handoff combines the release bundle, GitHub publication packet, and registry submission packet into one operator-facing handoff JSON/markdown pair so the remaining external blockers can be handed to the next session without reopening multiple artifacts by hand.

The install smoke goes one step further: it installs the packed tarball into a temporary project, runs the installed seojeom-mcp bin, and verifies that onboarding and server.json metadata still work from the packed artifact.

Maintainer Release Prep

pnpm -C apps/desktop run release:prepare-mcp-server-package -- \
  --output-dir artifacts/mcp-server-release \
  --project-root /path/to/project

Because this command runs inside the apps/desktop package, the example above writes to apps/desktop/artifacts/mcp-server-release from the repo root. Use an absolute --output-dir if you want the bundle somewhere else.

This writes a versioned tarball plus 00-START-HERE.md, release-manifest.json, release-notes.md, checksums.txt, publish-checklist.md, release-bundle-readme.md, inspect-release-bundle.{sh,ps1}, inspect-publish-readiness.{sh,ps1}, verify-local-claude-proof.{sh,ps1}, local-claude-self-check.{sh,ps1}, capture-release-evidence.{sh,ps1}, refresh-release-status.{sh,ps1}, inspect-release-evidence.{sh,ps1}, prepublish-self-check.{sh,ps1}, publish-release.{sh,ps1}, complete-release-after-auth.{sh,ps1}, verify-tarball-release.{sh,ps1}, verify-published-release.{sh,ps1}, verify-published-claude-proof.{sh,ps1}, and postpublish-self-check.{sh,ps1} into the selected output directory so the publish command, registry verification, Claude install snippet, release checksum, and bundle self-inspection entrypoint are ready before publish on both shell and PowerShell environments. The helper scripts resolve the tarball relative to their own directory, so the whole bundle can be moved before use.

Recommended bundle order for newly generated bundles:

1. Open RELEASE-NEXT-STEP.md or release-next-step.json
2. ./inspect-release-bundle.sh --json
3. ./local-claude-self-check.sh --json --project-root <path>
4. ./capture-release-evidence.sh --json --project-root <path>
5. ./refresh-release-status.sh --json --project-root <path>
6. ./inspect-release-evidence.sh --json
7. ./inspect-publish-readiness.sh --json
8. ./prepublish-self-check.sh --json
9. ./complete-release-after-auth.sh --json --project-root <path> --project-id demo-project
10. ./publish-release.sh
11. ./postpublish-self-check.sh --json --project-root <path> --project-id demo-project
12. ./verify-published-claude-proof.sh --json --project-root <path>

Steps 10-12 are the stepwise path. If you use step 9, it already composes the publish and postpublish checks and then refreshes the stable status files.

If you only want the direct Claude tarball proof without the outer bundle inspection step, ./verify-local-claude-proof.sh --json --project-root <path> remains available.

On an unauthenticated host, inspect-publish-readiness --json is expected to stop with failureStep: "npm-auth" and recommendedCommand: "npm adduser". In that state, prepublish-self-check --json also stops early at failureStep: "inspect-publish-readiness" instead of continuing to the tarball verify and publish dry-run steps.

If npm auth is already present but the target version is already in the registry, inspect-publish-readiness --json stops with failureStep: "version-already-published" and recommendedCommand: "npm version patch". In that case, bump the package version first and then regenerate the bundle with pnpm -C apps/desktop run release:prepare-mcp-server-package -- --output-dir artifacts/mcp-server-release --project-root <path> before rerunning the publish flow.

Current actual operator state on this machine:

• @seojeom/[email protected] is published
• the last published postpublish proof still points at verifyPublished.registryVersion = 0.2.3
• the current local release-candidate bundle is 0.2.4
• inspect-publish-readiness.sh --json succeeded for the 0.2.4 bundle
• prepublish-self-check.sh --json succeeded for the 0.2.4 bundle
• local-claude-self-check.sh --json succeeded for the 0.2.4 bundle
• the next release-candidate action from this exact bundle is:
  • npm publish "/mnt/c/ainovel/apps/desktop/artifacts/mcp-server-release-prepublish-0.2.4/seojeom-mcp-server-0.2.4.tgz" --access public
• the next public-launch action from the same bundle is:
  • ./postpublish-self-check.sh --json --project-root /mnt/c/ainovel --project-id demo-project
  • then ./verify-published-claude-proof.sh --json --project-root /mnt/c/ainovel

After npm adduser succeeds, the preferred one-shot path is:

./apps/desktop/artifacts/mcp-server-release/complete-release-after-auth.sh --json \
  --project-root /path/to/project \
  --project-id demo-project

This helper composes inspect-publish-readiness, prepublish-self-check, publish-release, postpublish-self-check, and refresh-release-status. For operator dry-run proof without a live publish, set SEOJEOM_RELEASE_COMPLETE_AFTER_AUTH_PUBLISH_DRY_RUN=1 before calling it.

Local Claude proof before publish:

./apps/desktop/artifacts/mcp-server-release/local-claude-self-check.sh --json \
  --project-root /path/to/project \
  --project-id demo-project

This is the preferred one-shot bundle entrypoint. It runs inspect-release-bundle first, then delegates to verify-local-claude-proof, and returns a single structured JSON payload with both inspectBundle and verifyLocalClaude.

If you want to capture the whole current operator state into files under evidence/, use:

./apps/desktop/artifacts/mcp-server-release/capture-release-evidence.sh --json \
  --project-root /path/to/project \
  --project-id demo-project

This helper always writes summary.json, SUMMARY.md, and one JSON file per executed helper. It keeps going even when publish readiness or prepublish checks fail, so the evidence pack still records the current blocker. It also refreshes stable pointers at evidence/LATEST.json, evidence/LATEST.md, and evidence/latest-path.txt, so the next session can read the latest pack without looking up the timestamped directory first.

The evidence summary now records provenance too. executionMode is live when no helper override seams were used, and simulated when readiness/postpublish/published-Claude overrides or publish dry-run seams were active. simulationMarkers explains which seams were active.

If you want the freshest status in one shot after an environment change like npm adduser, use:

./apps/desktop/artifacts/mcp-server-release/refresh-release-status.sh --json \
  --project-root /path/to/project \
  --project-id demo-project

This helper runs capture-release-evidence first, then reopens the new LATEST.json through inspect-release-evidence, so the result includes diagnosis, recommendedCommand, and followupCommand without making you run two helpers by hand.

It also writes stable bundle-root status files at release-status.json and RELEASE-STATUS.md, so the latest operator state is available without opening the timestamped evidence/ directory.

Those stable status files now include executionMode and simulationMarkers too, so an override-backed green dry-run is distinguishable from a real live-ready run.

Mode-specific copies are written too:

• ./apps/desktop/artifacts/mcp-server-release/release-status-live.json
• ./apps/desktop/artifacts/mcp-server-release/RELEASE-STATUS-live.md
• ./apps/desktop/artifacts/mcp-server-release/release-status-simulated.json
• ./apps/desktop/artifacts/mcp-server-release/RELEASE-STATUS-simulated.md

The mode compare helper also writes stable bundle-root compare files:

• ./apps/desktop/artifacts/mcp-server-release/release-status-compare.json
• ./apps/desktop/artifacts/mcp-server-release/RELEASE-STATUS-COMPARE.md

And refresh also writes a single operator-facing next-step pair:

• ./apps/desktop/artifacts/mcp-server-release/release-next-step.json
• ./apps/desktop/artifacts/mcp-server-release/RELEASE-NEXT-STEP.md

Use the generic release-status.* pair for "what happened last" and the mode-specific files when you need the latest live blocker and the latest simulated dry-run proof side by side.

To reopen the latest captured state without browsing the timestamped directory, use:

./apps/desktop/artifacts/mcp-server-release/inspect-release-evidence.sh --json

This helper reads evidence/LATEST.json, reports the current blockingStep, includes executionMode plus any simulationMarkers, adds a short diagnosis, and surfaces both the immediate recommendedCommand and the next followupCommand.

If you want the same latest status in stable files, read:

• ./apps/desktop/artifacts/mcp-server-release/release-status.json
• ./apps/desktop/artifacts/mcp-server-release/RELEASE-STATUS.md

If you want the latest captured evidence for a specific mode, use:

./apps/desktop/artifacts/mcp-server-release/inspect-release-evidence.sh --json --mode live
./apps/desktop/artifacts/mcp-server-release/inspect-release-evidence.sh --json --mode simulated

Those reopen evidence/LATEST-live.json or evidence/LATEST-simulated.json directly.

If you want the latest live blocker and the latest simulated dry-run proof in one response, use:

./apps/desktop/artifacts/mcp-server-release/inspect-release-status-modes.sh --json

This helper reads release-status-live.json and release-status-simulated.json together, compares them against the current tarball SHA in release-manifest.json, and reports one of four operator states:

• live_blocked_simulated_ready
• live_ready_simulated_ready
• live_ready_simulated_blocked
• stale_status_files

It reports one of those four states based on what the bundle actually saw. If the bundle was regenerated after the last status capture, it switches to comparisonState=stale_status_files. When the stale side is just the simulated status and the current live blocker is version-already-published, the helper now points at npm version patch and rebundling instead of blindly rerunning complete-release-after-auth.

The generic release-status.json / RELEASE-STATUS.md pair carries the same compare summary:

• compareStatus.comparisonState
• compareJsonPath = ./apps/desktop/artifacts/mcp-server-release/release-status-compare.json
• compareMarkdownPath = ./apps/desktop/artifacts/mcp-server-release/RELEASE-STATUS-COMPARE.md

If you only want the current operator action without reopening status and compare separately, open:

• ./apps/desktop/artifacts/mcp-server-release/release-next-step.json
• ./apps/desktop/artifacts/mcp-server-release/RELEASE-NEXT-STEP.md

These files carry the currently recommended command, followup command, compare state, and the stable status/compare file paths.

Newly generated 00-START-HERE.md and release-bundle-readme.md point at this pair first, so the operator can start from one stable bundle-root file instead of choosing between status, compare, and evidence helpers manually.

If you want the direct helper only, use:

./apps/desktop/artifacts/mcp-server-release/verify-local-claude-proof.sh --json \
  --project-root /path/to/project \
  --project-id demo-project

Or use the repo-side verifier:

pnpm -C apps/desktop run verify:mcp-server-local-claude-proof -- \
  --tarball artifacts/mcp-server-release/seojeom-mcp-server-<version>.tgz \
  --project-root /path/to/project \
  --project-id demo-project

Replace <version> with the actual tarball version in artifacts/mcp-server-release/release-manifest.json.

This verifier installs the local tarball into a temp directory, adds a unique local-scope Claude MCP alias, calls seojeom_get_claude_mcp_onboarding, validates the returned packageName and firstToolName, then removes the alias again. It does not prove the published npx -y @seojeom/mcp-server path yet, but it does prove that the packed tarball can be installed into Claude, connected as an MCP server, and used for a first tool call before publish.

Post-publish verification:

pnpm -C apps/desktop run verify:mcp-server-release -- \
  --manifest artifacts/mcp-server-release/release-manifest.json \
  --source published \
  --project-root /path/to/project

Because this command also runs inside the apps/desktop package, use artifacts/mcp-server-release/release-manifest.json relative to that package, or pass an absolute manifest path from the repo root.

Use --source tarball to verify the packed artifact before publish. Use --source published after npm publish to confirm that the registry version matches the manifest and that the published package still answers --print-claude-onboarding-json.

Published Claude proof after publish:

./apps/desktop/artifacts/mcp-server-release/verify-published-claude-proof.sh --json \
  --project-root /path/to/project \
  --project-id demo-project

By default this helper runs the real published-path contract, claude mcp add ... -- npx -y @seojeom/mcp-server@<version> ... (using the version from release-manifest.json), then calls seojeom_get_claude_mcp_onboarding, validates packageName and firstToolName, and removes the temporary local alias again. For smoke or pre-publish contract checks, SEOJEOM_RELEASE_VERIFY_PUBLISHED_CLAUDE_PACKAGE_SPEC and SEOJEOM_RELEASE_VERIFY_PUBLISHED_CLAUDE_LAUNCH_MODE=npm-exec-package can redirect the helper to a tarball-backed npm exec --package path without changing the published default behavior.

One-shot postpublish verification can also include the published Claude proof directly:

# Replace <version> with the actual release version (check package.json or release-manifest.json).
# Replace /path/to/project with your project-root.
VERSION="<version>"
PROJECT_ROOT="/path/to/project"

SEOJEOM_RELEASE_POSTPUBLISH_REGISTRY_VERSION="$VERSION" \
SEOJEOM_RELEASE_POSTPUBLISH_ONBOARDING_JSON="{\"ok\":true,\"install\":{\"packageName\":\"@seojeom/mcp-server\",\"claudeMcpAddCommand\":\"claude mcp add seojeom -- npx -y @seojeom/mcp-server@${VERSION} --project-root ${PROJECT_ROOT} --project-id demo-project --graph-authority local-snapshot --approval-mode prompt\"},\"firstCalls\":[{\"toolName\":\"seojeom_list_graph_playbooks\"}]}" \
SEOJEOM_RELEASE_VERIFY_PUBLISHED_CLAUDE_PACKAGE_SPEC="${PROJECT_ROOT}/apps/desktop/artifacts/mcp-server-release/seojeom-mcp-server-${VERSION}.tgz" \
SEOJEOM_RELEASE_VERIFY_PUBLISHED_CLAUDE_LAUNCH_MODE=npm-exec-package \
./apps/desktop/artifacts/mcp-server-release/postpublish-self-check.sh --json \
  --project-root "${PROJECT_ROOT}" \
  --project-id demo-project

In that mode the helper returns one JSON envelope containing inspectBundle, verifyPublished, and verifyPublishedClaude.

Recommended Claude startup loop:

1. Call seojeom_get_claude_mcp_onboarding.
2. Run the returned claude mcp add command if the server is not installed yet.
3. Call seojeom_list_graph_playbooks with an optional focusNodeId.
4. Pick the preset that matches the current task.
5. Call seojeom_prepare_graph_playbook.
6. Follow the returned handoffPrompt, approvalCheckpoints, and verificationSteps.

--api-base-url is still used whenever a tool stays on api-bridge, and it remains the fallback path for unsupported graph apply flows.

--approval-mode:

• prompt: open a controlling-terminal prompt for mutating tools
• always: auto-approve mutating tools
• never: deny mutating tools

Desktop sidecar usage

node dist/index.js \
  --project-root . \
  --project-id demo-project \
  --port 0 \
  --api-base-url http://127.0.0.1:3000 \
  --api-header-name x-seojeom-desktop-bridge \
  --api-header-value <token>

The desktop path remains the authority for launcher approval queue and loopback HTTP registration. It still defaults wiki and graph operations to api-bridge, although --wiki-authority local-filesystem and --graph-authority local-snapshot are available for desktop-local experiments.