@nestxapp/ato-mcp 0.0.0-stage → 1.5.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,68 @@
-# 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
+```
+
+Keep `.ato/` and `.mcp.json` out of git: they hold your API key.
+
+## 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.
+
+## 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`. |
+
+## 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, if `npx` is not found by the client, 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/index.js

@@ -0,0 +1,508 @@
+#!/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 BASE_URL = process.env.ATO_API_BASE_URL || 'http://localhost:5000/api/v1/ato';
+
+function loadIdentity() {
+  const dir = process.env.ATO_IDENTITY_DIR || path.join(process.cwd(), '.ato');
+  const file = path.join(dir, 'identity.json');
+  if (fs.existsSync(file)) {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  }
+  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');
+  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 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.',
+    schema: { type: 'object', properties: {} },
+    fn: async () => api('GET', '/ai/whoami'),
+  },
+  {
+    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, 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.',
+    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; commitHash required before review).',
+    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 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 } }),
+  },
+  {
+    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.',
+    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).',
+    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.',
+    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.',
+    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_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;
+}
+
+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') {
+    return respond(msg.id, {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: { listChanged: true } },
+      serverInfo: { name: 'ato-mcp', version: '1.5.0' },
+    });
+  }
+  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 = 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}`);
+}
+
+// `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();
+
+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,109 @@
+// 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');
+
+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 };
+}
+
+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 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 start = await post(baseUrl, '/connect/device', {
+    name: args.name || null,
+    role: args.role || null,
+    aiModel: args.model || null,
+  });
+  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'}`);
+  }
+
+  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('');
+
+  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 t = r.json.data;
+      fs.mkdirSync(dir, { recursive: true });
+      writeSecretFile(path.join(dir, '.env'), `ATO_API_KEY=${t.apiKey}\n`);
+      fs.writeFileSync(path.join(dir, 'identity.json'), JSON.stringify({
+        assigneeId: t.handle,
+        memberId: t.memberId,
+        role: t.role,
+        tenantId: t.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).`);
+      try {
+        const who = await fetch(`${baseUrl}/ai/whoami`, { headers: { 'X-API-Key': t.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.`);
+      } 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;
+    }
+    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 (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('The code expired before it was approved. Run login again.');
+}
+
+module.exports = { run, parseArgs };

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@nestxapp/ato-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.5.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",
+    "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"]
+}