@nestxapp/ato-mcp 1.5.0 → 1.6.0

package/README.md

@@ -12,7 +12,39 @@ key is written once to `<dir>/.env` (never printed).
 npx -y @nestxapp/ato-mcp login --name my-ai --role dev --model claude --dir ./.ato
 ```
 
-Keep `.ato/` and `.mcp.json` out of git: they hold your API key.
+The command prints a code `XXXX-XXXX` and the portal URL, waits for approval (the code is valid 10 minutes,
+polled every 5 seconds) and then writes `<dir>/.env` (one line, `ATO_API_KEY`) and `<dir>/identity.json`. At the
+end it prints the `mcpServers` block to paste into your client, correct for your operating system. The same block is
+available at any time with `npx -y @nestxapp/ato-mcp config` (`--platform win32|darwin|linux` previews another OS).
+
+`login` (the AI side) and **Connect AI** in the portal (the human side, where the name, the real company role and
+the model are adjusted) are the two halves of one flow. The `--role` you pass is only a hint of a role family.
+An AI identity can never approve connections; only a signed-in person can.
+
+Keep `.ato/` and `.mcp.json` out of git: they hold your API key. `login` also creates `<dir>/.gitignore` with `*`,
+so the key cannot be committed by accident.
+
+### Language
+
+Messages of the command line (login, errors, expiry) are shown in English or Spanish. The language is chosen,
+in order, by `--lang es|en`, the `ATO_LANG` variable, `LC_ALL` / `LC_MESSAGES` / `LANG`, and finally the system
+locale; anything else is English. Tool descriptions and API errors are not translated.
+
+```bash
+npx -y @nestxapp/ato-mcp login --name my-ai --lang es
+ATO_LANG=es npx -y @nestxapp/ato-mcp login --name my-ai
+```
+
+## Windows, macOS and Linux
+
+| | Windows | macOS / Linux |
+|---|---|---|
+| `.mcp.json` command | `"command": "cmd", "args": ["/c", "npx", "-y", "@nestxapp/ato-mcp"]` (clients cannot start the `npx.cmd` shim directly) | `"command": "npx", "args": ["-y", "@nestxapp/ato-mcp"]` |
+| Key file `<dir>/.env` | Inherited permissions are replaced by a single grant to your user (`icacls`); a warning is printed if that fails | Mode `0600` (owner only) |
+| `ATO_IDENTITY_DIR` | Absolute path with backslashes (escaped in JSON) | Absolute path; `~` is expanded by ato-mcp |
+
+Use an absolute `ATO_IDENTITY_DIR`: an MCP client may start the server from any folder. Files with a UTF-8 BOM
+or CRLF line endings (common on Windows) are read correctly.
 
 ## Which tools you get
 
@@ -24,13 +56,22 @@ always listed. Servers that do not return permissions yet fall back to the legac
 cannot be read (no key, bad key, network), only the open tools are listed until it works; call `ato_whoami`
 to retry and see the reason.
 
+## Working guide of your role
+
+At start the server also reads your role's working guide (`GET /ai/playbook`: how to do the job with rigor,
+evidence, severities, when to escalate) and sends it as the MCP `instructions` of `initialize`, which clients
+such as Claude Code add to the model's context. Each company can edit its guides in the portal (Team, AI
+guides); otherwise the ATO default applies. `ato_playbook` returns it again at any time. If the guide cannot
+be read at start (no key, network), a short default text is sent instead and the server starts normally.
+
 ## Configuration
 
 | Variable | Meaning |
 |---|---|
 | `ATO_API_KEY` | Plaintext API key of the identity (or name another variable in `ATO_API_KEY_VAR`). If absent, `<identity dir>/.env` is used. |
 | `ATO_API_BASE_URL` | API base including the version prefix, e.g. `https://<your-ato-gateway>/api/v1/ato`. Default `http://localhost:5000/api/v1/ato`. |
-| `ATO_IDENTITY_DIR` | Directory with `identity.json` (and `.env`). Default `./.ato`. |
+| `ATO_IDENTITY_DIR` | Directory with `identity.json` (and `.env`). Default `./.ato`. Prefer an absolute path. |
+| `ATO_LANG` | `es` or `en`: language of the command-line messages. |
 
 ## Claude Code (`.mcp.json` in the repo root)
 
@@ -52,8 +93,7 @@ to retry and see the reason.
 
 ## Claude Desktop (`claude_desktop_config.json`) and Cursor (`.cursor/mcp.json`)
 
-Same `mcpServers` block as above. On Windows, if `npx` is not found by the client, use
-`"command": "cmd"` with `"args": ["/c", "npx", "-y", "@nestxapp/ato-mcp"]`.
+Same `mcpServers` block as above. On Windows use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@nestxapp/ato-mcp"]`.
 
 ## Verify
 

package/i18n.js

@@ -0,0 +1,85 @@
+// Messages of the ato-mcp command line (login, errors, expiry) in English and Spanish. No dependencies.
+//
+// Language: --lang, then ATO_LANG, then LC_ALL / LC_MESSAGES / LANG, then the system locale (Intl), then English.
+// Anything that is not Spanish is shown in English. The MCP tool descriptions and API errors are not translated.
+
+'use strict';
+
+const SUPPORTED = ['en', 'es'];
+
+/** "es_CO.UTF-8", "es-CO", "ES" -> "es"; "C", "POSIX", "" and unsupported languages -> null. */
+function normalize(value) {
+  if (!value || typeof value !== 'string') return null;
+  const tag = value.trim().split(/[.@:]/)[0].split(/[-_]/)[0].toLowerCase();
+  if (!tag || tag === 'c' || tag === 'posix') return null;
+  return SUPPORTED.includes(tag) ? tag : null;
+}
+
+/** Whether a value names a language at all (so "fr" stops the search and falls back to English). */
+function names(value) {
+  if (!value || typeof value !== 'string') return false;
+  const tag = value.trim().split(/[.@:]/)[0].split(/[-_]/)[0].toLowerCase();
+  return !!tag && tag !== 'c' && tag !== 'posix';
+}
+
+function systemLocale() {
+  try { return Intl.DateTimeFormat().resolvedOptions().locale; } catch { return null; }
+}
+
+/** The first source that names a language decides; an unsupported one means English. */
+function detectLang({ flag, env = process.env, locale = systemLocale() } = {}) {
+  for (const value of [flag, env.ATO_LANG, env.LC_ALL, env.LC_MESSAGES, env.LANG, locale]) {
+    if (names(value)) return normalize(value) || 'en';
+  }
+  return 'en';
+}
+
+const MESSAGES = {
+  en: {
+    'login.header': 'Connect this AI to ATO',
+    'login.step_open': 'Open:',
+    'login.step_code': 'Check the code matches:',
+    'login.step_approve': 'Approve it (you choose the agent name and role). It expires in {minutes} minutes.',
+    'login.connected': 'Connected as {handle} ({role}). Key stored in {file} (not printed).',
+    'login.role': 'Role: {role}. {count} permissions; the MCP tools follow them.',
+    'login.restart': 'Make sure .ato/ is in .gitignore, then restart your MCP client so it picks up the key.',
+    'login.config_intro': 'Add this to .mcp.json (Claude Code) or .cursor/mcp.json (Cursor); the key is read from {file}:',
+    'login.acl_warning': 'Could not restrict {file} to your user; check its permissions.',
+    'error.start_failed': 'Could not start the connection (HTTP {status}): {detail}',
+    'error.denied': 'The request was denied in the portal.',
+    'error.expired_used': 'The code expired or was already used. Run login again.',
+    'error.expired_unapproved': 'The code expired before it was approved. Run login again.',
+    'error.unexpected': 'Unexpected response while waiting (HTTP {status}): {detail}',
+    'error.no_details': 'no details',
+    'error.network': 'Could not reach ATO at {url}: {detail}',
+    'config.title': 'MCP client configuration for {platform}:',
+  },
+  es: {
+    'login.header': 'Conectar esta IA a ATO',
+    'login.step_open': 'Abre:',
+    'login.step_code': 'Verifica que el codigo coincida:',
+    'login.step_approve': 'Apruebalo (tu eliges el nombre y el rol del agente). Caduca en {minutes} minutos.',
+    'login.connected': 'Conectado como {handle} ({role}). La clave se guardo en {file} (no se muestra).',
+    'login.role': 'Rol: {role}. {count} permisos; las herramientas del MCP los siguen.',
+    'login.restart': 'Verifica que .ato/ este en .gitignore y reinicia tu cliente MCP para que cargue la clave.',
+    'login.config_intro': 'Agrega esto a .mcp.json (Claude Code) o .cursor/mcp.json (Cursor); la clave se lee de {file}:',
+    'login.acl_warning': 'No se pudo restringir {file} a tu usuario; revisa sus permisos.',
+    'error.start_failed': 'No se pudo iniciar la conexion (HTTP {status}): {detail}',
+    'error.denied': 'La solicitud fue rechazada en el portal.',
+    'error.expired_used': 'El codigo caduco o ya se uso. Ejecuta login de nuevo.',
+    'error.expired_unapproved': 'El codigo caduco antes de ser aprobado. Ejecuta login de nuevo.',
+    'error.unexpected': 'Respuesta inesperada mientras se esperaba (HTTP {status}): {detail}',
+    'error.no_details': 'sin detalles',
+    'error.network': 'No se pudo contactar a ATO en {url}: {detail}',
+    'config.title': 'Configuracion del cliente MCP para {platform}:',
+  },
+};
+
+/** Returns a translator for a language: t('key', { name: value }). Unknown keys come back as the key. */
+function makeT(lang) {
+  const table = MESSAGES[SUPPORTED.includes(lang) ? lang : 'en'];
+  return (key, params = {}) => String(table[key] ?? MESSAGES.en[key] ?? key)
+    .replace(/\{(\w+)\}/g, (m, name) => (name in params ? String(params[name]) : m));
+}
+
+module.exports = { detectLang, makeT, normalize, SUPPORTED, MESSAGES };

package/index.js

@@ -14,25 +14,27 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const platformLib = require('./platform');
 
 const BASE_URL = process.env.ATO_API_BASE_URL || 'http://localhost:5000/api/v1/ato';
 
+// "~" is expanded here because MCP clients pass the value as is. Prefer an absolute path: a client may start the server from any folder.
+const identityDir = () => path.resolve(platformLib.expandHome(process.env.ATO_IDENTITY_DIR || path.join(process.cwd(), '.ato')));
+
 function loadIdentity() {
-  const dir = process.env.ATO_IDENTITY_DIR || path.join(process.cwd(), '.ato');
-  const file = path.join(dir, 'identity.json');
+  const file = path.join(identityDir(), 'identity.json');
   if (fs.existsSync(file)) {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
+    return JSON.parse(platformLib.readText(file));
   }
   return null;
 }
 
 // The key written by `login` lives in <identity dir>/.env (git-ignored); env vars still win.
 function loadDotEnvKey() {
-  const dir = process.env.ATO_IDENTITY_DIR || path.join(process.cwd(), '.ato');
-  const file = path.join(dir, '.env');
+  const file = path.join(identityDir(), '.env');
   if (!fs.existsSync(file)) return null;
-  const line = fs.readFileSync(file, 'utf8').split(/\r?\n/).find(l => l.startsWith('ATO_API_KEY='));
-  return line ? line.slice('ATO_API_KEY='.length).trim() : null;
+  const line = platformLib.readText(file).split(/\r?\n/).find(l => l.startsWith('ATO_API_KEY='));
+  return line ? line.slice('ATO_API_KEY='.length).trim().replace(/^(["'])(.*)\1$/, '$2') : null;
 }
 
 const identity = loadIdentity();
@@ -140,10 +142,17 @@ function summarize(body) {
 const TOOLS = [
   {
     name: 'ato_whoami', roles: ['dev', 'code_review', 'qa', 'pmo'], perms: null,
-    desc: 'Returns the caller identity (AssigneeId/Role/AiModel) resolved from the configured API key.',
+    desc: 'Returns the caller identity (AssigneeId/Role/AiModel) resolved from the configured API key. Before working on any task, read your role working guide (ato_playbook; also sent as this server\'s instructions) and follow it.',
     schema: { type: 'object', properties: {} },
     fn: async () => api('GET', '/ai/whoami'),
   },
+  {
+    name: 'ato_playbook', roles: ['dev', 'code_review', 'qa', 'pmo'], perms: null,
+    desc: 'Returns the working guide of your role (how to do your job with rigor: evidence, severities, when to escalate), as set by your company or the ATO default. Read it before your first task and whenever you are unsure.',
+    schema: { type: 'object', properties: {} },
+    fn: async () => api('GET', '/ai/playbook'),
+    text: (json) => (json && json.data && json.data.content) || null,
+  },
   {
     name: 'ato_resume', roles: ['dev', 'code_review', 'qa', 'pmo'], perms: null,
     desc: 'Resumes this assignee open work: in_progress/changes_requested/qa_rejected tasks + last 10 events.',
@@ -170,7 +179,7 @@ const TOOLS = [
     name: 'ato_tasks', roles: ['dev', 'pmo'], perms: ['task.view'],
     desc: 'List project tasks by status (any lifecycle state — e.g. "done", "in_review,qa_testing" — comma-separated, or omit for all statuses). Same endpoint as ato_backlog but not locked to status=backlog — use it to see what has already shipped, not just what is claimable.',
     schema: { type: 'object', properties: {
-      status: { type: 'string', description: 'Comma-separated TaskStatus names (proposed, backlog, in_progress, blocked, in_review, changes_requested, qa_testing, qa_rejected, done, rejected). Omit for every status.' },
+      status: { type: 'string', description: 'Comma-separated TaskStatus names (proposed, backlog, in_progress, blocked, in_review, changes_requested, qa_testing, qa_rejected, ready_to_deploy, ready_to_close, done, rejected). Omit for every status.' },
       projectId: { type: 'string' },
       priority: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
       type: { type: 'string', enum: ['backend', 'frontend', 'infra', 'docs', 'test', 'bug'] },
@@ -186,7 +195,7 @@ const TOOLS = [
   },
   {
     name: 'ato_task_context', roles: ['dev', 'code_review', 'qa', 'pmo'], perms: null,
-    desc: 'Full detail for a task: acceptance criteria, ContextSnapshot, timeline, evidence, comments.',
+    desc: 'Full detail for a task: acceptance criteria, ContextSnapshot, timeline, evidence, comments, and the project flow: task.workflow (useCodeReview, useQa, useReadyToDeploy, ordered stages) and task.nextStatusOnSubmit (where your submit will send the work).',
     schema: { type: 'object', properties: { taskId: TASK_REF }, required: ['taskId'] },
     fn: async (a) => api('GET', `/ai/tasks/${tid(a)}`),
   },
@@ -210,7 +219,7 @@ const TOOLS = [
   },
   {
     name: 'ato_progress', roles: ['dev'], perms: ['task.progress'],
-    desc: 'Report progress (bumps heartbeat; commitHash required before review).',
+    desc: 'Report progress (bumps heartbeat; a commitHash is required before review unless you submit with noCodeChanges).',
     schema: { type: 'object', properties: { taskId: TASK_REF, summary: { type: 'string' }, commitHash: { type: 'string' }, filesChanged: { type: 'array', items: { type: 'string' } }, tokensEstimateUsed: { type: 'integer' } }, required: ['taskId'] },
     fn: async (a) => api('POST', `/ai/tasks/${tid(a)}/progress`, { body: { summary: a.summary || null, commitHash: a.commitHash || null, filesChanged: a.filesChanged || null, tokensEstimateUsed: a.tokensEstimateUsed ?? null } }),
   },
@@ -234,9 +243,9 @@ const TOOLS = [
   },
   {
     name: 'ato_submit_for_review', roles: ['dev'], perms: ['task.submit'],
-    desc: 'Submit for review (requires VerificationEvidence + a progress event with commitHash).',
-    schema: { type: 'object', properties: { taskId: TASK_REF, verificationEvidence: { type: 'string' } }, required: ['taskId', 'verificationEvidence'] },
-    fn: async (a) => api('PATCH', `/ai/tasks/${tid(a)}/submit-for-review`, { body: { verificationEvidence: a.verificationEvidence } }),
+    desc: 'Submit your finished work (requires verificationEvidence + a progress event with commitHash). When the task truly needed no code change (already implemented, documentation only...), set noCodeChanges=true with a noCodeChangesReason instead of a commit: the reason is shown to QA on the timeline, and verificationEvidence becomes optional. Never declare it to dodge the commit rule. The destination depends on the project flow: in_review when code review is on; otherwise qa_testing when QA is on; otherwise ready_to_deploy or done. Check task.nextStatusOnSubmit in ato_task_context first; the event payload lists skippedStages.',
+    schema: { type: 'object', properties: { taskId: TASK_REF, verificationEvidence: { type: 'string' }, noCodeChanges: { type: 'boolean', description: 'true = the work needed no code change; requires noCodeChangesReason and waives the commitHash rule.' }, noCodeChangesReason: { type: 'string', description: 'Why no commit was needed (max 2000 chars), e.g. "Already implemented in AF-TK-12; only the docs changed". Required when noCodeChanges is true; rejected otherwise.' } }, required: ['taskId'] },
+    fn: async (a) => api('PATCH', `/ai/tasks/${tid(a)}/submit-for-review`, { body: { verificationEvidence: a.verificationEvidence || null, noCodeChanges: a.noCodeChanges === true, noCodeChangesReason: a.noCodeChangesReason || null } }),
   },
   {
     name: 'ato_propose_subtask', roles: ['dev'], perms: ['task.progress'],
@@ -253,13 +262,13 @@ const TOOLS = [
   },
   {
     name: 'ato_review_queue', roles: ['code_review'], perms: ['task.review'],
-    desc: 'Tasks in in_review, oldest first.',
+    desc: 'Tasks in in_review, oldest first. Empty for projects without the code review stage (except tasks that were already in review when it was switched off).',
     schema: { type: 'object', properties: { projectId: { type: 'string' } } },
     fn: async (a) => api('GET', `/review/queue${a.projectId ? `?projectId=${a.projectId}` : ''}`),
   },
   {
     name: 'ato_review_approve', roles: ['code_review'], perms: ['task.review'],
-    desc: 'Approve code review (in_review → qa_testing).',
+    desc: 'Approve code review. The destination depends on the project flow: qa_testing when QA is on; otherwise ready_to_deploy (deploy gate on) or done.',
     schema: { type: 'object', properties: { taskId: TASK_REF, notes: { type: 'string' } }, required: ['taskId'] },
     fn: async (a) => api('PATCH', `/review/tasks/${tid(a)}/approve`, { body: { notes: a.notes || null } }),
   },
@@ -271,16 +280,22 @@ const TOOLS = [
   },
   {
     name: 'ato_qa_queue', roles: ['qa'], perms: ['task.qa'],
-    desc: 'Tasks in qa_testing, oldest first.',
+    desc: 'Tasks in qa_testing, oldest first. Empty for projects without the QA stage (except tasks that were already in QA when it was switched off).',
     schema: { type: 'object', properties: { projectId: { type: 'string' } } },
     fn: async (a) => api('GET', `/qa/queue${a.projectId ? `?projectId=${a.projectId}` : ''}`),
   },
   {
     name: 'ato_qa_approve', roles: ['qa'], perms: ['task.qa'],
-    desc: 'Approve QA (qa_testing → done). QaEvidence must be independently derived.',
+    desc: 'Approve QA (qa_testing → done, or → ready_to_deploy when the project enables the ready-to-deploy gate). QaEvidence must be independently derived.',
     schema: { type: 'object', properties: { taskId: TASK_REF, qaEvidence: { type: 'string' } }, required: ['taskId', 'qaEvidence'] },
     fn: async (a) => api('PATCH', `/qa/tasks/${tid(a)}/approve`, { body: { qaEvidence: a.qaEvidence } }),
   },
+  {
+    name: 'ato_qa_mark_deployed', roles: ['qa'], perms: ['task.qa'],
+    desc: 'Mark a QA-approved task as deployed (ready_to_deploy → done). Only projects with the ready-to-deploy gate have tasks in ready_to_deploy.',
+    schema: { type: 'object', properties: { taskId: TASK_REF }, required: ['taskId'] },
+    fn: async (a) => api('PATCH', `/qa/tasks/${tid(a)}/mark-deployed`),
+  },
   {
     name: 'ato_qa_reject', roles: ['qa'], perms: ['task.qa'],
     desc: 'Reject QA (qa_testing → qa_rejected; qaNotes must describe the observed failure).',
@@ -423,6 +438,40 @@ async function loadAuth() {
   auth.ready = true;
 }
 
+// ── Working guide (playbook) ─────────────────────────────────────────────
+// Fetched once at start with the key and sent as the `instructions` of initialize (InitializeResult.instructions exists
+// since protocol 2024-11-05). Never blocks the start for long and never breaks it: on failure a short default is sent.
+const PLAYBOOK_TIMEOUT_MS = 4000;
+const FALLBACK_INSTRUCTIONS = [
+  'You are an AI teammate in ATO. Your role working guide could not be loaded now; call ato_playbook to read it before you start.',
+  'Until then: read the whole task and its acceptance criteria before acting; back every claim with verifiable evidence (HTTP response,',
+  'database query, log, screenshot); only blockers (security, wrong data, unmet criterion, something broken) send a task back, should/nit',
+  'go as comments; record out-of-scope findings as new tasks; after 2 rounds of changes without closing, escalate to a human with a comment.',
+].join(' ');
+const playbook = { content: null, family: null, customized: false, error: null };
+
+async function loadPlaybook() {
+  if (!apiKey) { playbook.error = 'no API key configured'; return; }
+  try {
+    const res = await fetch(`${BASE_URL}/ai/playbook`, { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(PLAYBOOK_TIMEOUT_MS) });
+    const json = await res.json().catch(() => null);
+    const d = json && json.data;
+    if (res.ok && d && typeof d.content === 'string' && d.content.trim()) {
+      Object.assign(playbook, { content: d.content, family: d.family || null, customized: !!d.isCustomized, error: null });
+    } else {
+      playbook.error = `HTTP ${res.status}${json && json.code ? ' ' + json.code : ''}`;
+    }
+  } catch (e) {
+    playbook.error = e.message;
+  }
+}
+
+function instructions() {
+  if (!playbook.content) return FALLBACK_INSTRUCTIONS;
+  const source = playbook.customized ? 'set by your company' : 'the ATO default';
+  return `You are connected to ATO as the '${playbook.family}' role. Follow this working guide (${source}) on every task; re-read it any time with ato_playbook.\n\n${playbook.content}`;
+}
+
 const allowed = (t) => {
   if (!t.perms) return true;
   if (auth.error) return false;
@@ -448,10 +497,12 @@ async function refreshAfterWhoami(status, json) {
 
 async function handle(msg) {
   if (msg.method === 'initialize') {
+    await Promise.race([playbookReady, new Promise((r) => setTimeout(r, PLAYBOOK_TIMEOUT_MS))]);
     return respond(msg.id, {
       protocolVersion: '2024-11-05',
       capabilities: { tools: { listChanged: true } },
-      serverInfo: { name: 'ato-mcp', version: '1.5.0' },
+      serverInfo: { name: 'ato-mcp', version: '1.6.0' },
+      instructions: instructions(),
     });
   }
   if (msg.method === 'notifications/initialized') return;
@@ -472,7 +523,7 @@ async function handle(msg) {
       const { status, json } = await tool.fn(args || {});
       if (tool.name === 'ato_whoami') await refreshAfterWhoami(status, json);
       const content = [{ type: 'text', text: JSON.stringify({ httpStatus: status, body: json }, null, 2) }];
-      const digest = summarize(json);
+      const digest = tool.text ? tool.text(json) : summarize(json);
       if (digest) content.unshift({ type: 'text', text: digest });
       return respond(msg.id, { content, isError: false });
     } catch (e) {
@@ -483,6 +534,19 @@ async function handle(msg) {
   return respondError(msg.id, -32601, `Method not found: ${msg.method}`);
 }
 
+// `ato-mcp config [--platform win32|darwin|linux] [--lang es|en]` prints the .mcp.json block for this machine (or the given OS).
+if (process.argv[2] === 'config') {
+  const { parseArgs } = require('./login');
+  const { detectLang, makeT } = require('./i18n');
+  const args = parseArgs(process.argv.slice(3));
+  const t = makeT(detectLang({ flag: args.lang }));
+  const target = args.platform || process.platform;
+  const cfg = platformLib.mcpConfig({ baseUrl: BASE_URL, identityDir: identityDir(), platform: target });
+  console.log(t('config.title', { platform: target }));
+  console.log(JSON.stringify(cfg, null, 2));
+  process.exit(0);
+}
+
 // `node index.js login ...` runs the "Connect my AI" device flow instead of the MCP server.
 if (process.argv[2] === 'login') {
   require('./login').run(process.argv.slice(3))
@@ -492,6 +556,7 @@ if (process.argv[2] === 'login') {
 }
 
 loadAuth();
+const playbookReady = loadPlaybook();
 
 let buffer = '';
 process.stdin.setEncoding('utf8');

package/login.js

@@ -12,6 +12,8 @@
 'use strict';
 const fs = require('fs');
 const path = require('path');
+const { detectLang, makeT } = require('./i18n');
+const platformLib = require('./platform');
 
 function parseArgs(argv) {
   const out = {};
@@ -38,31 +40,33 @@ async function post(baseUrl, p, body) {
   return { status: res.status, json };
 }
 
-function writeSecretFile(file, content) {
-  fs.writeFileSync(file, content, { encoding: 'utf8', mode: 0o600 });
-  try { fs.chmodSync(file, 0o600); } catch { /* not supported on this platform */ }
-}
-
 async function run(argv, env = process.env, log = console.log) {
   const args = parseArgs(argv);
+  const t = makeT(detectLang({ flag: args.lang, env }));
   const baseUrl = (args['base-url'] || env.ATO_API_BASE_URL || 'http://localhost:5000/api/v1/ato').replace(/\/+$/, '');
-  const dir = path.resolve(args.dir || env.ATO_IDENTITY_DIR || path.join(process.cwd(), '.ato'));
+  const dir = path.resolve(platformLib.expandHome(args.dir || env.ATO_IDENTITY_DIR || path.join(process.cwd(), '.ato')));
 
-  const start = await post(baseUrl, '/connect/device', {
-    name: args.name || null,
-    role: args.role || null,
-    aiModel: args.model || null,
-  });
+  let start;
+  try {
+    start = await post(baseUrl, '/connect/device', {
+      name: args.name || null,
+      role: args.role || null,
+      aiModel: args.model || null,
+    });
+  } catch (e) {
+    throw new Error(t('error.network', { url: baseUrl, detail: e.message }));
+  }
+  const detail = (r) => (r.json && r.json.message) || t('error.no_details');
   if (start.status !== 200 || !start.json || !start.json.data) {
-    throw new Error(`Could not start the connection (HTTP ${start.status}): ${start.json && start.json.message || 'no details'}`);
+    throw new Error(t('error.start_failed', { status: start.status, detail: detail(start) }));
   }
 
   const d = start.json.data;
   log('');
-  log('  Connect this AI to ATO');
-  log(`  1. Open:   ${d.verificationUriComplete}`);
-  log(`  2. Check the code matches: ${d.userCode}`);
-  log(`  3. Approve it (you choose the agent name and role). It expires in ${Math.round(d.expiresIn / 60)} minutes.`);
+  log(`  ${t('login.header')}`);
+  log(`  1. ${t('login.step_open')}   ${d.verificationUriComplete}`);
+  log(`  2. ${t('login.step_code')} ${d.userCode}`);
+  log(`  3. ${t('login.step_approve', { minutes: Math.round(d.expiresIn / 60) })}`);
   log('');
 
   let interval = Math.max(1, d.interval || 5) * 1000;
@@ -74,36 +78,42 @@ async function run(argv, env = process.env, log = console.log) {
     const code = r.json && r.json.code;
 
     if (r.status === 200 && r.json.data && r.json.data.apiKey) {
-      const t = r.json.data;
+      const tk = r.json.data;
       fs.mkdirSync(dir, { recursive: true });
-      writeSecretFile(path.join(dir, '.env'), `ATO_API_KEY=${t.apiKey}\n`);
+      platformLib.ensureIgnored(dir);
+      const envFile = path.join(dir, '.env');
+      const saved = platformLib.writeSecretFile(envFile, `ATO_API_KEY=${tk.apiKey}\n`);
+      if (!saved.ok) log(`  ${t('login.acl_warning', { file: envFile })}`);
       fs.writeFileSync(path.join(dir, 'identity.json'), JSON.stringify({
-        assigneeId: t.handle,
-        memberId: t.memberId,
-        role: t.role,
-        tenantId: t.tenantId,
+        assigneeId: tk.handle,
+        memberId: tk.memberId,
+        role: tk.role,
+        tenantId: tk.tenantId,
         aiModel: args.model || null,
         apiKeyEnvVar: 'ATO_API_KEY',
       }, null, 2) + '\n', 'utf8');
 
-      log(`  Connected as ${t.handle} (${t.role}). Key stored in ${path.join(dir, '.env')} (not printed).`);
+      log(`  ${t('login.connected', { handle: tk.handle, role: tk.role, file: envFile })}`);
       try {
-        const who = await fetch(`${baseUrl}/ai/whoami`, { headers: { 'X-API-Key': t.apiKey } });
+        const who = await fetch(`${baseUrl}/ai/whoami`, { headers: { 'X-API-Key': tk.apiKey } });
         const wj = who.ok ? await who.json() : null;
         const wd = wj && wj.data;
-        if (wd && Array.isArray(wd.permissions)) log(`  Role: ${wd.roleName || wd.role}. ${wd.permissions.length} permissions; the MCP tools follow them.`);
+        if (wd && Array.isArray(wd.permissions)) log(`  ${t('login.role', { role: wd.roleName || wd.role, count: wd.permissions.length })}`);
       } catch { /* the MCP reads whoami again on start */ }
-      log('  Make sure .ato/ is in .gitignore, then restart your MCP client so it picks up the key.');
-      return t;
+      log(`  ${t('login.restart')}`);
+      log('');
+      log(`  ${t('login.config_intro', { file: envFile })}`);
+      log(JSON.stringify(platformLib.mcpConfig({ baseUrl, identityDir: dir }), null, 2).replace(/^/gm, '  '));
+      return tk;
     }
     if (code === 'CONNECT_AUTHORIZATION_PENDING') continue;
     if (code === 'CONNECT_SLOW_DOWN') { interval += 5000; continue; }
-    if (code === 'CONNECT_ACCESS_DENIED') throw new Error('The request was denied in the portal.');
-    if (code === 'CONNECT_EXPIRED_TOKEN') throw new Error('The code expired or was already used. Run login again.');
+    if (code === 'CONNECT_ACCESS_DENIED') throw new Error(t('error.denied'));
+    if (code === 'CONNECT_EXPIRED_TOKEN') throw new Error(t('error.expired_used'));
     if (r.status === 429) { interval += 5000; continue; }
-    throw new Error(`Unexpected response while waiting (HTTP ${r.status}): ${r.json && r.json.message || 'no details'}`);
+    throw new Error(t('error.unexpected', { status: r.status, detail: detail(r) }));
   }
-  throw new Error('The code expired before it was approved. Run login again.');
+  throw new Error(t('error.expired_unapproved'));
 }
 
 module.exports = { run, parseArgs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestxapp/ato-mcp",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "MCP server for ATO (AI Task Orchestrator): lets an AI client take, work and report tasks.",
   "license": "MIT",
   "main": "index.js",
@@ -10,6 +10,8 @@
   "files": [
     "index.js",
     "login.js",
+    "i18n.js",
+    "platform.js",
     "LICENSE",
     "README.md"
   ],

package/platform.js

@@ -0,0 +1,75 @@
+// Operating-system details of ato-mcp: how to launch it from an MCP client, where it keeps things and how the key file is protected.
+// Everything takes the platform as a parameter (default process.platform) so it can be exercised for any OS from any OS.
+
+'use strict';
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const PACKAGE = '@nestxapp/ato-mcp';
+
+/** Path module of the target platform (so Windows paths can be built and checked from Linux and the other way around). */
+const pathFor = (platform) => (platform === 'win32' ? path.win32 : path.posix);
+
+/** "~" and "~/x" -> home directory. MCP clients do not expand it, shells do not either inside JSON. */
+function expandHome(p, home = os.homedir()) {
+  if (typeof p !== 'string') return p;
+  return p === '~' || /^~[\\/]/.test(p) ? path.join(home, p.slice(1)) : p;
+}
+
+/**
+ * How an MCP client must launch the server. On Windows `npx` is a .cmd shim that clients cannot start directly,
+ * so it goes through cmd; macOS and Linux run npx as is.
+ */
+function launchCommand(platform = process.platform) {
+  return platform === 'win32'
+    ? { command: 'cmd', args: ['/c', 'npx', '-y', PACKAGE] }
+    : { command: 'npx', args: ['-y', PACKAGE] };
+}
+
+/**
+ * The "mcpServers" block for .mcp.json / .cursor/mcp.json. The key itself is not included: it stays in
+ * <identityDir>/.env, which the server reads.
+ */
+function mcpConfig({ baseUrl, identityDir, platform = process.platform }) {
+  const p = pathFor(platform);
+  // A path of another OS cannot be resolved here: show a placeholder to fill in instead of a wrong path.
+  const dir = p.isAbsolute(identityDir) ? p.normalize(identityDir) : platform === process.platform ? p.resolve(identityDir) : '<absolute-path-to-repo>/.ato';
+  const env = { ATO_API_BASE_URL: baseUrl, ATO_IDENTITY_DIR: dir };
+  return { mcpServers: { ato: { ...launchCommand(platform), env } } };
+}
+
+/** The identity folder is git-ignored by itself: a `*` .gitignore inside it keeps the key out of commits. */
+function ensureIgnored(dir) {
+  const file = path.join(dir, '.gitignore');
+  if (!fs.existsSync(file)) fs.writeFileSync(file, '*\n', 'utf8');
+}
+
+/**
+ * Writes a file only its owner can read. POSIX: mode 0600 (also fixed afterwards in case the file existed).
+ * Windows has no mode bits: the inherited access list is replaced with a single grant to the current user
+ * (icacls). Returns { ok, how }; ok is false when Windows could not restrict it (the caller warns, the key is still written).
+ */
+function writeSecretFile(file, content, { platform = process.platform, run = execFileSync, user = safeUser() } = {}) {
+  fs.writeFileSync(file, content, { encoding: 'utf8', mode: 0o600 });
+  if (platform === 'win32') {
+    if (!user) return { ok: false, how: 'icacls' };
+    try {
+      run('icacls', [file, '/inheritance:r', '/grant:r', `${user}:F`], { stdio: 'ignore', windowsHide: true });
+      return { ok: true, how: 'icacls' };
+    } catch {
+      return { ok: false, how: 'icacls' };
+    }
+  }
+  try { fs.chmodSync(file, 0o600); return { ok: true, how: 'chmod' }; } catch { return { ok: false, how: 'chmod' }; }
+}
+
+function safeUser() {
+  try { return os.userInfo().username; } catch { return process.env.USERNAME || null; }
+}
+
+/** Text of a file without the UTF-8 BOM some Windows editors add. */
+const readText = (file) => fs.readFileSync(file, 'utf8').replace(/^/, '');
+
+module.exports = { PACKAGE, pathFor, expandHome, launchCommand, mcpConfig, ensureIgnored, writeSecretFile, readText };