keisei/KeiSeiKit-1.0
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
KeiSeiKit-1.0/PLUGIN.md
Parfii-bot a5ef8963c7 feat(mcp-server): production-ready publish path via GitHub Packages 
Renamed @keisei/mcp-server → @keisei84/mcp-server (scope must match
github org KeiSei84 for GitHub Packages publish). Replaced private:true
with publishConfig pinned to npm.pkg.github.com so an accidental
`npm publish` cannot leak to npm.org. CI npm-publish job rewired to
GitHub Packages auth (GITHUB_TOKEN with packages:write permission).

Why GitHub Packages, not npm.org:
- Authentication piggybacks on existing github org / PAT — no separate
  account or NPM_TOKEN required for the core kit
- Scope @keisei84 maps 1:1 to org KeiSei84 (npm rule for github)
- Doesn't require public DNS for our private Forgejo (Tailscale-only
  100.91.246.53 cannot be the publish target — IP-leak in public ref)
- Published artefacts live under github.com/orgs/KeiSei84/packages,
  same access surface as the source repo

Why not @keisei (un-scoped or different scope):
- npm scope @keisei IS reachable on npm.org but we don't own it there
  (would require email-verified npm account claim + ongoing maintenance)
- @keisei84 requires zero new accounts; works the moment KeiSei84 org
  has packages enabled (github default)

Files changed (11):
- _ts_packages/packages/mcp-server/package.json — rename + publishConfig
  + repository field (required by GitHub Packages); removed private:true
- _ts_packages/package-lock.json — regenerated via `npm install`
  (workspace recognises @keisei84/mcp-server symlink)
- README.md (2 hunks) — maturity row says "alpha" not
  "alpha (unpublished)"; install section documents `~/.npmrc` setup
  for `@keisei84:registry=https://npm.pkg.github.com/`
- PLUGIN.md (3 hunks) — same `~/.npmrc` setup; .mcp.json references
  @keisei84/mcp-server; "not yet on npm" replaced with "lives on
  GitHub Packages, not npm.org"
- .claude-plugin/mcp-template.json — args use @keisei84 scope
- _ts_packages/README.md (4 hunks) — package layout + npx examples
- docs/INSTALL.md, install/lib-rust.sh — comment refs
- docs/encyclopedia/substrate-overview.md (2 hunks) — package table +
  publishing notes (was "published to keigit.com npm" — wrong; keigit
  is a separate community-publish path for user-contributed packages,
  not the destination for core @keisei84 packages)
- .github/workflows/release.yml — npm-publish job rebuilt:
  · permissions: packages:write
  · Two-scope .npmrc temp-write: @keisei84 → npm.pkg.github.com (always),
    @keisei → npm.org (only if NPM_TOKEN secret set, else skipped per pkg)
  · NODE_AUTH_TOKEN sourced from GITHUB_TOKEN
  · .npmrc cleaned up via `if: always()` step
- .gitignore — _ts_packages/.npmrc + .npmrc excluded (RULE 0.8: auth
  tokens never in git; CI temp-creates per-job)

Verification:
- `npm install` clean against new scope: node_modules/@keisei84/mcp-server
  symlinks to packages/mcp-server, other adapters untouched in
  node_modules/@keisei/* [REAL: install ran 2026-05-03 in this session]
- `npm run build --workspace=@keisei84/mcp-server` produces dist/index.js
  [REAL: tsc -b exit 0]
- Server starts cleanly: `node dist/index.js` runs >1s, emits expected
  "[adapters] not installed" warnings for un-built sibling adapters,
  doesn't throw
- 17 references to old @keisei/mcp-server scope migrated; 0 left
  [REAL: grep -rn "@keisei/mcp-server" returns 0 lines]

Bad-commit-hygiene note:
- Two earlier local commits (cb8dc2a + revert 474fe1c) attempted a
  keigit.com-pinned variant; soft-reset past them so this commit lands
  on top of public 368df5b. Bad commits never reached remote.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-03 17:50:59 +08:00

5.4 KiB
Raw Blame History

KeiSeiKit — Anthropic Claude Code plugin format

This document describes the plugin-format install path (v0.16+) and how it relates to the classic ./install.sh path. Both paths are supported; use whichever fits.

TL;DR

# One-time
/plugin marketplace add KeiSei84/KeiSeiKit
# Install
/plugin install keisei@keisei-marketplace

The plugin auto-registers: agents, skills, hooks, and the MCP server. No manual ~/.claude/settings.json edits. No install.sh needed for the core (non-primitive) experience.

Layout

The repo follows the Anthropic Claude Code plugin spec:

.claude-plugin/
  plugin.json          # plugin manifest (name, version, author, license, keywords)
  marketplace.json     # marketplace manifest — lets this repo serve as a marketplace source
  mcp-template.json    # template for .mcp.json (copy to repo root; see "MCP prerequisite" below)
agents/                # auto-discovered by Claude Code at plugin-install time
skills/<name>/SKILL.md # auto-discovered
hooks/hooks.json       # PreToolUse / PostToolUse / Stop hooks with ${CLAUDE_PLUGIN_ROOT} paths
.mcp.json              # MCP server registration (see prerequisite note)

Paths inside hooks/hooks.json use ${CLAUDE_PLUGIN_ROOT} (expanded by Claude Code at runtime to the plugin install directory) rather than absolute $HOME/.claude/hooks/... paths. This lets the same hooks ship unchanged whether the plugin is installed from GitHub, npm, or a local path.

Plugin install vs classic install — what differs

Feature Plugin install Classic ./install.sh
Agents registered yes, automatic yes, copied to ~/.claude/agents/
Skills registered yes, automatic yes, copied to ~/.claude/skills/
Hooks wired yes, via hooks/hooks.json requires --activate-hooks (jq-merge of settings-snippet.json)
MCP server yes, via .mcp.json (uses @keisei84/mcp-server from GitHub Packages — requires ~/.npmrc setup, see below) same
47 Rust primitives no — plugin ships manifest sources only; no cargo build yes, --profile=<name> builds the selected set
13 shell primitives no yes, copied to ~/.claude/agents/_primitives/
Disk footprint ~2 MB (plugin cache) ~2 MB minimal up to ~200 MB full
Update path /plugin update keisei git pull && ./install.sh
Update visibility Claude Code shows version change silent

Bottom line: plugin install is the right default for the agent-kit experience (agents + skills + hooks). For the Rust primitives (tomd, kei-ledger, provision-hetzner, kei-migrate, etc.), fall back to the classic installer or run it alongside the plugin — the two don't collide because the plugin namespaces into its own install dir and the classic installer writes to ~/.claude/.

Prerequisites

For plugin install:

  • Claude Code 2.1+ (check with claude --version)
  • Network access to github.com/KeiSei84/KeiSeiKit on /plugin marketplace add

For the MCP server subset:

  • @keisei84/mcp-server available from GitHub Packages (https://npm.pkg.github.com/). One-time ~/.npmrc setup: 
    @keisei84:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=<github PAT with read:packages>
    Without the ~/.npmrc rows, npx cannot resolve the scoped package and the keisei MCP server simply won't appear in your tool list — the agents, skills, and hooks all work without it.
  • Node.js 18+ (for npx to fetch the server on demand)

For the Rust primitives (classic install only):

  • Rust stable, jq, plus the soft-deps listed in the main README per-profile table.

Known limitations

  1. Rust primitives not auto-installed. The plugin format doesn't currently express "also run cargo build at install time". We ship the manifest sources in-repo so that users who want the primitives can run ./install.sh --profile=full alongside the plugin. A future version may add pre-built release binaries for common platforms (macOS arm64/x86_64, Linux x86_64) into bin/ so the plugin can ship primitives without a cargo step.
  2. @keisei84/mcp-server lives on GitHub Packages, not npm.org. The .mcp.json entry uses npx -y @keisei84/mcp-server which resolves through the ~/.npmrc @keisei84:registry line above. Without that line, npx will hit npm.org by default and 404. See _ts_packages/packages/mcp-server/README.md for the publish pipeline.
  3. Hooks use ${CLAUDE_PLUGIN_ROOT}. This is the official Claude Code plugin variable. Older Claude Code versions (<2.1) that predate plugin support will not expand this variable — stick with classic install on those versions.
  4. No version-pinning yet. /plugin install keisei@keisei-marketplace installs the default branch HEAD. For reproducible team installs, add the --ref=<tag> flag once it lands in Claude Code (currently in the spec per the extension schema ref field).

Feedback & bugs

Open an issue at github.com/KeiSei84/KeiSeiKit/issues. A well-formed problem description is already half the solution.

References

  • Anthropic Claude Code plugins docs
  • README.md — main install guide (plugin section is the new default)
  • settings-snippet.json — retained for classic install; the plugin path does not use it
  • install.sh --help — classic installer options, now with a plugin-first banner