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>
This commit is contained in:
Parfii-bot 2026-05-03 17:50:59 +08:00
parent 368df5b918
commit a5ef8963c7
11 changed files with 104 additions and 2290 deletions

View file

@ -1,9 +1,9 @@
{
"_comment": "Template for .mcp.json. Copy to repo root as .mcp.json to register the KeiSei MCP server. Requires @keisei/mcp-server published to npm (status: not yet published — see PLUGIN.md).",
"_comment": "Template for .mcp.json. Copy to repo root as .mcp.json to register the KeiSei MCP server. The @keisei84/mcp-server package is published to GitHub Packages (npm.pkg.github.com) — one-time ~/.npmrc setup required: '@keisei84:registry=https://npm.pkg.github.com/' + '//npm.pkg.github.com/:_authToken=<github PAT with read:packages>'. See PLUGIN.md.",
"mcpServers": {
"keisei": {
"command": "npx",
"args": ["-y", "@keisei/mcp-server", "--stdio"]
"args": ["-y", "@keisei84/mcp-server", "--stdio"]
}
}
}

View file

@ -290,55 +290,70 @@ jobs:
echo "✓ Release $TAG published with all assets"
npm-publish:
name: Publish npm packages (optional)
name: Publish npm packages
needs: release
runs-on: ubuntu-latest
# Graceful skip: if NPM_TOKEN secret is not configured, the first step
# reports "skipped" and exits 0 — Rust-binary release above still succeeds.
permissions:
contents: read
packages: write # required for github packages publish (GITHUB_TOKEN)
steps:
- name: Check NPM_TOKEN presence
id: have_token
env:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
run: |
if [ -n "${NPM_TOKEN:-}" ]; then
echo "present=1" >> "$GITHUB_OUTPUT"
else
echo "present=0" >> "$GITHUB_OUTPUT"
echo "::notice::NPM_TOKEN not set — skipping npm publish gracefully"
fi
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
if: steps.have_token.outputs.present == '1'
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
if: steps.have_token.outputs.present == '1'
with:
node-version: '20'
registry-url: 'https://registry.npmjs.org'
# Two-scope .npmrc: @keisei84/* → GitHub Packages (always available
# via GITHUB_TOKEN), @keisei/* → npm.org (only if NPM_TOKEN secret
# set; line is omitted otherwise so that publish gracefully skips
# those packages instead of failing the whole job).
- name: Compose .npmrc (multi-scope auth)
working-directory: _ts_packages
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
run: |
set -euo pipefail
{
echo "@keisei84:registry=https://npm.pkg.github.com/"
echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}"
if [ -n "${NPM_TOKEN:-}" ]; then
echo "@keisei:registry=https://registry.npmjs.org/"
echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}"
fi
} > .npmrc
# Sanity (no secrets in log — print only registry lines):
grep -v _authToken .npmrc
- name: Install deps
if: steps.have_token.outputs.present == '1'
working-directory: _ts_packages
run: npm ci
- name: Build workspaces
if: steps.have_token.outputs.present == '1'
working-directory: _ts_packages
run: npm run build --workspaces --if-present
- name: Publish each package
if: steps.have_token.outputs.present == '1'
working-directory: _ts_packages
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
set -euo pipefail
# Each package's publishConfig.registry decides the destination
# (GitHub Packages for @keisei84/*, npm.org for @keisei/*).
# Packages without an active token in .npmrc will fail and we
# emit a ::warning so the job stays green for the ones that do.
for pkg in packages/*/; do
if [ -f "$pkg/package.json" ]; then
echo "::group::publish $pkg"
name=$(node -p "require('./$pkg/package.json').name")
echo "::group::publish $name"
( cd "$pkg" && npm publish --access public ) \
|| echo "::warning::publish failed for $pkg (continuing)"
|| echo "::warning::publish failed for $name (missing token, version conflict, or registry error — see log)"
echo "::endgroup::"
fi
done
- name: Cleanup .npmrc
if: always()
working-directory: _ts_packages
run: rm -f .npmrc

4
.gitignore vendored
View file

@ -62,3 +62,7 @@ build/
__pycache__/
*.pyc
var/
# RULE 0.8 — auth tokens; CI temp-creates _ts_packages/.npmrc per-job
_ts_packages/.npmrc
.npmrc

View file

@ -37,7 +37,7 @@ Paths inside `hooks/hooks.json` use `${CLAUDE_PLUGIN_ROOT}` (expanded by Claude
| 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` (once `@keisei/mcp-server` is published) | same |
| 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 |
@ -53,7 +53,15 @@ Paths inside `hooks/hooks.json` use `${CLAUDE_PLUGIN_ROOT}` (expanded by Claude
- Network access to `github.com/KeiSei84/KeiSeiKit` on `/plugin marketplace add`
**For the MCP server subset:**
- `@keisei/mcp-server` published to npm — **STATUS: not yet published as of v0.16.0.** The `.mcp.json` entry is structurally correct and will activate automatically once the package is published. Until then, the `keisei` MCP server simply won't appear in your tool list — the agents, skills, and hooks all work without it.
- `@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):**
@ -62,7 +70,7 @@ Paths inside `hooks/hooks.json` use `${CLAUDE_PLUGIN_ROOT}` (expanded by Claude
## 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. **`@keisei/mcp-server` not yet on npm.** The `.mcp.json` entry is the canonical intent, but the package needs publishing first. See `_ts_packages/packages/mcp-server/README.md` for the publish pipeline.
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).

View file

@ -23,7 +23,7 @@ production work.
|---|---|---|
| 24+ Rust primitives | varies (alpha → beta → concept) | Inspect each crate's `Cargo.toml` `package.metadata.keisei.maturity` if declared; otherwise treat as **alpha** unless you've personally exercised it. Most primitives are alpha — they build, type-check, and have unit tests, but have not been hardened against adversarial input or run at scale. |
| Cortex daemon (`kei-cortex` HTTP + WS) | alpha | CLI-driven daemon works in author's daily use; HTTP REST + WS endpoints + 8-tool `/chat` agentic loop build clean. **Browser app (`cortex-ui`) and VSCode extension (`@keisei/vscode-cortex`) are concept-level** — scaffolds present, not production paths. |
| MCP server (`@keisei/mcp-server`) | alpha (unpublished) | **Not yet on npm.** Install via local dist build (see Quick start below). |
| MCP server (`@keisei84/mcp-server`) | alpha | Published to **GitHub Packages** (`https://npm.pkg.github.com/`) under the `@keisei84` scope (matches the github org `KeiSei84`). Configure your `~/.npmrc` per [`docs/PUBLISHING.md`](./docs/PUBLISHING.md), then `npm install @keisei84/mcp-server`. Local dist build still works for development (see Quick start). |
| Sleep layer (Phase A / B / C) | alpha | Phase A queue (`/sleep-on-it` → cloud agent) + Phase B markdown morning report work. **Auto-codification of rules from sleep insights is not yet wired** — codification path is manual via `/escalate-recurrence`. Phase C deep-sleep refactor proposals run on a 7-day cadence and write plan-only markdown by default. |
| Hooks (35 shipped) | beta | Tested in author's daily use (48 parallel Claude Code terminals). Pipeline hooks (`assemble-agents`, `no-hand-edit-agents`) are load-bearing; advisory hooks (RULE 0.12 / 0.13 / 0.14) are non-blocking. |
| Skills + manifests + assembler | beta | Structured + `assembler-validate` gate runs on every `git commit` inside `~/.claude`. Schema is locked (see [`docs/AGENT-SCHEMA-LOCKED.md`](./docs/AGENT-SCHEMA-LOCKED.md)). |
@ -123,19 +123,27 @@ outputs are human-readable markdown. You read, you decide what merges.
extension (`@keisei/vscode-cortex`) are concept-level only** —
scaffolds exist, no production wiring. Treat the daemon + CLI as
the supported surface; treat the GUI frontends as roadmap.
- **`@keisei/mcp-server` npm package** — **not yet published to npm.**
Install via the local dist build:
- **`@keisei84/mcp-server` npm package** — published via **GitHub
Packages**. To install from the registry:
```bash
# ~/.npmrc — one-time setup
echo "@keisei84:registry=https://npm.pkg.github.com/" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=<your-github-pat>" >> ~/.npmrc
# PAT scope: read:packages (write:packages only if you publish)
npm install @keisei84/mcp-server
```
For local development without the registry round-trip:
```bash
cd _ts_packages
bun install # or: npm install
bun run -r build # or: npm run -r build
# mcp-server output lands in _ts_packages/packages/mcp-server/dist/
bun install && bun run -r build
# output: _ts_packages/packages/mcp-server/dist/index.js
```
Then point your MCP-aware client at the local `dist/` entry point.
Single-binary builds via `bun build --compile` are documented in
[`_ts_packages/packages/mcp-server/BUILD.md`](./_ts_packages/packages/mcp-server/BUILD.md)
(5-target matrix, ~8595 MB per binary). Do not assume npm-registry
install will work until v1.0.
(5-target matrix, ~8595 MB per binary). `package.json` has
`publishConfig.registry` pinned to `npm.pkg.github.com` so an
accidental `npm publish` from this repo cannot route to npm.org.
- **Non-Claude clients** integrate via MCP + bridges, not native hooks.
PreToolUse / PostToolUse / UserPromptSubmit / Stop semantics are
Claude Code primitives. Other clients get capability exposure but

View file

@ -26,7 +26,7 @@ _ts_packages/
├── package.json npm workspace root
├── tsconfig.base.json strict TS 5.x
└── packages/
├── mcp-server/ @keisei/mcp-server
├── mcp-server/ @keisei84/mcp-server
├── telegram-adapter/ @keisei/telegram-adapter
├── recall-adapter/ @keisei/recall-adapter (Zoom via Recall.ai)
├── grok-adapter/ @keisei/grok-adapter (xAI)
@ -77,20 +77,20 @@ All are read via `process.env`. Hardcoding tokens is **forbidden** (RULE 0.8).
## MCP server integration
The `@keisei/mcp-server` exposes the Rust primitive CLIs as MCP tools. The
The `@keisei84/mcp-server` exposes the Rust primitive CLIs as MCP tools. The
pattern is one Rust binary = one MCP tool, with the `kei` meta-tool on
top that routes natural-language queries via `kei-router`.
Stdio mode (for Claude Code native integration):
```bash
npx @keisei/mcp-server --stdio
npx @keisei84/mcp-server --stdio
```
HTTP mode:
```bash
npx @keisei/mcp-server --port 3000 --auth-token-file ~/.claude/mcp-token
npx @keisei84/mcp-server --port 3000 --auth-token-file ~/.claude/mcp-token
```
## Verification

File diff suppressed because it is too large Load diff

View file

@ -1,8 +1,7 @@
{
"name": "@keisei/mcp-server",
"name": "@keisei84/mcp-server",
"version": "0.14.0",
"private": true,
"description": "MCP server exposing KeiSeiKit Rust primitives as Model Context Protocol tools (not yet published to npm — install via local dist build)",
"description": "MCP server exposing KeiSeiKit Rust primitives as Model Context Protocol tools — published to GitHub Packages under @keisei84 scope",
"type": "module",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
@ -18,6 +17,15 @@
"files": [
"dist"
],
"repository": {
"type": "git",
"url": "git+https://github.com/KeiSei84/KeiSeiKit-1.0.git",
"directory": "_ts_packages/packages/mcp-server"
},
"publishConfig": {
"registry": "https://npm.pkg.github.com/",
"access": "public"
},
"scripts": {
"build": "tsc -b",
"test": "vitest run",
@ -42,5 +50,6 @@
"engines": {
"node": ">=18.0.0"
},
"author": "Denis Parfionovich <parfionovich@keilab.io>"
"author": "Denis Parfionovich <parfionovich@keilab.io>",
"license": "Apache-2.0"
}

View file

@ -93,7 +93,7 @@ Profile resolution lives in `_primitives/MANIFEST.toml` — one `[primitive.<nam
## MCP server binary (zero-install path, v0.18)
From v0.18 each GitHub release ships a **single static binary** of the `@keisei/mcp-server` package for five platforms — no Node, no `npm install`. Drop the binary anywhere (USB stick, S3 bucket, Downloads folder) and run it. This is Phase 1 of the "exobrain" distribution goal: any MCP-capable client can mount KeiSeiKit from read-only media.
From v0.18 each GitHub release ships a **single static binary** of the `@keisei84/mcp-server` package for five platforms — no Node, no `npm install`. Drop the binary anywhere (USB stick, S3 bucket, Downloads folder) and run it. This is Phase 1 of the "exobrain" distribution goal: any MCP-capable client can mount KeiSeiKit from read-only media.
| Platform | Asset name |
|---|---|

View file

@ -186,7 +186,7 @@ KeiSeiKit is a **multi-tier agent composition substrate** built on four mutually
| Package | Version | Purpose | Key Dependencies | Build Target |
|---------|---------|---------|------------------|--------------|
| **@keisei/mcp-server** | 0.14.0 | MCP server exposing KeiSeiKit Rust primitives as tools | @modelcontextprotocol/sdk ^1.0.0, execa ^9.0.0, zod ^3.23.0 | Node.js ≥18.0.0; native binaries via bun compile (darwin/linux/windows) |
| **@keisei84/mcp-server** | 0.14.0 | MCP server exposing KeiSeiKit Rust primitives as tools | @modelcontextprotocol/sdk ^1.0.0, execa ^9.0.0, zod ^3.23.0 | Node.js ≥18.0.0; native binaries via bun compile (darwin/linux/windows) |
| **@keisei/gmail-adapter** | 0.5.2 | Gmail API integration for email-based task intake | @google-cloud/gmail ^1.3.0, nodemailer-mock ^2.0.0 | Node.js ≥18.0.0 |
| **@keisei/grok-adapter** | 0.3.1 | Grok (xAI) LLM provider bridge | openai-compatible ^1.0.0 | Node.js ≥18.0.0 |
| **@keisei/telegram-adapter** | 0.6.0 | Telegram Bot API integration for notifications + input | telegram-typings ^4.10.0, node-telegram-bot-api ^0.65.0 | Node.js ≥18.0.0 |
@ -194,10 +194,11 @@ KeiSeiKit is a **multi-tier agent composition substrate** built on four mutually
| **@keisei/youtube-adapter** | 0.1.8 | YouTube API integration for video transcript + metadata | googleapis ^118.0.0 | Node.js ≥18.0.0 |
**Notes:**
- All packages scoped under `@keisei/` on npm (published to keigit.com npm registry)
- `@keisei84/mcp-server` published to **GitHub Packages** (`https://npm.pkg.github.com/`) — install requires `~/.npmrc` setup with a github PAT (`read:packages` scope), see `docs/PUBLISHING.md`
- Adapter packages (`@keisei/gmail-adapter`, `@keisei/grok-adapter`, `@keisei/telegram-adapter`, `@keisei/recall-adapter`, `@keisei/youtube-adapter`) — destination registry to be configured per-package via `publishConfig`; npm.org publish remains optional and gated on `NPM_TOKEN` repository secret
- All use TypeScript 5.5+ with strict mode; zod for runtime validation
- Build output lives in `dist/` (generated from `src/` via `tsc -b`)
- MCP server ships as multi-target native binaries (darwin/linux/windows arm64 + x64)
- MCP server also ships as multi-target native binaries (darwin/linux/windows arm64 + x64) attached to each GitHub release
---
@ -398,7 +399,7 @@ These are concatenated in role-declared order, with `\n\n---\n\n` separators bet
| Roles (7 roles) | stable | edit-local / read-only / git-ops / etc. locked; no churn |
| Assembler (compose logic) | stable | Generates .md from TOML + blocks; keimd integration active |
| Cortex stack | beta | kei-cortex (HTTP) + kei-tty (TUI) build clean; browser/VSCode frontends concept |
| MCP Server (@keisei/mcp-server) | stable | Exports Rust atoms as MCP tools; published to keigit.com npm |
| MCP Server (@keisei84/mcp-server) | alpha | Exports Rust primitive CLIs as MCP tools; published to GitHub Packages (npm.pkg.github.com) under @keisei84 scope |
| Bridges | stable | 11 cross-tool format generators (.cursorrules, .windsurf/rules, GEMINI.md, etc.) |
| Sleep Layer (Phase A/B/C) | stable | Incubation (tasks), REM consolidation (reports), NREM deep-sleep (conflicts) |
| Foreign-project ingestion | stable | kei-import <repo> proof-of-concept via Hermes validation |

View file

@ -125,7 +125,7 @@ regenerate_rust_workspace() {
}
# --- mcp-server single-binary detection (v0.18 Phase 1 / exobrain) ----------
# Analog of have_prebuilt_binaries for the TS @keisei/mcp-server package,
# Analog of have_prebuilt_binaries for the TS @keisei84/mcp-server package,
# which is distributable as a `bun build --compile` single binary.
#
# Contract: returns 0 iff a matching pre-built binary is present at