@testomatio/mcp 2.2.1 → 3.0.0-beta.1

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.1",
   "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/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;
+  }
 }