@testomatio/mcp 2.2.1 → 3.0.0-beta.2

package/README.md

@@ -47,7 +47,15 @@ export TESTOMATIO_PROJECT_ID=<PROJECT_ID>
 testomatio-mcp
 ```
 
-**Optional: custom base URL**
+**Optional: custom host**
+```bash
+export TESTOMATIO_HOST=beta.testomat.io
+testomatio-mcp --host beta.testomat.io
+```
+
+A bare hostname is expanded to `https://<host>`. For full control use
+`--base-url` / `TESTOMATIO_BASE_URL`, which takes precedence over the host option:
+
 ```bash
 export TESTOMATIO_BASE_URL=https://beta.testomat.io
 ```
@@ -151,6 +159,48 @@ Add this config to `opencode.json` in your project root, or to `~/.config/openco
 }
 ```
 
+## HTTP Transport
+
+Besides stdio, the server runs over Streamable HTTP on a Cloudflare Worker hosted by
+Testomat.io. The project is part of the URL, so every tool signature stays the same:
+
+```
+https://mcp.testomat.io/mcp/<project_id>
+```
+
+Point an MCP client at that URL with a project token:
+
+```json
+{
+  "mcpServers": {
+    "testomatio": {
+      "url": "https://mcp.testomat.io/mcp/<PROJECT_ID>",
+      "headers": {
+        "Authorization": "Bearer <PROJECT_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+Web connectors such as claude.ai have nowhere to put a static token and instead run
+OAuth 2.1 with PKCE and Dynamic Client Registration against the same URL. Tokens
+starting with `testomat_` or `tstmt_` always bypass OAuth and are passed straight
+through, so IDE clients and CI keep working.
+
+The endpoint is POST only; `GET` returns `405`, because the server never initiates
+traffic. Testing with `curl` requires both media types in `Accept`:
+
+```bash
+curl -sS https://mcp.testomat.io/mcp/<PROJECT_ID> \
+  -H "Authorization: Bearer <PROJECT_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+Self-hosted installations keep using stdio.
+
 ## Quick Examples
 
 **List tests:**
@@ -232,7 +282,8 @@ src/
 | `TESTOMATIO_PROJECT_TOKEN` | Yes* | - | Project token (preferred) |
 | `TESTOMATIO_API_TOKEN` | Yes* | - | Alternative token |
 | `TESTOMATIO_PROJECT_ID` | Yes | - | Project ID |
-| `TESTOMATIO_BASE_URL` | No | `https://app.testomat.io` | API base URL |
+| `TESTOMATIO_HOST` | No | - | API host, e.g. `beta.testomat.io` |
+| `TESTOMATIO_BASE_URL` | No | `https://app.testomat.io` | API base URL, wins over `TESTOMATIO_HOST` |
 | `TESTOMATIO_TOOLS` | No | `full` | Tool profile: `full`, `core`, or `read` |
 
 *Either `TESTOMATIO_PROJECT_TOKEN` or `TESTOMATIO_API_TOKEN`
@@ -287,6 +338,7 @@ NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem testomatio-mcp --token <TOKEN>
 ```bash
 npm install
 npm run start -- --token <TOKEN> --project <PROJECT_ID>
+npm test
 ```
 
 For local MCP development, point Claude Desktop to the checked-out entrypoint:
@@ -372,3 +424,37 @@ Example `analytics_charts_results` call:
   }
 }
 ```
+
+### Worker deployment
+
+The `worker/` directory holds the Cloudflare Worker and is excluded from the npm
+package. Deploy it from that directory:
+
+```bash
+cd worker
+npx wrangler kv namespace create OAUTH_KV
+npx wrangler secret put TESTOMATIO_MCP_WORKER_SECRET
+npx wrangler deploy
+```
+
+Put the namespace id returned by the first command into `kv_namespaces` in
+`worker/wrangler.jsonc`. `TESTOMATIO_MCP_WORKER_SECRET` is the shared secret used to
+redeem authorization codes against Testomat.io server-to-server and is never
+committed.
+
+Before exposing the Worker publicly, configure Cloudflare rate-limiting rules for
+`/register`, `/authorize`, `/token`, and `/mcp/*`. These endpoints intentionally
+support unauthenticated OAuth discovery and client registration, so rate limiting
+belongs at the edge rather than in per-isolate memory. Keep separate rules and KV
+namespaces for beta and production.
+
+A beta worker is the same code deployed to the `beta` environment, which targets
+`https://beta.testomat.io` and keeps its own KV namespace so beta grants never
+reach the production one:
+
+```bash
+npx wrangler kv namespace create OAUTH_KV --env beta
+npx wrangler secret put TESTOMATIO_MCP_WORKER_SECRET --env beta
+npx wrangler deploy --env beta
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testomatio/mcp",
-  "version": "2.2.1",
+  "version": "3.0.0-beta.2",
   "description": "Model Context Protocol server for Testomatio API",
   "main": "src/index.js",
   "bin": {
@@ -10,7 +10,8 @@
   "scripts": {
     "start": "node index.js",
     "dev": "node index.js",
-    "sync:enterprise-package": "node scripts/sync-enterprise-package.js"
+    "sync:enterprise-package": "node scripts/sync-enterprise-package.js",
+    "test": "vitest run"
   },
   "keywords": [
     "testomatio",
@@ -27,7 +28,7 @@
     "url": "https://github.com/testomatio/mcp"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.4.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "commander": "^12.0.0",
     "dotenv": "^17.2.3"
   },
@@ -39,5 +40,11 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "devDependencies": {}
+  "devDependencies": {
+    "@cfworker/json-schema": "^4.1.1",
+    "@cloudflare/vitest-pool-workers": "^0.22.0",
+    "@cloudflare/workers-oauth-provider": "^0.10.3",
+    "vitest": "^4.1.11",
+    "wrangler": "^4.131.2"
+  }
 }

package/src/api/testomatio-client.js

@@ -1,4 +1,5 @@
 import { HttpClient } from './http-client.js';
+import { encodePathParameter } from '../core/path-segment.js';
 
 export class TestomatioApiClient {
   constructor({ baseUrl, projectId, token, logger }) {
@@ -14,9 +15,12 @@ export class TestomatioApiClient {
   }
 
   buildPath(resource, id = '') {
+    const safeProjectId = encodePathParameter(this.projectId, 'Project ID');
     const safeResource = String(resource).replace(/^\/+|\/+$/g, '');
-    const safeId = id ? `/${String(id).replace(/^\/+|\/+$/g, '')}` : '';
-    return `/api/v2/${this.projectId}/${safeResource}${safeId}`;
+    const resourceId = String(id ?? '');
+    const safeId = resourceId ? `/${encodePathParameter(resourceId, 'Resource ID')}` : '';
+
+    return `/api/v2/${safeProjectId}/${safeResource}${safeId}`;
   }
 
   list(resource, query = {}) {

package/src/cli/main.js

@@ -15,6 +15,7 @@ export function parseArgs(argv = process.argv) {
     .option('-t, --token <token>', 'Testomatio Project token')
     .option('-p, --project <project>', 'Project ID')
     .option('--base-url <url>', 'Base URL for Testomatio API')
+    .option('--host <host>', 'Testomatio host, e.g. beta.testomat.io')
     .option(
       '--tools <profile>',
       'Tool surface: full (default, all tools), core (common entities only), read (read-only)'

package/src/config/load-config.js

@@ -10,13 +10,43 @@ function normalizeBaseUrl(value) {
   return normalized.replace(/\/+$/, '');
 }
 
-export function loadConfig(argvOptions = {}) {
+function hostToBaseUrl(value) {
+  const host = normalizeBaseUrl(value);
+
+  if (!host) {
+    return '';
+  }
+
+  return /^https?:\/\//i.test(host) ? host : `https://${host}`;
+}
+
+export function resolveBaseUrl(argvOptions = {}, env = process.env) {
+  const explicitBaseUrl = normalizeBaseUrl(argvOptions.baseUrl || env.TESTOMATIO_BASE_URL);
+  if (explicitBaseUrl) {
+    return explicitBaseUrl;
+  }
+
+  const hostBaseUrl = hostToBaseUrl(argvOptions.host || env.TESTOMATIO_HOST);
+  if (hostBaseUrl) {
+    return hostBaseUrl;
+  }
+
+  return DEFAULT_BASE_URL;
+}
+
+export function loadServerConfig(argvOptions = {}, env = process.env) {
+  return {
+    baseUrl: resolveBaseUrl(argvOptions, env),
+  };
+}
+
+export function loadConfig(argvOptions = {}, env = process.env) {
   const token = normalizeString(
-    argvOptions.token || process.env.TESTOMATIO_PROJECT_TOKEN || process.env.TESTOMATIO_API_TOKEN
+    argvOptions.token || env.TESTOMATIO_PROJECT_TOKEN || env.TESTOMATIO_API_TOKEN
   );
-  const projectId = normalizeString(argvOptions.project || process.env.TESTOMATIO_PROJECT_ID);
-  const baseUrl = normalizeBaseUrl(argvOptions.baseUrl || process.env.TESTOMATIO_BASE_URL || DEFAULT_BASE_URL);
-  const rawToolsProfile = normalizeString(argvOptions.tools || process.env.TESTOMATIO_TOOLS).toLowerCase();
+  const projectId = normalizeString(argvOptions.project || env.TESTOMATIO_PROJECT_ID);
+  const baseUrl = resolveBaseUrl(argvOptions, env);
+  const rawToolsProfile = normalizeString(argvOptions.tools || env.TESTOMATIO_TOOLS).toLowerCase();
   const toolsProfile = rawToolsProfile || DEFAULT_PROFILE;
 
   if (!token) {

package/src/core/path-segment.js

@@ -0,0 +1,21 @@
+function pathParameter(value, label = 'Path parameter') {
+  const segment = String(value ?? '');
+
+  if (!segment || segment === '.' || segment === '..' || segment.includes('/') || segment.includes('\\')) {
+    throw new TypeError(`${label} must be a single URL path segment`);
+  }
+
+  return segment;
+}
+
+export function encodePathParameter(value, label) {
+  return encodeURIComponent(pathParameter(value, label));
+}
+
+export function decodePathParameter(value, label) {
+  try {
+    return pathParameter(decodeURIComponent(value), label);
+  } catch {
+    return '';
+  }
+}

package/src/mcp/create-server.js

@@ -0,0 +1,16 @@
+import { TestomatioApiClient } from '../api/testomatio-client.js';
+import { createLogger } from '../core/logger.js';
+import { TestomatioMCPServer } from './server.js';
+
+export function createMcpServer({ token, projectId, baseUrl, logger, version, jsonSchemaValidator }) {
+  const config = { token, projectId, baseUrl };
+  const serverLogger = logger || createLogger();
+
+  return new TestomatioMCPServer({
+    config,
+    apiClient: new TestomatioApiClient({ ...config, logger: serverLogger }),
+    logger: serverLogger,
+    version,
+    jsonSchemaValidator,
+  });
+}

package/src/mcp/definitions/shares.js

@@ -0,0 +1,110 @@
+export const SHARES_TOOLS = [
+  {
+    "name": "tests_share",
+    "description": "Share tests into a suite of another project (/api/v2/{project_id}/shares/tests). Select tests by test_ids, labels, or both (combined). The source project stays the single source of truth; shared copies in the target project are read-only until unlinked. Re-sharing into the same target project does not duplicate. Requests are processed asynchronously: status 'queued' means accepted, not completed. Matched tests that are themselves shared copies are skipped and listed in skipped_test_ids. Source and target projects must be of the same type (Classic/BDD).",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "test_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Test IDs to share. At least one of test_ids/labels is required. Max 1000 tests per request."
+        },
+        "labels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Label slugs or titles; every test carrying any of these labels is shared, in addition to test_ids."
+        },
+        "target_project_id": {
+          "type": "string",
+          "description": "Project ID (slug) of the destination project. Must be accessible to the current user."
+        },
+        "target_suite_id": {
+          "type": "string",
+          "description": "Suite ID in the target project to place the shared tests into. Must be a file-type suite, not a folder."
+        }
+      },
+      "required": [
+        "target_project_id",
+        "target_suite_id"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "suites_share",
+    "description": "Share suites (with their tests) into one or more other projects (/api/v2/{project_id}/shares/suites). Select suites by suite_ids, labels, or both (combined). File-type suites are linked (read-only copies that stay in sync); folder suites are deep-copied as regular editable copies. Re-sharing a linked suite into a project that already has it does not duplicate. Suites that are themselves shared copies link to their original source. Omit destination_folder_id to share into the root of the target project(s). Requests are processed asynchronously: status 'queued' means accepted, not completed. Source and target projects must be of the same type (Classic/BDD).",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "suite_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Suite IDs to share. At least one of suite_ids/labels is required. Max 200 suites per request."
+        },
+        "labels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Label slugs or titles; every suite carrying any of these labels is shared, in addition to suite_ids."
+        },
+        "target_project_ids": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Project IDs (slugs) of the destination projects. Must be accessible to the current user."
+        },
+        "destination_folder_id": {
+          "type": "string",
+          "description": "Folder suite ID in the target project to place the shared suites into. Only allowed when sharing to a single target project."
+        }
+      },
+      "required": [
+        "target_project_ids"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "tests_unshare",
+    "description": "Remove a test's share, converting the shared copy back into a regular, editable test (/api/v2/{project_id}/shares/tests/{id}). Only the shared copy can be targeted — the original source test is untouched. Must be called against the project that holds the shared copy.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "test_id": {
+          "type": "string",
+          "description": "ID of the shared test copy to unlink."
+        }
+      },
+      "required": [
+        "test_id"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "suites_unshare",
+    "description": "Remove a suite's share, converting the shared copy back into a regular, editable suite (/api/v2/{project_id}/shares/suites/{id}). Only the shared (linked) copy can be targeted — the original source suite is untouched. Must be called against the project that holds the shared copy.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "suite_id": {
+          "type": "string",
+          "description": "ID of the shared suite copy to unlink."
+        }
+      },
+      "required": [
+        "suite_id"
+      ],
+      "additionalProperties": false
+    }
+  }
+];

package/src/mcp/registry/shares.js

@@ -0,0 +1,53 @@
+export const shareMethods = {
+  registerShareHandlers(handlers) {
+    handlers.tests_share = async (args = {}) => {
+      const payload = {
+        target_project_id: this.pickRequiredArg(args, 'target_project_id'),
+        target_suite_id: this.pickRequiredArg(args, 'target_suite_id'),
+      };
+      this.pickSelectionArgs(args, ['test_ids', 'labels'], payload);
+      return this.asText(await this.apiClient.create('shares/tests', payload));
+    };
+
+    handlers.suites_share = async (args = {}) => {
+      const payload = {
+        target_project_ids: this.pickRequiredArg(args, 'target_project_ids'),
+      };
+      this.pickSelectionArgs(args, ['suite_ids', 'labels'], payload);
+      if (args.destination_folder_id !== undefined) {
+        payload.destination_folder_id = args.destination_folder_id;
+      }
+      return this.asText(await this.apiClient.create('shares/suites', payload));
+    };
+
+    handlers.tests_unshare = async (args = {}) =>
+      this.asText(await this.apiClient.delete('shares/tests', this.pickRequiredArg(args, 'test_id')));
+
+    handlers.suites_unshare = async (args = {}) =>
+      this.asText(
+        await this.apiClient.delete('shares/suites', this.pickRequiredArg(args, 'suite_id'))
+      );
+  },
+
+  /**
+   * Copy the selection args (e.g. test_ids/labels) into the payload, requiring at least
+   * one of them — the API rejects a share request without a selection.
+   */
+  pickSelectionArgs(args = {}, keys, payload) {
+    const provided = keys.filter((key) => {
+      const value = args[key];
+      if (value === undefined || value === null || value === '') return false;
+      if (Array.isArray(value) && value.length === 0) return false;
+      return true;
+    });
+
+    if (provided.length === 0) {
+      throw new Error(`Provide at least one selection argument: ${keys.join(', ')}.`);
+    }
+
+    for (const key of provided) {
+      payload[key] = args[key];
+    }
+    return provided;
+  },
+};

package/src/mcp/server.js

@@ -14,6 +14,8 @@ export class TestomatioMCPServer {
     tools = TOOL_DEFINITIONS,
     name = 'testomatio-mcp-server',
     registryOptions = {},
+    version,
+    jsonSchemaValidator,
   }) {
     this.config = config;
     this.apiClient = apiClient;
@@ -26,17 +28,19 @@ export class TestomatioMCPServer {
       tools,
       ...registryOptions,
     });
-    this.cleanupStarted = false;
+    this.closePromise = null;
+    this.sessionCleanupPromise = null;
 
     this.server = new Server(
       {
         name,
-        version: getPackageVersion(),
+        version: version || getPackageVersion(),
       },
       {
         capabilities: {
           tools: {},
         },
+        jsonSchemaValidator,
       }
     );
 
@@ -57,36 +61,52 @@ export class TestomatioMCPServer {
     });
   }
 
-  async run() {
-    const transport = new StdioServerTransport();
+  async connect(transport) {
     await this.server.connect(transport);
+  }
+
+  async run() {
+    await this.connect(new StdioServerTransport());
     this.installSessionCleanup();
     this.logger.info('Testomatio MCP server started');
   }
 
-  installSessionCleanup() {
-    const cleanup = async () => {
-      if (this.cleanupStarted) {
-        return;
-      }
+  close() {
+    if (!this.closePromise) {
+      this.closePromise = (async () => {
+        try {
+          await this.server.close();
+        } finally {
+          await this.#stopSession();
+        }
+      })();
+    }
 
-      this.cleanupStarted = true;
-      await this.apiClient?.stopSession?.();
-    };
+    return this.closePromise;
+  }
 
+  installSessionCleanup() {
     this.server.onclose = () => {
-      void cleanup();
+      void this.#stopSession();
     };
 
     process.once('beforeExit', () => {
-      void cleanup();
+      void this.#stopSession();
     });
 
     for (const signal of ['SIGINT', 'SIGTERM']) {
       process.once(signal, async () => {
-        await cleanup();
+        await this.#stopSession();
         process.exit(0);
       });
     }
   }
+
+  #stopSession() {
+    if (!this.sessionCleanupPromise) {
+      this.sessionCleanupPromise = Promise.resolve().then(() => this.apiClient?.stopSession?.());
+    }
+
+    return this.sessionCleanupPromise;
+  }
 }

package/src/mcp/tool-definitions.js

@@ -2,6 +2,7 @@ import { SYSTEM_TOOLS } from './definitions/system.js';
 import { PROJECT_TOOLS } from './definitions/projects.js';
 import { TESTS_TOOLS } from './definitions/tests.js';
 import { SUITES_TOOLS } from './definitions/suites.js';
+import { SHARES_TOOLS } from './definitions/shares.js';
 import { RUNS_TOOLS } from './definitions/runs.js';
 import { TESTRUNS_TOOLS } from './definitions/testruns.js';
 import { RUNGROUPS_TOOLS } from './definitions/rungroups.js';
@@ -22,6 +23,7 @@ export const TOOL_DEFINITIONS = withCountGroupOptions(withListOptions([
   ...PROJECT_TOOLS,
   ...TESTS_TOOLS,
   ...SUITES_TOOLS,
+  ...SHARES_TOOLS,
   ...RUNS_TOOLS,
   ...TESTRUNS_TOOLS,
   ...RUNGROUPS_TOOLS,

package/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 { shareMethods } from './registry/shares.js';
 
 function withPagination(payload) {
   if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
@@ -72,6 +73,7 @@ export class ToolRegistry {
     this.registerScopedIssueHandlers(handlers);
     this.registerScopedAttachmentHandlers(handlers);
     this.registerGlobalHandlers(handlers);
+    this.registerShareHandlers(handlers);
     for (const registerHandlers of this.handlerRegistrars) {
       registerHandlers.call(this, handlers);
     }
@@ -116,5 +118,6 @@ Object.assign(
   attachmentMethods,
   listingMethods,
   issueMethods,
-  payloadMethods
+  payloadMethods,
+  shareMethods
 );