@aipermission/mcp 0.2.38 → 0.2.39

package/README.md

@@ -18,6 +18,10 @@ target/profile/action permission model as future connectors.
 
 `@aipermission/mcp` is the official MCP bridge package. The unscoped `aipermission` npm package is only a placeholder that points users here.
 
+The bridge requires Node.js 20+ and npm/npx in the AI client's child-process
+environment. GUI clients and native Windows shells can use a different `PATH`
+from your interactive terminal.
+
 The package includes MCP Registry metadata:
 
 - `mcpName` in `package.json`
@@ -26,14 +30,37 @@ The package includes MCP Registry metadata:
 ## Install
 
 ```bash
-npx -y @aipermission/mcp init \
+npx -y @aipermission/mcp setup \
   --provider codex \
+  --scope user \
   --name aipermission
 ```
 
-The init command prompts for your AIPermission API token and writes the MCP client configuration for the selected provider. Generated runtime configs pin the exact package version that wrote them; re-run init when you intentionally upgrade a client.
+The setup command prompts for your AIPermission API token, writes the MCP client
+configuration, and installs the native operator skill for the selected client.
+Generated runtime configs pin the exact package version that wrote them; re-run
+setup when you intentionally upgrade a client. Use `init` when you only want the
+MCP config, or `install-skill` when you only want the skill.
+
+Check both paths without printing the bearer token:
+
+```bash
+npx -y @aipermission/mcp doctor --client codex --scope user
+```
 
-The generated MCP config contains a bearer token. Keep it private. For project-local configs such as `.mcp.json`, `.cursor/mcp.json`, and `.vscode/mcp.json`, the init command refuses to write into files already tracked by Git unless `--force` is passed. For untracked project-local configs, it adds both the final file and its crash-safe temporary-file pattern to `.git/info/exclude` before writing. Symbolic-link config destinations are rejected instead of being silently replaced; use `--print` and update a symlink-managed config through its owning tool. If a token config is committed or shared, revoke that token in the AIPermission UI.
+The generated MCP config contains a bearer token. Keep it private. For
+project-local configs such as `.mcp.json`, `.cursor/mcp.json`, and
+`.vscode/mcp.json`, setup refuses to write into files already tracked by Git
+unless `--force` is passed. For untracked project-local configs, it locally
+excludes and verifies four paths: the final config, crash-safe temporary-file
+pattern, Windows staging-directory pattern, and update lock. Config and skill
+destinations reject symbolic links or junctions rather than following them.
+Use `init --print` and update a link-managed config through its owning tool.
+Print mode does not read or print a bearer token: it emits `YOUR_TOKEN_HERE`,
+writes no config or skill, and requires you to replace the placeholder through
+the client's private environment or config mechanism. Install the skill
+separately when needed. If a token config is committed or shared, revoke that
+token in the AIPermission UI.
 
 ## Manual Config
 
@@ -42,7 +69,7 @@ The generated MCP config contains a bearer token. Keep it private. For project-l
   "mcpServers": {
     "aipermission": {
       "command": "npx",
-      "args": ["-y", "@aipermission/mcp@0.2.38"],
+      "args": ["-y", "@aipermission/mcp@0.2.39"],
       "env": {
         "NODE_ENV": "production",
         "AIPERMISSION_API_URL": "http://localhost:3210",
@@ -53,6 +80,9 @@ The generated MCP config contains a bearer token. Keep it private. For project-l
 }
 ```
 
+Replace `VERSION` with the release you intend to pin. The setup command does
+this automatically.
+
 ## Tools
 
 - `list_connector_targets`
@@ -162,30 +192,42 @@ temporary paths, archive staging paths, or local upload contents.
 
 ## Operator Skill
 
-Install the optional AIPermission operator instructions for your AI client:
+Install only the AIPermission native operator skill for your AI client:
 
 ```bash
-npx -y @aipermission/mcp install-skill --client codex
+npx -y @aipermission/mcp install-skill --client codex --scope user
 ```
 
 Supported clients:
 
-- `codex`: `~/.codex/skills/aipermission-operator/SKILL.md`
-- `claude-code`: `.claude/rules/aipermission-operator.md`
-- `cursor`: `.cursor/rules/aipermission-operator.mdc`
-- `vscode`: `.github/instructions/aipermission-operator.instructions.md`
-- `windsurf`: `.windsurf/rules/aipermission-operator.md`
-- `antigravity`: `.agents/rules/aipermission-operator.md`
-- `gemini`: `GEMINI.md`
-- `custom`: prints portable Markdown to stdout
+- `codex`: `~/.agents/skills/.../SKILL.md` or `.agents/skills/.../SKILL.md`
+- `claude-code`: `~/.claude/skills/.../SKILL.md` or `.claude/skills/.../SKILL.md`
+- `cursor`: `~/.cursor/skills/.../SKILL.md` or `.cursor/skills/.../SKILL.md`
+- `vscode` / `copilot`: `~/.copilot/skills/.../SKILL.md` or `.github/skills/.../SKILL.md`
+- `windsurf`: `~/.codeium/windsurf/skills/.../SKILL.md` or `.windsurf/skills/.../SKILL.md`
+- `antigravity`: `~/.gemini/config/skills/.../SKILL.md` or `.agents/skills/.../SKILL.md`
+- `antigravity-cli`: `~/.gemini/antigravity-cli/skills/.../SKILL.md` or `.agents/skills/.../SKILL.md`
+- `gemini`: `~/.gemini/skills/.../SKILL.md` or `.gemini/skills/.../SKILL.md`
+- `grok`: `~/.grok/skills/.../SKILL.md` or `.grok/skills/.../SKILL.md`
+- `agents`: `~/.agents/skills/.../SKILL.md` or `.agents/skills/.../SKILL.md`
+- `custom`: prints the canonical skill Markdown to stdout
 
 These instructions teach the agent how to discover connector targets, poll
 `approval_pending` and `running` connector action requests, handle `stale`
 approvals by sending a fresh request, avoid blind retries for `outcome_unknown`,
 write short reasons, use explicit file transfer paths, and avoid printing
 secrets. The default installer uses the
-operator instruction bundled in the npm package; `--source` accepts local file
-paths only and rejects HTTP(S) sources.
+operator skill bundled in the npm package; `--source` accepts local file paths
+only and rejects HTTP(S) sources. The MCP server also publishes a concise
+instruction summary during initialization for clients that surface protocol
+instructions.
+
+Client-specific home overrides are honored where the client documents them:
+`CODEX_HOME` for Codex MCP config, `CLAUDE_CONFIG_DIR` for Claude user skills,
+`COPILOT_HOME` for Copilot config and skills, `GEMINI_CLI_HOME` for Gemini
+config and skills, and `GROK_HOME` for Grok config and skills. An explicit
+`--home` remains the base home directory and takes precedence over those
+environment overrides.
 
 ## Security Boundary
 

package/dist/cli-flags.js

@@ -0,0 +1,81 @@
+const commonPathFlags = {
+  home: "value",
+  "project-dir": "value",
+};
+
+const schemas = {
+  init: {
+    provider: "value",
+    scope: "value",
+    name: "value",
+    "api-url": "value",
+    "token-stdin": "boolean",
+    print: "boolean",
+    force: "boolean",
+    ...commonPathFlags,
+  },
+  setup: {
+    provider: "value",
+    scope: "value",
+    "skill-scope": "value",
+    name: "value",
+    "api-url": "value",
+    "token-stdin": "boolean",
+    print: "boolean",
+    force: "boolean",
+    "skill-source": "value",
+    ...commonPathFlags,
+  },
+  "install-skill": {
+    client: "value",
+    scope: "value",
+    source: "value",
+    ...commonPathFlags,
+  },
+  doctor: {
+    client: "value",
+    provider: "value",
+    scope: "value",
+    "mcp-scope": "value",
+    "skill-scope": "value",
+    name: "value",
+    ...commonPathFlags,
+  },
+};
+
+export function parseCommandFlags(command, argv = []) {
+  const schema = schemas[command];
+  if (!schema) throw new Error(`Unknown command schema: ${command}`);
+  const result = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (!argument.startsWith("--")) throw new Error(`${command} does not accept positional argument: ${argument}`);
+    const separator = argument.indexOf("=");
+    const rawKey = argument.slice(2, separator < 0 ? undefined : separator);
+    if (!rawKey) throw new Error(`${command} received an empty option name`);
+    if (rawKey === "token") throw new Error("--token is not supported; use the hidden prompt or --token-stdin");
+    const kind = schema[rawKey];
+    if (!kind) throw new Error(`Unknown ${command} option: --${rawKey}`);
+    const key = camelCase(rawKey);
+    if (Object.hasOwn(result, key)) throw new Error(`Duplicate ${command} option: --${rawKey}`);
+    const inlineValue = separator < 0 ? undefined : argument.slice(separator + 1);
+    if (kind === "boolean") {
+      result[key] = parseBooleanOption(rawKey, inlineValue);
+      continue;
+    }
+    const value = inlineValue === undefined ? argv[++index] : inlineValue;
+    if (!value || value.startsWith("--")) throw new Error(`--${rawKey} requires a non-empty value`);
+    result[key] = value;
+  }
+  return result;
+}
+
+function parseBooleanOption(key, value) {
+  if (value === undefined || value === "true") return true;
+  if (value === "false") return false;
+  throw new Error(`--${key} accepts only true or false`);
+}
+
+function camelCase(value) {
+  return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}

package/dist/cli.js

@@ -1,13 +1,19 @@
 #!/usr/bin/env node
 
+import { getClientCatalog } from "./client-registry.js";
+
 const command = process.argv[2] || "serve";
 
-if (command === "init") {
-  const { runInit } = await import("./init.js");
-  await runInit(process.argv.slice(3));
+if (command === "init" || command === "setup") {
+  const { runInit, runSetup } = await import("./init.js");
+  await (command === "setup" ? runSetup : runInit)(process.argv.slice(3));
 } else if (command === "install-skill") {
   const { runInstallSkill } = await import("./install-skill.js");
   await runInstallSkill(process.argv.slice(3));
+} else if (command === "doctor") {
+  const { runDoctor } = await import("./doctor.js");
+  const result = await runDoctor(process.argv.slice(3));
+  if (!result.ok) process.exitCode = 1;
 } else if (command === "serve" || command === "server" || command === "start") {
   await import("./server.js");
 } else if (command === "--help" || command === "-h" || command === "help") {
@@ -19,25 +25,50 @@ if (command === "init") {
 }
 
 function printHelp() {
+  const catalog = getClientCatalog();
+  const mcpClients = catalog.filter((client) => client.supportsMCP).map((client) => client.id);
+  const skillClients = catalog.filter((client) => client.supportsSkill).map((client) => client.id);
+  const doctorClients = catalog.filter((client) => client.supportsMCP && client.supportsSkill).map((client) => client.id);
   console.log(`aipermission MCP
 
 Usage:
   aipermission-mcp                 Start the MCP stdio server
   aipermission-mcp init            Configure an AI client interactively
+  aipermission-mcp setup           Configure MCP and install its native skill
   aipermission-mcp install-skill   Install the operator skill for an AI client
+  aipermission-mcp doctor          Check MCP config and native skill paths
 
 Init flags:
-  --provider codex|claude-code|cursor|vscode|windsurf|antigravity|gemini|custom
+  --provider ${[...mcpClients, "custom"].join("|")}
+  --scope user|project
   --name aipermission
   --token-stdin
   --api-url http://localhost:3210
-  --print
+  --print                         Print a token-placeholder preview; change no files
+  --force
+  --home /path/to/home
+  --project-dir /path/to/workspace
+
+Setup-only flags:
+  --skill-scope user|project
+  --skill-source /path/to/SKILL.md  Local file only
 
 Install skill flags:
-  --client codex|claude-code|cursor|vscode|windsurf|antigravity|gemini|custom
+  --client ${[...skillClients, "custom"].join("|")}
+  --scope user|project
+  --home /path/to/home
   --project-dir /path/to/workspace
   --source /path/to/SKILL.md  Local file only; HTTP(S) sources are rejected
 
+Doctor flags:
+  --client ${doctorClients.join("|")}
+  --scope user|project
+  --mcp-scope user|project
+  --skill-scope user|project
+  --name aipermission
+  --home /path/to/home
+  --project-dir /path/to/workspace
+
 Security:
   Use the hidden token prompt or --token-stdin. AIPERMISSION_API_URL must point
   to localhost, 127.0.0.1, or [::1].

package/dist/client-registry.js

@@ -0,0 +1,281 @@
+import os from "node:os";
+import path from "node:path";
+
+const clients = [
+  client("codex", "OpenAI Codex", {
+    mcp: mcpConfig("user", {
+      user: tomlTarget("home", ".codex/config.toml", { homeEnv: "CODEX_HOME", envPath: "config.toml" }),
+      project: tomlTarget("project", ".codex/config.toml"),
+    }),
+    skill: skillConfig("user", {
+      user: skillTarget("home", ".agents/skills"),
+      project: skillTarget("project", ".agents/skills"),
+    }),
+  }),
+  client("claude-code", "Claude Code", {
+    aliases: ["claude", "claude_code"],
+    mcp: mcpConfig("project", {
+      user: jsonTarget("home", ".claude.json", "mcpServers"),
+      project: jsonTarget("project", ".mcp.json", "mcpServers"),
+    }),
+    skill: skillConfig("project", {
+      user: skillTarget("home", ".claude/skills", { homeEnv: "CLAUDE_CONFIG_DIR", envPath: "skills" }),
+      project: skillTarget("project", ".claude/skills"),
+    }),
+  }),
+  client("cursor", "Cursor", {
+    mcp: mcpConfig("project", {
+      user: jsonTarget("home", ".cursor/mcp.json", "mcpServers"),
+      project: jsonTarget("project", ".cursor/mcp.json", "mcpServers"),
+    }),
+    skill: skillConfig("project", {
+      user: skillTarget("home", ".cursor/skills"),
+      project: skillTarget("project", ".cursor/skills"),
+    }),
+  }),
+  client("vscode", "VS Code", {
+    aliases: ["vs-code"],
+    mcp: mcpConfig(
+      "project",
+      { project: jsonTarget("project", ".vscode/mcp.json", "servers") },
+      { printScopes: { user: virtualJSONTarget("servers") } },
+    ),
+    skill: skillConfig("project", {
+      user: skillTarget("home", ".copilot/skills"),
+      project: skillTarget("project", ".github/skills"),
+    }),
+  }),
+  client("copilot", "GitHub Copilot CLI", {
+    aliases: ["copilot-cli", "github-copilot"],
+    mcp: mcpConfig(
+      "user",
+      {
+        user: jsonTarget("home", ".copilot/mcp-config.json", "mcpServers", {
+          homeEnv: "COPILOT_HOME",
+          envPath: "mcp-config.json",
+        }),
+        project: jsonTarget("project", ".mcp.json", "mcpServers"),
+      },
+      { serverExtras: { type: "local", tools: ["*"] } },
+    ),
+    skill: skillConfig("user", {
+      user: skillTarget("home", ".copilot/skills", { homeEnv: "COPILOT_HOME", envPath: "skills" }),
+      project: skillTarget("project", ".github/skills"),
+    }),
+  }),
+  client("windsurf", "Windsurf Cascade (legacy)", {
+    aliases: ["windsurf-legacy", "cascade"],
+    mcp: mcpConfig("user", { user: jsonTarget("home", ".codeium/windsurf/mcp_config.json", "mcpServers") }),
+    skill: skillConfig("user", {
+      user: skillTarget("home", ".codeium/windsurf/skills"),
+      project: skillTarget("project", ".windsurf/skills"),
+    }),
+  }),
+  client("antigravity", "Google Antigravity IDE", {
+    aliases: ["google-antigravity"],
+    mcp: mcpConfig("user", {
+      user: jsonTarget("home", ".gemini/config/mcp_config.json", "mcpServers"),
+      project: jsonTarget("project", ".agents/mcp_config.json", "mcpServers"),
+    }),
+    skill: skillConfig("user", {
+      user: skillTarget("home", ".gemini/config/skills"),
+      project: skillTarget("project", ".agents/skills"),
+    }),
+  }),
+  client("antigravity-cli", "Google Antigravity CLI", {
+    aliases: ["agy"],
+    mcp: mcpConfig("user", {
+      user: jsonTarget("home", ".gemini/antigravity-cli/mcp_config.json", "mcpServers"),
+      project: jsonTarget("project", ".agents/mcp_config.json", "mcpServers"),
+    }),
+    skill: skillConfig("user", {
+      user: skillTarget("home", ".gemini/antigravity-cli/skills"),
+      project: skillTarget("project", ".agents/skills"),
+    }),
+  }),
+  client("gemini", "Gemini CLI", {
+    aliases: ["gemini-cli"],
+    mcp: mcpConfig("user", {
+      user: jsonTarget("home", ".gemini/settings.json", "mcpServers", {
+        homeEnv: "GEMINI_CLI_HOME",
+        envPath: "settings.json",
+      }),
+      project: jsonTarget("project", ".gemini/settings.json", "mcpServers"),
+    }),
+    skill: skillConfig("user", {
+      user: skillTarget("home", ".gemini/skills", { homeEnv: "GEMINI_CLI_HOME", envPath: "skills" }),
+      project: skillTarget("project", ".gemini/skills"),
+    }),
+  }),
+  client("grok", "Grok Build CLI", {
+    aliases: ["grok-build", "grok-cli"],
+    mcp: mcpConfig(
+      "user",
+      {
+        user: tomlTarget("home", ".grok/config.toml", { homeEnv: "GROK_HOME", envPath: "config.toml" }),
+        project: tomlTarget("project", ".grok/config.toml"),
+      },
+      { serverExtras: { startup_timeout_sec: 60 } },
+    ),
+    skill: skillConfig("user", {
+      user: skillTarget("home", ".grok/skills", { homeEnv: "GROK_HOME", envPath: "skills" }),
+      project: skillTarget("project", ".grok/skills"),
+    }),
+  }),
+  client("agents", "Agents standard", {
+    aliases: ["agents-standard"],
+    skill: skillConfig("project", {
+      user: skillTarget("home", ".agents/skills"),
+      project: skillTarget("project", ".agents/skills"),
+    }),
+  }),
+  client("custom", "Custom / copy-paste"),
+];
+
+export const MCP_PROVIDERS = clients
+  .filter((entry) => entry.mcp || entry.id === "custom")
+  .map((entry) => ({ id: entry.id, label: entry.label, description: providerDescription(entry) }));
+
+export function getClient(value) {
+  const normalized = normalizeClientID(value);
+  return clients.find((entry) => entry.id === normalized);
+}
+
+export function getClientCatalog() {
+  return clients.map(({ id, label, aliases, mcp, skill }) => ({
+    id,
+    label,
+    aliases: [...aliases],
+    supportsMCP: Boolean(mcp),
+    supportsSkill: Boolean(skill),
+  }));
+}
+
+export function adaptMCPServerConfig(clientValue, config) {
+  const clientEntry = getClient(clientValue);
+  return { ...config, ...(clientEntry.mcp?.serverExtras || {}) };
+}
+
+export function resolveSkillTarget(clientValue, scopeValue, options = {}) {
+  return resolveTarget(clientValue, "skill", scopeValue, options, "skill");
+}
+
+export function resolveMCPConfigTarget(clientValue, scopeValue, options = {}) {
+  return resolveTarget(clientValue, "mcp", scopeValue, options, "MCP config");
+}
+
+export function resolveMCPPrintTarget(clientValue, scopeValue, options = {}) {
+  const clientEntry = getClient(clientValue);
+  if (!clientEntry.mcp) throw new Error(`${clientEntry.label} does not have an MCP config format.`);
+  const scope = normalizeScope(scopeValue || clientEntry.mcp.defaultScope);
+  const target = clientEntry.mcp.scopes[scope] || clientEntry.mcp.printScopes?.[scope];
+  if (!target) return resolveMCPConfigTarget(clientValue, scope, options);
+  return resolvedTarget(clientEntry, target, scope, options);
+}
+
+export function normalizeClientID(value) {
+  const candidate = String(value || "")
+    .trim()
+    .toLowerCase();
+  const clientEntry = clients.find(
+    (entry) => entry.id === candidate || entry.label.toLowerCase() === candidate || entry.aliases.includes(candidate),
+  );
+  if (!clientEntry) throw new Error(`Unknown client: ${value}`);
+  return clientEntry.id;
+}
+
+export function clientLabel(value) {
+  return getClient(value).label;
+}
+
+export function normalizeScope(value) {
+  const scope = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (scope !== "user" && scope !== "project") throw new Error(`Unknown scope: ${value}. Use user or project.`);
+  return scope;
+}
+
+function resolveTarget(clientValue, capability, scopeValue, options, capabilityLabel) {
+  const clientEntry = getClient(clientValue);
+  const config = clientEntry[capability];
+  if (!config) throw new Error(`${clientEntry.label} does not have an automatic ${capabilityLabel} target.`);
+  const scope = normalizeScope(scopeValue || config.defaultScope);
+  const target = config.scopes[scope];
+  if (!target) {
+    const supported = Object.keys(config.scopes).join(", ");
+    throw new Error(`${clientEntry.label} does not support ${scope} ${capabilityLabel} scope. Supported scopes: ${supported}.`);
+  }
+  return resolvedTarget(clientEntry, target, scope, options);
+}
+
+function resolvedTarget(clientEntry, target, scope, options) {
+  const usesHomeOverride =
+    target.base === "home" && !options.homeDir && Boolean(target.homeEnv && (options.env || process.env)[target.homeEnv]);
+  const root = target.base === "project" ? path.resolve(options.projectDir || process.cwd()) : resolveHomeRoot(target, options);
+  return {
+    ...target,
+    client: clientEntry.id,
+    label: clientEntry.label,
+    scope,
+    path: target.virtual ? "" : path.join(root, ...(usesHomeOverride ? target.envSegments : target.segments)),
+    trustedRoot: root,
+    projectConfig: target.base === "project",
+  };
+}
+
+function resolveHomeRoot(target, options) {
+  if (options.homeDir) return path.resolve(options.homeDir);
+  const overridden = target.homeEnv && (options.env || process.env)[target.homeEnv];
+  return path.resolve(overridden || os.homedir());
+}
+
+function client(id, label, options = {}) {
+  return { id, label, aliases: options.aliases || [], mcp: options.mcp || null, skill: options.skill || null };
+}
+
+function mcpConfig(defaultScope, scopes, options = {}) {
+  return { defaultScope, scopes, printScopes: options.printScopes || {}, serverExtras: options.serverExtras || {} };
+}
+
+function skillConfig(defaultScope, scopes) {
+  return { defaultScope, scopes };
+}
+
+function jsonTarget(base, relativePath, rootKey, options = {}) {
+  return target(base, relativePath, { ...options, format: "json", rootKey });
+}
+
+function virtualJSONTarget(rootKey) {
+  return { base: "home", segments: [], envSegments: [], format: "json", rootKey, virtual: true };
+}
+
+function tomlTarget(base, relativePath, options = {}) {
+  return target(base, relativePath, { ...options, format: "toml", rootKey: "mcp_servers" });
+}
+
+function skillTarget(base, relativePath, options = {}) {
+  const suffix = "aipermission-operator/SKILL.md";
+  return target(base, `${relativePath}/${suffix}`, {
+    ...options,
+    envPath: options.envPath ? `${options.envPath}/${suffix}` : undefined,
+  });
+}
+
+function target(base, relativePath, options = {}) {
+  return {
+    base,
+    segments: relativePath.split("/"),
+    homeEnv: options.homeEnv,
+    envSegments: (options.envPath || relativePath).split("/"),
+    format: options.format,
+    rootKey: options.rootKey,
+  };
+}
+
+function providerDescription(clientEntry) {
+  if (!clientEntry.mcp) return "Prints config snippets only";
+  const targetEntry = clientEntry.mcp.scopes[clientEntry.mcp.defaultScope];
+  const prefix = targetEntry.base === "home" ? "~/" : "./";
+  return `Writes ${prefix}${targetEntry.segments.join("/")} (${clientEntry.mcp.defaultScope})`;
+}