strest-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Christopher Hailfinger (Diamantenschmiede)
+Original work Copyright (c) 2018-2023 Eyke Rehbein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# ⚡ Strest MCP (Strest Orchestrator)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Glama Score](https://glama.ai/mcp/servers/tastenkasperle/strest-mcp/badges/score.svg)](https://glama.ai/mcp/servers/tastenkasperle/strest-mcp)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
+[![Tests](https://img.shields.io/badge/Tests-3%2F3%20Passed-brightgreen.svg)](tests/)
+[![Security Guard](https://img.shields.io/badge/Security-Raptor_Guard_Hardened-orange.svg)](src/core/guard.mjs)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-blue.svg)](package.json)
+
+> **Headless Declarative Multi-Step REST API Test & Chaining Engine for Autonomous AI Agents and DevSecOps.**  
+> *Execute complex, multi-stage API workflows (Auth ➔ Token Extraction ➔ Resource Creation ➔ Assertions) in a single deterministic MCP tool call.*
+
+---
+
+## 💡 The Problem
+
+Autonomous AI agents (Claude Code, Cursor, Antigravity, AutoGen, CrewAI) and CI pipelines frequently need to interact with multi-step REST APIs.  
+When executing chained requests step-by-step with individual `curl` commands:
+
+1. **Context Window Waste & Token Bloat:** Passing whole JSON payloads back and forth across multiple LLM turns wastes hundreds of tokens.
+2. **Fragile State Propagation:** Extracting tokens, session IDs, and foreign keys across separate prompts introduces hallucinations and state loss.
+3. **SSRF & Security Hazards:** AI agents given raw network access can be coerced into probing internal cloud metadata endpoints (`169.254.169.254`).
+
+**Strest MCP solves this:** You pass a declarative multi-step scenario definition to the engine. It executes all steps sequentially with in-memory variable chaining, enforces strict assertions, applies active SSRF defense, and returns a clean, structured execution report in a single round-trip.
+
+---
+
+## ⚡ Key Capabilities
+
+* 🔗 **Declarative Multi-Step Chaining:** Chain outputs from previous steps into downstream headers, query params, or JSON bodies using `<$ steps.<step_name>.body.<property> $>`.
+* 🛡️ **Built-in SSRF & Cloud Metadata Shield:** Proactively blocks attacks against AWS/GCP/Azure instance metadata endpoints (`169.254.169.254`, `metadata.google.internal`), local loopbacks, and dangerous protocols (`file://`, `ftp://`).
+* 🪶 **Zero External Dependencies:** Built entirely with native Node.js 20+ `fetch`, keeping the package footprint lightweight and lightning-fast.
+* 🤖 **Model Context Protocol (MCP) Native:** Integrates seamlessly via stdio JSON-RPC 2.0 with Claude Desktop, Cursor, Antigravity, and any MCP-compliant client.
+* 🎯 **Rich Assertions:** Status code validation, regex header checks, deep JSON body assertions, and timing thresholds.
+
+---
+
+## 🤖 Model Context Protocol (MCP) Setup
+
+### Add to Claude Desktop / Cursor / Antigravity
+
+Add the following to your `claude_desktop_config.json` or MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "strest-mcp": {
+      "command": "npx",
+      "args": ["-y", "strest-mcp"]
+    }
+  }
+}
+```
+
+Or run directly from a local clone:
+
+```json
+{
+  "mcpServers": {
+    "strest-mcp": {
+      "command": "node",
+      "args": ["/path/to/strest_orchestrator/src/mcp/server.mjs"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Description | Input Parameters |
+| :--- | :--- | :--- |
+| `strest_run_scenario` | Executes a declarative multi-step REST API workflow scenario with automatic variable chaining and schema assertions. | `scenario` (object) OR `scenarioPath` (string) |
+| `strest_template` | Generates a ready-to-use template for multi-step authentication and CRUD chaining. | `baseUrl` (optional string, e.g. `http://localhost:5000`) |
+
+---
+
+## 💻 CLI Usage
+
+You can also run Strest Orchestrator as a standalone CLI tool:
+
+```bash
+# Display help and usage
+npx strest help
+
+# Run an API workflow scenario from a JSON file
+npx strest run scenarios/auth_and_crud.json
+
+# Generate a starter template
+npx strest template > scenario.json
+```
+
+---
+
+## 📋 Scenario Example (Chaining in Action)
+
+```json
+{
+  "name": "Auth and User Project Creation",
+  "steps": [
+    {
+      "name": "login",
+      "url": "https://api.example.com/v1/auth/login",
+      "method": "POST",
+      "headers": { "Content-Type": "application/json" },
+      "body": { "username": "admin", "password": "SuperSecretPassword" },
+      "assert": {
+        "status": 200,
+        "body": { "token": "defined" }
+      }
+    },
+    {
+      "name": "create_project",
+      "url": "https://api.example.com/v1/projects",
+      "method": "POST",
+      "headers": {
+        "Content-Type": "application/json",
+        "Authorization": "Bearer <$ steps.login.body.token $>"
+      },
+      "body": {
+        "title": "Autonomous Agent Workspace",
+        "requestId": "<$ faker.uuid $>"
+      },
+      "assert": {
+        "status": 201,
+        "body": { "id": "defined" }
+      }
+    }
+  ]
+}
+```
+
+---
+
+## 🛡️ Security & Hardening (Raptor Guard v2.0)
+
+* **SSRF Prevention:** Blocks requests to IPv4/IPv6 link-local addresses, link-local multicast, and known cloud metadata IP ranges (`169.254.169.254`, `100.100.100.200`).
+* **Path Traversal Shield:** Resolves and validates scenario file paths against path traversal sequences (`../`, null bytes, system files).
+* **Hermetic Execution:** 100% offline self-testing suite with embedded ephemeral mock servers.
+
+---
+
+## 📜 Origin & Credits
+
+* Based on the concept of [`eykrehbein/strest`](https://github.com/eykrehbein/strest) (1.7k+ ⭐, MIT).
+* Modernized, decoupled, SSRF-hardened, and transformed into an autonomous Model Context Protocol server by Christopher Hailfinger ([@tastenkasperle](https://github.com/tastenkasperle)) as part of the **Diamantenschmiede** initiative.
+
+---
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "strest-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Declarative Multi-Step REST API Test & Chaining Engine for AI Agents and DevSecOps",
+  "main": "src/index.mjs",
+  "bin": {
+    "strest": "src/cli/index.mjs",
+    "strest-mcp": "src/mcp/server.mjs"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "node tests/run_all.mjs",
+    "start": "node src/mcp/server.mjs",
+    "run": "node src/cli/index.mjs run"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "strest",
+    "api-testing",
+    "rest-client",
+    "chaining",
+    "ai-agents",
+    "devsecops",
+    "ssrf-protection",
+    "automation"
+  ],
+  "author": "Christopher Hailfinger (Diamantenschmiede)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tastenkasperle/strest-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tastenkasperle/strest-mcp/issues"
+  },
+  "homepage": "https://github.com/tastenkasperle/strest-mcp#readme"
+}

package/server.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "strest-mcp",
+  "version": "1.0.0",
+  "description": "Declarative Multi-Step REST API Test & Chaining Engine for AI Agents and DevSecOps",
+  "author": {
+    "name": "Diamantenschmiede",
+    "url": "https://github.com/tastenkasperle"
+  },
+  "homepage": "https://github.com/tastenkasperle/strest-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tastenkasperle/strest-mcp.git"
+  },
+  "capabilities": {
+    "tools": true
+  },
+  "transport": {
+    "type": "stdio",
+    "command": "node",
+    "args": [
+      "src/mcp/server.mjs"
+    ]
+  }
+}

package/smithery.yaml

@@ -0,0 +1,6 @@
+startCommand:
+  type: stdio
+  config:
+    command: node
+    args:
+      - src/mcp/server.mjs

package/src/cli/index.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * Strest Standalone CLI Interface
+ * Part of Diamantenschmiede (AYA Protocol)
+ */
+
+import fs from 'fs';
+import { executeScenario } from '../core/executor.mjs';
+import { SecurityGuard } from '../core/guard.mjs';
+
+function printHelp() {
+  console.log(`
+⚡ Strest Orchestrator CLI – Headless Multi-Step REST Engine
+
+VERWENDUNG:
+  strest <command> [options]
+
+BEFEHLE:
+  run <scenario.json>      Führt ein mehrstufiges API-Szenario aus
+                           Optionen: --bail (Stop bei erstem Fehler, Standard: true)
+
+  template                 Gibt ein Beispiel-Szenario auf stdout aus
+
+  help                     Zeigt diese Hilfe an
+`);
+}
+
+async function handleRun(args) {
+  const filePath = args[0];
+  if (!filePath) {
+    console.error('❌ Fehler: Bitte Pfad zur scenario.json angeben.');
+    process.exit(1);
+  }
+
+  const safePath = SecurityGuard.validateSafePath(filePath);
+  if (!fs.existsSync(safePath)) {
+    console.error(`❌ Fehler: Datei nicht gefunden: ${safePath}`);
+    process.exit(1);
+  }
+
+  const raw = fs.readFileSync(safePath, 'utf-8');
+  const scenario = JSON.parse(raw);
+
+  console.log(`🚀 Führe Szenario aus: '${scenario.name || safePath}'...`);
+  const result = await executeScenario(scenario);
+
+  console.log('\n--- ERGEBNIS ---');
+  console.log(`Status:        ${result.success ? '✅ ERFOLGREICH' : '❌ FEHLGESCHLAGEN'}`);
+  console.log(`Schritte:      ${result.executedSteps} / ${result.totalSteps}`);
+  console.log(`Dauer:         ${result.durationMs}ms\n`);
+
+  for (const step of result.steps) {
+    const symbol = step.success ? '✔' : '✖';
+    console.log(`${symbol} [${step.request.method}] ${step.stepName} (${step.response?.status || 'ERR'} in ${step.response?.durationMs || 0}ms)`);
+    if (!step.success && step.errors) {
+      for (const err of step.errors) {
+        console.log(`   └─ 🚨 ${err}`);
+      }
+    }
+  }
+
+  if (!result.success) {
+    process.exit(1);
+  }
+}
+
+function handleTemplate() {
+  const template = {
+    name: "Sample Multi-Step Flow",
+    steps: [
+      {
+        name: "login",
+        url: "http://localhost:3000/api/login",
+        method: "POST",
+        body: { username: "admin", password: "password" },
+        assert: { status: 200, body: { token: "defined" } }
+      },
+      {
+        name: "get_user",
+        url: "http://localhost:3000/api/users/me",
+        method: "GET",
+        headers: { authorization: "Bearer <$ steps.login.body.token $>" },
+        assert: { status: 200 }
+      }
+    ]
+  };
+  console.log(JSON.stringify(template, null, 2));
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+  const args = argv.slice(1);
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  switch (command) {
+    case 'run':
+      await handleRun(args);
+      break;
+    case 'template':
+      handleTemplate();
+      break;
+    default:
+      console.error(`❌ Unbekannter Befehl: ${command}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('❌ Fehler:', err.message);
+  process.exit(1);
+});

package/src/core/assert.mjs

@@ -0,0 +1,71 @@
+/**
+ * Strest Assertion Validator
+ * Part of Diamantenschmiede (AYA Protocol)
+ */
+
+import { getByPath } from './interpolator.mjs';
+
+/**
+ * Validates step response against assertions
+ * @param {Object} response { status: number, headers: {}, body: any }
+ * @param {Object} assertions
+ * @returns {{ passed: boolean, errors: string[] }}
+ */
+export function validateAssertions(response, assertions = {}) {
+  const errors = [];
+
+  // 1. Status Code Check
+  if (assertions.status !== undefined) {
+    if (response.status !== assertions.status) {
+      errors.push(`Expected HTTP status ${assertions.status} but got ${response.status}`);
+    }
+  }
+
+  // 2. Status Range Check (e.g. statusRange: [200, 299])
+  if (Array.isArray(assertions.statusRange) && assertions.statusRange.length === 2) {
+    const [min, max] = assertions.statusRange;
+    if (response.status < min || response.status > max) {
+      errors.push(`Status ${response.status} outside expected range [${min}, ${max}]`);
+    }
+  }
+
+  // 3. Header Checks
+  if (assertions.headers && typeof assertions.headers === 'object') {
+    for (const [key, expectedVal] of Object.entries(assertions.headers)) {
+      const actualVal = response.headers[key.toLowerCase()];
+      if (actualVal === undefined) {
+        errors.push(`Expected header '${key}' is missing`);
+      } else if (expectedVal !== '*' && !String(actualVal).includes(String(expectedVal))) {
+        errors.push(`Header '${key}' value '${actualVal}' does not match '${expectedVal}'`);
+      }
+    }
+  }
+
+  // 4. Body Property Assertions (e.g. body: { "token": "string", "user.id": 42 })
+  if (assertions.body && typeof assertions.body === 'object') {
+    for (const [propPath, expectedVal] of Object.entries(assertions.body)) {
+      const actualVal = getByPath(response.body, propPath);
+
+      if (expectedVal === 'defined') {
+        if (actualVal === undefined || actualVal === null) {
+          errors.push(`Body property '${propPath}' must be defined`);
+        }
+      } else if (expectedVal === 'string') {
+        if (typeof actualVal !== 'string') {
+          errors.push(`Body property '${propPath}' must be a string, got ${typeof actualVal}`);
+        }
+      } else if (expectedVal === 'number') {
+        if (typeof actualVal !== 'number') {
+          errors.push(`Body property '${propPath}' must be a number, got ${typeof actualVal}`);
+        }
+      } else if (actualVal !== expectedVal) {
+        errors.push(`Body property '${propPath}' expected '${expectedVal}' but got '${actualVal}'`);
+      }
+    }
+  }
+
+  return {
+    passed: errors.length === 0,
+    errors
+  };
+}

package/src/core/executor.mjs

@@ -0,0 +1,171 @@
+/**
+ * Strest Headless Execution Engine
+ * Part of Diamantenschmiede (AYA Protocol)
+ */
+
+import { interpolateDeep } from './interpolator.mjs';
+import { validateAssertions } from './assert.mjs';
+import { SecurityGuard } from './guard.mjs';
+
+const MAX_REDIRECTS = 5;
+
+/**
+ * Executes a single HTTP step with SSRF-safe redirect handling and timeout protection
+ * @param {Object} stepDefinition 
+ * @param {Object} context { steps: {}, env: {} }
+ * @param {Object} options 
+ * @returns {Promise<Object>} stepResult
+ */
+export async function executeStep(stepDefinition, context = {}, options = {}) {
+  // 1. Interpolate request definition with accumulated context
+  const step = interpolateDeep(stepDefinition, context);
+
+  const url = step.url;
+  const method = (step.method || 'GET').toUpperCase();
+  const headers = step.headers || {};
+  const body = step.body;
+  const allowLocalhost = options.allowLocalhost ?? true;
+  const timeoutMs = options.timeoutMs || step.timeoutMs || 15000;
+
+  // Validate initial URL with SSRF Guard
+  SecurityGuard.validateUrl(url, { allowLocalhost });
+
+  const fetchOptions = {
+    method,
+    headers: { ...headers },
+    redirect: 'manual',
+    signal: AbortSignal.timeout(timeoutMs)
+  };
+
+  if (body !== undefined && method !== 'GET' && method !== 'HEAD') {
+    if (typeof body === 'object') {
+      fetchOptions.body = JSON.stringify(body);
+      const hasContentType = Object.keys(fetchOptions.headers).some(
+        k => k.toLowerCase() === 'content-type'
+      );
+      if (!hasContentType) {
+        fetchOptions.headers['content-type'] = 'application/json';
+      }
+    } else {
+      fetchOptions.body = String(body);
+    }
+  }
+
+  const startTime = Date.now();
+  let response;
+  let parsedBody;
+
+  try {
+    let currentUrl = url;
+    let currentOptions = { ...fetchOptions };
+
+    for (let redirectCount = 0; redirectCount <= MAX_REDIRECTS; redirectCount++) {
+      response = await fetch(currentUrl, currentOptions);
+
+      if ([301, 302, 303, 307, 308].includes(response.status)) {
+        const location = response.headers.get('location');
+        if (!location) break;
+        if (redirectCount === MAX_REDIRECTS) {
+          throw new Error(`Maximum redirect limit (${MAX_REDIRECTS}) exceeded`);
+        }
+        const resolvedRedirect = new URL(location, currentUrl).toString();
+        // Validate every redirect hop against SSRF Guard
+        SecurityGuard.validateUrl(resolvedRedirect, { allowLocalhost });
+        currentUrl = resolvedRedirect;
+        if (response.status === 303 || ((response.status === 301 || response.status === 302) && currentOptions.method === 'POST')) {
+          currentOptions = { ...currentOptions, method: 'GET', body: undefined };
+        }
+        continue;
+      }
+      break;
+    }
+
+    const durationMs = Date.now() - startTime;
+
+    const responseHeaders = {};
+    for (const [k, v] of response.headers.entries()) {
+      responseHeaders[k.toLowerCase()] = v;
+    }
+
+    const contentType = responseHeaders['content-type'] || '';
+    if (contentType.includes('application/json')) {
+      parsedBody = await response.json();
+    } else {
+      parsedBody = await response.text();
+    }
+
+    const responseObj = {
+      status: response.status,
+      statusText: response.statusText,
+      headers: responseHeaders,
+      body: parsedBody,
+      durationMs
+    };
+
+    // 2. Validate Assertions
+    const assertionResult = validateAssertions(responseObj, step.assert || {});
+
+    return {
+      stepName: step.name || step.id || 'anonymous_step',
+      success: assertionResult.passed,
+      errors: assertionResult.errors,
+      request: { method, url, headers: fetchOptions.headers, body },
+      response: responseObj
+    };
+  } catch (err) {
+    return {
+      stepName: step.name || step.id || 'anonymous_step',
+      success: false,
+      errors: [err.message],
+      request: { method, url, headers: fetchOptions.headers, body },
+      response: null
+    };
+  }
+}
+
+/**
+ * Executes a multi-step scenario
+ * @param {Object} scenario { name: string, steps: Array<Object>, env: {} }
+ * @param {Object} options 
+ * @returns {Promise<Object>} scenarioResult
+ */
+export async function executeScenario(scenario, options = {}) {
+  const steps = scenario.steps || [];
+  const context = {
+    steps: {},
+    env: { ...(scenario.env || {}), ...(options.env || {}) },
+    allowProcessEnv: options.allowProcessEnv === true
+  };
+
+  const results = [];
+  let scenarioSuccess = true;
+  const startTime = Date.now();
+
+  for (const stepDef of steps) {
+    const stepResult = await executeStep(stepDef, context, options);
+    results.push(stepResult);
+
+    // Save step response into context for downstream steps
+    const stepKey = stepDef.name || stepDef.id;
+    if (stepKey) {
+      context.steps[stepKey] = stepResult.response;
+    }
+
+    if (!stepResult.success) {
+      scenarioSuccess = false;
+      if (options.bail !== false) {
+        // Stop execution on first failed step (bail mode)
+        break;
+      }
+    }
+  }
+
+  return {
+    scenarioName: scenario.name || 'Unnamed Scenario',
+    success: scenarioSuccess,
+    totalSteps: steps.length,
+    executedSteps: results.length,
+    durationMs: Date.now() - startTime,
+    steps: results
+  };
+}

package/src/core/guard.mjs

@@ -0,0 +1,108 @@
+/**
+ * Strest SecurityGuard v2.0
+ * SSRF & Malicious Input Defense (AYA Protocol / Fire Team Elite Certified)
+ */
+
+import path from 'path';
+
+// Dangerous SSRF / Cloud Metadata Hosts
+const METADATA_HOSTS = new Set([
+  '169.254.169.254',          // AWS / Azure / OpenStack IMDSv1/v2
+  'metadata.google.internal', // GCP Metadata
+  'metadata',
+  '100.100.100.200',          // Alibaba Cloud Metadata
+  'instance-data',
+  '[fd00:ec2::254]',          // AWS IPv6 IMDS
+  'fd00:ec2::254'
+]);
+
+export class SecurityGuard {
+  /**
+   * Validates target URL against SSRF and Cloud Metadata Exfiltration
+   * @param {string} rawUrl 
+   * @param {Object} options 
+   * @param {boolean} [options.allowLocalhost=true] Allow testing local dev servers (e.g. localhost:5000, 127.0.0.1)
+   * @returns {URL} Validated URL object
+   */
+  static validateUrl(rawUrl, options = { allowLocalhost: true }) {
+    if (!rawUrl || typeof rawUrl !== 'string') {
+      throw new Error('Security Violation: Invalid URL provided');
+    }
+
+    let parsed;
+    try {
+      parsed = new URL(rawUrl);
+    } catch (e) {
+      throw new Error(`Security Violation: Malformed URL: ${rawUrl}`);
+    }
+
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error(`Security Violation: Prohibited protocol '${parsed.protocol}'. Only http/https allowed.`);
+    }
+
+    const hostname = parsed.hostname.toLowerCase();
+
+    // Check Cloud Metadata Endpoints & Link-Local Ranges (Strict block, cannot be bypassed)
+    if (
+      METADATA_HOSTS.has(hostname) ||
+      hostname.startsWith('169.254.') ||
+      hostname.includes('ffff:169.254.') ||
+      hostname.includes('ffff:a9fe:a9fe')
+    ) {
+      throw new Error(`Security Violation: Access to cloud instance metadata service (${hostname}) is blocked.`);
+    }
+
+    if (!options.allowLocalhost) {
+      if (
+        hostname === 'localhost' ||
+        hostname === '127.0.0.1' ||
+        hostname === '::1' ||
+        hostname === '[::1]' ||
+        hostname === '0.0.0.0' ||
+        hostname.startsWith('127.')
+      ) {
+        throw new Error('Security Violation: Localhost access restricted in this environment.');
+      }
+    }
+
+    return parsed;
+  }
+
+  /**
+   * Validates safe file path against path traversal and sensitive credential exposure
+   * @param {string} targetPath 
+   * @param {string} allowedBaseDir 
+   * @returns {string}
+   */
+  static validateSafePath(targetPath, allowedBaseDir = process.cwd()) {
+    if (!targetPath || typeof targetPath !== 'string') {
+      throw new Error('Security Violation: Invalid path argument');
+    }
+
+    if (targetPath.includes('\0')) {
+      throw new Error('Security Violation: Null byte detected in path');
+    }
+
+    const base = path.resolve(allowedBaseDir);
+    const resolved = path.resolve(base, targetPath);
+    const basename = path.basename(resolved);
+
+    // Block sensitive secrets first
+    if (
+      /^\.env(\..+)?$/i.test(basename) ||
+      /^id_(rsa|ed25519|ecdsa)/i.test(basename) ||
+      /masterpw/i.test(basename) ||
+      /credentials/i.test(basename)
+    ) {
+      throw new Error(`Security Violation: Protected credential file blocked: ${basename}`);
+    }
+
+    // Strict containment check inside allowedBaseDir
+    const rel = path.relative(base, resolved);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`Security Violation: Path traversal outside allowed workspace blocked: ${targetPath}`);
+    }
+
+    return resolved;
+  }
+}

package/src/core/interpolator.mjs

@@ -0,0 +1,118 @@
+/**
+ * Strest Data Interpolator & Chaining Engine
+ * Part of Diamantenschmiede (AYA Protocol)
+ */
+
+import crypto from 'crypto';
+
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Resolves dot-notated path in an object (e.g. "steps.login.body.token")
+ * @param {Object} obj 
+ * @param {string} path 
+ * @returns {any}
+ */
+export function getByPath(obj, path) {
+  if (!obj || !path || typeof path !== 'string') return undefined;
+  const parts = path.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) return undefined;
+    if (FORBIDDEN_KEYS.has(part)) return undefined;
+    if (typeof current !== 'object' || !Object.prototype.hasOwnProperty.call(current, part)) {
+      return undefined;
+    }
+    current = current[part];
+  }
+  return current;
+}
+
+/**
+ * Generates synthetic helper data
+ */
+export const SYNTHETIC_HELPERS = {
+  uuid: () => crypto.randomUUID(),
+  timestamp: () => Date.now(),
+  isoDate: () => new Date().toISOString(),
+  randomInt: (min = 1, max = 1000) => Math.floor(Math.random() * (max - min + 1)) + min
+};
+
+/**
+ * Interpolates string with `<$ expression $>` patterns
+ * @param {string} template 
+ * @param {Object} context { steps: {}, env: {} }
+ * @returns {any}
+ */
+export function interpolateString(template, context = {}) {
+  if (typeof template !== 'string') return template;
+
+  // Single exact match replacement (preserving numbers/objects/booleans)
+  const singleMatch = template.match(/^<\$\s*([a-zA-Z0-9_.]+)\s*\$>$/);
+  if (singleMatch) {
+    const expr = singleMatch[1];
+    return resolveExpression(expr, context);
+  }
+
+  // Multi-match substring replacement
+  return template.replace(/<\$\s*([a-zA-Z0-9_.]+)\s*\$>/g, (_, expr) => {
+    const val = resolveExpression(expr, context);
+    return val !== undefined ? String(val) : '';
+  });
+}
+
+/**
+ * Resolves expression against context or helpers
+ * @param {string} expr 
+ * @param {Object} context 
+ * @returns {any}
+ */
+function resolveExpression(expr, context) {
+  if (expr.startsWith('faker.') || expr.startsWith('helper.')) {
+    const helperName = expr.split('.')[1];
+    if (Object.prototype.hasOwnProperty.call(SYNTHETIC_HELPERS, helperName)) {
+      return SYNTHETIC_HELPERS[helperName]();
+    }
+  }
+
+  if (expr.startsWith('env.')) {
+    const envKey = expr.slice(4);
+    if (FORBIDDEN_KEYS.has(envKey)) return undefined;
+    if (context?.env && Object.prototype.hasOwnProperty.call(context.env, envKey)) {
+      return context.env[envKey];
+    }
+    if (context?.allowProcessEnv === true) {
+      return process.env[envKey];
+    }
+    return undefined;
+  }
+
+  return getByPath(context, expr);
+}
+
+/**
+ * Recursively interpolates objects, arrays, and strings
+ * @param {any} target 
+ * @param {Object} context 
+ * @returns {any}
+ */
+export function interpolateDeep(target, context = {}) {
+  if (typeof target === 'string') {
+    return interpolateString(target, context);
+  }
+
+  if (Array.isArray(target)) {
+    return target.map(item => interpolateDeep(item, context));
+  }
+
+  if (target !== null && typeof target === 'object') {
+    const result = {};
+    for (const [key, value] of Object.entries(target)) {
+      if (FORBIDDEN_KEYS.has(key)) continue;
+      result[key] = interpolateDeep(value, context);
+    }
+    return result;
+  }
+
+  return target;
+}

package/src/index.mjs

@@ -0,0 +1,19 @@
+/**
+ * Strest Orchestrator - Main Package Entry Point
+ * Part of Diamantenschmiede (AYA Protocol)
+ */
+
+export { executeScenario, executeStep } from './core/executor.mjs';
+export {
+  interpolateDeep,
+  interpolateDeep as interpolate,
+  interpolateString,
+  getByPath,
+  SYNTHETIC_HELPERS
+} from './core/interpolator.mjs';
+export {
+  validateAssertions,
+  validateAssertions as assertResponse
+} from './core/assert.mjs';
+export { SecurityGuard } from './core/guard.mjs';
+export { handleRequest } from './mcp/server.mjs';

package/src/mcp/server.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * Strest MCP Server (Model Context Protocol)
+ * Native Stdio JSON-RPC 2.0 Server for Local AI Agents
+ * Part of Diamantenschmiede (AYA Protocol / Gang 3)
+ */
+
+import readline from 'readline';
+import fs from 'fs';
+import { executeScenario } from '../core/executor.mjs';
+import { SecurityGuard } from '../core/guard.mjs';
+
+const SERVER_NAME = 'strest-mcp';
+const SERVER_VERSION = '1.0.0';
+
+const TOOLS = [
+  {
+    name: 'strest_run_scenario',
+    description: 'Executes a declarative multi-step REST API workflow scenario with automatic variable chaining and schema assertions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scenario: {
+          type: 'object',
+          description: 'The scenario definition object containing steps and assertions'
+        },
+        scenarioPath: {
+          type: 'string',
+          description: 'Path to a scenario JSON file on disk'
+        }
+      }
+    }
+  },
+  {
+    name: 'strest_template',
+    description: 'Generates a ready-to-use template for multi-step authentication and CRUD chaining.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        baseUrl: { type: 'string', description: 'Base URL for the scenario (e.g. http://localhost:5000)' }
+      }
+    }
+  }
+];
+
+export async function handleRequest(request) {
+  const { id, method, params } = request;
+
+  if (
+    method === 'notifications/initialized' ||
+    method === 'initialized' ||
+    (typeof method === 'string' && method.startsWith('notifications/')) ||
+    id === undefined
+  ) {
+    return null;
+  }
+
+  if (method === 'initialize') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION }
+      }
+    };
+  }
+
+  if (method === 'ping') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {}
+    };
+  }
+
+  if (method === 'tools/list') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: { tools: TOOLS }
+    };
+  }
+
+  if (method === 'tools/call') {
+    const { name, arguments: args = {} } = params;
+
+    try {
+      if (name === 'strest_run_scenario') {
+        let scenarioObj;
+        if (args.scenario) {
+          scenarioObj = args.scenario;
+        } else if (args.scenarioPath) {
+          const safePath = SecurityGuard.validateSafePath(args.scenarioPath);
+          scenarioObj = JSON.parse(fs.readFileSync(safePath, 'utf-8'));
+        } else {
+          throw new Error('Either scenario object or scenarioPath must be provided');
+        }
+
+        const result = await executeScenario(scenarioObj);
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(result, null, 2)
+            }]
+          }
+        };
+      }
+
+      if (name === 'strest_template') {
+        const base = args.baseUrl || 'http://127.0.0.1:5000';
+        const template = {
+          name: "Generated Multi-Step Scenario",
+          steps: [
+            {
+              name: "auth_step",
+              url: `${base}/api/auth/login`,
+              method: "POST",
+              body: { username: "admin", password: "password123" },
+              assert: { status: 200, body: { token: "defined" } }
+            },
+            {
+              name: "query_step",
+              url: `${base}/api/data`,
+              method: "GET",
+              headers: { authorization: "Bearer <$ steps.auth_step.body.token $>" },
+              assert: { status: 200 }
+            }
+          ]
+        };
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: {
+            content: [{
+              type: 'text',
+              text: JSON.stringify(template, null, 2)
+            }]
+          }
+        };
+      }
+
+      throw new Error(`Unknown tool: ${name}`);
+    } catch (err) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32000, message: err.message }
+      };
+    }
+  }
+
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: { code: -32601, message: `Method not found: ${method}` }
+  };
+}
+
+if (process.argv[1] && process.argv[1].endsWith('server.mjs')) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+
+  rl.on('line', async (line) => {
+    if (!line.trim()) return;
+    try {
+      const request = JSON.parse(line);
+      const response = await handleRequest(request);
+      if (response !== null && response !== undefined) {
+        process.stdout.write(JSON.stringify(response) + '\n');
+      }
+    } catch (err) {
+      process.stdout.write(JSON.stringify({
+        jsonrpc: '2.0',
+        id: null,
+        error: { code: -32700, message: 'Parse error: ' + err.message }
+      }) + '\n');
+    }
+  });
+}