tovanix-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astrenix Inc.
+
+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.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# tovanix-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One command to connect your AI tools to your [Tovanix](https://tovanix.com) account over MCP and install the Tovanix agent skill.
+
+```sh
+npx tovanix-mcp
+```
+
+It looks for the AI tools on your machine (Claude Code, Cursor, Codex, Gemini CLI, Qwen Code, Windsurf and more), asks for your MCP credential once, and then for each tool:
+
+- registers the Tovanix MCP server — by running the tool's own `mcp add` command, or by merging one entry into its config file;
+- installs the `tovanix-mcp` agent skill into the tool's skills folder.
+
+Create a credential first at <https://tovanix.com/m/mcp>. A credential can do nothing until you switch on capabilities for it there.
+
+## Options
+
+| Option | Meaning |
+|---|---|
+| `--tool <ids>` | Tools to set up, comma separated. Default: every tool found. |
+| `--yes`, `-y` | Do not ask; set up every tool found. |
+| `--credential <v>` | MCP credential. Prefer the `TOVANIX_MCP_CREDENTIAL` environment variable. |
+| `--skill-only` / `--mcp-only` | Do only one of the two steps. |
+| `--list` | Show every supported tool and whether it is set up automatically. |
+| `--dry-run` | Show what would change without changing anything. |
+| `--lang <en\|zh>` | Language of the output. |
+
+No Node.js? `curl -fsSL https://tovanix.com/install.sh | sh` installs the skill and registers the server with command-line tools.
+
+## What it changes, and what it does not
+
+- Config files are **merged**, never replaced. The previous file is kept next to it as `<file>.tovanix-backup`.
+- A config file that contains comments, or is not valid JSON, is left untouched; the block to add is printed instead.
+- Tools that are configured inside their own app (Claude desktop, Dify, Coze, n8n), or through YAML, are not edited; you get a link to the steps.
+- A project file that would hold your credential (for example `.trae/mcp.json`) is only written when you name that tool with `--tool`.
+- New config files are created readable by you only.
+
+## Your credential
+
+- It is sent to one place: the Tovanix MCP endpoint, to check that it works before anything is written.
+- It is never printed, logged or stored by this installer outside the tool config you asked for.
+- The installer has no dependencies and contains no platform code or secrets. The list of tools and the skill come from Tovanix's public endpoints (`/api/public/agent/*`).
+
+If a credential leaks, disable or delete it at <https://tovanix.com/m/mcp>.
+
+## Requirements
+
+Node.js 18 or newer.
+
+## License
+
+MIT

package/bin/tovanix-mcp.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js'
+
+main(process.argv.slice(2)).then(
+  (code) => { process.exitCode = code },
+  (err) => {
+    process.stderr.write(`tovanix-mcp: ${err?.message || err}\n`)
+    process.exitCode = 1
+  },
+)

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "tovanix-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "One-command installer that connects your AI tools (Claude Code, Cursor, Codex, Gemini CLI and more) to your Tovanix account over MCP and installs the Tovanix agent skill.",
+  "type": "module",
+  "bin": {
+    "tovanix-mcp": "bin/tovanix-mcp.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "tovanix",
+    "claude",
+    "cursor",
+    "codex",
+    "agent-skills",
+    "ai-agent"
+  ],
+  "homepage": "https://tovanix.com/agent",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Astrenix/tovanix-agent.git",
+    "directory": "installer"
+  },
+  "bugs": {
+    "url": "https://github.com/Astrenix/tovanix-agent/issues"
+  },
+  "author": "Astrenix Inc."
+}

package/src/cli.js

@@ -0,0 +1,281 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import readline from 'node:readline'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import {
+  PLACEHOLDER, SERVER_NAME, commandFor, configPath, installSkill, isCredential, isDetected,
+  planJson, planToml, shellWords, skillTarget, strategyOf, which, writeConfig,
+} from './core.js'
+import { pickLang, translator } from './messages.js'
+
+const DEFAULT_BASE = 'https://tovanix.com'
+const ENV_VAR = 'TOVANIX_MCP_CREDENTIAL'
+
+export function version () {
+  const pkg = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'))
+  return pkg.version
+}
+
+export function parseArgs (argv) {
+  const o = { tools: [], yes: false, credential: '', skillOnly: false, mcpOnly: false, list: false, dryRun: false, base: '', lang: '', help: false, version: false }
+  const need = (i, name) => {
+    if (i + 1 >= argv.length) throw new Error(`${name} needs a value`)
+    return argv[i + 1]
+  }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--yes' || a === '-y') o.yes = true
+    else if (a === '--skill-only') o.skillOnly = true
+    else if (a === '--mcp-only') o.mcpOnly = true
+    else if (a === '--list') o.list = true
+    else if (a === '--dry-run') o.dryRun = true
+    else if (a === '--help' || a === '-h') o.help = true
+    else if (a === '--version' || a === '-v') o.version = true
+    else if (a === '--tool') o.tools.push(...need(i++, a).split(',').map((s) => s.trim()).filter(Boolean))
+    else if (a === '--credential') o.credential = need(i++, a)
+    else if (a === '--base') o.base = need(i++, a)
+    else if (a === '--lang') o.lang = need(i++, a)
+    else throw new Error(`unknown option: ${a}`)
+  }
+  if (o.skillOnly && o.mcpOnly) throw new Error('--skill-only and --mcp-only cannot be used together')
+  return o
+}
+
+// Only https sites, plus http for a machine-local address (development).
+export function normalizeBase (v) {
+  const u = new URL(v || DEFAULT_BASE)
+  const local = u.hostname === 'localhost' || u.hostname === '127.0.0.1'
+  if (u.protocol !== 'https:' && !(u.protocol === 'http:' && local)) throw new Error('--base must be an https URL')
+  return u.origin
+}
+
+async function getJSON (url) {
+  const res = await fetch(url, { headers: { Accept: 'application/json', 'User-Agent': `tovanix-mcp/${version()}` } })
+  if (!res.ok) throw new Error(`HTTP ${res.status}`)
+  const body = await res.json()
+  if (!body || body.code !== 0 || !body.data) throw new Error('unexpected response')
+  return body.data
+}
+
+// Ask the MCP server what this credential may use. 'rejected' only on a clear 401/403.
+export async function checkCredential (endpoint, credential) {
+  try {
+    const res = await fetch(endpoint, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${credential}`, 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
+    })
+    if (res.status === 401 || res.status === 403) return { state: 'rejected' }
+    if (!res.ok) return { state: 'unknown', err: `HTTP ${res.status}` }
+    const body = await res.json()
+    const tools = body?.result?.tools
+    if (!Array.isArray(tools)) return { state: 'unknown', err: 'unexpected response' }
+    // feedback tools are always present; they are not something the user switched on
+    return { state: 'ok', count: tools.filter((t) => !/^tovanix_platform_feedback_/.test(t.name)).length }
+  } catch (e) {
+    return { state: 'unknown', err: e?.message || String(e) }
+  }
+}
+
+function ask (question, { hidden = false } = {}) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true })
+    if (hidden) {
+      // print the question, then swallow what is typed
+      rl.output.write(question)
+      rl._writeToOutput = () => {}
+      rl.question('', (a) => { rl.close(); process.stdout.write('\n'); resolve(a.trim()) })
+    } else {
+      rl.question(question, (a) => { rl.close(); resolve(a.trim()) })
+    }
+  })
+}
+
+export function pickByNumbers (answer, items) {
+  if (answer === '') return items
+  const idx = answer.split(/[\s,，]+/).filter(Boolean).map((s) => Number(s))
+  if (idx.some((n) => !Number.isInteger(n) || n < 1 || n > items.length)) return null
+  return [...new Set(idx)].map((n) => items[n - 1])
+}
+
+const pad = (s, n) => s + ' '.repeat(Math.max(1, n - s.length))
+
+export async function main (argv, io = {}) {
+  const out = io.out || ((s) => process.stdout.write(s + '\n'))
+  const env = io.env || process.env
+  const home = io.home || os.homedir()
+  const cwd = io.cwd || process.cwd()
+  const interactive = io.interactive ?? (process.stdin.isTTY && process.stdout.isTTY)
+  const place = { home, cwd, env }
+
+  let opts
+  try { opts = parseArgs(argv) } catch (e) { out(`tovanix-mcp: ${e.message}`); return 2 }
+  const t = translator(pickLang(opts.lang, env))
+  if (opts.version) { out(version()); return 0 }
+  let base
+  try { base = normalizeBase(opts.base || env.TOVANIX_BASE) } catch (e) { out(`tovanix-mcp: ${e.message}`); return 2 }
+  if (opts.help) { out(t('help', { base })); return 0 }
+
+  out(t('title'))
+  let data
+  try {
+    data = await getJSON(`${base}/api/public/agent/clients`)
+  } catch (e) {
+    out(t('fetchFailed', { base, err: e.message }))
+    return 1
+  }
+  const clients = data.clients || []
+
+  if (opts.list) {
+    out(t('listHead'))
+    const w = Math.max(...clients.map((c) => c.id.length)) + 2
+    for (const c of clients) out(`  ${pad(c.id, w)}${pad(c.name, 28)}${strategyOf(c) === 'manual' ? t('listManual') : t('listAuto')}`)
+    return 0
+  }
+  if (opts.dryRun) out(t('dryRun'))
+
+  // ---- which tools
+  let chosen
+  if (opts.tools.length) {
+    chosen = []
+    for (const id of opts.tools) {
+      const c = clients.find((x) => x.id === id)
+      if (!c) { out(t('unknownTool', { id })); return 2 }
+      chosen.push(c)
+    }
+  } else {
+    // project-level tools are picked up only when the current folder already uses them
+    const found = clients.filter((c) => isDetected(c, place))
+    if (!found.length) { out(t('noneFound')); out(t('noneFoundHint')); return 1 }
+    out(t('found'))
+    found.forEach((c, i) => out(`  ${i + 1}. ${c.name}`))
+    if (opts.yes || !interactive) {
+      if (!opts.yes) { out(t('needTty')); return 2 }
+      chosen = found
+    } else {
+      chosen = pickByNumbers(await ask(t('choose')), found)
+      if (!chosen) { out(t('badChoice')); return 2 }
+    }
+  }
+
+  // ---- credential (only tools that put it somewhere need it)
+  const wantMcp = !opts.skillOnly
+  const wantSkill = !opts.mcpOnly
+  let credential = ''
+  const needsCred = wantMcp && chosen.some((c) => c.mcp_snippet.includes(PLACEHOLDER) || strategyOf(c) === 'toml')
+  if (needsCred) {
+    credential = opts.credential || env[ENV_VAR] || ''
+    if (!credential && opts.dryRun) credential = PLACEHOLDER // a dry run changes nothing, so it needs no secret
+    if (!credential) {
+      if (!interactive) { out(t('needTty')); return 2 }
+      credential = await ask(t('askCredential', { base }), { hidden: true })
+    }
+    if (credential !== PLACEHOLDER) {
+      if (!isCredential(credential)) { out(t('badCredential')); return 2 }
+      out(t('checking'))
+      const chk = await (io.checkCredential || checkCredential)(data.endpoint, credential)
+      if (chk.state === 'rejected') { out(t('credRejected')); return 1 }
+      if (chk.state === 'ok') out(chk.count > 0 ? t('credOk', { n: chk.count }) : t('credOkNoAbility', { base }))
+      else out(t('credUnknown', { err: chk.err }))
+    }
+  }
+
+  // ---- skill files (fetched once, written per distinct folder)
+  let skill = null
+  if (wantSkill && chosen.some((c) => c.skill_dir)) {
+    try {
+      skill = await getJSON(`${base}/api/public/agent/skill.json`)
+    } catch (e) {
+      out(t('fetchFailed', { base, err: e.message }))
+      return 1
+    }
+  }
+
+  const run = io.spawn || ((bin, args) => spawnSync(bin, args, { encoding: 'utf8', shell: process.platform === 'win32' }))
+  const doneFiles = new Set()
+  const doneSkillDirs = new Set()
+  let changed = 0
+  const would = opts.dryRun ? `${t('would')}: ` : ''
+
+  for (const c of chosen) {
+    out('')
+    out(`${c.name}`)
+    const strat = strategyOf(c)
+
+    if (wantMcp) {
+      if (strat === 'shell') {
+        const words = commandFor(c, credential)
+        const bin = words[0]
+        const shown = shellWords(c.mcp_snippet).join(' ')
+        if (!which(bin, place)) {
+          out(`  ${t('cmdMissing', { bin })}`)
+          out(`    ${c.mcp_snippet}`)
+        } else if (opts.dryRun) {
+          out(`  ${would}${shown}`)
+        } else {
+          let r = run(bin, words.slice(1))
+          if (r.status !== 0 && /exist/i.test(`${r.stdout || ''}${r.stderr || ''}`)) {
+            // registered before: replace it so a new credential takes effect
+            run(bin, ['mcp', 'remove', SERVER_NAME])
+            r = run(bin, words.slice(1))
+          }
+          if (r.status === 0) { out(`  ${t('mcpDone')}`); changed++ } else {
+            const err = String(r.stderr || r.stdout || r.error?.message || '').trim().split('\n')[0]
+            out(`  ${t('cmdFailed', { err: err.split(credential).join('***') })}`)
+          }
+        }
+      } else if (strat === 'json' || strat === 'project' || strat === 'toml') {
+        const file = configPath(c, place)
+        if (doneFiles.has(file)) {
+          out(`  ${t('mcpUnchanged')}`)
+        } else {
+          doneFiles.add(file)
+          const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null
+          const plan = strat === 'toml' ? planToml(existing, c.mcp_snippet) : planJson(existing, c.mcp_snippet, credential)
+          const note = strat === 'project' ? ` ${t('projectNote')}` : ''
+          if (plan.action === 'manual') {
+            out(`  ${t(plan.reason === 'comments' ? 'mcpManualComments' : 'mcpManualInvalid', { file })}`)
+            for (const l of c.mcp_snippet.split('\n')) out(`    ${l}`)
+          } else if (plan.action === 'unchanged') {
+            out(`  ${t('mcpUnchanged')}`)
+          } else if (opts.dryRun) {
+            out(`  ${would}${t('mcpFile', { file })}${note}`)
+          } else {
+            const backup = writeConfig(file, plan.text)
+            out(`  ${t('mcpFile', { file })}${note}`)
+            if (backup) out(`    ${t('backup', { file: backup })}`)
+            if (strat === 'project' && c.credential_in_file) out(`    ${t('gitignoreWarn', { file: c.mcp_file })}`)
+            changed++
+          }
+          if (strat === 'toml' && plan.action !== 'manual') {
+            out(`  ${t('envHint')}`)
+            // shown with the placeholder: the credential was typed hidden, do not echo it back
+            out(`    export ${data.credential_env_var || ENV_VAR}='${PLACEHOLDER}'`)
+          }
+        }
+      } else {
+        out(`  ${t('mcpManual')}`)
+        out(`    ${c.docs || `${base}/docs/mcp`}`)
+      }
+    }
+
+    if (wantSkill) {
+      const dir = skillTarget(c, place)
+      if (!dir) {
+        if (opts.skillOnly) out(`  ${t('skillNone')}`)
+      } else if (doneSkillDirs.has(dir)) {
+        out(`  ${t('skillDone', { dir: path.join(dir, skill.name) })}`)
+      } else {
+        doneSkillDirs.add(dir)
+        if (opts.dryRun) out(`  ${would}${t('skillDone', { dir: path.join(dir, skill.name) })}`)
+        else { out(`  ${t('skillDone', { dir: installSkill(dir, skill) })}`); changed++ }
+      }
+    }
+  }
+
+  out('')
+  out(opts.dryRun ? t('dryRun') : (changed ? t('summaryOk') : t('summaryNothing')))
+  return 0
+}

package/src/core.js

@@ -0,0 +1,247 @@
+// Pure logic of the installer: how each tool is configured and how files are changed.
+// Nothing here talks to the network or the terminal, so it can be tested directly.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export const PLACEHOLDER = '<YOUR_MCP_CREDENTIAL>'
+export const SERVER_NAME = 'tovanix'
+
+// A Tovanix MCP credential: "mcp_live_" + 64 hex characters.
+// Strict on purpose — the value is substituted into shell commands and config files.
+export function isCredential (v) {
+  return typeof v === 'string' && /^mcp_live_[0-9a-f]{64}$/.test(v)
+}
+
+export function expandHome (p, home = os.homedir()) {
+  if (p === '~') return home
+  if (p.startsWith('~/')) return path.join(home, p.slice(2))
+  return p
+}
+
+// How the installer handles a tool. Derived from the published client list, not from tool ids,
+// so tools added on the server side work without a new release of this package.
+//   shell    run the tool's own "mcp add" command
+//   json     merge into a JSON config file under the home directory
+//   project  merge into a JSON config file inside the current project
+//   toml     append a section to a TOML config file under the home directory
+//   manual   cannot be done safely from here (UI-only tools, YAML, per-user file locations)
+export function strategyOf (client) {
+  const file = client.mcp_file || ''
+  if (client.mcp_format === 'shell') return 'shell'
+  if (client.mcp_format === 'json' && file) {
+    if (client.mcp_file_in_project) return 'project'
+    if (file.startsWith('~/')) return 'json'
+  }
+  if (client.mcp_format === 'toml' && file.startsWith('~/')) return 'toml'
+  return 'manual'
+}
+
+export function configPath (client, { home = os.homedir(), cwd = process.cwd() } = {}) {
+  const s = strategyOf(client)
+  if (s === 'json' || s === 'toml') return expandHome(client.mcp_file, home)
+  if (s === 'project') return path.join(cwd, client.mcp_file)
+  return ''
+}
+
+export function skillTarget (client, { home = os.homedir(), cwd = process.cwd() } = {}) {
+  if (!client.skill_dir) return ''
+  return client.skill_dir_in_project ? path.join(cwd, client.skill_dir) : expandHome(client.skill_dir, home)
+}
+
+// ---------------------------------------------------------------- detection
+
+export function which (bin, { env = process.env, platform = process.platform } = {}) {
+  const dirs = (env.PATH || env.Path || '').split(path.delimiter).filter(Boolean)
+  const exts = platform === 'win32' ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : ['']
+  for (const d of dirs) {
+    for (const e of exts) {
+      const full = path.join(d, bin + e)
+      try {
+        if (fs.statSync(full).isFile()) return full
+      } catch { /* not here */ }
+    }
+  }
+  return ''
+}
+
+// Is this tool present on the machine? Only tools we can configure are reported.
+export function isDetected (client, opts = {}) {
+  const s = strategyOf(client)
+  if (s === 'shell') return which(shellWords(client.mcp_snippet)[0] || '', opts) !== ''
+  if (s === 'json' || s === 'toml') return dirExists(path.dirname(configPath(client, opts)))
+  // A project file that holds the credential is never picked automatically: it would put a secret
+  // into whatever repository the command happens to be run in. Such tools need an explicit --tool.
+  if (s === 'project') return !client.credential_in_file && dirExists(path.dirname(configPath(client, opts)))
+  return false
+}
+
+function dirExists (p) {
+  try { return fs.statSync(p).isDirectory() } catch { return false }
+}
+
+// ---------------------------------------------------------------- shell commands
+
+// Split a command line into words, honouring single and double quotes.
+// The published commands are plain "tool mcp add ..." lines; no variables, pipes or globs.
+export function shellWords (line) {
+  const out = []
+  let cur = ''
+  let quote = ''
+  let has = false
+  for (const ch of String(line)) {
+    if (quote) {
+      if (ch === quote) quote = ''
+      else cur += ch
+    } else if (ch === '"' || ch === "'") {
+      quote = ch
+      has = true
+    } else if (/\s/.test(ch)) {
+      if (has || cur) out.push(cur)
+      cur = ''
+      has = false
+    } else cur += ch
+  }
+  if (quote) throw new Error('unbalanced quote in command')
+  if (has || cur) out.push(cur)
+  return out
+}
+
+export function commandFor (client, credential) {
+  return shellWords(client.mcp_snippet).map((w) => w.split(PLACEHOLDER).join(credential))
+}
+
+// ---------------------------------------------------------------- JSON configs
+
+// Remove // and /* */ comments and trailing commas, leaving string contents untouched.
+// Used only to decide whether a file is "JSON with comments"; such files are never rewritten.
+export function stripJsonc (text) {
+  let out = ''
+  let i = 0
+  let inStr = false
+  while (i < text.length) {
+    const ch = text[i]
+    const next = text[i + 1]
+    if (inStr) {
+      out += ch
+      if (ch === '\\') { out += next ?? ''; i += 2; continue }
+      if (ch === '"') inStr = false
+      i++
+    } else if (ch === '"') {
+      inStr = true
+      out += ch
+      i++
+    } else if (ch === '/' && next === '/') {
+      while (i < text.length && text[i] !== '\n') i++
+    } else if (ch === '/' && next === '*') {
+      i += 2
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++
+      i += 2
+    } else {
+      out += ch
+      i++
+    }
+  }
+  return out.replace(/,(\s*[}\]])/g, '$1')
+}
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+// Merge `add` into `base` without dropping anything that is already there.
+// Objects merge key by key; arrays of {id} objects are upserted by id (VS Code "inputs");
+// any other array is left alone when it already exists.
+export function mergeConfig (base, add) {
+  if (!isObj(base)) return add
+  const out = { ...base }
+  for (const [k, v] of Object.entries(add)) {
+    const cur = out[k]
+    if (isObj(v) && isObj(cur)) out[k] = mergeConfig(cur, v)
+    else if (Array.isArray(v) && Array.isArray(cur)) {
+      const byId = v.every((x) => isObj(x) && 'id' in x) && cur.every((x) => isObj(x) && 'id' in x)
+      out[k] = byId ? [...cur.filter((x) => !v.some((y) => y.id === x.id)), ...v] : cur
+    } else out[k] = v
+  }
+  return out
+}
+
+function detectIndent (text) {
+  const m = /\n([ \t]+)"/.exec(text)
+  return m ? m[1] : '  '
+}
+
+// Plan the change to a JSON config file. Returns:
+//   { action: 'create' | 'update' | 'unchanged', text }   — safe to write
+//   { action: 'manual', reason }                          — do not touch the file
+export function planJson (existingText, snippetText, credential) {
+  const add = JSON.parse(snippetText.split(PLACEHOLDER).join(credential))
+  if (existingText == null || existingText.trim() === '') {
+    return { action: 'create', text: JSON.stringify(add, null, 2) + '\n' }
+  }
+  let base
+  try {
+    base = JSON.parse(existingText)
+  } catch {
+    try {
+      JSON.parse(stripJsonc(existingText))
+      return { action: 'manual', reason: 'comments' } // rewriting would delete the user's comments
+    } catch {
+      return { action: 'manual', reason: 'invalid' }
+    }
+  }
+  if (!isObj(base)) return { action: 'manual', reason: 'invalid' }
+  const merged = mergeConfig(base, add)
+  const text = JSON.stringify(merged, null, detectIndent(existingText)) + (existingText.endsWith('\n') ? '\n' : '')
+  if (JSON.stringify(merged) === JSON.stringify(base)) return { action: 'unchanged', text: existingText }
+  return { action: 'update', text }
+}
+
+// ---------------------------------------------------------------- TOML configs
+
+// The published TOML snippet is one table, e.g. [mcp_servers.tovanix]. Append it when absent;
+// when the table is already there the file is left alone (editing TOML in place is not worth the risk).
+export function planToml (existingText, snippetText) {
+  const header = (/^\s*\[[^\]]+\]/m.exec(snippetText) || [''])[0].trim()
+  if (!header) return { action: 'manual', reason: 'invalid' }
+  if (existingText == null || existingText.trim() === '') return { action: 'create', text: snippetText.trim() + '\n' }
+  const has = existingText.split('\n').some((l) => l.trim() === header)
+  if (has) return { action: 'unchanged', text: existingText }
+  return { action: 'update', text: existingText.replace(/\n*$/, '\n\n') + snippetText.trim() + '\n' }
+}
+
+// ---------------------------------------------------------------- writing files
+
+// Write a config file, keeping a copy of the previous content next to it.
+// New files are created private (0600): several tools keep the credential in this file.
+export function writeConfig (file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  let backup = ''
+  if (fs.existsSync(file)) {
+    backup = `${file}.tovanix-backup`
+    fs.copyFileSync(file, backup)
+    fs.writeFileSync(file, text)
+  } else {
+    fs.writeFileSync(file, text, { mode: 0o600 })
+  }
+  return backup
+}
+
+// Put the skill's files under <dir>/<name>/, replacing a previous copy of the same skill.
+// File paths come from the server; anything that would land outside the skill folder is refused.
+export function installSkill (dir, skill) {
+  if (!/^[a-z0-9-]+$/.test(skill.name || '')) throw new Error('unexpected skill name')
+  const root = path.join(dir, skill.name)
+  const plan = []
+  for (const f of skill.files || []) {
+    const rel = String(f.path || '')
+    const dest = path.resolve(root, rel)
+    if (!rel || path.isAbsolute(rel) || !dest.startsWith(root + path.sep)) throw new Error(`unexpected file path in skill: ${rel}`)
+    plan.push([dest, String(f.content ?? '')])
+  }
+  if (!plan.some(([d]) => path.basename(d) === 'SKILL.md')) throw new Error('skill has no SKILL.md')
+  fs.rmSync(root, { recursive: true, force: true })
+  for (const [dest, content] of plan) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true })
+    fs.writeFileSync(dest, content)
+  }
+  return root
+}

package/src/messages.js

@@ -0,0 +1,135 @@
+// Terminal text in English and Simplified Chinese.
+const en = {
+  title: 'Tovanix MCP installer',
+  help: `Usage: npx tovanix-mcp [options]
+
+Connects your AI tools to your Tovanix account over MCP and installs the Tovanix agent skill.
+
+Options:
+  --tool <ids>        Tools to set up, comma separated (see --list). Default: every tool found.
+  --yes, -y           Do not ask; set up every tool found.
+  --credential <v>    MCP credential. Prefer the TOVANIX_MCP_CREDENTIAL environment variable.
+  --skill-only        Install the agent skill only.
+  --mcp-only          Register the MCP server only.
+  --list              Show every supported tool and how it is set up, then exit.
+  --dry-run           Show what would change without changing anything.
+  --base <url>        Tovanix site to use (default https://tovanix.com).
+  --lang <en|zh>      Language of this output.
+  --version, -v       Print the version.
+  --help, -h          Print this help.
+
+Create a credential at {base}/m/mcp first. Your credential is only ever sent to {base}.`,
+  fetching: 'Reading the tool list from {base} ...',
+  fetchFailed: 'Could not reach {base}: {err}',
+  noneFound: 'No supported AI tool was found on this machine.',
+  noneFoundHint: 'Run with --list to see every supported tool, or --tool <id> to set one up anyway.',
+  found: 'Found on this machine:',
+  choose: 'Press Enter to set up all of them, or type the numbers to pick (e.g. 1,3): ',
+  badChoice: 'Could not read that choice.',
+  unknownTool: 'Unknown tool: {id}. Run with --list to see the ids.',
+  needTty: 'No terminal to ask on. Pass --yes (or --tool) and set TOVANIX_MCP_CREDENTIAL.',
+  askCredential: 'Paste your MCP credential (create one at {base}/m/mcp; input is hidden): ',
+  badCredential: 'That does not look like a Tovanix MCP credential (it starts with mcp_live_).',
+  checking: 'Checking the credential ...',
+  credOk: 'Credential accepted — {n} tools available to it.',
+  credOkNoAbility: 'Credential accepted, but no capability is switched on for it yet. Open {base}/m/mcp to switch on what the AI may do.',
+  credRejected: 'The platform rejected this credential (wrong, disabled or expired). Nothing was changed.',
+  credUnknown: 'Could not verify the credential ({err}). Continuing.',
+  dryRun: 'Dry run — nothing will be changed.',
+  mcpDone: 'MCP server registered',
+  mcpUnchanged: 'MCP server already set up',
+  mcpFile: 'MCP server written to {file}',
+  backup: 'previous file kept as {file}',
+  mcpManualComments: 'Left {file} untouched because it contains comments. Add this block yourself:',
+  mcpManualInvalid: 'Left {file} untouched because it is not valid JSON. Add this block yourself:',
+  mcpManual: 'This tool is set up inside its own settings. Follow:',
+  cmdMissing: 'Its command-line tool "{bin}" is not on PATH. Run this yourself:',
+  cmdFailed: 'Its command-line tool refused the command: {err}',
+  envHint: 'This tool reads the credential from an environment variable. Add to your shell profile:',
+  skillDone: 'Skill installed to {dir}',
+  skillNone: 'No skill folder for this tool',
+  projectNote: '(inside the current project folder)',
+  gitignoreWarn: 'This file now holds your credential. Add {file} to .gitignore so it is not committed.',
+  would: 'would',
+  summaryOk: 'Done. Restart the AI tool (or reload its MCP servers) to pick up the change.',
+  summaryNothing: 'Nothing was set up.',
+  listHead: 'Supported tools:',
+  listAuto: 'automatic',
+  listManual: 'manual steps',
+}
+
+const zh = {
+  title: 'Tovanix MCP 安装器',
+  help: `用法: npx tovanix-mcp [选项]
+
+把你的 AI 工具通过 MCP 接入 Tovanix 账户,并安装配套的 Agent Skill。
+
+选项:
+  --tool <ids>        要配置的工具,逗号分隔(见 --list)。默认:本机找到的全部工具。
+  --yes, -y           不询问,直接配置找到的全部工具。
+  --credential <v>    MCP 凭据。建议改用环境变量 TOVANIX_MCP_CREDENTIAL。
+  --skill-only        只安装 Agent Skill。
+  --mcp-only          只注册 MCP 服务器。
+  --list              列出全部支持的工具与配置方式后退出。
+  --dry-run           只显示会改什么,不做任何修改。
+  --base <url>        使用的 Tovanix 站点(默认 https://tovanix.com)。
+  --lang <en|zh>      输出语言。
+  --version, -v       显示版本。
+  --help, -h          显示本帮助。
+
+请先在 {base}/m/mcp 创建凭据。凭据只会发送到 {base}。`,
+  fetching: '正在从 {base} 读取工具清单 ...',
+  fetchFailed: '无法连接 {base}:{err}',
+  noneFound: '本机没有找到受支持的 AI 工具。',
+  noneFoundHint: '用 --list 查看全部支持的工具,或用 --tool <id> 指定要配置的工具。',
+  found: '本机找到:',
+  choose: '直接回车配置全部,或输入序号选择(如 1,3): ',
+  badChoice: '没看懂这个选择。',
+  unknownTool: '未知的工具:{id}。用 --list 查看可用的 id。',
+  needTty: '当前没有可交互的终端。请加 --yes(或 --tool)并设置 TOVANIX_MCP_CREDENTIAL。',
+  askCredential: '粘贴你的 MCP 凭据(在 {base}/m/mcp 创建;输入不显示): ',
+  badCredential: '这不像 Tovanix 的 MCP 凭据(应以 mcp_live_ 开头)。',
+  checking: '正在校验凭据 ...',
+  credOk: '凭据有效 —— 它可以使用 {n} 个工具。',
+  credOkNoAbility: '凭据有效,但还没有开启任何功能。请到 {base}/m/mcp 勾选允许 AI 使用的功能。',
+  credRejected: '平台拒绝了这个凭据(填错、已停用或已过期)。没有做任何修改。',
+  credUnknown: '无法校验凭据({err}),继续安装。',
+  dryRun: '演练模式 —— 不会做任何修改。',
+  mcpDone: '已注册 MCP 服务器',
+  mcpUnchanged: 'MCP 服务器已经配置过',
+  mcpFile: 'MCP 服务器已写入 {file}',
+  backup: '原文件保留为 {file}',
+  mcpManualComments: '{file} 里有注释,为了不丢注释没有改动它。请自行加入这一段:',
+  mcpManualInvalid: '{file} 不是合法的 JSON,没有改动它。请自行加入这一段:',
+  mcpManual: '这个工具要在它自己的设置里配置,请按这里操作:',
+  cmdMissing: '它的命令行工具 "{bin}" 不在 PATH 里。请自行执行:',
+  cmdFailed: '它的命令行工具拒绝了这条命令:{err}',
+  envHint: '这个工具从环境变量读取凭据。请加到你的 shell 配置里:',
+  skillDone: 'Skill 已安装到 {dir}',
+  skillNone: '这个工具没有技能目录',
+  projectNote: '(在当前项目目录下)',
+  gitignoreWarn: '这个文件里现在有你的凭据。请把 {file} 加进 .gitignore,避免提交到仓库。',
+  would: '将会',
+  summaryOk: '完成。重启 AI 工具(或重新加载它的 MCP 服务器)后生效。',
+  summaryNothing: '没有配置任何工具。',
+  listHead: '支持的工具:',
+  listAuto: '自动配置',
+  listManual: '需手动操作',
+}
+
+export function pickLang (flag, env = process.env) {
+  if (flag === 'zh' || flag === 'en') return flag
+  const v = `${env.LC_ALL || ''}${env.LC_MESSAGES || ''}${env.LANG || ''}`.toLowerCase()
+  if (v.includes('zh')) return 'zh'
+  try {
+    if (Intl.DateTimeFormat().resolvedOptions().locale.toLowerCase().startsWith('zh')) return 'zh'
+  } catch { /* keep English */ }
+  return 'en'
+}
+
+export function translator (lang) {
+  const table = lang === 'zh' ? zh : en
+  return (key, vars = {}) => String(table[key] ?? en[key] ?? key).replace(/\{(\w+)\}/g, (_, k) => (k in vars ? String(vars[k]) : `{${k}}`))
+}
+
+export const _tables = { en, zh }