@nestxapp/ato-mcp 0.0.0-stage → 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NestX Software
+
+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,108 @@
-# Temporary Holding Version
+# @nestxapp/ato-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.
+MCP server for ATO (AI Task Orchestrator). It exposes the ATO tools valid for one role identity
+(dev, qa, ...) to any MCP client. No dependencies; requires Node 18 or newer.
+
+## Connect your AI
+
+The simplest way is the device login: it asks ATO for a code, you approve it in the portal, and the
+key is written once to `<dir>/.env` (never printed).
+
+```bash
+npx -y @nestxapp/ato-mcp login --name my-ai --role dev --model claude --dir ./.ato
+```
+
+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
+
+At start the server asks ATO who you are (`whoami`) and lists only the tools your role's permissions allow
+(for example `task.claim` for `ato_claim`, `task.review` for the review tools, `proposal.decide` for
+approving proposals). Roles are configured per company, so two AIs with different roles see different tools.
+Tools open to every identity (`ato_whoami`, `ato_resume`, `ato_task_context`, comments, attachment reads) are
+always listed. Servers that do not return permissions yet fall back to the legacy role families. If `whoami`
+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`. Prefer an absolute path. |
+| `ATO_LANG` | `es` or `en`: language of the command-line messages. |
+
+## Claude Code (`.mcp.json` in the repo root)
+
+```json
+{
+  "mcpServers": {
+    "ato": {
+      "command": "npx",
+      "args": ["-y", "@nestxapp/ato-mcp"],
+      "env": {
+        "ATO_API_KEY": "<your-api-key>",
+        "ATO_API_BASE_URL": "https://<your-ato-gateway>/api/v1/ato",
+        "ATO_IDENTITY_DIR": "<absolute-path-to-repo>/.ato"
+      }
+    }
+  }
+}
+```
+
+## Claude Desktop (`claude_desktop_config.json`) and Cursor (`.cursor/mcp.json`)
+
+Same `mcpServers` block as above. On Windows use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@nestxapp/ato-mcp"]`.
+
+## Verify
+
+Restart the client; the `ato` server should list its tools (`ato_*`). The server speaks MCP over
+stdio, so running it by hand just waits for input.
+
+Releasing: push a tag `mcp-vX.Y.Z` matching the `version` in `package.json` (see
+`.github/workflows/publish-ato-mcp.yml`).
+
+## License
+
+MIT, see `LICENSE`. This license covers only this MCP client package.

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

@@ -0,0 +1,573 @@
+#!/usr/bin/env node
+// ato-mcp — MCP server for ATO. One instance per role identity.
+// Reads .ato/identity.json (assigneeId/role/apiKeyEnvVar) + the API key from env, asks whoami for the
+// identity's permissions and exposes ONLY the tools those permissions allow. Talks to the ATO REST API over HTTP with X-API-Key.
+//
+// Config via env:
+//   ATO_IDENTITY_DIR   (dir containing identity.json, default cwd/.ato)
+//   ATO_API_KEY        (the role's plaintext key; or set ATO_API_KEY_VAR to name an env var)
+//   ATO_API_BASE_URL   (full API base incl. version prefix — gateway …/api/v1/ato, or raw …:5008/api/v1)
+//
+// Connect an AI without copying keys by hand:  node index.js login --name claude-dev-1 --role dev --model claude
+
+'use strict';
+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 file = path.join(identityDir(), 'identity.json');
+  if (fs.existsSync(file)) {
+    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 file = path.join(identityDir(), '.env');
+  if (!fs.existsSync(file)) return 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();
+const apiKey = process.env.ATO_API_KEY || (identity && identity.apiKeyEnvVar ? process.env[identity.apiKeyEnvVar] : null) || loadDotEnvKey() || '';
+const role = (identity && identity.role) || process.env.ATO_ROLE || '';
+
+async function api(method, p, { body } = {}) {
+  const res = await fetch(`${BASE_URL}${p}`, {
+    method,
+    headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json; try { json = JSON.parse(text); } catch { json = { raw: text }; }
+  return { status: res.status, json };
+}
+
+// Evidence files (v3.2): multipart upload and binary download, so these two bypass the JSON-only api() helper.
+const ATTACH_TYPES = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'pdf', 'txt', 'csv', 'json', 'zip'];
+const ATTACH_MAX_BYTES = 10 * 1024 * 1024;
+async function uploadFile(p, filePath, fields) {
+  const abs = path.resolve(String(filePath));
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) throw new Error(`filePath: '${abs}' is not a file.`);
+  const ext = path.extname(abs).slice(1).toLowerCase();
+  if (!ATTACH_TYPES.includes(ext)) throw new Error(`filePath: '.${ext}' is not allowed. Allowed: ${ATTACH_TYPES.join(', ')}.`);
+  const size = fs.statSync(abs).size;
+  if (size === 0) throw new Error('filePath: the file is empty.');
+  if (size > ATTACH_MAX_BYTES) throw new Error(`filePath: ${size} bytes exceeds the 10 MB limit.`);
+  const form = new FormData();
+  form.append('file', new Blob([fs.readFileSync(abs)]), path.basename(abs));
+  for (const [k, v] of Object.entries(fields)) if (v) form.append(k, v);
+  const res = await fetch(`${BASE_URL}${p}`, { method: 'POST', headers: { 'X-API-Key': apiKey }, body: form });
+  const text = await res.text();
+  let json; try { json = JSON.parse(text); } catch { json = { raw: text }; }
+  return { status: res.status, json };
+}
+async function downloadFile(fileId, dir) {
+  const res = await fetch(`${BASE_URL}/attachments/${encodeURIComponent(String(fileId).trim())}/content`, { headers: { 'X-API-Key': apiKey } });
+  if (!res.ok) { const t = await res.text(); let json; try { json = JSON.parse(t); } catch { json = { raw: t }; } return { status: res.status, json }; }
+  const disposition = res.headers.get('content-disposition') || '';
+  const star = /filename\*=UTF-8''([^;]+)/i.exec(disposition);
+  const name = path.basename(star ? decodeURIComponent(star[1]) : `${fileId}`);
+  const target = path.join(dir || path.join(os.tmpdir(), 'ato-attachments'), String(fileId), name);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.writeFileSync(target, Buffer.from(await res.arrayBuffer()));
+  return { status: 200, json: { savedTo: target, contentType: res.headers.get('content-type'), bytes: fs.statSync(target).size } };
+}
+
+// A task reference is the task GUID, its typed key ("AF-HU-12": project, kind prefix EP/HU/TK/ST/BG/TS, number per kind)
+// or the legacy project-wide key ("AF-80", still resolves). The API resolves all three on every {id} route, so the value is
+// only URL-encoded here. A typed key stops resolving if the task's kind changes (it gets a new number); the GUID never changes.
+const TASK_REF = { type: 'string', description: 'Task key, typed (e.g. AF-HU-12) or legacy (e.g. AF-80), or GUID.' };
+// Request bodies are deserialized as Guid: only {id} route segments resolve keys server-side, so the bodies below take GUIDs.
+// Tools that accept a TASK_REF in a body field resolve it here first (GET /tasks/{ref}).
+const BODY_REF = { type: 'string', description: 'Task key, typed (e.g. AF-HU-12) or legacy (e.g. AF-80), or GUID (resolved by this MCP before sending).' };
+const GUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function resolveId(ref, field) {
+  const v = String(ref).trim();
+  if (GUID_RE.test(v)) return v;
+  const { status, json } = await api('GET', `/tasks/${encodeURIComponent(v)}`);
+  const id = json && json.data && json.data.id;
+  if (status !== 200 || !id) throw new Error(`${field}: cannot resolve task reference '${v}' (HTTP ${status}${json && json.code ? ' ' + json.code : ''}).`);
+  return id;
+}
+const BUG_NOTE = ' kind=bug requires a parent that is an epic, or a story/task whose parent is an epic; otherwise the API answers 422 BUG_REQUIRES_EPIC (returned unchanged in the tool output).';
+// Planning fields shared by create, update and estimate. Estimate is in hours (decimal, e.g. 2.5); dates are YYYY-MM-DD.
+const PLANNING = {
+  estimate: { type: 'number', description: 'Estimated effort in hours (e.g. 4 or 2.5).' },
+  startDate: { type: 'string', description: 'Planned start, YYYY-MM-DD.' },
+  dueDate: { type: 'string', description: 'Planned end, YYYY-MM-DD (on or after startDate).' },
+};
+const planningBody = (a) => {
+  const b = {};
+  if (a.estimate !== undefined && a.estimate !== null) b.estimate = a.estimate;
+  if (a.startDate) b.startDate = a.startDate;
+  if (a.dueDate) b.dueDate = a.dueDate;
+  return b;
+};
+const KINDS = ['epic', 'story', 'task', 'subtask', 'bug', 'test'];
+const tid = (a) => encodeURIComponent(String(a.taskId).trim());
+
+// One-line digest of a task DTO, prepended to tool output so key/kind/labels/reviewRounds are
+// visible without reading the JSON. v2 fields are optional: a v1 server simply omits them.
+function taskLine(t) {
+  if (!t || typeof t !== 'object' || !t.title || !t.status) return null;
+  const parts = [t.key || t.id, `[${t.status}]`];
+  if (t.legacyKey && t.legacyKey !== t.key) parts.push(`(also ${t.legacyKey})`);
+  if (t.kind) parts.push(`kind=${t.kind}`);
+  if (Array.isArray(t.labels) && t.labels.length) parts.push(`labels=${t.labels.join(',')}`);
+  if (typeof t.reviewRounds === 'number') parts.push(`reviewRounds=${t.reviewRounds}`);
+  parts.push(`- ${t.title}`);
+  return parts.join(' ');
+}
+
+function summarize(body) {
+  const data = body && typeof body === 'object' && 'data' in body ? body.data : body;
+  const items = Array.isArray(data) ? data : [data];
+  const lines = items.map(taskLine).filter(Boolean);
+  return lines.length ? lines.join('\n') : null;
+}
+
+// ── Tool registry: name -> { desc, schema, perms, roles, fn } ──────────────────
+// perms: capabilities (any one is enough; null = open to every identity). roles: legacy role families, only used
+// as a fallback when the server does not return `permissions` from whoami (older ATO servers).
+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. 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.',
+    schema: { type: 'object', properties: {} },
+    fn: async () => api('GET', '/ai/resume'),
+  },
+  {
+    name: 'ato_backlog', roles: ['dev', 'pmo'], perms: ['task.view'],
+    desc: 'List the project backlog (status=backlog). Returns each task with its key (e.g. AF-TK-42), id, rowVersion, projectId, epicLabel, priority and title so you can pick work and claim it with ato_claim.',
+    schema: { type: 'object', properties: {
+      projectId: { type: 'string' },
+      priority: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
+      type: { type: 'string', enum: ['backend', 'frontend', 'infra', 'docs', 'test', 'bug'] },
+    } },
+    fn: async (a) => {
+      const q = new URLSearchParams({ status: 'backlog' });
+      if (a.projectId) q.set('projectId', a.projectId);
+      if (a.priority) q.set('priority', a.priority);
+      if (a.type) q.set('type', a.type);
+      return api('GET', `/ai/tasks?${q.toString()}`);
+    },
+  },
+  {
+    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, 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'] },
+    } },
+    fn: async (a) => {
+      const q = new URLSearchParams();
+      if (a.status) q.set('status', a.status);
+      if (a.projectId) q.set('projectId', a.projectId);
+      if (a.priority) q.set('priority', a.priority);
+      if (a.type) q.set('type', a.type);
+      return api('GET', `/ai/tasks?${q.toString()}`);
+    },
+  },
+  {
+    name: 'ato_task_context', roles: ['dev', 'code_review', 'qa', 'pmo'], perms: null,
+    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)}`),
+  },
+  {
+    name: 'ato_comment', roles: ['dev', 'code_review', 'qa', 'pmo'], perms: null,
+    desc: 'Post a comment/suggestion/question/objection/reply on a task (never changes status).',
+    schema: { type: 'object', properties: { taskId: TASK_REF, body: { type: 'string' }, kind: { type: 'string', enum: ['suggestion', 'question', 'objection', 'reply'] }, parentCommentId: { type: 'string' } }, required: ['taskId', 'body', 'kind'] },
+    fn: async (a) => api('POST', `/tasks/${tid(a)}/comments`, { body: { body: a.body, kind: a.kind, parentCommentId: a.parentCommentId || null } }),
+  },
+  {
+    name: 'ato_debate', roles: ['dev', 'code_review', 'qa', 'pmo'], perms: null,
+    desc: 'List the comment/debate thread for a task.',
+    schema: { type: 'object', properties: { taskId: TASK_REF }, required: ['taskId'] },
+    fn: async (a) => api('GET', `/tasks/${tid(a)}/comments`),
+  },
+  {
+    name: 'ato_claim', roles: ['dev'], perms: ['task.claim'],
+    desc: 'Atomically claim a backlog task. Second concurrent claim gets a clean 409.',
+    schema: { type: 'object', properties: { taskId: TASK_REF, rowVersion: { type: 'string' }, chatLabel: { type: 'string' } }, required: ['taskId', 'rowVersion'] },
+    fn: async (a) => api('PATCH', `/ai/tasks/${tid(a)}/claim`, { body: { rowVersion: a.rowVersion, chatLabel: a.chatLabel || null } }),
+  },
+  {
+    name: 'ato_progress', roles: ['dev'], perms: ['task.progress'],
+    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 } }),
+  },
+  {
+    name: 'ato_handoff', roles: ['dev'], perms: ['task.progress'],
+    desc: 'Hand off context (does NOT release the claim).',
+    schema: { type: 'object', properties: { taskId: TASK_REF, pendingSteps: { type: 'array', items: { type: 'string' } }, reason: { type: 'string' }, contextSnapshot: { type: 'object' } }, required: ['taskId'] },
+    fn: async (a) => api('POST', `/ai/tasks/${tid(a)}/handoff`, { body: { pendingSteps: a.pendingSteps || null, reason: a.reason || 'session_end', contextSnapshot: a.contextSnapshot || null } }),
+  },
+  {
+    name: 'ato_block', roles: ['dev'], perms: ['task.progress'],
+    desc: 'Block a task (in_progress → blocked).',
+    schema: { type: 'object', properties: { taskId: TASK_REF, reason: { type: 'string' }, blockedByTaskIds: { type: 'array', items: BODY_REF } }, required: ['taskId'] },
+    fn: async (a) => api('PATCH', `/ai/tasks/${tid(a)}/block`, { body: { reason: a.reason || null, blockedByTaskIds: a.blockedByTaskIds ? await Promise.all(a.blockedByTaskIds.map(r => resolveId(r, 'blockedByTaskIds'))) : null } }),
+  },
+  {
+    name: 'ato_unblock', roles: ['dev'], perms: ['task.progress'],
+    desc: 'Unblock a task (blocked → in_progress).',
+    schema: { type: 'object', properties: { taskId: TASK_REF }, required: ['taskId'] },
+    fn: async (a) => api('PATCH', `/ai/tasks/${tid(a)}/unblock`, { body: {} }),
+  },
+  {
+    name: 'ato_submit_for_review', roles: ['dev'], perms: ['task.submit'],
+    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'],
+    desc: 'Propose a subtask (proposed status; PMO approves). Never creates a task directly. taskId is the parent.' + BUG_NOTE,
+    schema: { type: 'object', properties: { taskId: TASK_REF, title: { type: 'string' }, type: { type: 'string', enum: ['backend', 'frontend', 'infra', 'docs', 'test', 'bug'], description: 'Legacy discipline, kept for compatibility. Prefer kind + labels.' }, kind: { type: 'string', enum: KINDS }, labels: { type: 'array', items: { type: 'string' } }, priority: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] }, description: { type: 'string' }, reason: { type: 'string' } }, required: ['taskId', 'title', 'priority'] },
+    fn: async (a) => {
+      if (!a.type && !a.kind) throw new Error('Provide kind (v2) or type (legacy).');
+      const body = { title: a.title, priority: a.priority, description: a.description || null, reason: a.reason || null };
+      if (a.type) body.type = a.type;
+      if (a.kind) body.kind = a.kind;
+      if (a.labels) body.labels = a.labels;
+      return api('POST', `/ai/tasks/${tid(a)}/propose-subtask`, { body });
+    },
+  },
+  {
+    name: 'ato_review_queue', roles: ['code_review'], perms: ['task.review'],
+    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. 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 } }),
+  },
+  {
+    name: 'ato_review_request_changes', roles: ['code_review'], perms: ['task.review'],
+    desc: 'Request changes (in_review → changes_requested; notes must name file/line/problem).',
+    schema: { type: 'object', properties: { taskId: TASK_REF, notes: { type: 'string' } }, required: ['taskId', 'notes'] },
+    fn: async (a) => api('PATCH', `/review/tasks/${tid(a)}/request-changes`, { body: { notes: a.notes } }),
+  },
+  {
+    name: 'ato_qa_queue', roles: ['qa'], perms: ['task.qa'],
+    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, 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).',
+    schema: { type: 'object', properties: { taskId: TASK_REF, qaNotes: { type: 'string' } }, required: ['taskId', 'qaNotes'] },
+    fn: async (a) => api('PATCH', `/qa/tasks/${tid(a)}/reject`, { body: { qaNotes: a.qaNotes } }),
+  },
+  {
+    name: 'ato_qa_claim_test', roles: ['qa'], perms: ['task.qa'],
+    desc: 'Claim a Type=Test task for QA (backlog → in_progress). QA owns test tasks end to end — no dev/code review. Rejects non-Test tasks with TASK_TYPE_MISMATCH.',
+    schema: { type: 'object', properties: { taskId: TASK_REF, rowVersion: { type: 'string' }, chatLabel: { type: 'string' } }, required: ['taskId', 'rowVersion'] },
+    fn: async (a) => api('PATCH', `/qa/tasks/${tid(a)}/claim-test`, { body: { rowVersion: a.rowVersion, chatLabel: a.chatLabel || null } }),
+  },
+  {
+    name: 'ato_qa_start_testing', roles: ['qa'], perms: ['task.qa'],
+    desc: 'Move a Type=Test task straight to QA testing (in_progress → qa_testing), skipping code review (VerificationEvidence/CodeReviewStatus stay null). Rejects non-Test tasks with TASK_TYPE_MISMATCH.',
+    schema: { type: 'object', properties: { taskId: TASK_REF }, required: ['taskId'] },
+    fn: async (a) => api('PATCH', `/qa/tasks/${tid(a)}/start-testing`, { body: {} }),
+  },
+  {
+    name: 'ato_pmo_create_task', roles: ['pmo'], perms: ['task.create'],
+    desc: 'Create a task directly (subject to the MVP gate). Pass kind (+ labels) for the v2 model, or type for the legacy discipline; at least one of kind/type is required. parentTaskId accepts a key or GUID.' + BUG_NOTE,
+    schema: { type: 'object', properties: { projectId: { type: 'string' }, title: { type: 'string' }, type: { type: 'string', enum: ['backend', 'frontend', 'infra', 'docs', 'test', 'bug'], description: 'Legacy discipline, kept for compatibility. Prefer kind + labels.' }, kind: { type: 'string', enum: KINDS }, labels: { type: 'array', items: { type: 'string' }, description: 'Discipline and free labels, e.g. ["backend"].' }, priority: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] }, sprintId: { type: 'string' }, epicLabel: { type: 'string' }, parentTaskId: BODY_REF, description: { type: 'string' }, acceptanceCriteria: { type: 'string' }, isUrgentOverride: { type: 'boolean' }, humanApprovedBy: { type: 'string' }, ...PLANNING, assigneeMemberId: { type: 'string', description: 'Member id (GUID) responsible for the task; optional.' } }, required: ['projectId', 'title', 'priority'] },
+    fn: async (a) => {
+      if (!a.type && !a.kind) throw new Error('Provide kind (v2) or type (legacy).');
+      const body = { projectId: a.projectId, title: a.title, priority: a.priority, sprintId: a.sprintId || null, epicLabel: a.epicLabel || null, description: a.description || null, acceptanceCriteria: a.acceptanceCriteria || null, isUrgentOverride: !!a.isUrgentOverride, humanApprovedBy: a.humanApprovedBy || null };
+      if (a.type) body.type = a.type;
+      if (a.kind) body.kind = a.kind;
+      if (a.labels) body.labels = a.labels;
+      if (a.parentTaskId) body.parentTaskId = await resolveId(a.parentTaskId, 'parentTaskId');
+      Object.assign(body, planningBody(a));
+      if (a.assigneeMemberId) body.assigneeMemberId = a.assigneeMemberId;
+      return api('POST', '/pmo/tasks', { body });
+    },
+  },
+  {
+    name: 'ato_pmo_approve_proposal', roles: ['pmo'], perms: ['proposal.decide'],
+    desc: 'Approve a dev proposal (proposed → backlog).',
+    schema: { type: 'object', properties: { taskId: TASK_REF }, required: ['taskId'] },
+    fn: async (a) => api('PATCH', `/pmo/tasks/${tid(a)}/approve-proposal`, { body: {} }),
+  },
+  {
+    name: 'ato_pmo_reject_proposal', roles: ['pmo'], perms: ['proposal.decide'],
+    desc: 'Reject a dev proposal (proposed → rejected).',
+    schema: { type: 'object', properties: { taskId: TASK_REF }, required: ['taskId'] },
+    fn: async (a) => api('PATCH', `/pmo/tasks/${tid(a)}/reject-proposal`, { body: {} }),
+  },
+  {
+    name: 'ato_update_task', roles: ['pmo'], perms: ['task.edit'],
+    desc: 'Edit a task (pmo/tech_lead): title, description, acceptance criteria, priority, kind, labels, parent (epic/story), sprint, assignee, project, estimate (hours) and planned dates. Only the fields you pass change; the history records one "updated" event.' + BUG_NOTE,
+    schema: { type: 'object', properties: {
+      taskId: TASK_REF,
+      title: { type: 'string' }, description: { type: 'string' }, acceptanceCriteria: { type: 'string' },
+      priority: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
+      kind: { type: 'string', enum: KINDS }, labels: { type: 'array', items: { type: 'string' } },
+      parentTaskId: BODY_REF, clearParent: { type: 'boolean' },
+      sprintId: { type: 'string' }, clearSprint: { type: 'boolean' },
+      assigneeMemberId: { type: 'string', description: 'Member id (GUID).' }, clearAssignee: { type: 'boolean' },
+      projectId: { type: 'string', description: 'Move to another project (no children, not done).' },
+      ...PLANNING,
+    }, required: ['taskId'] },
+    fn: async (a) => {
+      const body = {};
+      for (const k of ['title', 'description', 'acceptanceCriteria', 'priority', 'kind', 'labels', 'clearParent', 'sprintId', 'clearSprint', 'assigneeMemberId', 'clearAssignee', 'projectId'])
+        if (a[k] !== undefined && a[k] !== null) body[k] = a[k];
+      if (a.parentTaskId) body.parentTaskId = await resolveId(a.parentTaskId, 'parentTaskId');
+      Object.assign(body, planningBody(a));
+      return api('PUT', `/tasks/${tid(a)}`, { body });
+    },
+  },
+  {
+    name: 'ato_estimate', roles: ['dev', 'pmo'], perms: ['task.edit', 'task.claim'],
+    desc: 'Plan a task you own (or any task as pmo/tech_lead): estimated effort in hours and planned start/end dates. Use it right after claiming a task to say how long it will take.',
+    schema: { type: 'object', properties: { taskId: TASK_REF, ...PLANNING }, required: ['taskId'] },
+    fn: async (a) => {
+      const body = planningBody(a);
+      if (Object.keys(body).length === 0) throw new Error('Pass estimate, startDate and/or dueDate.');
+      return api('PATCH', `/tasks/${tid(a)}/estimate`, { body });
+    },
+  },
+  {
+    name: 'ato_pmo_backlog_health', roles: ['pmo'], perms: ['task.view'],
+    desc: 'Backlog health: ready backlog vs active dev capacity.',
+    schema: { type: 'object', properties: { projectId: { type: 'string' } }, required: ['projectId'] },
+    fn: async (a) => api('GET', `/pmo/projects/${a.projectId}/backlog-health`),
+  },
+  {
+    name: 'ato_pmo_link_dependency', roles: ['pmo'], perms: ['task.edit'],
+    desc: 'Declares that a backlog/proposed task depends on (is blocked by) another task (BlockedByTaskIds). Only applies to tasks in backlog/proposed.',
+    schema: { type: 'object', properties: { taskId: TASK_REF, blockedByTaskIds: { type: 'array', items: BODY_REF } }, required: ['taskId', 'blockedByTaskIds'] },
+    fn: async (a) => api('PATCH', `/pmo/tasks/${tid(a)}/blocked-by`, { body: { blockedByTaskIds: await Promise.all(a.blockedByTaskIds.map(r => resolveId(r, 'blockedByTaskIds'))) } }),
+  },
+  {
+    name: 'ato_attach_evidence', roles: ['dev', 'code_review', 'qa', 'pmo'], perms: ['attachment.upload'],
+    desc: 'Attach a local file to a task as evidence (a QA screenshot, a test log as .txt, a spec mockup). Types: png, jpg, gif, webp, pdf, txt, csv, json, zip; at most 10 MB per file and 30 per task. purpose: evidence (default), spec or other; reviewId optionally ties the file to a review round of the same task. Returns the stored attachment (fileId, url).',
+    schema: { type: 'object', properties: {
+      taskId: TASK_REF,
+      filePath: { type: 'string', description: 'Path of the local file to upload.' },
+      purpose: { type: 'string', enum: ['evidence', 'spec', 'other'] },
+      reviewId: { type: 'string', description: 'Optional review (code review or QA round) of the same task this file backs.' },
+    }, required: ['taskId', 'filePath'] },
+    fn: async (a) => uploadFile(`/tasks/${tid(a)}/attachments`, a.filePath, { purpose: a.purpose || 'evidence', reviewId: a.reviewId }),
+  },
+  {
+    name: 'ato_attachments', roles: ['dev', 'code_review', 'qa', 'pmo'], perms: null,
+    desc: 'List the files attached to a task (name, type, size, purpose, who uploaded it, fileId). Use ato_fetch_attachment to read one.',
+    schema: { type: 'object', properties: { taskId: TASK_REF }, required: ['taskId'] },
+    fn: async (a) => api('GET', `/tasks/${tid(a)}/attachments`),
+  },
+  {
+    name: 'ato_fetch_attachment', roles: ['dev', 'code_review', 'qa', 'pmo'], perms: null,
+    desc: 'Download an attached file by fileId into a local folder (default: a temp folder) and return its path, so you can open a mockup or read an evidence file.',
+    schema: { type: 'object', properties: { fileId: { type: 'string' }, saveDir: { type: 'string', description: 'Optional folder to save into.' } }, required: ['fileId'] },
+    fn: async (a) => downloadFile(a.fileId, a.saveDir),
+  },
+];
+
+// ── Permission state ─────────────────────────────────────────────────────
+// Tools are filtered by the capabilities whoami returns (roles are configurable per company, so role names
+// mean nothing here). Servers that do not return `permissions` get the legacy role mapping (tech_lead = all).
+// If whoami cannot be read the identity is unknown: fail closed, only the open tools (perms: null) are listed.
+const auth = { ready: false, permissions: null, role, roleName: null, error: null };
+
+function applyWhoami(json) {
+  const d = (json && json.data) || json || {};
+  if (d.role) auth.role = d.role;
+  auth.roleName = d.roleName || null;
+  auth.permissions = Array.isArray(d.permissions) ? d.permissions : null;
+  auth.error = null;
+}
+
+async function loadAuth() {
+  if (!apiKey) { auth.error = 'No API key configured (ATO_API_KEY or <identity dir>/.env).'; auth.ready = true; return; }
+  try {
+    const { status, json } = await api('GET', '/ai/whoami');
+    if (status === 200) applyWhoami(json);
+    else auth.error = `whoami answered HTTP ${status}${json && json.code ? ' ' + json.code : ''}.`;
+  } catch (e) {
+    auth.error = `whoami failed: ${e.message}`;
+  }
+  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;
+  if (auth.permissions) return t.perms.some((p) => auth.permissions.includes(p));
+  return auth.role === 'tech_lead' || t.roles.includes(auth.role);
+};
+const visibleTools = () => TOOLS.filter(allowed).map(t => ({ name: t.name, description: t.desc, inputSchema: t.schema }));
+
+function respond(id, result) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
+}
+function respondError(id, code, message) {
+  process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n');
+}
+
+// Calling ato_whoami re-reads the permissions; tell the client if the visible tool set changed.
+async function refreshAfterWhoami(status, json) {
+  const before = visibleTools().map(t => t.name).join();
+  if (status === 200) applyWhoami(json); else auth.error = `whoami answered HTTP ${status}.`;
+  if (visibleTools().map(t => t.name).join() !== before) process.stdout.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/tools/list_changed' }) + String.fromCharCode(10));
+  if (auth.error && json && typeof json === 'object') json.mcpStatus = `Identity not verified: ${auth.error} Only tools open to every identity are listed.`;
+}
+
+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.6.0' },
+      instructions: instructions(),
+    });
+  }
+  if (msg.method === 'notifications/initialized') return;
+  if (msg.method === 'tools/list') {
+    if (!auth.ready || auth.error) await loadAuth();
+    return respond(msg.id, { tools: visibleTools() });
+  }
+  if (msg.method === 'tools/call') {
+    const { name, arguments: args } = msg.params || {};
+    const tool = TOOLS.find(t => t.name === name);
+    if (!tool) return respondError(msg.id, -32601, `Unknown tool: ${name}`);
+    if (!auth.ready || auth.error) await loadAuth();
+    if (!allowed(tool)) {
+      const why = auth.error ? `identity not verified (${auth.error})` : `your role${auth.roleName ? ` '${auth.roleName}'` : ''} lacks ${tool.perms.join(' or ')}`;
+      return respondError(msg.id, -32602, `Tool '${name}' is not available: ${why}`);
+    }
+    try {
+      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 = tool.text ? tool.text(json) : summarize(json);
+      if (digest) content.unshift({ type: 'text', text: digest });
+      return respond(msg.id, { content, isError: false });
+    } catch (e) {
+      return respond(msg.id, { content: [{ type: 'text', text: 'ERROR: ' + e.message }], isError: true });
+    }
+  }
+  if (msg.method && msg.method.startsWith('notifications/')) return;
+  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))
+    .then(() => process.exit(0))
+    .catch((e) => { console.error('  ' + e.message); process.exit(1); });
+  return;
+}
+
+loadAuth();
+const playbookReady = loadPlaybook();
+
+let buffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  buffer += chunk;
+  let idx;
+  while ((idx = buffer.indexOf('\n')) >= 0) {
+    const line = buffer.slice(0, idx).trim();
+    buffer = buffer.slice(idx + 1);
+    if (!line) continue;
+    let msg; try { msg = JSON.parse(line); } catch { continue; }
+    handle(msg).catch(e => console.error('mcp handler error', e));
+  }
+});

package/login.js

@@ -0,0 +1,119 @@
+// ato-mcp login — "Connect my AI" (device authorization grant, RFC 8628 style).
+//
+//   node ato-mcp/index.js login [--name claude-dev-1] [--role dev] [--model claude]
+//                               [--base-url https://.../api/v1/ato] [--dir ./.ato]
+//
+// 1. Asks ATO for a device code and a short user code.
+// 2. Prints the code and the portal URL; a logged-in human approves it there (and picks the final
+//    name and role, never above their own).
+// 3. Polls until approved, then writes the key ONCE to <dir>/.env (ATO_API_KEY=...) and the identity
+//    to <dir>/identity.json. The key is never printed. Both files must stay git-ignored.
+
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { detectLang, makeT } = require('./i18n');
+const platformLib = require('./platform');
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const k = a.slice(2);
+    const v = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[++i] : 'true';
+    out[k] = v;
+  }
+  return out;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function post(baseUrl, p, body) {
+  const res = await fetch(`${baseUrl}${p}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body || {}),
+  });
+  const text = await res.text();
+  let json; try { json = JSON.parse(text); } catch { json = { raw: text }; }
+  return { status: res.status, json };
+}
+
+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(platformLib.expandHome(args.dir || env.ATO_IDENTITY_DIR || path.join(process.cwd(), '.ato')));
+
+  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(t('error.start_failed', { status: start.status, detail: detail(start) }));
+  }
+
+  const d = start.json.data;
+  log('');
+  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;
+  const deadline = Date.now() + d.expiresIn * 1000;
+
+  while (Date.now() < deadline) {
+    await sleep(interval);
+    const r = await post(baseUrl, '/connect/token', { deviceCode: d.deviceCode });
+    const code = r.json && r.json.code;
+
+    if (r.status === 200 && r.json.data && r.json.data.apiKey) {
+      const tk = r.json.data;
+      fs.mkdirSync(dir, { recursive: true });
+      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: tk.handle,
+        memberId: tk.memberId,
+        role: tk.role,
+        tenantId: tk.tenantId,
+        aiModel: args.model || null,
+        apiKeyEnvVar: 'ATO_API_KEY',
+      }, null, 2) + '\n', 'utf8');
+
+      log(`  ${t('login.connected', { handle: tk.handle, role: tk.role, file: envFile })}`);
+      try {
+        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(`  ${t('login.role', { role: wd.roleName || wd.role, count: wd.permissions.length })}`);
+      } catch { /* the MCP reads whoami again on start */ }
+      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(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(t('error.unexpected', { status: r.status, detail: detail(r) }));
+  }
+  throw new Error(t('error.expired_unapproved'));
+}
+
+module.exports = { run, parseArgs };

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@nestxapp/ato-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "bin": {
+    "ato-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "login.js",
+    "i18n.js",
+    "platform.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NestX-Software/AtoApi.git",
+    "directory": "ato-mcp"
+  },
+  "keywords": ["mcp", "ato", "ai", "tasks"]
+}

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 };