feat(adapters/introspect-mcp-ts): TS port of the bridge for npx distribution

The TypeScript port of korg-introspect-mcp. Completes the npm
distribution story alongside @korg/recall-mcp — after both publish,
the entire korg ecosystem becomes npx-installable in Claude Code with
zero Python + pipx + venv friction.

Same architecture as the Python sibling, same wire contract, same
safety gating, same convention for command_id → CLI argv mapping.
Both ports can coexist; the Python version stays as the reference
implementation.

src/:
- discovery.ts: resolveBinary (PATH lookup), runIntrospect (spawn +
  parse with 15s timeout), validateDocument (schema check, required-
  field check, duplicate command_id check). Mirrors Python module.
- args.ts: convention-based argv builder. snake_case → kebab-case
  long flags, bool true → flag-only, arrays repeat the flag,
  command_id dot-split → subcommand path. Same behavior across
  ecosystem.
- safety.ts: Policy with allowed side_effects set. Defaults to
  none + fs_read only; KORG_INTROSPECT_MCP_ALLOW opts into broader
  access. all/* aliases supported.
- invoker.ts: spawn the binary, format stdout per output_mode
  (envelope JSON pretty-printed, stream raw, session refused, none
  → "ok"). Non-zero exit codes append stderr + exit_code to the
  response so agents can debug.
- server.ts: builds MCP server via SDK's low-level Server class.
  Tool names use command_id directly so cross-tool agents see the
  same identifier as recall returns.
- cli.ts: <binary> [--allow] [--list-tools] [--version] [--help]
  with the connect-then-await-close fix.

tests: 56 covering args (15), safety (12), discovery (10),
invoker (6), server (6) including end-to-end SDK-client →
compiled CLI → fixture binary roundtrip, sanity (1).

End-to-end smoke-tested against real Rust thump binary: discovered
9 callables, default policy correctly flagged fs_write/network
ones as denied. Pairs cleanly with @korg/recall-mcp for the full
loop.

Also adds adapters/PUBLISHING.md documenting the npm publish flow:
one-time @korg org creation, npm login, `npm publish --access
public` per package, versioning, deprecate-vs-unpublish policy.

npm pack dry-run preview verified:
  - @korg/recall-mcp v0.1.0: 12.8 kB packed, 39.1 kB unpacked
  - @korg/introspect-mcp v0.1.0: 10.8 kB packed, 33.9 kB unpacked
Each ships only dist/ + README + LICENSE.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: New1Direction

adapters/PUBLISHING.md

@@ -0,0 +1,113 @@
+# Publishing the npm packages
+
+This doc covers the publish flow for `@korg/recall-mcp` and
+`@korg/introspect-mcp`. Both packages are TypeScript ports of their
+Python siblings (`adapters/recall-mcp/` and `adapters/introspect-mcp/`)
+intended for `npx`-style distribution to Claude Code users.
+
+## One-time setup
+
+### 1. Create the `@korg` org on npm
+
+Scoped packages (`@korg/...`) require an npm org. **Public packages
+under a scope are free.**
+
+1. Go to https://www.npmjs.com/org/create
+2. Org name: `korg`
+3. Visibility: public
+4. After creation, add yourself (and any co-maintainers) as
+   members under https://www.npmjs.com/settings/korg/members
+
+If the `@korg` scope is taken, fall back to your personal scope
+(e.g. `@new1direction`) by editing each `package.json`:
+
+```json
+"name": "@new1direction/recall-mcp"
+```
+
+### 2. Log in to npm
+
+```bash
+npm login
+# follow the OTP / 2FA prompts
+npm whoami        # confirm
+```
+
+## Publish flow
+
+For each package (`recall-mcp-ts`, `introspect-mcp-ts`):
+
+```bash
+cd adapters/recall-mcp-ts
+
+# Sanity check what would ship
+npm publish --dry-run
+
+# Run the test suite one more time
+npm test
+
+# Publish (scoped packages default to private, override with --access)
+npm publish --access public
+```
+
+Same flow for `introspect-mcp-ts`.
+
+After publishing, both packages become available via:
+
+```bash
+npx -y @korg/recall-mcp --help
+npx -y @korg/introspect-mcp thump --list-tools
+```
+
+## What gets published
+
+The `files` field in each `package.json` ships only:
+
+- `dist/` — compiled JavaScript + `.d.ts` declarations
+- `README.md`
+- `LICENSE`
+
+The `tests/`, `src/`, `tsconfig.json`, and `node_modules/` are NOT
+included. The published tarball weighs ~11–13 kB.
+
+## Versioning
+
+Both packages use Semantic Versioning. Bump via npm:
+
+```bash
+npm version patch    # 0.1.0 → 0.1.1
+npm version minor    # 0.1.0 → 0.2.0
+npm version major    # 0.1.0 → 1.0.0
+```
+
+`npm version` creates a git tag automatically. Commit + push the
+version bump + tag, then `npm publish`.
+
+## Coordinating with the Python siblings
+
+The TS port shares the `korg:introspect@v1` schema with the Python
+reference. If the schema bumps (e.g. `@v2`), both implementations must
+bump in lockstep. There's a contract test in both that asserts the
+current schema ID — CI on either side will fail if drift sneaks in.
+
+Tool name (`korg-recall-mcp.recall`), exit-code table, and Capabilities
+field set are all part of the cross-language contract. The Python
+reference is authoritative for any new field.
+
+## What the npm org name unlocks
+
+When users see `npx -y @korg/recall-mcp` in a doc or blog post, the
+`@korg` prefix immediately signals "this is part of the korg
+ecosystem" — discoverable on npm via `npm search @korg`. The scope
+also reserves the namespace; nobody else can publish `@korg/whatever`.
+
+## Withdraw / unpublish
+
+npm's 24-hour withdrawal window: `npm unpublish @korg/recall-mcp@0.1.0`
+within 24 hours of publishing. After 24 hours, npm only allows
+`deprecate`, not `unpublish` (security policy). Use `deprecate` for
+any breaking issue:
+
+```bash
+npm deprecate @korg/recall-mcp@0.1.0 "Critical bug — use 0.1.1+"
+```

adapters/introspect-mcp-ts/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Korg ecosystem maintainers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adapters/introspect-mcp-ts/README.md

@@ -0,0 +1,186 @@
+# @korg/introspect-mcp
+
+> **Bridge any `--introspect`-aware CLI to Claude Code via MCP. TypeScript edition.**
+
+One MCP server, any binary in the ecosystem. After installing once,
+adding a new tool surface to Claude Code's agent is **just one line of
+config per binary**. The TS port of `korg-introspect-mcp` — same wire
+contract, same safety gating, same `command_id` conventions as the
+Python reference, distributed via npm for `npx` install.
+
+```bash
+npx -y @korg/introspect-mcp thump --list-tools
+# [korg-introspect-mcp] thump v0.2.0 — 9 tool(s):
+#   thump.tui            side_effects=fs_read   ...
+#   thump.generate       side_effects=fs_write  ... (would be denied)
+#   ...
+```
+
+## Why a TypeScript port
+
+The Python `korg-introspect-mcp` works perfectly — but it requires
+`pipx install` + a Python venv. For Claude Code (a TypeScript app)
+users on Mac/Linux, the canonical "install a new MCP server" idiom is
+`npx -y @some/package`. This TS port closes that distribution gap.
+
+The Python version stays as the reference implementation. Both ports
+emit the same MCP wire format, accept the same args, and produce the
+same tool results.
+
+## Register with Claude Code
+
+Add one entry per binary you want to expose:
+
+```json
+{
+  "mcpServers": {
+    "korg-thump": {
+      "command": "npx",
+      "args": ["-y", "@korg/introspect-mcp", "thump"],
+      "env": { "KORG_INTROSPECT_MCP_ALLOW": "fs_write" }
+    },
+    "korg": {
+      "command": "npx",
+      "args": ["-y", "@korg/introspect-mcp", "/usr/local/bin/korg"],
+      "env": { "KORG_INTROSPECT_MCP_ALLOW": "all" }
+    },
+    "korg-korgex": {
+      "command": "npx",
+      "args": ["-y", "@korg/introspect-mcp", "korgex"]
+    }
+  }
+}
+```
+
+Restart Claude Code. **30+ tools across the entire korg ecosystem**
+land in the agent's toolset. Tool names match each binary's
+`command_id` from its `--introspect` document, so the
+recall→re-invoke loop (when paired with `@korg/recall-mcp`) is
+deterministic.
+
+## What it does
+
+1. At startup, runs `<binary> --introspect` and parses the
+   `korg:introspect@v1` document.
+2. Registers one MCP tool per `Callable`, using the introspect
+   `input_schema` directly as the MCP `inputSchema` (no re-encoding).
+3. When the agent calls a tool, the bridge:
+   - maps MCP arguments to CLI argv (kebab-case long flags,
+     bool flag-on-true, arrays repeat the flag, command_id segments
+     become subcommand path),
+   - execs the binary as a subprocess,
+   - formats stdout per the declared `output_mode` (envelope JSON
+     parsed + pretty-printed, stream returned raw, session refused
+     as unsupported in v1, none → "ok"),
+   - honors `capabilities.side_effects` — refuses
+     `fs_write` / `network` / `ledger_write` invocations unless
+     explicitly allowed.
+
+## Safety gate
+
+By default only `none` and `fs_read` callables are invocable.
+Everything else requires explicit opt-in via the
+`KORG_INTROSPECT_MCP_ALLOW` env var (set in the MCP server's
+`env` block):
+
+| Value | Allows |
+|---|---|
+| (unset) | `none`, `fs_read` (safe default) |
+| `fs_write` | + file writes |
+| `network` | + network access |
+| `ledger_write` | + writing to the korg ledger |
+| `fs_write,network,ledger_write` | full access (combine) |
+| `all` or `*` | everything |
+
+When the agent calls a denied tool, the response explains exactly
+which env var to set. **The default is stricter than running the
+binary directly via Bash** — defense in depth for MCP-driven
+invocations.
+
+## Argv mapping convention
+
+| MCP argument | CLI argv |
+|---|---|
+| `"query": "x"` | `--query x` |
+| `"top_n": 5` | `--top-n 5` |
+| `"quiet": true` | `--quiet` |
+| `"quiet": false` | *(omitted)* |
+| `"tags": ["a", "b"]` | `--tags a --tags b` |
+| `command_id: "thump.bun.script.run"` | `bun script run` as subcommand path |
+
+This convention matches clap + argparse with kebab-case long flags,
+which the entire korg ecosystem uses. If a binary deviates, the right
+fix is on the binary side — keep this mapper boring.
+
+## CLI usage
+
+```bash
+# Sanity-check what an agent will see (no MCP server launched):
+npx -y @korg/introspect-mcp thump --list-tools
+
+# Run as MCP server on stdio (default — what Claude Code calls):
+npx -y @korg/introspect-mcp thump --allow fs_write
+
+# Pass an absolute path or PATH name:
+npx -y @korg/introspect-mcp /usr/local/bin/korgex --allow all
+```
+
+## What's deliberately NOT supported in v1
+
+- **`output_mode: session`** — long-lived stateful sessions over stdio
+  MCP need persistent bidirectional I/O. Agents that try to call a
+  session-mode callable get a clear error explaining why.
+- **Streaming progress mid-call.** Stdout is buffered and returned at
+  completion. A v2 could stream chunks back via MCP notifications.
+- **Auto-rerun on tool drift.** If `<binary> --introspect` changes
+  between bridge invocations, restart the MCP server to pick up
+  the new schema.
+
+## Tests
+
+56 tests covering:
+- **args.test.ts** (15) — kebab conversion, bool/array/null handling,
+  command_id subcommand-path splitting, naked binary, nested
+  subcommand paths, dashed names not split, fallback for
+  missing-prefix command_ids.
+- **safety.test.ts** (12) — default deny, env-var parsing
+  (single/comma/`all`/`*`/whitespace), case-insensitivity, factories,
+  denial-message contents.
+- **discovery.test.ts** (10) — binary lookup (absolute/PATH),
+  `--introspect` invocation, malformed JSON, schema mismatch,
+  duplicate IDs, missing required fields, valid minimal document,
+  end-to-end with a fixture binary.
+- **invoker.test.ts** (6) — envelope JSON pretty-print, kebab-case
+  flag flow-through, array flag repetition, session-mode refused,
+  non-zero exit reports stderr+code, timeout.
+- **server.test.ts** (6) — `buildToolsList` produces correct MCP
+  shape, tags capabilities in description, passes input_schema
+  verbatim, end-to-end SDK client → compiled CLI → fixture binary
+  roundtrip (init + list + call), default policy refuses fs_write
+  with a helpful env-var hint.
+- **_sanity.test.ts** (1) — fixture binary spawns correctly.
+
+Run them:
+```bash
+npm test
+```
+
+## Architecture
+
+```
+src/
+├── discovery.ts   # exec <binary> --introspect, validate doc
+├── args.ts        # MCP arguments → CLI argv (uniform convention)
+├── safety.ts      # Policy: side_effects allow-list
+├── invoker.ts     # exec the binary, format by output_mode
+├── server.ts      # MCP wiring via @modelcontextprotocol/sdk
+├── cli.ts         # CLI entry: <binary> [--allow] [--list-tools]
+└── index.ts       # public API for programmatic use
+```
+
+Zero required runtime dependencies beyond `@modelcontextprotocol/sdk`.
+Pure stdlib for everything else.
+
+## License
+
+MIT.

adapters/introspect-mcp-ts/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@korg/introspect-mcp",
+  "version": "0.1.0",
+  "description": "Generic --introspect → MCP server bridge. Wrap any korg:introspect@v1 binary as an MCP server with one line of Claude Code config.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "korg-introspect-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "node --test --import tsx tests/*.test.ts",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "introspect",
+    "cli-bridge",
+    "korg"
+  ],
+  "author": "Korg ecosystem maintainers",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/New1Direction/korg.git",
+    "directory": "adapters/introspect-mcp-ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}