Parfii-bot a6f1c72472 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 2bb2f10. 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

3.5 KiB

Raw Blame History

KeiSeiKit TypeScript Packages

v0.14.0 part B: MCP server layer + external-API adapters.

RULE 0.2 exception

TypeScript is chosen here under RULE 0.2 exception #4 (Browser/DOM adjacent) because:

The official Model Context Protocol SDK is TypeScript-native; Rust MCP libraries are immature (as of 2026-04).
The API adapters rely on JS-native SDKs with no Rust equivalents:
- grammy (type-safe Telegram bot)
- googleapis (official Google API SDK for Gmail + YouTube)
- youtube-transcript (Tier-1 free transcript extractor)
Async, JSON-heavy glue code is TypeScript's sweet spot.

Core primitives (signing, ledger, graph, memory, refactor, etc.) remain Rust in ../_primitives/_rust/. This TS layer is a THIN wrapper: it spawns the Rust CLIs as subprocesses and exposes them as MCP tools, plus the six adapters above that have no Rust equivalent.

Layout

_ts_packages/
├── package.json              npm workspace root
├── tsconfig.base.json        strict TS 5.x
└── packages/
    ├── 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)
    ├── gmail-adapter/        @keisei/gmail-adapter
    └── youtube-adapter/      @keisei/youtube-adapter

Install (for end users)

1. Install workspace deps

cd _ts_packages
npm install
npm run build

2. Link each package as a global CLI (optional)

npm i -g ./packages/mcp-server
npm i -g ./packages/telegram-adapter
# ... etc

Or install into a Claude agent directory:

npm i --prefix ~/.claude/agents/_ts_packages/packages/mcp-server \
      ./_ts_packages/packages/mcp-server

Environment variables (RULE 0.8 — secrets in `~/.claude/secrets/.env`)

Var	Package	Purpose
`TELEGRAM_BOT_TOKEN`	telegram-adapter	Bot API token
`RECALL_API_KEY`	recall-adapter	Recall.ai API key (Zoom meetings)
`XAI_API_KEY`	grok-adapter	xAI Grok API key
`GMAIL_CLIENT_ID`	gmail-adapter	Google OAuth2 client id
`GMAIL_CLIENT_SECRET`	gmail-adapter	Google OAuth2 client secret
`GMAIL_REFRESH_TOKEN`	gmail-adapter	Long-lived OAuth2 refresh token
`YOUTUBE_API_KEY`	youtube-adapter	YouTube Data API v3 key
`KEI_MCP_AUTH_TOKEN`	mcp-server	HMAC token for tool callers
`KEI_RUST_BIN_DIR`	mcp-server	Override directory holding Rust primitive CLIs

All are read via process.env. Hardcoding tokens is forbidden (RULE 0.8).

MCP server integration

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):

npx @keisei84/mcp-server --stdio

HTTP mode:

npx @keisei84/mcp-server --port 3000 --auth-token-file ~/.claude/mcp-token

Verification

npm install
npm run build --workspaces
npm run test --workspaces

All six packages compile under strict: true. Total new LOC: see commit.

Migration notes

Zero impact on existing KeiSeiKit users unless they opt into the MCP server (planned v0.14.1 installer flag --enable-mcp).
The Rust primitives are unchanged; this layer only wraps them.
Gmail and YouTube adapters are new (gaps in LBM).

3.5 KiB Raw Blame History