@neuralbridge/bio-pipelines-mcp 0.0.0 → 1.0.0

package/README.md

@@ -1,6 +1,98 @@
 # @neuralbridge/bio-pipelines-mcp
 
-MCP server by NeuralBridge. Bioinformatics pipelines with Nextflow, WDL and Snakemake.
+MCP server for bioinformatics pipelines written for Nextflow, WDL (run with miniwdl) and Snakemake. It is the server
+behind the `nb-bio-pipelines` power of NeuralBridge IDE, and works with any MCP client over stdio.
 
-This version is a placeholder and contains no server. The first release will be published from
-https://github.com/vasya6653666/nb-mcp-servers.
+## Tools
+
+| Tool | What it does | Changes |
+|---|---|---|
+| `bio_detect` | Which of `nextflow`, `miniwdl`, `snakemake` are installed and their versions; with `dir`, lists `main.nf`, `nextflow.config`, `.wdl` files and Snakefiles | nothing |
+| `bio_lint` | `nextflow lint -o json`, `miniwdl check`, `snakemake --lint json`; findings as `file:line:column: message` | nothing (Snakemake evaluates the Snakefile) |
+| `bio_plan` | Dry run: Nextflow `run -preview -with-dag` (processes of the DAG), Snakemake `--dry-run` (jobs per rule), miniwdl `check` + required inputs + `run --json`; saves the exact command and file hashes as a plan | tool metadata (`.nextflow`, `.snakemake`) in the launch directory |
+| `bio_run` | Starts exactly the planned command in the background, once, and returns a run id | **runs the pipeline**: computes, writes results, may overwrite outputs |
+| `bio_run_status` | Running or finished, exit code, duration, progress, last 100 lines of the log | nothing |
+| `bio_run_stop_plan` | Shows what is running and for how long; saves a stop plan | a plan file in the data folder |
+| `bio_run_stop_apply` | Sends SIGTERM to the planned run, once | **stops the run** |
+| `bio_runs` | Runs started through this server, newest first | nothing |
+
+Read-only are only `bio_detect`, `bio_run_status` and `bio_runs`. `bio_lint` is not marked read-only because
+`snakemake --lint` executes the Snakefile, which is Python code; `bio_plan` evaluates the pipeline code of all three tools.
+`bio_run` and `bio_run_stop_apply` are marked destructive.
+
+### Plan, then run
+
+`bio_run` takes only a plan id. Before starting, it checks that the program still resolves to the same binary, that the
+launch directory exists and that the pipeline file, the `nextflow.config` files (pipeline and launch directory), the
+params file, the Snakemake config and profile files and the WDL inputs file have the same sha256 as at planning time.
+Then it runs exactly the saved arguments and removes the plan. Plans expire after 24 hours.
+
+The run is a detached process: its stdout and stderr go to `runs/<id>.log`, the PID and start time to `runs/<id>.json`.
+While the server is alive, it records the exit code when the process ends. If the server was restarted during a run,
+`bio_run_status` checks the PID (on Linux also its command line) and guesses the outcome from the end of the log. Records
+of finished runs, their logs and Nextflow reports are removed after 7 days.
+
+| Tool | Command started by `bio_run` |
+|---|---|
+| Nextflow | `nextflow run <main.nf> [-params-file F] [-profile P] [-work-dir D] [-resume] -with-report <data>/runs/<id>-report.html` |
+| Snakemake | `snakemake [targets] --snakefile S --directory D --nocolor --cores N [--configfile …] [--profile P] [--software-deployment-method …]` |
+| miniwdl | `miniwdl run <file.wdl> [-i inputs.json] [--task T] --dir <outputDir> --no-color` (a timestamp-named run directory is created under it) |
+
+Stopping sends SIGTERM to the program itself; Nextflow, Snakemake and miniwdl then cancel their running tasks and exit.
+
+## Local pipelines only, and what the tools download
+
+The server installs and downloads nothing. It starts only programs already installed, found on `PATH` or through
+`NB_BIO_NEXTFLOW`, `NB_BIO_MINIWDL`, `NB_BIO_SNAKEMAKE`.
+
+- **Pipelines must be local.** `pipeline` is an absolute path to `main.nf` (or the directory that contains it), a
+  Snakefile (or its project directory with `Snakefile` / `workflow/Snakefile`), or a `.wdl` file. Names like
+  `owner/repo`, which Nextflow would download from a git hosting service, and URLs are not accepted. Clone the pipeline
+  first and point to the local copy.
+- **Nextflow** downloads plugins and, on the very first start of its launcher, its own runtime into `~/.nextflow`. With
+  `offline: true` the server sets `NXF_OFFLINE=true`: Nextflow downloads no pipelines and no plugins (since 24.04), so the
+  plugins must already be installed. Tasks run with the executor configured in `nextflow.config`.
+- **Container images and Conda environments** used by the processes, rules or tasks are pulled or created by Nextflow,
+  Snakemake (only with `softwareDeployment`) and the container runtime of miniwdl when the run starts. miniwdl also
+  downloads input files given as URIs. The plan says so in its answer.
+- Snakemake software deployment (`--software-deployment-method conda|apptainer|env-modules`) is off unless requested.
+
+## Environment
+
+| Variable | Meaning |
+|---|---|
+| `NB_BIO_NEXTFLOW`, `NB_BIO_MINIWDL`, `NB_BIO_SNAKEMAKE` | Path of the program; default — the name on `PATH`. Each program is optional |
+| `PLUGIN_DATA` | Data folder for plans and runs; default — `nb-bio-pipelines` in the system temp folder. Mode 0700, files 0600 |
+
+Programs run without a shell, with closed stdin, `NO_COLOR=1` and a time limit (lint 5 minutes, plan 30 minutes, the
+run itself has none). Nextflow also gets `NXF_ANSI_LOG=false`, `NXF_DISABLE_CHECK_LATEST=true` (no check for a newer
+version) and `NXF_AGENT_MODE=false` (keeps the normal log format the progress parser reads). Credentials stay where the
+tools read them (their config files and the environment of the server). Answers mask passwords in URLs (`user:***@`),
+`password=` / `token:` pairs and bearer tokens; params files are shown by key names only. Logs of the server go to
+stderr.
+
+## Versions
+
+- `nextflow lint` needs Nextflow 25.04 or newer; with older versions `bio_lint` skips Nextflow files with a note.
+  `-preview` needs Nextflow 22.10 or newer.
+- `softwareDeployment` needs Snakemake 8 or newer. Dry-run job statistics are read from the `Job stats:` table.
+- miniwdl: `check`, `input-template` and `run --json` of current releases (1.x).
+
+## Run
+
+```bash
+npx -y @neuralbridge/bio-pipelines-mcp@1.0.0
+```
+
+Requires Node.js 20+.
+
+## Develop
+
+```bash
+npm install
+npm test   # build + unit and end-to-end tests with fake nextflow, miniwdl and snakemake programs
+```
+
+## License
+
+Apache-2.0. See `LICENSE` and `NOTICE`.

package/dist/src/context.js

@@ -0,0 +1,23 @@
+// Copyright (c) NeuralBridge. Licensed under the Apache License, Version 2.0. See LICENSE.
+// Состояние сервера на время его жизни: окружение, кэш найденных программ и исход прогонов, запущенных этим
+// процессом сервера (код выхода известен сразу, до записи на диск). Используют все обработчики.
+import { PROGRAMS, resolveProgram } from './runner.js';
+export function createContext(env) {
+    return { env, programs: {}, exits: new Map(), children: new Map() };
+}
+/** Программа или `undefined`; неудачный поиск не кэшируется — пользователь может поставить программу без перезапуска. */
+export async function findProgram(ctx, kind) {
+    ctx.programs[kind] ??= resolveProgram(kind, ctx.env);
+    const program = await ctx.programs[kind];
+    if (!program) {
+        delete ctx.programs[kind];
+    }
+    return program;
+}
+export async function programOf(ctx, kind) {
+    const program = await findProgram(ctx, kind);
+    if (!program) {
+        throw new Error(PROGRAMS[kind].notFound);
+    }
+    return program;
+}

package/dist/src/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Copyright (c) NeuralBridge. Licensed under the Apache License, Version 2.0. See LICENSE.
+// Точка входа пакета `@neuralbridge/bio-pipelines-mcp`: сервер `server.ts` на транспорте stdio. Логи — только в
+// stderr: stdout занят протоколом.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+const server = createServer();
+await server.connect(new StdioServerTransport());
+process.stderr.write('nb-bio-pipelines MCP server ready\n');

package/dist/src/inspect.js

@@ -0,0 +1,100 @@
+// Copyright (c) NeuralBridge. Licensed under the Apache License, Version 2.0. See LICENSE.
+// Обработчики `bio_detect` и `bio_lint`: какие программы установлены, какие пайплайны лежат в каталоге, и статическая
+// проверка `nextflow lint`, `miniwdl check`, `snakemake --lint`. Регистрация в MCP — `server.ts`.
+import { promises as fs } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { findProgram } from './context.js';
+import { parseMiniwdlCheck, parseNextflowLint, parseSnakemakeLint } from './parse.js';
+import { existingPath, findPipelineFiles, pipelineOf } from './paths.js';
+import { compareVersions, failure, MINUTE, PROGRAM_KINDS, PROGRAMS, programEnv, run } from './runner.js';
+/** `nextflow lint` появился в Nextflow 25.04. */
+export const NEXTFLOW_LINT_SINCE = '25.04.0';
+const LINT_TIMEOUT = 5 * MINUTE;
+const MAX_WDL = 20;
+const MAX_SNAKEFILES = 5;
+export async function detect(ctx, args) {
+    const lines = [];
+    for (const kind of PROGRAM_KINDS) {
+        const program = await findProgram(ctx, kind);
+        lines.push(program ? `${kind} ${program.version} (${program.path})` : `${kind}: not found. ${PROGRAMS[kind].notFound}`);
+    }
+    if (args.dir) {
+        const root = await existingPath(args.dir, '"dir"', 'dir');
+        const found = await findPipelineFiles(root);
+        const list = (title, files) => files.length ? [`${title}:`, ...files.map(f => `  ${f}`)] : [];
+        const files = [...list('Nextflow (main.nf, nextflow.config)', found.nextflow), ...list('WDL', found.wdl), ...list('Snakemake', found.snakemake)];
+        lines.push('', files.length ? `Pipelines under ${root}:\n${files.join('\n')}` : `No main.nf, nextflow.config, .wdl or Snakefile under ${root}.`);
+    }
+    return lines.join('\n');
+}
+/** Что проверять: файл — по имени; папка — все найденные пайплайны (Nextflow — папкой целиком). */
+async function lintTargets(path, only) {
+    const stat = await fs.stat(path);
+    const targets = [];
+    if (stat.isFile()) {
+        const name = basename(path);
+        const kind = /\.(nf|config)$/.test(name) ? 'nextflow' : name.endsWith('.wdl') ? 'miniwdl' : /^[Ss]nakefile$|\.smk$/.test(name) ? 'snakemake' : undefined;
+        if (!kind) {
+            throw new Error(`Cannot tell the pipeline language of ${path}: expected .nf, .config, .wdl, Snakefile or .smk.`);
+        }
+        targets.push({ kind, path, cwd: dirname(path) });
+    }
+    else {
+        const found = await findPipelineFiles(path);
+        if (found.nextflow.length) {
+            targets.push({ kind: 'nextflow', path, cwd: path });
+        }
+        for (const file of found.wdl.slice(0, MAX_WDL)) {
+            targets.push({ kind: 'miniwdl', path: join(path, file), cwd: dirname(join(path, file)) });
+        }
+        for (const file of found.snakemake.filter(f => !/(^|[\\/])rules[\\/]/.test(f)).slice(0, MAX_SNAKEFILES)) {
+            const pipeline = await pipelineOf('snakemake', join(path, file));
+            targets.push({ kind: 'snakemake', path: pipeline.file, cwd: pipeline.root });
+        }
+    }
+    return only ? targets.filter(t => t.kind === only) : targets;
+}
+async function lintOne(program, target, env) {
+    const options = { cwd: target.cwd, timeoutMs: LINT_TIMEOUT, env: programEnv(program.kind, env, { offline: true }) };
+    if (program.kind === 'nextflow') {
+        if (compareVersions(program.version, NEXTFLOW_LINT_SINCE) < 0) {
+            return `nextflow lint ${target.path}: skipped — "nextflow lint" needs Nextflow 25.04 or newer, found ${program.version}. Use bio_plan (nextflow -preview) to check that the script compiles.`;
+        }
+        const result = await run(program.path, ['lint', '-o', 'json', target.path], options);
+        const findings = parseNextflowLint(result.stdout);
+        if (!findings) {
+            throw failure('nextflow lint', result);
+        }
+        return `nextflow lint ${target.path}: ${findings.length ? `${findings.length} finding(s)\n${findings.join('\n')}` : 'no errors or warnings.'}`;
+    }
+    if (program.kind === 'miniwdl') {
+        const result = await run(program.path, ['check', target.path], options);
+        const { findings } = parseMiniwdlCheck(target.path, result.stdout, result.stderr);
+        const head = result.code === 0 ? 'parsed and type-checked' : 'FAILED to parse or type-check';
+        const extra = result.code !== 0 && !findings.some(f => f.startsWith('error:')) ? `\n${(result.stderr || result.stdout).trim()}` : '';
+        return `miniwdl check ${target.path}: ${head}${findings.length ? `, ${findings.length} finding(s)\n${findings.join('\n')}` : '.'}${extra}`;
+    }
+    const result = await run(program.path, ['--lint', 'json', '--snakefile', target.path, '--directory', target.cwd, '--nocolor'], options);
+    const findings = parseSnakemakeLint(result.stdout);
+    if (!findings) {
+        throw failure('snakemake --lint', result);
+    }
+    return `snakemake --lint ${target.path}: ${findings.length ? `${findings.length} finding(s)\n${findings.join('\n')}` : 'no lints.'}`;
+}
+export async function lint(ctx, args) {
+    const path = await existingPath(args.path, '"path"');
+    const targets = await lintTargets(path, args.program);
+    if (!targets.length) {
+        return `Nothing to lint under ${path}${args.program ? ` for ${args.program}` : ''}.`;
+    }
+    const sections = [];
+    for (const target of targets) {
+        const program = await findProgram(ctx, target.kind);
+        if (!program) {
+            sections.push(`${target.path}: skipped — ${PROGRAMS[target.kind].notFound}`);
+            continue;
+        }
+        sections.push(await lintOne(program, target, ctx.env).catch((error) => `${target.path}: ${error.message}`));
+    }
+    return sections.join('\n\n');
+}

package/dist/src/parse.js

@@ -0,0 +1,144 @@
+/** JSON из вывода, перед которым программа могла напечатать что-то ещё. */
+function jsonOf(text) {
+    const start = text.indexOf('{');
+    if (start < 0) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text.slice(start));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `nextflow lint -o json`: `{ errors: [...], warnings: [...] }` с полями filename, startLine, startColumn, message. */
+export function parseNextflowLint(stdout) {
+    const parsed = jsonOf(stdout);
+    if (!parsed || typeof parsed !== 'object') {
+        return undefined;
+    }
+    const line = (severity, item) => `${severity}: ${String(item.filename ?? '?')}:${Number(item.startLine ?? 0)}:${Number(item.startColumn ?? 0)}: ${String(item.message ?? '').replace(/\s+/g, ' ').trim()}`;
+    const list = (value) => Array.isArray(value) ? value : [];
+    return [...list(parsed.errors).map(e => line('error', e)), ...list(parsed.warnings).map(w => line('warning', w))];
+}
+/**
+ * `miniwdl check`: в stdout — схема документа с замечаниями «(Ln 2, Col 7) UnusedDeclaration, …» и строками `call`;
+ * ошибки разбора и типов — в stderr «(file.wdl Ln 3 Col 5) …».
+ */
+export function parseMiniwdlCheck(file, stdout, stderr) {
+    const findings = [];
+    let calls = 0;
+    for (const line of stdout.split('\n')) {
+        const warning = /^\s*\(Ln (\d+), Col (\d+)\)\s*(.*)$/.exec(line);
+        if (warning) {
+            findings.push(`warning: ${file}:${warning[1]}:${warning[2]}: ${warning[3].trim()}`);
+        }
+        else if (/^\s+call\s+\S/.test(line)) {
+            calls++;
+        }
+    }
+    for (const line of stderr.split('\n')) {
+        const error = /^\((.+?) Ln (\d+) Col (\d+)\)\s*(.*)$/.exec(line.trim());
+        if (error) {
+            findings.push(`error: ${error[1]}:${error[2]}:${error[3]}: ${error[4].trim()}`);
+        }
+    }
+    return { calls, findings };
+}
+/** `snakemake --lint json`: `{ snakefiles: [{ for: { snakefile }, lints }], rules: [{ for: { rule, line, snakefile }, lints }] }`. */
+export function parseSnakemakeLint(stdout) {
+    const parsed = jsonOf(stdout);
+    if (!parsed || typeof parsed !== 'object' || (!('snakefiles' in parsed) && !('rules' in parsed))) {
+        return undefined;
+    }
+    const out = [];
+    const groups = (value) => Array.isArray(value) ? value : [];
+    for (const group of [...groups(parsed.snakefiles), ...groups(parsed.rules)]) {
+        const where = `${String(group.for?.snakefile ?? '?')}${group.for?.line !== undefined && group.for.line !== null ? `:${Number(group.for.line)}` : ''}`;
+        const rule = group.for?.rule ? ` rule ${String(group.for.rule)}:` : '';
+        for (const lint of Array.isArray(group.lints) ? group.lints : []) {
+            out.push(`lint: ${where}:${rule} ${String(lint.title ?? '')} — ${String(lint.body ?? '').replace(/\s+/g, ' ').trim()}`);
+        }
+    }
+    return out;
+}
+/** Таблица «Job stats» сухого прогона Snakemake: число заданий по правилам и итог. */
+export function parseSnakemakeJobStats(text) {
+    const lines = text.split('\n');
+    const start = lines.findIndex(line => line.trim() === 'Job stats:');
+    if (start < 0) {
+        return undefined;
+    }
+    const rules = [];
+    for (const line of lines.slice(start + 1)) {
+        const row = /^\s*(\S+)\s+(\d+)\s*$/.exec(line);
+        if (row) {
+            if (row[1] === 'total') {
+                return { total: Number(row[2]), rules };
+            }
+            rules.push({ name: row[1], count: Number(row[2]) });
+        }
+        else if (line.trim() && !/^[-\s]+$/.test(line) && !/^\s*job\s+count\s*$/.test(line)) {
+            break;
+        }
+    }
+    return rules.length ? { total: rules.reduce((sum, r) => sum + r.count, 0), rules } : undefined;
+}
+/** Процессы в DAG Nextflow в формате Mermaid: узлы процессов — `v3(["NAME"])`; операторы без `-verbose` — `(( ))`. */
+export function parseNextflowDag(mermaid) {
+    const names = new Set();
+    for (const match of mermaid.matchAll(/\b[a-z]?\d+\(\["?([^"\]]+)"?\]\)/g)) {
+        names.add(match[1].trim());
+    }
+    return [...names];
+}
+/**
+ * Прогресс Nextflow по логу без ANSI: строки «[ab/123456] Submitted process > NAME (1)», «Cached process >», а в
+ * ANSI-сводке «[ab/123456] process > NAME (3) [100%] 3 of 3 ✔» — берётся последняя строка каждого процесса.
+ */
+export function nextflowProgress(log) {
+    const ansi = new Map();
+    const counts = new Map();
+    let executor = '';
+    for (const line of log.split('\n')) {
+        const exec = /^executor\s*>\s*(.+)$/.exec(line.trim());
+        if (exec) {
+            executor = `executor > ${exec[1].trim()}`;
+        }
+        const bar = /\[[0-9a-f-]{2}\/[0-9a-f-]{6}\]\s+process\s*>\s*(\S+)(.*\[\s*\d+%\].*)$/.exec(line);
+        if (bar) {
+            ansi.set(bar[1], `${bar[1]}${bar[2]}`.replace(/\s+/g, ' ').trim());
+            continue;
+        }
+        const plain = /\[[0-9a-f]{2}\/[0-9a-f]{6}\]\s+(Submitted|Re-submitted|Cached) process\s*>\s*(\S+)/.exec(line);
+        if (plain) {
+            const entry = counts.get(plain[2]) ?? { submitted: 0, cached: 0 };
+            if (plain[1] === 'Cached') {
+                entry.cached++;
+            }
+            else {
+                entry.submitted++;
+            }
+            counts.set(plain[2], entry);
+        }
+    }
+    const rows = ansi.size
+        ? [...ansi.values()]
+        : [...counts.entries()].map(([name, c]) => `${name}: ${c.submitted} submitted${c.cached ? `, ${c.cached} cached` : ''}`);
+    return executor && rows.length ? [executor, ...rows] : rows;
+}
+/** Прогресс Snakemake: последняя строка «3 of 5 steps (60%) done». */
+export function snakemakeProgress(log) {
+    const matches = [...log.matchAll(/^\s*(\d+ of \d+ steps \(\d+%\) done)/gm)];
+    return matches.length ? [matches[matches.length - 1][1]] : [];
+}
+/** Исход по хвосту лога, когда код выхода неизвестен (сервер перезапускался во время прогона). */
+export function inferOutcome(program, log) {
+    const patterns = {
+        nextflow: { ok: /^Succeeded\s*:|Workflow completed successfully|^Completed at:/m, fail: /^ERROR ~|Execution aborted|Workflow failed/m },
+        snakemake: { ok: /\(100%\) done|Nothing to be done/, fail: /Exiting because a job execution failed|^Error in rule|WorkflowError/m },
+        miniwdl: { ok: /"outputs"\s*:/, fail: /\bfailed\b.*\btask\b|"error"\s*:|Traceback/i },
+    };
+    const { ok, fail } = patterns[program];
+    return fail.test(log) ? 'failed' : ok.test(log) ? 'succeeded' : undefined;
+}

package/dist/src/paths.js

@@ -0,0 +1,108 @@
+// Copyright (c) NeuralBridge. Licensed under the Apache License, Version 2.0. See LICENSE.
+// Пути проекта: проверка абсолютных путей, поиск файлов пайплайнов (`main.nf`, `nextflow.config`, `*.wdl`, `Snakefile`),
+// выбор файла пайплайна по программе и sha256 файлов, по которым план сверяется перед запуском.
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+/** Абсолютный путь к существующему файлу или папке. */
+export async function existingPath(path, what, kind) {
+    if (!isAbsolute(path)) {
+        throw new Error(`${what} must be an absolute local path, got "${path}".`);
+    }
+    const full = resolve(path);
+    const stat = await fs.stat(full).catch(() => undefined);
+    if (!stat || (kind === 'file' && !stat.isFile()) || (kind === 'dir' && !stat.isDirectory())) {
+        throw new Error(`${what} not found: ${full}`);
+    }
+    return full;
+}
+export async function isFile(path) {
+    return (await fs.stat(path).catch(() => undefined))?.isFile() === true;
+}
+export function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/** sha256 каждого файла; отсутствующий файл получает пометку `missing`. */
+export async function hashFiles(files) {
+    const hashes = {};
+    for (const file of [...new Set(files)].sort()) {
+        const data = await fs.readFile(file).catch(() => undefined);
+        hashes[file] = data ? sha256(data) : 'missing';
+    }
+    return hashes;
+}
+/** Файлы, которые изменились, появились или исчезли с момента плана. */
+export function changedFiles(before, after) {
+    const names = new Set([...Object.keys(before), ...Object.keys(after)]);
+    return [...names].filter(name => before[name] !== after[name]).sort();
+}
+const SKIPPED = new Set(['.git', 'node_modules', 'work', '.nextflow', '.snakemake', '_LAST', '__pycache__']);
+/** Файлы пайплайнов под `root`, не глубже `depth`, не больше `limit` каждого вида; пути — относительно `root`. */
+export async function findPipelineFiles(root, depth = 5, limit = 100) {
+    const found = { nextflow: [], wdl: [], snakemake: [] };
+    const walk = async (dir, level) => {
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const full = join(dir, entry.name);
+            const rel = relative(root, full);
+            if (entry.isFile()) {
+                if ((entry.name === 'main.nf' || entry.name === 'nextflow.config') && found.nextflow.length < limit) {
+                    found.nextflow.push(rel);
+                }
+                else if (entry.name.endsWith('.wdl') && found.wdl.length < limit) {
+                    found.wdl.push(rel);
+                }
+                else if (/^[Ss]nakefile$/.test(entry.name) && found.snakemake.length < limit) {
+                    found.snakemake.push(rel);
+                }
+            }
+            else if (entry.isDirectory() && level < depth && !SKIPPED.has(entry.name) && !entry.name.startsWith('.')) {
+                await walk(full, level + 1);
+            }
+        }
+    };
+    await walk(root, 0);
+    return found;
+}
+/**
+ * Файл пайплайна по программе. Принимается только локальный абсолютный путь: имя вида `owner/repo` Nextflow
+ * скачал бы с git-хостинга, URL Snakefile — с веба. Папка: `main.nf` / `Snakefile`, `workflow/Snakefile`.
+ */
+export async function pipelineOf(kind, path) {
+    const full = await existingPath(path, '"pipeline"');
+    const stat = await fs.stat(full);
+    if (kind === 'nextflow') {
+        const file = stat.isDirectory() ? join(full, 'main.nf') : full;
+        if (!file.endsWith('.nf') || !await isFile(file)) {
+            throw new Error(`No Nextflow script at ${file}. Pass the absolute path of a local main.nf or of the pipeline directory that contains it; remote pipeline names are not accepted.`);
+        }
+        return { file, root: dirname(file) };
+    }
+    if (kind === 'miniwdl') {
+        if (!stat.isFile() || !full.endsWith('.wdl')) {
+            throw new Error(`"pipeline" must be the absolute path of a local .wdl file, got ${full}.`);
+        }
+        return { file: full, root: dirname(full) };
+    }
+    let file = full;
+    if (stat.isDirectory()) {
+        const candidates = ['Snakefile', 'snakefile', join('workflow', 'Snakefile'), join('workflow', 'snakefile')].map(name => join(full, name));
+        const found = [];
+        for (const candidate of candidates) {
+            if (await isFile(candidate)) {
+                found.push(candidate);
+            }
+        }
+        if (!found[0]) {
+            throw new Error(`No Snakefile or workflow/Snakefile in ${full}.`);
+        }
+        file = found[0];
+    }
+    const parent = dirname(file);
+    return { file, root: basename(parent) === 'workflow' ? dirname(parent) : parent };
+}
+/** Каталог существует и в нём что-то есть: запуск может перезаписать файлы. */
+export async function nonEmptyDir(path) {
+    const entries = await fs.readdir(path).catch(() => undefined);
+    return entries !== undefined && entries.length > 0;
+}

package/dist/src/plan.js

@@ -0,0 +1,168 @@
+// Copyright (c) NeuralBridge. Licensed under the Apache License, Version 2.0. See LICENSE.
+// Обработчик `bio_plan`: сухой прогон (`nextflow run -preview -with-dag`, `snakemake --dry-run`, `miniwdl check` + сверка
+// входов) и сохранённый план — ровно те аргументы, которые получит программа в `bio_run`, и sha256 файлов пайплайна.
+import { promises as fs } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { programOf } from './context.js';
+import { parseMiniwdlCheck, parseNextflowDag, parseSnakemakeJobStats } from './parse.js';
+import { existingPath, hashFiles, isFile, nonEmptyDir, pipelineOf } from './paths.js';
+import { failure, MINUTE, programEnv, run } from './runner.js';
+import { newId, plansDir, runPaths, savePlan } from './store.js';
+const PLAN_TIMEOUT = 30 * MINUTE;
+const optionalFile = async (path, what) => path ? existingPath(path, what, 'file') : undefined;
+/** Ключи и `outdir` из файла параметров: значения могут быть секретами и не показываются. */
+async function paramsSummary(file) {
+    const text = await fs.readFile(file, 'utf8');
+    try {
+        const parsed = JSON.parse(text);
+        return { keys: Object.keys(parsed), ...typeof parsed['outdir'] === 'string' ? { outdir: parsed['outdir'] } : {} };
+    }
+    catch {
+        const keys = [...text.matchAll(/^([A-Za-z_][\w-]*)\s*:/gm)].map(m => m[1]);
+        const outdir = /^outdir\s*:\s*["']?([^"'\n#]+?)["']?\s*(#.*)?$/m.exec(text)?.[1];
+        return { keys, ...outdir ? { outdir } : {} };
+    }
+}
+const nextflow = async (program, a, c) => {
+    const paramsFile = await optionalFile(a.paramsFile, '"paramsFile"');
+    const workDir = a.workDir ? await existingPath(a.workDir, '"workDir"', 'dir') : undefined;
+    const common = [...paramsFile ? ['-params-file', paramsFile] : [], ...a.profile ? ['-profile', a.profile] : [], ...workDir ? ['-work-dir', workDir] : [], ...a.resume ? ['-resume'] : []];
+    const dag = join(await plansDir(c.env), `${c.id}-dag.mmd`);
+    const preview = await run(program.path, ['run', c.file, '-preview', '-with-dag', dag, ...common], { cwd: c.launchDir, timeoutMs: PLAN_TIMEOUT, env: programEnv('nextflow', c.env, { offline: a.offline }) });
+    const processes = parseNextflowDag(await fs.readFile(dag, 'utf8').catch(() => ''));
+    await fs.rm(dag, { force: true });
+    if (preview.code !== 0) {
+        throw failure('nextflow run -preview', preview);
+    }
+    const configs = [join(c.root, 'nextflow.config'), join(c.launchDir, 'nextflow.config')];
+    const files = [c.file, ...paramsFile ? [paramsFile] : []];
+    for (const config of configs) {
+        if (await isFile(config)) {
+            files.push(config);
+        }
+    }
+    const params = paramsFile ? await paramsSummary(paramsFile) : undefined;
+    const report = (await runPaths(c.env, c.id)).report;
+    const outputs = `${params?.outdir ? `published results: ${params.outdir} (params.outdir)` : 'published results: where the pipeline publishes them (commonly params.outdir)'}; intermediate files: ${workDir ?? join(c.launchDir, 'work')}`;
+    return {
+        args: ['run', c.file, ...common, '-with-report', report],
+        files,
+        outputs,
+        report,
+        summary: [
+            processes.length ? `Processes in the pipeline DAG: ${processes.length} (${processes.join(', ')}). The number of tasks depends on the input data.` : 'The preview did not report the processes of the pipeline.',
+            ...params ? [`Parameters from ${paramsFile}: ${params.keys.join(', ') || 'none'} (values not shown).`] : [],
+            `Profile: ${a.profile ?? 'default'}. Tasks run with the executor configured in nextflow.config.`,
+            'Container images, Conda environments and plugins that the pipeline uses are downloaded by Nextflow when the run starts, unless they are already cached.',
+        ],
+    };
+};
+const snakemake = async (program, a, c) => {
+    if (!a.cores) {
+        throw new Error('"cores" is required for Snakemake: the maximum number of CPU cores the run may use.');
+    }
+    const configFiles = await Promise.all((a.configFiles ?? []).map(f => existingPath(f, '"configFiles"', 'file')));
+    const profileDir = a.profile && /^([A-Za-z]:)?[\\/]/.test(a.profile) ? await existingPath(a.profile, '"profile"') : undefined;
+    const deploy = a.softwareDeployment ?? [];
+    const common = [...a.targets ?? [], '--snakefile', c.file, '--directory', c.launchDir, '--nocolor', '--cores', String(a.cores),
+        ...configFiles.length ? ['--configfile', ...configFiles] : [], ...a.profile ? ['--profile', a.profile] : [],
+        ...deploy.length ? ['--software-deployment-method', ...deploy] : []];
+    const dry = await run(program.path, [...common, '--dry-run'], { cwd: c.launchDir, timeoutMs: PLAN_TIMEOUT, env: programEnv('snakemake', c.env) });
+    if (dry.code !== 0) {
+        throw failure('snakemake --dry-run', dry);
+    }
+    const text = `${dry.stdout}\n${dry.stderr}`;
+    const stats = parseSnakemakeJobStats(text);
+    const files = [c.file, ...configFiles];
+    if (profileDir) {
+        const stat = await fs.stat(profileDir);
+        const names = stat.isDirectory() ? (await fs.readdir(profileDir)).map(n => join(profileDir, n)) : [profileDir];
+        for (const name of names) {
+            if (await isFile(name)) {
+                files.push(name);
+            }
+        }
+    }
+    return {
+        args: common,
+        files,
+        outputs: `${c.launchDir} (Snakemake working directory; output paths of the rules are relative to it)`,
+        summary: [
+            stats ? `Jobs to run: ${stats.total} (${stats.rules.map(r => `${r.name}: ${r.count}`).join(', ')}).` : /Nothing to be done/i.test(text) ? 'Nothing to be done: all requested outputs are present and up to date.' : 'The dry run did not print job statistics.',
+            `Cores: ${a.cores}.${a.profile ? ` Profile: ${a.profile}.` : ''}`,
+            deploy.length ? `Software deployment: ${deploy.join(', ')}. Snakemake creates Conda environments and pulls container images for the rules when the run starts.` : 'No software deployment method: rules run with the tools already on PATH.',
+        ],
+    };
+};
+const miniwdl = async (program, a, c) => {
+    const inputs = await optionalFile(a.inputs, '"inputs"');
+    const task = a.task ? ['--task', a.task] : [];
+    const env = programEnv('miniwdl', c.env);
+    const options = { cwd: c.launchDir, timeoutMs: PLAN_TIMEOUT, env };
+    const check = await run(program.path, ['check', c.file], options);
+    const checked = parseMiniwdlCheck(c.file, check.stdout, check.stderr);
+    if (check.code !== 0) {
+        throw new Error(`miniwdl check failed:\n${checked.findings.join('\n') || (check.stderr || check.stdout).trim()}`);
+    }
+    const template = await run(program.path, ['input-template', c.file, ...task], options);
+    if (template.code !== 0) {
+        throw failure('miniwdl input-template', template);
+    }
+    const required = Object.keys(JSON.parse(template.stdout.slice(Math.max(0, template.stdout.indexOf('{')))));
+    const given = inputs ? Object.keys(JSON.parse(await fs.readFile(inputs, 'utf8'))) : [];
+    const missing = required.filter(key => !given.includes(key));
+    if (missing.length) {
+        throw new Error(`Required inputs are missing${inputs ? ` in ${inputs}` : ' (no "inputs" file given)'}: ${missing.join(', ')}.`);
+    }
+    const validated = await run(program.path, ['run', c.file, ...inputs ? ['-i', inputs] : [], ...task, '--json'], options);
+    if (validated.code !== 0) {
+        throw failure('miniwdl run --json (input check)', validated);
+    }
+    const outputDir = a.outputDir ?? c.launchDir;
+    return {
+        args: ['run', c.file, ...inputs ? ['-i', inputs] : [], ...task, '--dir', outputDir, '--no-color'],
+        files: [c.file, ...inputs ? [inputs] : []],
+        makeDir: outputDir,
+        outputs: `a new timestamp-named subdirectory under ${outputDir}`,
+        summary: [
+            `Calls in the workflow: ${checked.calls}${checked.calls ? ' (scatters may run more tasks)' : ''}. Inputs: ${given.length} given, ${required.length} required, all required present.`,
+            ...checked.findings.length ? [`miniwdl check warnings: ${checked.findings.length}`] : [],
+            'Container images of the tasks are pulled by the container runtime configured for miniwdl, and input URIs are downloaded, when the run starts.',
+        ],
+    };
+};
+const PREPARE = { nextflow, snakemake, miniwdl };
+export async function plan(ctx, a) {
+    const program = await programOf(ctx, a.program);
+    const { file, root } = await pipelineOf(a.program, a.pipeline);
+    const launchDir = a.launchDir ? await existingPath(a.launchDir, '"launchDir"', 'dir') : root;
+    if (a.outputDir && a.program !== 'miniwdl') {
+        throw new Error('"outputDir" applies to miniwdl only. Snakemake writes outputs relative to "launchDir"; Nextflow publishes where the pipeline says (for example "outdir" in "paramsFile").');
+    }
+    if (a.outputDir && !isAbsolute(a.outputDir)) {
+        throw new Error(`"outputDir" must be an absolute local path, got "${a.outputDir}".`);
+    }
+    const outputDir = a.outputDir ? resolve(a.outputDir) : undefined;
+    const id = newId();
+    const prepared = await PREPARE[a.program](program, { ...a, ...outputDir ? { outputDir } : {} }, { id, file, root, launchDir, env: ctx.env });
+    const record = {
+        id, type: 'run', createdAt: new Date().toISOString(), program: a.program, binary: program.path, pipeline: file, launchDir,
+        args: prepared.args, offline: a.offline === true, hashes: await hashFiles(prepared.files), outputs: prepared.outputs,
+        ...prepared.makeDir ? { makeDir: prepared.makeDir } : {}, ...prepared.report ? { report: prepared.report } : {},
+    };
+    await savePlan(record, ctx.env);
+    const overwrite = (a.program === 'snakemake' && await nonEmptyDir(launchDir)) || (a.program === 'nextflow' && a.resume === true)
+        ? 'Existing files in the output location may be overwritten or reused.' : '';
+    return [
+        `Plan for ${a.program} ${program.version}: ${file}`,
+        `Launch directory: ${launchDir}`,
+        ...prepared.summary,
+        `Outputs: ${prepared.outputs}.`,
+        ...overwrite ? [overwrite] : [],
+        ...a.program === 'nextflow' ? [`Network: ${a.offline ? 'offline (NXF_OFFLINE=true): Nextflow will not download pipelines or plugins; plugins must already be installed' : 'Nextflow may download plugins and the images or environments named above'}.`] : [],
+        `Command: ${a.program} ${prepared.args.join(' ')}`,
+        '',
+        `Plan id: ${id}`,
+        'To start exactly this run after the user approves it, call bio_run with this id. The run starts in the background; follow it with bio_run_status.',
+    ].join('\n');
+}

package/dist/src/reply.js

@@ -0,0 +1,25 @@
+// Copyright (c) NeuralBridge. Licensed under the Apache License, Version 2.0. See LICENSE.
+// Ответ инструмента: текст или ошибка тем же текстом с `isError`, без падения сервера. Любой ответ проходит маскировку
+// секретов (пароли в URL, пары `password=` / `token:`, заголовки авторизации) и обрезку. Используют `server.ts` и тесты.
+export const MASK = '***';
+/** Обрезка длинного вывода: модели хватает начала, хвост помечается. */
+export function clip(text, max = 20_000) {
+    return text.length <= max ? text : `${text.slice(0, max)}\n… [output truncated: ${text.length - max} more characters]`;
+}
+const SENSITIVE_KEY = /([A-Za-z0-9_.-]*(?:password|passwd|passphrase|token|secret|api[_-]?key|access[_-]?key|private[_-]?key|credentials?))(["']?\s*[=:]\s*)(["']?)([^\s"',;&}]+)/gi;
+/** Маскировка свободного текста: логи прогонов, вывод программ, ошибки. */
+export function redactText(text) {
+    return text
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)([^\s:/@]+):([^\s@/]+)@/gi, `$1$2:${MASK}@`)
+        .replace(/\b(Authorization\s*[:=]\s*)(Bearer|Basic|Token)\s+[^\s"']+/gi, `$1$2 ${MASK}`)
+        .replace(/\b(Bearer)\s+[A-Za-z0-9._~+/=-]{16,}/g, `$1 ${MASK}`)
+        .replace(SENSITIVE_KEY, (all, key, sep, quote, value) => value === MASK || value.startsWith('<') ? all : `${key}${sep}${quote}${MASK}`);
+}
+export async function reply(work) {
+    try {
+        return { content: [{ type: 'text', text: clip(redactText(await work())) }] };
+    }
+    catch (error) {
+        return { content: [{ type: 'text', text: clip(redactText(error instanceof Error ? error.message : String(error))) }], isError: true };
+    }
+}

package/dist/src/runner.js

@@ -0,0 +1,95 @@
+// Copyright (c) NeuralBridge. Licensed under the Apache License, Version 2.0. See LICENSE.
+// Запуск nextflow, miniwdl и snakemake: поиск программы (переменные NB_BIO_*, затем PATH), версия, неинтерактивное
+// окружение каждой программы и исполнение без оболочки с тайм-аутом. Используют все обработчики инструментов.
+import { execFile } from 'node:child_process';
+export const MINUTE = 60_000;
+export const PROGRAM_KINDS = ['nextflow', 'miniwdl', 'snakemake'];
+export const PROGRAMS = {
+    nextflow: {
+        envVar: 'NB_BIO_NEXTFLOW',
+        // `-version` печатает баннер: «version 25.04.6 build 5954».
+        versionArgs: ['-version'],
+        parseVersion: out => /\bversion\s+(\d+\.\d+\.\d+[\w.-]*)/i.exec(out)?.[1],
+        notFound: 'nextflow was not found on PATH. Install Nextflow (https://www.nextflow.io/docs/latest/install.html), or set the NB_BIO_NEXTFLOW environment variable to its path and restart the IDE.',
+    },
+    miniwdl: {
+        envVar: 'NB_BIO_MINIWDL',
+        // `--version` печатает «miniwdl v1.12.1» и строки плагинов.
+        versionArgs: ['--version'],
+        parseVersion: out => /^miniwdl v?(\S+)/m.exec(out)?.[1],
+        notFound: 'miniwdl was not found on PATH. Install miniwdl (https://miniwdl.readthedocs.io, for example "pip install miniwdl"), or set the NB_BIO_MINIWDL environment variable to its path and restart the IDE.',
+    },
+    snakemake: {
+        envVar: 'NB_BIO_SNAKEMAKE',
+        // `--version` печатает номер версии одной строкой.
+        versionArgs: ['--version'],
+        parseVersion: out => /^\s*(\d+\.\d+[\w.+-]*)/.exec(out)?.[1],
+        notFound: 'snakemake was not found on PATH. Install Snakemake (https://snakemake.readthedocs.io/en/stable/getting_started/installation.html), or set the NB_BIO_SNAKEMAKE environment variable to its path and restart the IDE.',
+    },
+};
+/**
+ * Окружение запуска: без цвета. Nextflow — без ANSI-лога и без проверки новой версии; режим вывода для агентов
+ * (Nextflow 26.04+, включается сам при переменной AGENT) выключен, чтобы лог прогона был в обычном формате.
+ * `offline` — NXF_OFFLINE: Nextflow не скачивает пайплайны и плагины.
+ */
+export function programEnv(kind, base, options = {}) {
+    const env = { ...base, NO_COLOR: '1' };
+    if (kind === 'nextflow') {
+        env['NXF_ANSI_LOG'] = 'false';
+        env['NXF_DISABLE_CHECK_LATEST'] = 'true';
+        env['NXF_AGENT_MODE'] = 'false';
+        if (options.offline) {
+            env['NXF_OFFLINE'] = 'true';
+        }
+    }
+    return env;
+}
+export function run(binary, args, options) {
+    return new Promise(resolve => {
+        const child = execFile(binary, [...args], {
+            cwd: options.cwd,
+            timeout: options.timeoutMs,
+            maxBuffer: 64 * 1024 * 1024,
+            windowsHide: true,
+            env: options.env,
+        }, (error, stdout, stderr) => {
+            const failure = error;
+            const code = failure ? (typeof failure.code === 'number' ? failure.code : -1) : 0;
+            const missing = failure?.code === 'ENOENT' || failure?.code === 'EACCES';
+            resolve({
+                code,
+                stdout: String(stdout ?? ''),
+                stderr: missing ? `${binary}: command not found` : String(stderr ?? ''),
+                timedOut: failure?.killed === true && failure.signal === 'SIGTERM',
+            });
+        });
+        // Вопросы в stdin ответа не получат: поток закрыт сразу.
+        child.stdin?.end();
+    });
+}
+/** Программа из переменной окружения или с PATH; `undefined` — не найдена или не отвечает на запрос версии. */
+export async function resolveProgram(kind, env) {
+    const spec = PROGRAMS[kind];
+    const path = env[spec.envVar]?.trim() || kind;
+    // Запуск лаунчера Nextflow в первый раз скачивает его runtime: тайм-аут с запасом.
+    const result = await run(path, spec.versionArgs, { timeoutMs: 3 * MINUTE, env: programEnv(kind, env) });
+    const version = result.code === 0 ? spec.parseVersion(`${result.stdout}\n${result.stderr}`) : undefined;
+    return version ? { kind, path, version } : undefined;
+}
+/** Сравнение версий вида 25.04.6: отрицательное — `a` раньше `b`, ноль — равны. */
+export function compareVersions(a, b) {
+    const pa = a.split(/[.-]/).map(n => Number.parseInt(n, 10) || 0);
+    const pb = b.split(/[.-]/).map(n => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return 0;
+}
+/** Текст неудачного запуска: код, тайм-аут, вывод. */
+export function failure(step, result) {
+    const reason = result.timedOut ? 'timed out' : `exited with code ${result.code}`;
+    return new Error(`${step} ${reason}.\n${(result.stderr || result.stdout).trim()}`);
+}

package/dist/src/runs.js

@@ -0,0 +1,239 @@
+// Copyright (c) NeuralBridge. Licensed under the Apache License, Version 2.0. See LICENSE.
+// Прогоны: `bio_run` — сверка плана и запуск в фоне (отвязанный процесс, лог 0600, PID в записи прогона), состояние
+// и хвост лога, план и применение остановки (SIGTERM), список прогонов. Регистрация в MCP — `server.ts`.
+import { spawn } from 'node:child_process';
+import { closeSync, openSync, promises as fs } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { programOf } from './context.js';
+import { inferOutcome, nextflowProgress, snakemakeProgress } from './parse.js';
+import { changedFiles, existingPath, hashFiles } from './paths.js';
+import { programEnv } from './runner.js';
+import { dropPlan, dropStaleRuns, listRuns, loadPlan, loadRun, newId, runPaths, saveRun, savePlan, updateRun } from './store.js';
+const TAIL_LINES = 100;
+const TAIL_BYTES = 256 * 1024;
+/** Сколько ждать события `exit` у своего прогона, который уже не жив. */
+const EXIT_WAIT_MS = 3000;
+/** Процесс жив; на Linux заодно проверяется, что PID не занят чужим процессом (в командной строке — файл пайплайна). */
+export async function isAlive(record) {
+    try {
+        process.kill(record.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== 'EPERM') {
+            return false;
+        }
+    }
+    const cmdline = await fs.readFile(`/proc/${record.pid}/cmdline`, 'utf8').catch(() => undefined);
+    return cmdline === undefined || cmdline.includes(record.pipeline);
+}
+function exitText(exit) {
+    const how = exit.code === 0 ? 'succeeded (exit code 0)' : exit.code !== null ? `failed (exit code ${exit.code})` : `stopped by signal ${exit.signal ?? 'unknown'}`;
+    return { running: false, text: `${how}, finished ${exit.at}` };
+}
+/** Исход своего прогона, если событие `exit` придёт за `EXIT_WAIT_MS`. */
+async function awaitExit(ctx, id) {
+    const pending = ctx.children.get(id);
+    if (!pending) {
+        return undefined;
+    }
+    const stop = new AbortController();
+    try {
+        return await Promise.race([pending, delay(EXIT_WAIT_MS, undefined, { signal: stop.signal }).catch(() => undefined)]);
+    }
+    finally {
+        stop.abort();
+    }
+}
+/** Состояние прогона: сначала исход, известный этому процессу сервера, затем запись на диске, затем PID и лог. */
+async function stateOf(ctx, record, log) {
+    const exit = ctx.exits.get(record.id) ?? (record.finishedAt ? { code: record.exitCode ?? null, signal: record.signal ?? null, at: record.finishedAt } : undefined);
+    if (exit) {
+        return exitText(exit);
+    }
+    if (await isAlive(record)) {
+        return { running: true, text: `running (PID ${record.pid})${record.stopRequestedAt ? `, stop requested ${record.stopRequestedAt}` : ''}` };
+    }
+    // Свой прогон уже снят, а `exit` ещё не пришёл (сразу после SIGTERM или быстрого падения) — подождать его.
+    const late = await awaitExit(ctx, record.id);
+    if (late) {
+        return exitText(late);
+    }
+    const guess = inferOutcome(record.program, log);
+    return { running: false, text: `finished; exit code unknown (the server restarted during the run)${guess ? `, the log suggests it ${guess}` : ''}` };
+}
+async function tailOf(file) {
+    const handle = await fs.open(file, 'r').catch(() => undefined);
+    if (!handle) {
+        return '';
+    }
+    try {
+        const { size } = await handle.stat();
+        const length = Math.min(size, TAIL_BYTES);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, size - length);
+        return buffer.toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+function duration(from, to = new Date().toISOString()) {
+    const seconds = Math.max(0, Math.round((Date.parse(to) - Date.parse(from)) / 1000));
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor(seconds % 3600 / 60);
+    return `${h ? `${h}h ` : ''}${h || m ? `${m}m ` : ''}${seconds % 60}s`;
+}
+export async function startRun(ctx, args) {
+    const plan = await loadPlan(args.planId, 'run', ctx.env);
+    const program = await programOf(ctx, plan.program);
+    const problems = [];
+    if (program.path !== plan.binary) {
+        problems.push(`${plan.program} now resolves to ${program.path}, the plan was made with ${plan.binary}`);
+    }
+    await existingPath(plan.launchDir, 'Launch directory', 'dir').catch((e) => problems.push(e.message));
+    const changed = changedFiles(plan.hashes, await hashFiles(Object.keys(plan.hashes)));
+    if (changed.length) {
+        problems.push(`files changed since the plan: ${changed.join(', ')}`);
+    }
+    // План одноразовый: и после запуска, и после отказа он больше не годится.
+    await dropPlan(plan.id, ctx.env);
+    if (problems.length) {
+        throw new Error(`The plan no longer matches the project, nothing was started: ${problems.join('; ')}. Run bio_plan again and show the new plan to the user.`);
+    }
+    await cleanupRuns(ctx);
+    if (plan.makeDir) {
+        await fs.mkdir(plan.makeDir, { recursive: true });
+    }
+    const paths = await runPaths(ctx.env, plan.id);
+    const fd = openSync(paths.log, 'a', 0o600);
+    await fs.chmod(paths.log, 0o600).catch(() => undefined);
+    const child = spawn(plan.binary, [...plan.args], {
+        cwd: plan.launchDir,
+        env: programEnv(plan.program, ctx.env, { offline: plan.offline }),
+        detached: true,
+        stdio: ['ignore', fd, fd],
+        windowsHide: true,
+    });
+    // Обработчик выхода — сразу: короткий прогон может завершиться раньше, чем запись прогона ляжет на диск.
+    let saved = false;
+    let settle = () => undefined;
+    ctx.children.set(plan.id, new Promise(resolve => { settle = resolve; }));
+    child.on('exit', (code, signal) => {
+        const at = new Date().toISOString();
+        ctx.exits.set(plan.id, { code, signal, at });
+        ctx.children.delete(plan.id);
+        settle({ code, signal, at });
+        if (saved) {
+            void updateRun(plan.id, { finishedAt: at, exitCode: code, signal }, ctx.env).catch(() => undefined);
+        }
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            child.once('spawn', resolve);
+            child.once('error', reject);
+        });
+    }
+    catch (error) {
+        ctx.children.delete(plan.id);
+        throw new Error(`Could not start ${plan.binary}: ${error.message}`);
+    }
+    finally {
+        closeSync(fd);
+    }
+    // Поздние ошибки процесса не должны ронять сервер.
+    child.on('error', () => undefined);
+    const record = {
+        id: plan.id, program: plan.program, pipeline: plan.pipeline, launchDir: plan.launchDir, args: plan.args, outputs: plan.outputs,
+        pid: child.pid, startedAt: new Date().toISOString(), log: paths.log, ...plan.report ? { report: plan.report } : {},
+    };
+    await saveRun(record, ctx.env);
+    saved = true;
+    const early = ctx.exits.get(plan.id);
+    if (early) {
+        await updateRun(plan.id, { finishedAt: early.at, exitCode: early.code, signal: early.signal }, ctx.env);
+    }
+    child.unref();
+    return [
+        `Started ${plan.program} in the background (PID ${record.pid}).`,
+        `Run id: ${record.id}`,
+        `Log: ${paths.log}`,
+        ...plan.report ? [`Execution report (written when the run ends): ${plan.report}`] : [],
+        `Outputs: ${plan.outputs}.`,
+        'Call bio_run_status with the run id to follow progress.',
+    ].join('\n');
+}
+export async function runStatus(ctx, args) {
+    const record = await loadRun(args.runId, ctx.env);
+    const log = await tailOf(record.log);
+    const state = await stateOf(ctx, record, log);
+    const progress = record.program === 'nextflow' ? nextflowProgress(log) : record.program === 'snakemake' ? snakemakeProgress(log) : [];
+    const tail = log.split('\n').slice(-TAIL_LINES - 1).join('\n').trim();
+    return [
+        `Run ${record.id}: ${record.program} ${record.pipeline}`,
+        `State: ${state.text}`,
+        `Started: ${record.startedAt} (${duration(record.startedAt, record.finishedAt)} ${state.running ? 'so far' : 'total'})`,
+        `Outputs: ${record.outputs}.`,
+        ...record.report ? [`Report: ${record.report}`] : [],
+        ...progress.length ? ['Progress:', ...progress.map(line => `  ${line}`)] : [],
+        '',
+        `Last ${TAIL_LINES} lines of ${record.log}:`,
+        tail || '(log is empty)',
+    ].join('\n');
+}
+export async function stopPlan(ctx, args) {
+    const record = await loadRun(args.runId, ctx.env);
+    const state = await stateOf(ctx, record, await tailOf(record.log));
+    if (!state.running) {
+        throw new Error(`Run ${record.id} is not running: ${state.text}.`);
+    }
+    const plan = { id: newId(), type: 'stop', createdAt: new Date().toISOString(), runId: record.id, pid: record.pid, startedAt: record.startedAt };
+    await savePlan(plan, ctx.env);
+    const progress = record.program === 'nextflow' ? nextflowProgress(await tailOf(record.log)) : snakemakeProgress(await tailOf(record.log));
+    return [
+        `Stop ${record.program} run ${record.id}: ${record.pipeline}`,
+        `PID ${record.pid}, running for ${duration(record.startedAt)} (since ${record.startedAt}).`,
+        ...progress.length ? ['Progress:', ...progress.map(line => `  ${line}`)] : [],
+        `bio_run_stop_apply sends SIGTERM to this process. ${record.program === 'nextflow' ? 'Nextflow cancels its running tasks before it exits' : 'The program stops its running jobs'}; work already done is lost unless the pipeline can resume.`,
+        '',
+        `Plan id: ${plan.id}`,
+        'Call bio_run_stop_apply with this id only after the user confirms.',
+    ].join('\n');
+}
+export async function stopApply(ctx, args) {
+    const plan = await loadPlan(args.planId, 'stop', ctx.env);
+    await dropPlan(plan.id, ctx.env);
+    const record = await loadRun(plan.runId, ctx.env);
+    if (record.pid !== plan.pid || record.startedAt !== plan.startedAt) {
+        throw new Error(`Run ${record.id} is not the process the stop plan was made for. Nothing was stopped.`);
+    }
+    const state = await stateOf(ctx, record, await tailOf(record.log));
+    if (!state.running) {
+        throw new Error(`Run ${record.id} is no longer running: ${state.text}. Nothing was stopped.`);
+    }
+    process.kill(record.pid, 'SIGTERM');
+    await updateRun(record.id, { stopRequestedAt: new Date().toISOString() }, ctx.env);
+    return `SIGTERM sent to ${record.program} (PID ${record.pid}). It may take a while to cancel running tasks; check bio_run_status with run id ${record.id}.`;
+}
+/** Чистка записей старше недели; возвращает id идущих прогонов. */
+async function cleanupRuns(ctx) {
+    const running = new Set();
+    for (const record of await listRuns(ctx.env)) {
+        if (!ctx.exits.has(record.id) && !record.finishedAt && await isAlive(record)) {
+            running.add(record.id);
+        }
+    }
+    await dropStaleRuns(ctx.env, record => running.has(record.id));
+    return running;
+}
+export async function runsList(ctx) {
+    const running = await cleanupRuns(ctx);
+    const records = await listRuns(ctx.env);
+    if (!records.length) {
+        return 'No runs recorded by this server (records of finished runs are kept for 7 days).';
+    }
+    const rows = await Promise.all(records.map(async (record) => {
+        const state = await stateOf(ctx, record, running.has(record.id) ? '' : await tailOf(record.log));
+        return `${record.id}  ${record.program}  ${state.text}  started ${record.startedAt}  ${record.pipeline}`;
+    }));
+    return rows.join('\n');
+}

package/dist/src/server.js

@@ -0,0 +1,88 @@
+// Copyright (c) NeuralBridge. Licensed under the Apache License, Version 2.0. See LICENSE.
+// MCP-сервер power `nb-bio-pipelines`: инструменты Nextflow, miniwdl и Snakemake с описаниями и пометками для клиента.
+// «Только чтение» — у поиска программ, состояния и списка прогонов; lint Snakemake исполняет Snakefile, план — код пайплайна.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { createContext } from './context.js';
+import { detect, lint } from './inspect.js';
+import { plan } from './plan.js';
+import { reply } from './reply.js';
+import { runsList, runStatus, startRun, stopApply, stopPlan } from './runs.js';
+export const SERVER_NAME = 'nb-bio-pipelines';
+export const SERVER_VERSION = '1.0.0';
+const program = z.enum(['nextflow', 'snakemake', 'miniwdl']);
+const absolute = (what) => z.string().min(1).describe(`Absolute local path of ${what}.`);
+const planId = z.string().describe('Plan id returned by the matching plan tool.');
+const runId = z.string().describe('Run id returned by bio_run.');
+export function createServer(env = process.env) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    const ctx = createContext(env);
+    server.registerTool('bio_detect', {
+        title: 'Detect pipeline tools and pipelines',
+        description: 'Report which of nextflow, miniwdl and snakemake are installed and their versions. With "dir", also list main.nf, nextflow.config, .wdl files and Snakefiles under it. Read-only. The very first call of the nextflow launcher downloads the Nextflow runtime into ~/.nextflow; that is how Nextflow installs itself.',
+        inputSchema: { dir: absolute('the project directory to scan').optional() },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, args => reply(() => detect(ctx, args)));
+    server.registerTool('bio_lint', {
+        title: 'Lint pipelines',
+        description: 'Static checks with file and line: "nextflow lint" (Nextflow 25.04 or newer; skipped with a note for older versions), "miniwdl check" for each .wdl file, "snakemake --lint" for each Snakefile. "path" is a file or a directory. Does not run any task, but Snakemake evaluates the Snakefile (Python code of the project) to lint it.',
+        inputSchema: {
+            path: absolute('a pipeline file or directory'),
+            program: program.optional().describe('Lint only files of this tool.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, args => reply(() => lint(ctx, args)));
+    server.registerTool('bio_plan', {
+        title: 'Dry-run and plan a pipeline run',
+        description: 'Check a run without executing tasks and save it as a plan: Nextflow "run -preview -with-dag" (processes in the DAG), Snakemake "--dry-run" (jobs per rule), miniwdl "check" plus a check of the inputs JSON against the required inputs. Returns what will run, where outputs go, what the tools will download, the exact command and a plan id for bio_run. Only local pipelines: "pipeline" must be an absolute path, remote pipeline names are not accepted. Evaluates the pipeline code and may write tool metadata (.nextflow, .snakemake) in the launch directory; runs no tasks.',
+        inputSchema: {
+            program,
+            pipeline: absolute('main.nf or its directory (Nextflow), a Snakefile or its project directory (Snakemake), or a .wdl file (miniwdl)'),
+            launchDir: absolute('the directory to run in (Snakemake: --directory, where outputs are written). Default: the pipeline directory').optional(),
+            paramsFile: absolute('a JSON or YAML params file (Nextflow -params-file)').optional(),
+            profile: z.string().regex(/^[A-Za-z0-9_./\\:][A-Za-z0-9_.,/\\:-]*$/, 'not a profile name').optional().describe('Nextflow: -profile name(s), comma-separated. Snakemake: --profile name or absolute path.'),
+            workDir: absolute('the Nextflow work directory (-work-dir). Default: work/ in the launch directory').optional(),
+            resume: z.boolean().optional().describe('Nextflow: -resume, reuse cached results of a previous run.'),
+            offline: z.boolean().optional().describe('Nextflow: set NXF_OFFLINE=true, so Nextflow downloads no pipelines or plugins (plugins must already be installed).'),
+            configFiles: z.array(absolute('a Snakemake config file')).optional().describe('Snakemake: --configfile files.'),
+            cores: z.number().int().min(1).optional().describe('Snakemake: --cores, required for Snakemake.'),
+            softwareDeployment: z.array(z.enum(['conda', 'apptainer', 'env-modules'])).optional().describe('Snakemake 8+: --software-deployment-method. Off unless the user asks: Snakemake then creates Conda environments or pulls images.'),
+            targets: z.array(z.string().regex(/^[^-\s]\S*$/, 'not a target')).optional().describe('Snakemake: rules or files to build. Default: the first rule.'),
+            inputs: absolute('the inputs JSON (miniwdl -i)').optional(),
+            outputDir: absolute('the directory under which miniwdl creates the run directory (--dir); miniwdl only. Default: the launch directory').optional(),
+            task: z.string().regex(/^[A-Za-z_][\w]*$/, 'not a task name').optional().describe('miniwdl: --task, for documents with several tasks and no workflow.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, args => reply(() => plan(ctx, args)));
+    server.registerTool('bio_run', {
+        title: 'Start a reviewed pipeline run',
+        description: 'Start exactly the run saved by bio_plan, in the background, and return a run id at once. Checks first that the pipeline, config, params and inputs files are unchanged. Runs long computations, writes results and may overwrite existing outputs; container images and Conda environments are pulled by the tool when needed, and tasks run with the executor configured for the pipeline. Call only after showing the plan to the user and getting explicit approval. A plan id works once.',
+        inputSchema: { planId },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    }, args => reply(() => startRun(ctx, args)));
+    server.registerTool('bio_run_status', {
+        title: 'Run status',
+        description: 'State of a run started by bio_run: running or finished, exit code, duration, progress (Nextflow processes, Snakemake steps) and the last 100 lines of its log with secrets masked. Read-only.',
+        inputSchema: { runId },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, args => reply(() => runStatus(ctx, args)));
+    server.registerTool('bio_run_stop_plan', {
+        title: 'Plan stopping a run',
+        description: 'Show what is running for a run id and for how long, and save a stop plan. Stops nothing.',
+        inputSchema: { runId },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, args => reply(() => stopPlan(ctx, args)));
+    server.registerTool('bio_run_stop_apply', {
+        title: 'Stop a run',
+        description: 'Send SIGTERM to the run saved in a stop plan; the tool cancels its running tasks and exits. Call only after showing the plan to the user and getting explicit approval. A plan id works once.',
+        inputSchema: { planId },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+    }, args => reply(() => stopApply(ctx, args)));
+    server.registerTool('bio_runs', {
+        title: 'List runs',
+        description: 'Runs started through this server with their state, newest first. Records of finished runs and their logs are kept for 7 days. Read-only.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, () => reply(() => runsList(ctx)));
+    return server;
+}

package/dist/src/store.js

@@ -0,0 +1,126 @@
+// Copyright (c) NeuralBridge. Licensed under the Apache License, Version 2.0. See LICENSE.
+// Данные сервера в `PLUGIN_DATA` (или во временной папке): планы `plans/<id>.json` — одноразовые, живут сутки;
+// прогоны `runs/<id>.json` с логом `runs/<id>.log` и отчётом — неделю после завершения. Папки 0700, файлы 0600.
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const PLAN_TTL_MS = 24 * 60 * 60 * 1000;
+export const RUN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export function dataRoot(env) {
+    return env['PLUGIN_DATA'] || join(tmpdir(), 'nb-bio-pipelines');
+}
+/** Папка только владельцу, даже если уже была создана с другими правами. */
+async function ensureDir(path) {
+    await fs.mkdir(path, { recursive: true, mode: 0o700 });
+    await fs.chmod(path, 0o700).catch(() => undefined);
+    return path;
+}
+export async function plansDir(env) {
+    await ensureDir(dataRoot(env));
+    return ensureDir(join(dataRoot(env), 'plans'));
+}
+export async function runsDir(env) {
+    await ensureDir(dataRoot(env));
+    return ensureDir(join(dataRoot(env), 'runs'));
+}
+export function newId() {
+    return randomUUID();
+}
+/** Старые планы и временные файлы планов (`<id>*`) удаляются при каждом новом плане. */
+async function dropStalePlans(dir, now) {
+    const names = await fs.readdir(dir).catch(() => []);
+    await Promise.all(names.filter(name => ID.test(name.slice(0, 36))).map(async (name) => {
+        const stat = await fs.stat(join(dir, name)).catch(() => undefined);
+        if (stat && now - stat.mtimeMs > PLAN_TTL_MS) {
+            await fs.rm(join(dir, name), { force: true, recursive: true });
+        }
+    }));
+}
+export async function savePlan(plan, env, now = Date.now()) {
+    const dir = await plansDir(env);
+    await dropStalePlans(dir, now);
+    await fs.writeFile(join(dir, `${plan.id}.json`), JSON.stringify(plan, null, 2), { encoding: 'utf8', mode: 0o600 });
+}
+const TOOL_OF = { run: 'bio_plan', stop: 'bio_run_stop_plan' };
+/** План по id и виду: план остановки нельзя передать в запуск и наоборот. */
+export async function loadPlan(id, type, env, now = Date.now()) {
+    if (!ID.test(id)) {
+        throw new Error(`Unknown plan id "${id}".`);
+    }
+    const file = join(await plansDir(env), `${id}.json`);
+    const raw = await fs.readFile(file, 'utf8').catch(() => undefined);
+    const plan = raw ? JSON.parse(raw) : undefined;
+    if (!plan || now - Date.parse(plan.createdAt) > PLAN_TTL_MS) {
+        await fs.rm(file, { force: true });
+        throw new Error(`Plan "${id}" was not found (plans are used once and expire after 24 hours). Run ${TOOL_OF[type]} first.`);
+    }
+    if (plan.type !== type) {
+        throw new Error(`Plan "${id}" was made by ${TOOL_OF[plan.type]}, not by ${TOOL_OF[type]}.`);
+    }
+    return plan;
+}
+export async function dropPlan(id, env) {
+    const dir = await plansDir(env);
+    const names = await fs.readdir(dir).catch(() => []);
+    await Promise.all(names.filter(name => name.startsWith(id)).map(name => fs.rm(join(dir, name), { force: true, recursive: true })));
+}
+export async function runPaths(env, id) {
+    const dir = await runsDir(env);
+    return { json: join(dir, `${id}.json`), log: join(dir, `${id}.log`), report: join(dir, `${id}-report.html`) };
+}
+/** Запись прогона целиком: во временный файл и переименованием — читатель не увидит наполовину записанный файл. */
+export async function saveRun(record, env) {
+    const { json } = await runPaths(env, record.id);
+    const tmp = `${json}.${randomUUID()}.tmp`;
+    try {
+        await fs.writeFile(tmp, JSON.stringify(record, null, 2), { encoding: 'utf8', mode: 0o600 });
+        await fs.rename(tmp, json);
+    }
+    catch (error) {
+        await fs.rm(tmp, { force: true });
+        throw error;
+    }
+}
+/** Правки одной записи по очереди: выход процесса и запрос остановки не затирают друг друга. */
+const updates = new Map();
+export async function loadRun(id, env) {
+    if (!ID.test(id)) {
+        throw new Error(`Unknown run id "${id}".`);
+    }
+    const { json } = await runPaths(env, id);
+    const raw = await fs.readFile(json, 'utf8').catch(() => undefined);
+    if (!raw) {
+        throw new Error(`Run "${id}" was not found. Records of finished runs are kept for 7 days; see bio_runs.`);
+    }
+    return JSON.parse(raw);
+}
+export async function updateRun(id, patch, env) {
+    const next = (updates.get(id) ?? Promise.resolve()).then(async () => {
+        const record = await loadRun(id, env).catch(() => undefined);
+        if (record) {
+            await saveRun({ ...record, ...patch }, env);
+        }
+    });
+    const tail = next.catch(() => undefined);
+    updates.set(id, tail);
+    void tail.then(() => updates.get(id) === tail && updates.delete(id));
+    return next;
+}
+export async function listRuns(env) {
+    const dir = await runsDir(env);
+    const names = (await fs.readdir(dir).catch(() => [])).filter(name => ID.test(name.slice(0, 36)) && name.length === 41 && name.endsWith('.json'));
+    const records = await Promise.all(names.map(name => loadRun(name.slice(0, 36), env).catch(() => undefined)));
+    return records.filter((r) => r !== undefined).sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+/** Записи завершённых прогонов старше недели удаляются вместе с логом и отчётом; идущие прогоны не трогаются. */
+export async function dropStaleRuns(env, isRunning, now = Date.now()) {
+    for (const record of await listRuns(env)) {
+        const age = now - Date.parse(record.finishedAt ?? record.startedAt);
+        if (age > RUN_TTL_MS && !isRunning(record)) {
+            const paths = await runPaths(env, record.id);
+            await Promise.all([paths.json, paths.log, paths.report].map(file => fs.rm(file, { force: true })));
+        }
+    }
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@neuralbridge/bio-pipelines-mcp",
-  "version": "0.0.0",
-  "description": "MCP server by NeuralBridge. Bioinformatics pipelines with Nextflow, WDL and Snakemake. Placeholder: the server is not released yet.",
+  "version": "1.0.0",
+  "description": "MCP server for bioinformatics pipelines with Nextflow, miniwdl and Snakemake: detect, lint, dry-run plan, start a reviewed run in the background, follow and stop it.",
   "license": "Apache-2.0",
-  "author": "NeuralBridge (https://neuralbridge.ru)",
+  "author": "NeuralBridge",
   "homepage": "https://neuralbridge.ru",
   "repository": {
     "type": "git",
@@ -12,14 +12,36 @@
   },
   "keywords": [
     "mcp",
+    "nextflow",
+    "snakemake",
+    "miniwdl",
+    "wdl",
+    "bioinformatics",
     "neuralbridge"
   ],
+  "type": "module",
+  "bin": {
+    "nb-bio-pipelines-mcp": "dist/src/index.js"
+  },
   "files": [
+    "dist/src",
     "README.md",
     "LICENSE",
     "NOTICE"
   ],
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test \"dist/test/*.test.js\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.6",
+    "typescript": "7.0.2"
   }
 }