@bigbrain-work/mcp-connect 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# @bigbrain-work/mcp-connect
+
+石榴 AI MCP 一键配置工具。用于将石榴 AI 的远程 MCP 服务接入 Codex、Claude Code 或 Cursor。
+
+## 使用
+
+先在石榴 AI 页面复制当前账户的 API Key，然后执行对应命令：
+
+```bash
+npx -y @bigbrain-work/mcp-connect --agent codex
+npx -y @bigbrain-work/mcp-connect --agent claude
+npx -y @bigbrain-work/mcp-connect --agent cursor
+```
+
+安装器会隐藏输入 API Key。配置完成后，重启对应客户端并检查连接：
+
+```bash
+npx -y @bigbrain-work/mcp-connect status
+```
+
+如已设置 `SHILIU_AI_API_KEY` 环境变量，安装器会直接使用该变量，不再提示输入。
+
+## 安全说明
+
+- npm 包源码中不包含任何用户 API Key。
+- Codex、Claude Code 和 Cursor 的 MCP 配置只保存环境变量引用，不保存真实 API Key。
+- Windows 上，安装器通过标准输入将 API Key 写入当前用户环境变量，避免进入终端历史和子进程命令行。
+- macOS/Linux 上，API Key 保存在权限为 `0600` 的 `~/.config/shiliu-ai/env`，并由用户登录配置加载。
+- `status` 命令只显示“已设置/未设置”，不会输出 API Key。
+
+## 服务信息
+
+- MCP 地址：`https://api.bigbrain.work/shiliu/mcp`
+- 认证方式：`Authorization: Bearer <API_KEY>`
+- 配置名称：`shiliu_mcp`
+
+## 发布
+
+首次发布前，确认 npm 账号属于 `bigbrain-work` organization，并启用双重验证：
+
+```bash
+npm login
+npm whoami
+npm pack --dry-run
+npm publish --access public
+```
+
+后续版本先更新 `package.json` 版本号，再发布：
+
+```bash
+npm version patch
+npm publish --access public
+```

package/bin/mcp-connect.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js'
+
+runCli().catch((error) => {
+  console.error(`安装失败：${error.message}`)
+  process.exitCode = 1
+})

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@bigbrain-work/mcp-connect",
+  "version": "1.0.0",
+  "description": "石榴 AI MCP 一键配置工具，支持 Codex、Claude Code 和 Cursor。",
+  "type": "module",
+  "bin": {
+    "mcp-connect": "bin/mcp-connect.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "codex",
+    "claude-code",
+    "cursor",
+    "shiliu-ai"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}

package/src/arguments.js

@@ -0,0 +1,56 @@
+import { parseArgs } from 'node:util'
+
+import { SUPPORTED_AGENTS } from './constants.js'
+
+export function parseCliArguments(args) {
+  const parsed = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      agent: {
+        type: 'string',
+        short: 'a',
+      },
+      'dry-run': {
+        type: 'boolean',
+        default: false,
+      },
+      home: {
+        type: 'string',
+      },
+      help: {
+        type: 'boolean',
+        short: 'h',
+        default: false,
+      },
+      version: {
+        type: 'boolean',
+        short: 'v',
+        default: false,
+      },
+    },
+  })
+
+  const command = parsed.positionals[0] || 'install'
+  if (!['install', 'status'].includes(command)) {
+    throw new Error(`不支持的命令：${command}`)
+  }
+
+  const agent = parsed.values.agent?.toLowerCase()
+  if (agent && !SUPPORTED_AGENTS.includes(agent)) {
+    throw new Error(`不支持的客户端：${agent}。可选值：${SUPPORTED_AGENTS.join('、')}`)
+  }
+  if (command === 'install' && !agent && !parsed.values.help && !parsed.values.version) {
+    throw new Error('请通过 --agent 指定客户端：codex、claude 或 cursor')
+  }
+
+  return {
+    command,
+    agent,
+    dryRun: parsed.values['dry-run'],
+    home: parsed.values.home,
+    help: parsed.values.help,
+    version: parsed.values.version,
+  }
+}

package/src/cli.js

@@ -0,0 +1,68 @@
+import os from 'node:os'
+import path from 'node:path'
+
+import { parseCliArguments } from './arguments.js'
+import { configureAgent } from './configurators.js'
+import {
+  API_KEY_ENV,
+  MCP_URL,
+  PACKAGE_NAME,
+  PACKAGE_VERSION,
+  SUPPORTED_AGENTS,
+} from './constants.js'
+import { persistApiKey, resolveApiKey } from './credentials.js'
+import { printStatus } from './status.js'
+
+function printHelp() {
+  console.log(`${PACKAGE_NAME} ${PACKAGE_VERSION}
+
+用法：
+  mcp-connect --agent <${SUPPORTED_AGENTS.join('|')}>
+  mcp-connect status
+
+选项：
+  -a, --agent <name>  配置指定客户端
+      --dry-run       只显示将执行的操作
+      --home <path>   指定用户目录（主要用于测试）
+  -h, --help          显示帮助
+  -v, --version       显示版本
+
+认证：
+  安装器优先读取 ${API_KEY_ENV}；未设置时会隐藏提示输入。
+  真实 API Key 不会写入生成的 MCP 配置。`)
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  const options = parseCliArguments(argv)
+  if (options.help) {
+    printHelp()
+    return
+  }
+  if (options.version) {
+    console.log(PACKAGE_VERSION)
+    return
+  }
+
+  const home = path.resolve(options.home || os.homedir())
+  if (options.command === 'status') {
+    const result = await printStatus({ home })
+    if (!result.remote.ok) {
+      process.exitCode = 1
+    }
+    return
+  }
+
+  const apiKey = await resolveApiKey()
+  await persistApiKey(apiKey, {
+    dryRun: options.dryRun,
+    home,
+  })
+  await configureAgent(options.agent, {
+    dryRun: options.dryRun,
+    home,
+  })
+
+  console.log(options.dryRun
+    ? `检查完成：将为 ${options.agent} 配置 ${MCP_URL}，未写入任何文件。`
+    : `配置完成：${options.agent} 已接入石榴 AI MCP。请重启客户端后运行 ${PACKAGE_NAME} status 检查连接。`)
+}

package/src/configurators.js

@@ -0,0 +1,152 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+import { API_KEY_ENV, MCP_URL, SERVER_NAME } from './constants.js'
+
+export function codexArguments() {
+  return [
+    'mcp',
+    'add',
+    SERVER_NAME,
+    '--url',
+    MCP_URL,
+    '--bearer-token-env-var',
+    API_KEY_ENV,
+  ]
+}
+
+export function claudeServerDefinition() {
+  return {
+    type: 'http',
+    url: MCP_URL,
+    headers: {
+      Authorization: `Bearer \${${API_KEY_ENV}}`,
+    },
+  }
+}
+
+export function cursorServerDefinition() {
+  return {
+    type: 'http',
+    url: MCP_URL,
+    headers: {
+      Authorization: `Bearer \${env:${API_KEY_ENV}}`,
+    },
+  }
+}
+
+function commandText(command, args) {
+  return [command, ...args].map((value) => (
+    /[\s"]/u.test(value) ? JSON.stringify(value) : value
+  )).join(' ')
+}
+
+function execute(command, args, { dryRun = false } = {}) {
+  if (dryRun) {
+    console.log(`[dry-run] ${commandText(command, args)}`)
+    return
+  }
+
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    windowsHide: true,
+    shell: false,
+  })
+  if (result.error) {
+    if (result.error.code === 'ENOENT') {
+      throw new Error(`未找到 ${command}，请先安装对应客户端`)
+    }
+    throw result.error
+  }
+  if (result.status !== 0) {
+    const detail = `${result.stderr || ''}\n${result.stdout || ''}`.trim()
+    const error = new Error(detail || `${command} 返回退出码 ${result.status}`)
+    error.commandOutput = detail
+    throw error
+  }
+}
+
+function isDuplicateError(error) {
+  return /already|exist|duplicate|已存在/iu.test(error.commandOutput || error.message)
+}
+
+export function configureCodex(options = {}) {
+  try {
+    execute('codex', codexArguments(), options)
+  } catch (error) {
+    if (!isDuplicateError(error)) {
+      throw error
+    }
+    execute('codex', ['mcp', 'remove', SERVER_NAME], options)
+    execute('codex', codexArguments(), options)
+  }
+}
+
+export function configureClaude(options = {}) {
+  const addArgs = [
+    'mcp',
+    'add-json',
+    '--scope',
+    'user',
+    SERVER_NAME,
+    JSON.stringify(claudeServerDefinition()),
+  ]
+  try {
+    execute('claude', addArgs, options)
+  } catch (error) {
+    if (!isDuplicateError(error)) {
+      throw error
+    }
+    execute('claude', ['mcp', 'remove', '--scope', 'user', SERVER_NAME], options)
+    execute('claude', addArgs, options)
+  }
+}
+
+export async function configureCursor({ home, dryRun = false } = {}) {
+  const configPath = path.join(home, '.cursor', 'mcp.json')
+  if (dryRun) {
+    console.log(`[dry-run] 更新 ${configPath} 中的 ${SERVER_NAME}，认证头使用 ${API_KEY_ENV} 环境变量`)
+    return configPath
+  }
+
+  let config = {}
+  try {
+    const source = await readFile(configPath, 'utf8')
+    config = JSON.parse(source)
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      if (error instanceof SyntaxError) {
+        throw new Error(`${configPath} 不是有效 JSON，未做任何修改`)
+      }
+      throw error
+    }
+  }
+
+  config.mcpServers = {
+    ...(config.mcpServers || {}),
+    [SERVER_NAME]: cursorServerDefinition(),
+  }
+
+  await mkdir(path.dirname(configPath), { recursive: true })
+  const tempPath = `${configPath}.${process.pid}.tmp`
+  await writeFile(tempPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
+  await rename(tempPath, configPath)
+  return configPath
+}
+
+export async function configureAgent(agent, options) {
+  if (agent === 'codex') {
+    configureCodex(options)
+    return
+  }
+  if (agent === 'claude') {
+    configureClaude(options)
+    return
+  }
+  if (agent === 'cursor') {
+    await configureCursor(options)
+    return
+  }
+  throw new Error(`不支持的客户端：${agent}`)
+}

package/src/constants.js

@@ -0,0 +1,6 @@
+export const PACKAGE_NAME = '@bigbrain-work/mcp-connect'
+export const PACKAGE_VERSION = '1.0.0'
+export const SERVER_NAME = 'shiliu_mcp'
+export const MCP_URL = 'https://api.bigbrain.work/shiliu/mcp'
+export const API_KEY_ENV = 'SHILIU_AI_API_KEY'
+export const SUPPORTED_AGENTS = ['codex', 'claude', 'cursor']

package/src/credentials.js

@@ -0,0 +1,198 @@
+import { spawn } from 'node:child_process'
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { API_KEY_ENV } from './constants.js'
+
+function validateApiKey(value) {
+  const apiKey = value?.trim()
+  if (!apiKey) {
+    throw new Error('API Key 不能为空')
+  }
+  if (/\s/.test(apiKey)) {
+    throw new Error('API Key 不能包含空白字符')
+  }
+  if (apiKey.length < 12) {
+    throw new Error('API Key 长度异常，请确认复制完整')
+  }
+  return apiKey
+}
+
+export async function readHiddenInput(promptText, input = process.stdin, output = process.stdout) {
+  if (!input.isTTY || typeof input.setRawMode !== 'function') {
+    throw new Error(`当前终端不支持隐藏输入，请先设置 ${API_KEY_ENV} 环境变量后重试`)
+  }
+
+  output.write(promptText)
+  input.setRawMode(true)
+  input.resume()
+  input.setEncoding('utf8')
+
+  return new Promise((resolve, reject) => {
+    let value = ''
+
+    const cleanup = () => {
+      input.off('data', onData)
+      input.setRawMode(false)
+      input.pause()
+    }
+
+    const onData = (chunk) => {
+      for (const character of chunk) {
+        if (character === '\u0003') {
+          cleanup()
+          output.write('\n')
+          reject(new Error('操作已取消'))
+          return
+        }
+        if (character === '\r' || character === '\n') {
+          cleanup()
+          output.write('\n')
+          resolve(value)
+          return
+        }
+        if (character === '\u007f' || character === '\b') {
+          value = value.slice(0, -1)
+          continue
+        }
+        value += character
+      }
+    }
+
+    input.on('data', onData)
+  })
+}
+
+export async function resolveApiKey({ env = process.env, prompt = readHiddenInput } = {}) {
+  if (env[API_KEY_ENV]) {
+    return validateApiKey(env[API_KEY_ENV])
+  }
+  return validateApiKey(await prompt('请输入石榴 AI API Key（输入内容不会显示）：'))
+}
+
+function runPowerShellWithInput(script, input) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('powershell.exe', [
+      '-NoLogo',
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      script,
+    ], {
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+
+    let stderr = ''
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk
+    })
+    child.on('error', reject)
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve()
+      } else {
+        reject(new Error(stderr.trim() || `PowerShell 返回退出码 ${code}`))
+      }
+    })
+    child.stdin.end(input)
+  })
+}
+
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+async function persistPosixApiKey(apiKey, home, env) {
+  const configDir = path.join(home, '.config', 'shiliu-ai')
+  const envFile = path.join(configDir, 'env')
+  await mkdir(configDir, { recursive: true })
+  await writeFile(envFile, `export ${API_KEY_ENV}=${shellQuote(apiKey)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600,
+  })
+  await chmod(envFile, 0o600)
+
+  const shellName = path.basename(env.SHELL || '')
+  const profileName = shellName === 'zsh'
+    ? '.zprofile'
+    : shellName === 'bash'
+      ? '.bash_profile'
+      : '.profile'
+  const profilePath = path.join(home, profileName)
+  const sourceLine = `. ${shellQuote(envFile)} # shiliu-ai\n`
+  let profile = ''
+  try {
+    profile = await readFile(profilePath, 'utf8')
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error
+    }
+  }
+  if (!profile.includes('# shiliu-ai')) {
+    const separator = profile && !profile.endsWith('\n') ? '\n' : ''
+    await writeFile(profilePath, `${profile}${separator}${sourceLine}`, 'utf8')
+  }
+}
+
+export async function persistApiKey(apiKey, {
+  dryRun = false,
+  home,
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  if (dryRun) {
+    return
+  }
+
+  if (platform === 'win32') {
+    const script = `$value = [Console]::In.ReadToEnd(); [Environment]::SetEnvironmentVariable('${API_KEY_ENV}', $value, 'User')`
+    await runPowerShellWithInput(script, apiKey)
+  } else {
+    await persistPosixApiKey(apiKey, home, env)
+  }
+  process.env[API_KEY_ENV] = apiKey
+}
+
+export function readPersistedApiKey({
+  platform = process.platform,
+  env = process.env,
+  home,
+} = {}) {
+  if (env[API_KEY_ENV]) {
+    return env[API_KEY_ENV]
+  }
+
+  if (platform === 'win32') {
+    const result = spawnSync('powershell.exe', [
+      '-NoLogo',
+      '-NoProfile',
+      '-NonInteractive',
+      '-Command',
+      `[Console]::Out.Write([Environment]::GetEnvironmentVariable('${API_KEY_ENV}', 'User'))`,
+    ], {
+      windowsHide: true,
+      encoding: 'utf8',
+    })
+    return result.status === 0 ? result.stdout.trim() : ''
+  }
+
+  try {
+    const content = readFileSync(path.join(home, '.config', 'shiliu-ai', 'env'), 'utf8')
+    const prefix = `export ${API_KEY_ENV}=`
+    const line = content.split(/\r?\n/u).find((item) => item.startsWith(prefix))
+    if (!line) {
+      return ''
+    }
+    const encodedValue = line.slice(prefix.length)
+    if (encodedValue.startsWith("'") && encodedValue.endsWith("'")) {
+      return encodedValue.slice(1, -1).replaceAll("'\\''", "'")
+    }
+    return encodedValue
+  } catch {
+    return ''
+  }
+}

package/src/status.js

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+import { API_KEY_ENV, MCP_URL, SERVER_NAME } from './constants.js'
+import { readPersistedApiKey } from './credentials.js'
+
+async function readText(filePath) {
+  try {
+    return await readFile(filePath, 'utf8')
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return ''
+    }
+    throw error
+  }
+}
+
+async function hasServerConfig(filePath) {
+  const content = await readText(filePath)
+  return content.includes(SERVER_NAME) && content.includes(MCP_URL)
+}
+
+export async function inspectLocalConfiguration(home) {
+  return {
+    codex: await hasServerConfig(path.join(home, '.codex', 'config.toml')),
+    claude: await hasServerConfig(path.join(home, '.claude.json')),
+    cursor: await hasServerConfig(path.join(home, '.cursor', 'mcp.json')),
+  }
+}
+
+export async function probeMcp(apiKey, fetchImpl = fetch) {
+  if (!apiKey) {
+    return {
+      ok: false,
+      detail: `${API_KEY_ENV} 尚未设置`,
+    }
+  }
+
+  try {
+    const response = await fetchImpl(MCP_URL, {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json, text/event-stream',
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-03-26',
+          capabilities: {},
+          clientInfo: {
+            name: 'bigbrain-work-mcp-connect',
+            version: '1.0.0',
+          },
+        },
+      }),
+      signal: AbortSignal.timeout(10000),
+    })
+    return {
+      ok: response.ok,
+      detail: response.ok ? `HTTP ${response.status}` : `HTTP ${response.status}，请检查 API Key`,
+    }
+  } catch (error) {
+    return {
+      ok: false,
+      detail: `连接失败：${error.message}`,
+    }
+  }
+}
+
+function mark(ok) {
+  return ok ? '✓' : '○'
+}
+
+export async function printStatus({ home, platform = process.platform, env = process.env } = {}) {
+  const apiKey = readPersistedApiKey({ platform, env, home })
+  const configs = await inspectLocalConfiguration(home)
+  const remote = await probeMcp(apiKey)
+
+  console.log(`API Key 环境变量  ${mark(Boolean(apiKey))} ${apiKey ? '已设置' : '未设置'}`)
+  console.log(`Codex 配置         ${mark(configs.codex)} ${configs.codex ? '已写入' : '未发现'}`)
+  console.log(`Claude Code 配置   ${mark(configs.claude)} ${configs.claude ? '已写入' : '未发现'}`)
+  console.log(`Cursor 配置        ${mark(configs.cursor)} ${configs.cursor ? '已写入' : '未发现'}`)
+  console.log(`石榴 AI MCP        ${mark(remote.ok)} ${remote.detail}`)
+
+  return {
+    apiKey: Boolean(apiKey),
+    configs,
+    remote,
+  }
+}