From 7173cbdea9b2003d53e8cff8dcaf6a4bd38c2c28 Mon Sep 17 00:00:00 2001
From: Denys Kuchma <den.kuchma@ukr.net>
Date: Mon, 14 Sep 2026 16:04:05 +0200
Subject: [PATCH] Add tests_bulk_upsert MCP tool

---
 README.md                                |  14 ++
 docs/tools.md                            |  30 +++
 src/mcp/definitions/tests.js             |  28 +++
 src/mcp/markdown/parse-tests-markdown.js | 196 +++++++++++++++
 src/mcp/registry/bulk-upsert.js          | 292 +++++++++++++++++++++++
 src/mcp/registry/handlers.js             |  56 +++++
 src/mcp/tool-registry.js                 |   4 +-
 7 files changed, 619 insertions(+), 1 deletion(-)
 create mode 100644 src/mcp/markdown/parse-tests-markdown.js
 create mode 100644 src/mcp/registry/bulk-upsert.js

diff --git a/README.md b/README.md
index a99c23b..359e97f 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@ Model Context Protocol (MCP) server that enables AI assistants (Claude, Cursor,
   - Attachments (scoped helpers for tests/suites/testruns)
   - Requirements (including file uploads from local file paths)
 - **Project Information** - fetch project configuration, metadata, features, and CI profiles
+- **Bulk Test Upsert** - `tests_bulk_upsert` creates/updates many tests from one classical tests markdown document (with `dry_run` preview)
 - **Issue Linking** - link/unlink issues to any resource
 - **API Compatibility** - automatic handling of payload format differences (flat vs wrapped)
 - **Automatic API Sessions** - groups MCP changes in Testomat.io history using API sessions
@@ -207,6 +208,19 @@ Add this config to `opencode.json` in your project root, or to `~/.config/openco
 }
 ```
 
+**Bulk create/update tests from markdown:**
+```json
+{
+  "name": "tests_bulk_upsert",
+  "arguments": {
+    "markdown": "<!-- suite\nid: @S380c64db\n-->\n# Login Functionality\n<!-- test\nid: @T12345678\ntype: manual\npriority: high\n-->\n# Successful Login\n## Steps\n* Navigate to the login page\n  *Expected*: Login form is displayed\n<!-- test -->\n# Failed Login\n## Steps\n* Enter invalid credentials\n  *Expected*: Error message is displayed",
+    "dry_run": true
+  }
+}
+```
+
+`tests_bulk_upsert` accepts a document in the [classical tests markdown format](https://docs.testomat.io/project/import-export/export-tests/classical-tests-markdown-format/) (the same format used by markdown export/sync). Tests with an `id: @T...` in their metadata are updated; tests without an id are created. Suites are resolved by `id: @S...` or title, and created when missing (`create_missing_suites: false` disables this). Use `dry_run: true` to parse the document and preview the planned actions without writing anything. Limits: up to 100 tests and 25 suites per call. All writes are grouped in a single API session; per-test errors are reported without blocking the rest of the document.
+
 ## Documentation
 
 Complete tool reference: [docs/tools.md](./docs/tools.md)
diff --git a/docs/tools.md b/docs/tools.md
index 471a514..b8baa1a 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -354,6 +354,36 @@ Unlink an issue from a test.
 
 ---
 
+### tests_bulk_upsert
+
+Bulk create/update tests from a [classical tests markdown](https://docs.testomat.io/project/import-export/export-tests/classical-tests-markdown-format/) document. Tests with an `id: @T...` in their metadata are updated; tests without an id are created. Suites are resolved by `id: @S...` or title, and created when missing.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| markdown | string | Yes | Markdown document in the testomat.io classical tests format |
+| dry_run | boolean | No | Parse the document and report planned actions without writing (default: false) |
+| create_missing_suites | boolean | No | Create suites that cannot be resolved by id or title (default: true) |
+| branch | string | No | Branch name |
+
+**Example:**
+```json
+{
+  "name": "tests_bulk_upsert",
+  "arguments": {
+    "markdown": "<!-- suite\nid: @S380c64db\n-->\n# Login Functionality\n<!-- test\nid: @T12345678\npriority: high\n-->\n# Successful Login\n## Steps\n* Navigate to the login page\n  *Expected*: Login form is displayed\n<!-- test -->\n# Failed Login\n## Steps\n* Enter invalid credentials\n  *Expected*: Error message is displayed"
+  }
+}
+```
+
+**Response:** summary with `stats` (suites created/reused, tests created/updated, errors), per-test `created`/`updated` lists, and per-test `errors` (failures do not block the rest of the document).
+
+**Notes:** limits are 100 tests and 25 suites per call; all writes share one API session (single entry in the change history).
+
+**API Endpoint:** `POST /api/v2/{project_id}/tests/bulk` (falls back to sequential `POST /tests` + `PUT /tests/{id}` when the bulk endpoint is unavailable)
+
+---
+
 ## Suite Management
 
 ### suites_list
diff --git a/src/mcp/definitions/tests.js b/src/mcp/definitions/tests.js
index 3a6fa9a..ea6197f 100644
--- a/src/mcp/definitions/tests.js
+++ b/src/mcp/definitions/tests.js
@@ -310,5 +310,33 @@ export const TESTS_TOOLS = [
       ],
       "additionalProperties": false
     }
+  },
+  {
+    "name": "tests_bulk_upsert",
+    "description": "Bulk create/update tests from a testomat.io classical tests markdown document (/api/v2/{project_id}/tests). Tests with an id (@T...) in their metadata are updated, tests without id are created. Suites are resolved by id (@S...) or title, and created when missing. Recommended batch size: up to 100 tests per call.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "markdown": {
+          "type": "string",
+          "description": "Markdown document in the testomat.io classical tests format: suite blocks (<!-- suite ... -->) containing test blocks (<!-- test ... -->), each followed by a title heading and a description. See https://docs.testomat.io/project/import-export/export-tests/classical-tests-markdown-format/"
+        },
+        "dry_run": {
+          "type": "boolean",
+          "default": false,
+          "description": "Parse the document and report the planned actions without writing anything"
+        },
+        "create_missing_suites": {
+          "type": "boolean",
+          "default": true,
+          "description": "Create suites that cannot be resolved by id or title. When false, tests of unresolved suites are reported as errors"
+        },
+        "branch": BRANCH_PARAM
+      },
+      "required": [
+        "markdown"
+      ],
+      "additionalProperties": false
+    }
   }
 ];
diff --git a/src/mcp/markdown/parse-tests-markdown.js b/src/mcp/markdown/parse-tests-markdown.js
new file mode 100644
index 0000000..f3124a7
--- /dev/null
+++ b/src/mcp/markdown/parse-tests-markdown.js
@@ -0,0 +1,196 @@
+export const TESTS_BULK_LIMITS = {
+  maxTests: 100,
+  maxSuites: 25,
+  maxMarkdownBytes: 512 * 1024,
+};
+
+const SUITE_MARKER = '<!-- suite';
+const TEST_MARKER = '<!-- test';
+const HEADING_PREFIX = '#';
+const COMMA_SEPARATED_LIST_KEYS = new Set(['tags', 'labels']);
+
+function parseCommaSeparatedList(value) {
+  if (!value) return [];
+  return value
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean);
+}
+
+function parseMetadataBlock(lines, startIndex) {
+  if (lines[startIndex].trim().endsWith('-->')) {
+    return { data: {}, endIndex: startIndex + 1, unterminated: false };
+  }
+
+  const metadata = {};
+  let i = startIndex + 1;
+  while (i < lines.length && lines[i].trim() !== '-->') {
+    const match = lines[i].trim().match(/^([^:]+):\s*(.*)$/);
+    if (match) {
+      const key = match[1].trim();
+      const value = match[2].trim();
+      metadata[key] = COMMA_SEPARATED_LIST_KEYS.has(key) ? parseCommaSeparatedList(value) : value;
+    }
+    i += 1;
+  }
+
+  return {
+    data: metadata,
+    endIndex: Math.min(i + 1, lines.length),
+    unterminated: i >= lines.length,
+  };
+}
+
+function trimBlankLines(listOfLines) {
+  let start = 0;
+  let end = listOfLines.length;
+  while (start < end && !listOfLines[start].trim()) start += 1;
+  while (end > start && !listOfLines[end - 1].trim()) end -= 1;
+  return listOfLines.slice(start, end);
+}
+
+export function parseTestsMarkdown(markdown) {
+  const suites = [];
+  const errors = [];
+
+  if (typeof markdown !== 'string' || !markdown.trim()) {
+    errors.push({ line: 1, message: 'Markdown document is empty' });
+    return { suites, errors };
+  }
+
+  if (Buffer.byteLength(markdown, 'utf8') > TESTS_BULK_LIMITS.maxMarkdownBytes) {
+    errors.push({
+      line: 1,
+      message: `Document exceeds the ${TESTS_BULK_LIMITS.maxMarkdownBytes} bytes limit; split it into smaller documents`,
+    });
+    return { suites, errors };
+  }
+
+  const lines = markdown.replace(/\r\n?/g, '\n').split('\n');
+  let currentSuite = null;
+  let currentTest = null;
+  let suiteDescriptionLines = [];
+
+  const closeTest = () => {
+    if (!currentTest) return;
+    currentSuite.tests.push({
+      uid: currentTest.uid,
+      title: currentTest.title,
+      description: trimBlankLines(currentTest.descriptionLines).join('\n'),
+      state: currentTest.state,
+      priority: currentTest.priority,
+      assignee: currentTest.assignee,
+      tags: currentTest.tags,
+      labels: currentTest.labels,
+    });
+    currentTest = null;
+  };
+
+  const closeSuite = () => {
+    if (!currentSuite) return;
+    currentSuite.description = trimBlankLines(suiteDescriptionLines).join('\n');
+    suites.push(currentSuite);
+    currentSuite = null;
+    suiteDescriptionLines = [];
+  };
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i].trim();
+
+    if (line.startsWith(SUITE_MARKER)) {
+      const markerLine = i + 1;
+      const block = parseMetadataBlock(lines, i);
+      if (block.unterminated) {
+        closeTest();
+        closeSuite();
+        errors.push({ line: markerLine, message: 'Unterminated "<!-- suite" block' });
+        break;
+      }
+      i = block.endIndex;
+
+      while (i < lines.length && !lines[i].trim()) i += 1;
+      if (i >= lines.length || !lines[i].trim().startsWith(HEADING_PREFIX)) {
+        closeTest();
+        closeSuite();
+        errors.push({
+          line: markerLine,
+          message: 'Suite block is not followed by a title heading; suite skipped',
+        });
+        continue;
+      }
+
+      closeTest();
+      closeSuite();
+      currentSuite = {
+        uid: block.data.id ?? null,
+        title: lines[i].trim().replace(/^#+\s*/, ''),
+        description: '',
+        tags: block.data.tags ?? [],
+        labels: block.data.labels ?? [],
+        assignee: block.data.assignee,
+        tests: [],
+      };
+      i += 1;
+      continue;
+    }
+
+    if (line.startsWith(TEST_MARKER)) {
+      const markerLine = i + 1;
+      const block = parseMetadataBlock(lines, i);
+      if (block.unterminated) {
+        closeTest();
+        errors.push({ line: markerLine, message: 'Unterminated "<!-- test" block' });
+        break;
+      }
+      i = block.endIndex;
+
+      while (i < lines.length && !lines[i].trim()) i += 1;
+      if (i >= lines.length || !lines[i].trim().startsWith(HEADING_PREFIX)) {
+        closeTest();
+        errors.push({
+          line: markerLine,
+          message: 'Test block is not followed by a title heading; test skipped',
+        });
+        continue;
+      }
+
+      closeTest();
+      if (!currentSuite) {
+        errors.push({ line: markerLine, message: 'Test block appears before any suite block; test skipped' });
+        i += 1;
+        continue;
+      }
+
+      currentTest = {
+        uid: block.data.id ?? null,
+        title: lines[i].trim().replace(/^#+\s*/, ''),
+        state: block.data.type,
+        priority: block.data.priority,
+        assignee: block.data.assignee,
+        tags: block.data.tags ?? [],
+        labels: block.data.labels ?? [],
+        descriptionLines: [],
+      };
+      i += 1;
+
+      while (i < lines.length) {
+        const next = lines[i].trim();
+        if (next.startsWith(SUITE_MARKER) || next.startsWith(TEST_MARKER)) break;
+        currentTest.descriptionLines.push(lines[i]);
+        i += 1;
+      }
+      continue;
+    }
+
+    if (currentSuite && !currentTest) {
+      suiteDescriptionLines.push(lines[i]);
+    }
+    i += 1;
+  }
+
+  closeTest();
+  closeSuite();
+
+  return { suites, errors };
+}
diff --git a/src/mcp/registry/bulk-upsert.js b/src/mcp/registry/bulk-upsert.js
new file mode 100644
index 0000000..cf4d884
--- /dev/null
+++ b/src/mcp/registry/bulk-upsert.js
@@ -0,0 +1,292 @@
+const LIST_PAGE_SIZE = 100;
+const MAX_LIST_PAGES = 10;
+
+function normalizeUid(uid, prefixLetter) {
+  const raw = String(uid || '').trim();
+  const stripped = raw.replace(/^@/, '');
+  if (stripped.length && stripped[0].toLowerCase() === prefixLetter.toLowerCase()) {
+    return stripped.slice(1).toLowerCase();
+  }
+  return null;
+}
+
+function pickIdFromResponse(response) {
+  return response?.data?.id ?? response?.id ?? null;
+}
+
+export const bulkMethods = {
+  async testsBulkUpsert(parsed, { branch, createMissingSuites = true } = {}) {
+    const stats = {
+      suites_created: 0,
+      suites_reused: 0,
+      tests_created: 0,
+      tests_updated: 0,
+      errors: 0,
+    };
+    const created = [];
+    const updated = [];
+    const errors = [];
+
+    const suiteResults = await this.resolveSuitesForBulk(parsed.suites, { branch, createMissingSuites });
+
+    const operations = [];
+    for (const result of suiteResults) {
+      if (result.skipped) continue;
+
+      if (result.error) {
+        for (const test of result.suite.tests) {
+          errors.push({ suite: result.suite.title, test: test.title, uid: test.uid, error: result.error, status: result.status ?? null });
+        }
+        stats.errors += result.suite.tests.length;
+        continue;
+      }
+
+      if (result.created) stats.suites_created += 1;
+      else stats.suites_reused += 1;
+
+      for (const test of result.suite.tests) {
+        operations.push({
+          action: test.uid ? 'update' : 'create',
+          test,
+          suiteId: result.suiteId,
+          suiteTitle: result.suite.title,
+        });
+      }
+    }
+
+    const results = await this.dispatchTestUpserts(operations, { branch });
+
+    for (const result of results) {
+      if (result.ok) {
+        if (result.action === 'create') {
+          stats.tests_created += 1;
+          created.push({ title: result.test.title, uid: result.test.uid, id: result.id });
+        } else {
+          stats.tests_updated += 1;
+          updated.push({ title: result.test.title, uid: result.test.uid, id: result.id });
+        }
+      } else {
+        stats.errors += 1;
+        errors.push({
+          suite: result.suiteTitle,
+          test: result.test.title,
+          uid: result.test.uid,
+          error: result.error,
+          status: result.status ?? null,
+          details: result.details ?? null,
+        });
+      }
+    }
+
+    return { stats, created, updated, errors };
+  },
+
+  async resolveSuitesForBulk(suites, { branch, createMissingSuites = true } = {}) {
+    const results = [];
+    if (!suites.length) return results;
+
+    const items = await this.listAllForBulk('suites', { branch });
+    const byUid = new Map();
+    const byTitle = new Map();
+    for (const item of items) {
+      const uidKey = normalizeUid(item.uid, 'S');
+      if (uidKey) byUid.set(uidKey, item.id);
+      if (item.title) byTitle.set(String(item.title).trim().toLowerCase(), item.id);
+    }
+
+    for (const suite of suites) {
+      if (!suite.tests.length) {
+        results.push({ suite, skipped: true });
+        continue;
+      }
+
+      let suiteId = null;
+      if (suite.uid) suiteId = byUid.get(normalizeUid(suite.uid, 'S')) ?? null;
+      if (!suiteId && suite.title) suiteId = byTitle.get(suite.title.toLowerCase()) ?? null;
+
+      if (suiteId) {
+        results.push({ suite, suiteId });
+        continue;
+      }
+
+      if (!createMissingSuites) {
+        results.push({ suite, error: `Suite "${suite.title}" not found and create_missing_suites is false` });
+        continue;
+      }
+
+      try {
+        const response = await this.createWrapped(
+          'suites',
+          'suite',
+          this.buildSuitePayload({ title: suite.title, description: suite.description })
+        );
+        const newId = pickIdFromResponse(response);
+        if (!newId) throw new Error('Suite was created but the response contained no id');
+        byTitle.set(suite.title.toLowerCase(), newId);
+        if (suite.uid) byUid.set(normalizeUid(suite.uid, 'S'), newId);
+        results.push({ suite, suiteId: newId, created: true });
+      } catch (error) {
+        results.push({ suite, error: error?.message || String(error), status: error?.status ?? null });
+      }
+    }
+
+    return results;
+  },
+
+  // POST /api/v2/{project}/tests/bulk when available; sequential loop otherwise
+  async dispatchTestUpserts(operations, { branch }) {
+    const query = branch ? { branch } : {};
+
+    try {
+      const response = await this.apiClient.createWithQuery('tests/bulk', {
+        query,
+        body: {
+          tests: operations.map(operation => ({
+            ...(operation.test.uid ? { id: operation.test.uid } : {}),
+            ...this.buildBulkTestPayload(operation.test, operation.suiteId),
+          })),
+        },
+      });
+      return this.mapBulkEndpointResults(operations, response);
+    } catch (error) {
+      if (![404, 405, 501].includes(error?.status)) {
+        return operations.map(operation => ({
+          ...operation,
+          ok: false,
+          error: `Bulk endpoint failed: ${error?.message || String(error)}`,
+          status: error?.status ?? null,
+          details: error?.payload ?? null,
+        }));
+      }
+    }
+
+    return this.dispatchTestUpsertsSequentially(operations, { branch });
+  },
+
+  mapBulkEndpointResults(operations, response) {
+    const items = Array.isArray(response) ? response : (response?.data ?? response?.results ?? []);
+    return operations.map((operation, index) => {
+      const item = items[index] ?? {};
+      const id = item.id ?? item.test_id ?? null;
+      const itemError = item.error?.message || (typeof item.error === 'string' ? item.error : null);
+
+      if (itemError || ['error', 'failed'].includes(item.status)) {
+        return {
+          ...operation,
+          ok: false,
+          error: itemError || 'Bulk operation failed',
+          status: typeof item.status === 'number' ? item.status : null,
+          details: item,
+        };
+      }
+
+      return { action: operation.action, test: operation.test, suiteTitle: operation.suiteTitle, ok: true, id };
+    });
+  },
+
+  async dispatchTestUpsertsSequentially(operations, { branch }) {
+    const state = {};
+    const results = [];
+
+    for (const operation of operations) {
+      try {
+        results.push(await this.upsertSingleTest(operation, { branch, state }));
+      } catch (error) {
+        results.push({
+          ...operation,
+          ok: false,
+          error: error?.message || String(error),
+          status: error?.status ?? null,
+          details: error?.payload ?? null,
+        });
+      }
+    }
+
+    return results;
+  },
+
+  async upsertSingleTest({ action, test, suiteId, suiteTitle }, { branch, state }) {
+    const payload = this.buildBulkTestPayload(test, suiteId);
+    const query = branch ? { branch } : {};
+
+    if (action === 'create') {
+      const response = await this.createWrapped('tests', 'test', payload, query);
+      return { action, test, suiteTitle, ok: true, id: pickIdFromResponse(response) };
+    }
+
+    // try the @T uid as the path id, fall back to a uid → id lookup on 404
+    try {
+      const response = await this.updateWrapped('tests', test.uid, 'test', payload, query);
+      return { action, test, suiteTitle, ok: true, id: pickIdFromResponse(response) };
+    } catch (error) {
+      if (error?.status !== 404) throw error;
+    }
+
+    const testId = await this.resolveTestIdForBulk(test.uid, { branch, state });
+    if (!testId) {
+      const notFound = new Error(
+        `Test ${test.uid} not found (deleted or on another branch); remove its id from the markdown to re-create it`
+      );
+      notFound.status = 404;
+      throw notFound;
+    }
+
+    const response = await this.updateWrapped('tests', testId, 'test', payload, query);
+    return { action, test, suiteTitle, ok: true, id: pickIdFromResponse(response) ?? testId };
+  },
+
+  async resolveTestIdForBulk(uid, { branch, state }) {
+    if (!state.testIdIndex) {
+      const items = await this.listAllForBulk('tests', { branch });
+      const index = new Map();
+      for (const item of items) {
+        const key = normalizeUid(item.uid, 'T');
+        if (key) index.set(key, item.id);
+      }
+      state.testIdIndex = index;
+    }
+    return state.testIdIndex.get(normalizeUid(uid, 'T')) ?? null;
+  },
+
+  buildBulkTestPayload(test, suiteId) {
+    const link = [];
+    for (const tag of test.tags) {
+      link.push({ action: 'add', type: 'tag', value: tag });
+    }
+    for (const label of test.labels) {
+      link.push({ action: 'add', type: 'label', value: label });
+    }
+
+    return this.buildTestPayload({
+      title: test.title,
+      suite_id: suiteId,
+      description: test.description,
+      priority: test.priority,
+      state: test.state,
+      assigned_to: test.assignee,
+      link: link.length ? link : undefined,
+    });
+  },
+
+  async listAllForBulk(resource, { branch, query = {} } = {}) {
+    const items = [];
+    for (let page = 1; page <= MAX_LIST_PAGES; page += 1) {
+      const response = await this.apiClient.list(resource, {
+        ...query,
+        per_page: LIST_PAGE_SIZE,
+        page,
+        ...(branch ? { branch } : {}),
+      });
+      const data = Array.isArray(response?.data) ? response.data : [];
+      items.push(...data);
+
+      const meta = response?.meta;
+      let hasMore;
+      if (typeof meta?.has_more === 'boolean') hasMore = meta.has_more;
+      else if (typeof meta?.total === 'number') hasMore = page * LIST_PAGE_SIZE < meta.total;
+      else hasMore = data.length === LIST_PAGE_SIZE;
+      if (!hasMore) break;
+    }
+    return items;
+  },
+};
diff --git a/src/mcp/registry/handlers.js b/src/mcp/registry/handlers.js
index 45d8a9c..eea9ac3 100644
--- a/src/mcp/registry/handlers.js
+++ b/src/mcp/registry/handlers.js
@@ -2,6 +2,7 @@ import { ENTITY_CRUD_CONFIGS } from '../configs/entity-crud-config.js';
 import { ATTACHMENT_SCOPED_TOOL_CONFIGS } from '../configs/attachments-config.js';
 import { ISSUE_SCOPED_TOOL_CONFIGS } from '../configs/issues-config.js';
 import { backendSlimQuery, slimList } from '../list-projection.js';
+import { parseTestsMarkdown, TESTS_BULK_LIMITS } from '../markdown/parse-tests-markdown.js';
 
 export const handlerMethods = {
   registerEntityCrudHandlers(handlers) {
@@ -139,6 +140,61 @@ export const handlerMethods = {
     handlers.issues_create = async (args = {}) => this.asText(await this.createIssue(args));
     handlers.issues_delete = async ({ issue_id: issueId, type }) =>
       this.asText(await this.apiClient.delete('issues', issueId, { type }));
+
+    handlers.tests_bulk_upsert = async (args = {}) => {
+      const {
+        markdown,
+        branch,
+        dry_run: dryRun = false,
+        create_missing_suites: createMissingSuites = true,
+      } = args;
+
+      if (typeof markdown !== 'string' || !markdown.trim()) {
+        return this.asText({ error: 'Argument "markdown" is required and must be a non-empty string' });
+      }
+
+      const parsed = parseTestsMarkdown(markdown);
+      const totalTests = parsed.suites.reduce((sum, suite) => sum + suite.tests.length, 0);
+      const totalSuites = parsed.suites.length;
+
+      if (parsed.errors.length || !totalTests) {
+        return this.asText({
+          error: 'Markdown could not be parsed; nothing was written',
+          errors: parsed.errors,
+        });
+      }
+      if (totalTests > TESTS_BULK_LIMITS.maxTests) {
+        return this.asText({
+          error: `Document contains ${totalTests} tests; the limit is ${TESTS_BULK_LIMITS.maxTests}. Split the markdown into smaller documents.`,
+        });
+      }
+      if (totalSuites > TESTS_BULK_LIMITS.maxSuites) {
+        return this.asText({
+          error: `Document contains ${totalSuites} suites; the limit is ${TESTS_BULK_LIMITS.maxSuites}. Split the markdown into smaller documents.`,
+        });
+      }
+
+      if (dryRun) {
+        const plan = [];
+        for (const suite of parsed.suites) {
+          for (const test of suite.tests) {
+            plan.push({ suite: suite.title, action: test.uid ? 'update' : 'create', title: test.title, uid: test.uid });
+          }
+        }
+        return this.asText({
+          dry_run: true,
+          planned: {
+            suites: totalSuites,
+            tests: totalTests,
+            creates: plan.filter(item => item.action === 'create').length,
+            updates: plan.filter(item => item.action === 'update').length,
+          },
+          plan,
+        });
+      }
+
+      return this.asText(await this.testsBulkUpsert(parsed, { branch, createMissingSuites }));
+    };
   },
 
   pickRequiredArg(args = {}, key) {
diff --git a/src/mcp/tool-registry.js b/src/mcp/tool-registry.js
index 45a61a6..873d7b4 100644
--- a/src/mcp/tool-registry.js
+++ b/src/mcp/tool-registry.js
@@ -8,6 +8,7 @@ import { attachmentMethods } from './registry/attachments.js';
 import { issueMethods } from './registry/issues.js';
 import { listingMethods } from './registry/listings.js';
 import { payloadMethods } from './registry/payloads.js';
+import { bulkMethods } from './registry/bulk-upsert.js';
 
 function withPagination(payload) {
   if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
@@ -116,5 +117,6 @@ Object.assign(
   attachmentMethods,
   listingMethods,
   issueMethods,
-  payloadMethods
+  payloadMethods,
+  bulkMethods
 );