@emseepea/create-soap-backed-server 0.0.0

package/README.md

@@ -0,0 +1,96 @@
+# `@emseepea/create-soap-backed-server`
+
+This directory is both the maintained example and the template source for its
+public npm initializer.
+
+## Use This Template
+
+Use this template when an MCP tool must call an existing SOAP service whose
+WSDL and XSD remain authoritative. It shows local contract loading, generated
+TypeScript, raw XML validation before parsing, and a small public MCP schema.
+
+Choose the [API-backed server](../api-backed-server/README.md) for JSON over
+HTTP, or the [tool server](../tool-server/README.md) when no backend service is
+needed. [Compare all templates](https://emseepea.github.io/emseepea/examples/).
+
+## Create a Project
+
+```sh
+npm init @emseepea/soap-backed-server -- my-server
+```
+
+The command creates a standalone app in a new `my-server` directory and sets
+`private: true` in its `package.json` so the app cannot be published by
+accident. It includes local service contracts, checked-in generated types,
+lint checks, ordinary tests, and a semantic test.
+
+<!-- generated-project-readme -->
+
+## SOAP-Backed Server
+
+The committed WSDL defines the operation and imports the committed service XSD.
+That XSD generates `src/generated/pea-service.ts`. The same XSD is imported by
+the SOAP-envelope schema used to validate every raw response before the `soap`
+library parses it.
+
+Normal builds and starts use checked-in generated types and local contracts.
+They never fetch a WSDL or XSD. Compatible backend values pass through without
+translation tables.
+
+## Configure the Service
+
+Set the one fixed SOAP endpoint, then build and start:
+
+```sh
+npm install
+npm run build
+PEA_SOAP_URL=https://soap.example.test/pea npm start
+```
+
+Keep service credentials outside the URL and source code. Add authentication
+headers inside the server for your provider. Never accept an endpoint, schema
+location, SOAP action, or arbitrary XML from an MCP caller.
+
+## Change the Contract
+
+Edit the local files under `contracts/`, then regenerate and review the diff:
+
+```sh
+npm run generate
+npm run generate:check
+```
+
+The generator maps the XSD's required fields, optional fields, arrays, numeric
+types, and named types into TypeScript. The runtime XSD validator enforces the
+actual restrictions.
+
+## Safety Boundary
+
+The transport accepts responses only from `PEA_SOAP_URL`. It does not follow
+redirects. It rejects requests or responses over 64 KiB, DTDs, entity
+declarations, malformed XML, XSD-invalid XML, SOAP faults, and responses taking
+longer than 1.5 seconds. Schema imports are restricted to the committed local
+service XSD. Public failures contain no provider details.
+
+## Tool
+
+`get-pea-variety` retrieves one variety and returns described JSON. The MCP
+caller never sees SOAP XML or chooses transport details.
+
+## Check This Project
+
+Run generation, lint, build, and ordinary tests without spending model tokens:
+
+```sh
+npm run generate:check
+npm run lint
+npm test
+```
+
+Run the more expensive AI test separately:
+
+```sh
+npm run test:llm
+```
+
+If Claude is not already signed in, run `claude auth login` first.

package/initializer-dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Windy Road Technology Pty. Limited
+
+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/initializer-dist/create.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+const [destination, ...extra] = process.argv.slice(2);
+if (extra.length > 0 || !destination || !/^[a-z0-9][a-z0-9._-]*$/.test(destination)) {
+  throw new Error("Provide one simple lowercase destination name, such as my-server");
+}
+
+const target = resolve(destination);
+if (basename(target) !== destination) throw new Error("The destination must not contain a path");
+const staging = await mkdtemp(join(dirname(target), ".emseepea-create-"));
+
+try {
+  await copyContents(new URL("./template/", import.meta.url), staging);
+  const manifestPath = resolve(staging, "package.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  await writeFile(manifestPath, `${JSON.stringify({ ...manifest, name: destination }, null, 2)}\n`);
+  await mkdir(target);
+  try {
+    await copyContents(staging, target);
+  } catch (error) {
+    await rm(target, { recursive: true, force: true });
+    throw error;
+  }
+} catch (error) {
+  if (["EEXIST", "ENOTEMPTY"].includes(error.code)) {
+    throw new Error(`The destination already exists: ${destination}`);
+  }
+  throw error;
+} finally {
+  await rm(staging, { recursive: true, force: true });
+}
+
+async function copyContents(source, destination) {
+  for (const entry of await readdir(source)) {
+    const from = source instanceof URL ? new URL(entry, source) : join(source, entry);
+    await cp(from, join(destination, entry), { recursive: true, errorOnExist: true, force: false });
+  }
+}
+
+console.log(`Created ${destination}.`);
+console.log(`Next: cd ${destination}; npm install; npm test; npm start`);

package/initializer-dist/template/README.md

@@ -0,0 +1,68 @@
+# SOAP-Backed Server
+
+The committed WSDL defines the operation and imports the committed service XSD.
+That XSD generates `src/generated/pea-service.ts`. The same XSD is imported by
+the SOAP-envelope schema used to validate every raw response before the `soap`
+library parses it.
+
+Normal builds and starts use checked-in generated types and local contracts.
+They never fetch a WSDL or XSD. Compatible backend values pass through without
+translation tables.
+
+## Configure the Service
+
+Set the one fixed SOAP endpoint, then build and start:
+
+```sh
+npm install
+npm run build
+PEA_SOAP_URL=https://soap.example.test/pea npm start
+```
+
+Keep service credentials outside the URL and source code. Add authentication
+headers inside the server for your provider. Never accept an endpoint, schema
+location, SOAP action, or arbitrary XML from an MCP caller.
+
+## Change the Contract
+
+Edit the local files under `contracts/`, then regenerate and review the diff:
+
+```sh
+npm run generate
+npm run generate:check
+```
+
+The generator maps the XSD's required fields, optional fields, arrays, numeric
+types, and named types into TypeScript. The runtime XSD validator enforces the
+actual restrictions.
+
+## Safety Boundary
+
+The transport accepts responses only from `PEA_SOAP_URL`. It does not follow
+redirects. It rejects requests or responses over 64 KiB, DTDs, entity
+declarations, malformed XML, XSD-invalid XML, SOAP faults, and responses taking
+longer than 1.5 seconds. Schema imports are restricted to the committed local
+service XSD. Public failures contain no provider details.
+
+## Tool
+
+`get-pea-variety` retrieves one variety and returns described JSON. The MCP
+caller never sees SOAP XML or chooses transport details.
+
+## Check This Project
+
+Run generation, lint, build, and ordinary tests without spending model tokens:
+
+```sh
+npm run generate:check
+npm run lint
+npm test
+```
+
+Run the more expensive AI test separately:
+
+```sh
+npm run test:llm
+```
+
+If Claude is not already signed in, run `claude auth login` first.

package/initializer-dist/template/contracts/pea-service.wsdl

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="http://schemas.xmlsoap.org/wsdl/"
+  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
+  xmlns:xs="http://www.w3.org/2001/XMLSchema"
+  xmlns:pea="urn:emseepea:pea-service"
+  targetNamespace="urn:emseepea:pea-service">
+  <types>
+    <xs:schema>
+      <xs:import namespace="urn:emseepea:pea-service" schemaLocation="pea-service.xsd"/>
+    </xs:schema>
+  </types>
+  <message name="GetPeaInput"><part name="parameters" element="pea:GetPeaRequest"/></message>
+  <message name="GetPeaOutput"><part name="parameters" element="pea:GetPeaResponse"/></message>
+  <portType name="PeaServicePortType">
+    <operation name="GetPea"><input message="pea:GetPeaInput"/><output message="pea:GetPeaOutput"/></operation>
+  </portType>
+  <binding name="PeaServiceBinding" type="pea:PeaServicePortType">
+    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
+    <operation name="GetPea">
+      <soap:operation soapAction="GetPea"/>
+      <input><soap:body use="literal"/></input>
+      <output><soap:body use="literal"/></output>
+    </operation>
+  </binding>
+  <service name="PeaService">
+    <port name="PeaServicePort" binding="pea:PeaServiceBinding">
+      <soap:address location="http://127.0.0.1:3999/soap"/>
+    </port>
+  </service>
+</definitions>

package/initializer-dist/template/contracts/pea-service.xsd

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+  xmlns:pea="urn:emseepea:pea-service"
+  targetNamespace="urn:emseepea:pea-service"
+  elementFormDefault="qualified">
+  <xs:simpleType name="PeaType">
+    <xs:restriction base="xs:string">
+      <xs:minLength value="1"/>
+      <xs:maxLength value="40"/>
+    </xs:restriction>
+  </xs:simpleType>
+  <xs:complexType name="PeaVariety">
+    <xs:sequence>
+      <xs:element name="name" type="xs:string"/>
+      <xs:element name="peaType" type="pea:PeaType"/>
+      <xs:element name="daysToMaturity" type="xs:positiveInteger"/>
+      <xs:element name="note" type="xs:string" minOccurs="0"/>
+      <xs:element name="trait" type="xs:string" minOccurs="0" maxOccurs="5"/>
+    </xs:sequence>
+  </xs:complexType>
+  <xs:element name="GetPeaRequest">
+    <xs:complexType>
+      <xs:sequence>
+        <xs:element name="name" type="xs:string"/>
+      </xs:sequence>
+    </xs:complexType>
+  </xs:element>
+  <xs:element name="GetPeaResponse" type="pea:PeaVariety"/>
+</xs:schema>

package/initializer-dist/template/contracts/soap-envelope.xsd

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
+  xmlns:pea="urn:emseepea:pea-service"
+  targetNamespace="http://schemas.xmlsoap.org/soap/envelope/"
+  elementFormDefault="qualified">
+  <xs:import namespace="urn:emseepea:pea-service" schemaLocation="pea-service.xsd"/>
+  <xs:complexType name="SoapBody">
+    <xs:choice>
+      <xs:element ref="pea:GetPeaResponse"/>
+      <xs:element name="Fault" type="xs:anyType"/>
+    </xs:choice>
+  </xs:complexType>
+  <xs:complexType name="SoapEnvelope">
+    <xs:sequence>
+      <xs:element name="Body" type="soap:SoapBody"/>
+    </xs:sequence>
+  </xs:complexType>
+  <xs:element name="Envelope" type="soap:SoapEnvelope"/>
+</xs:schema>

package/initializer-dist/template/eval/meaning.test.mjs

@@ -0,0 +1,25 @@
+import test from "node:test";
+import {
+  assertResponseMeaning,
+  assertToolCalls,
+  createConversation,
+} from "@emseepea/testing/semantic";
+import { startSoapFixture } from "../test-support/soap-fixture.mjs";
+
+test("retrieves a pea variety from SOAP through a natural request", async (t) => {
+  const fixture = await startSoapFixture(t);
+  const chat = await createConversation(t, {
+    server: new URL("../dist/server.js", import.meta.url),
+    environment: { PEA_SOAP_URL: fixture.url.href },
+  });
+
+  // One turn covers the example's only model-visible decision. XML validation
+  // belongs in deterministic tests and would only waste model calls here.
+  const result = await chat.send("Tell me about the Sugar Ann pea variety.");
+  assertToolCalls(result, [{ name: "get-pea-variety", arguments: { name: "Sugar Ann" } }]);
+  await assertResponseMeaning(result, {
+    expected:
+      "Sugar Ann is a snap pea that typically matures in 56 days. " +
+      "It is an early bush variety with compact plants and edible pods.",
+  });
+});

package/initializer-dist/template/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "emseepea-starter",
+  "version": "0.0.0",
+  "description": "Create an Em See Pea server that validates a SOAP service from its XSD contract.",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.type-tests.json",
+    "generate": "node scripts/generate-types.mjs",
+    "generate:check": "node scripts/check-generated.mjs",
+    "start": "node dist/server.js",
+    "test": "npm run build && npm run test:built",
+    "test:built": "node --test test/*.test.mjs",
+    "test:llm": "npm run build && npm run test:llm:built",
+    "test:llm:built": "emseepea-test eval",
+    "lint": "oxlint src test test-types eval scripts test-support"
+  },
+  "devDependencies": {
+    "@emseepea/testing": "0.5.2",
+    "@types/node": "24.13.3",
+    "typescript": "6.0.3",
+    "oxlint": "1.80.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "private": true,
+  "dependencies": {
+    "@emseepea/server": "0.3.3",
+    "@types/sax": "1.2.7",
+    "soap": "1.11.0",
+    "xml-xsd-engine": "1.7.3",
+    "zod": "4.4.3"
+  }
+}

package/initializer-dist/template/scripts/check-generated.mjs

@@ -0,0 +1,15 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { generatedArtifacts } from "./generate-types.mjs";
+
+const generated = await generatedArtifacts();
+assert.equal(
+  await readFile(new URL("../src/generated/pea-service.ts", import.meta.url), "utf8"),
+  generated.types,
+  "generated SOAP types are stale",
+);
+assert.equal(
+  await readFile(new URL("../src/generated/pea-service.schema-model.json", import.meta.url), "utf8"),
+  generated.model,
+  "generated SOAP schema model is stale",
+);

package/initializer-dist/template/scripts/generate-types.mjs

@@ -0,0 +1,42 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { generateTypeScript, parseXsdAsync } from "xml-xsd-engine";
+
+const envelope = new URL("../contracts/soap-envelope.xsd", import.meta.url);
+const service = new URL("../contracts/pea-service.xsd", import.meta.url);
+
+export async function generatedArtifacts() {
+  const serviceSource = await readFile(service, "utf8");
+  return artifactsFromSources(await readFile(envelope, "utf8"), serviceSource);
+}
+
+export async function artifactsFromSources(envelopeSource, serviceSource) {
+  const schema = await parseXsdAsync(envelopeSource, async (location, namespace) => {
+    if (location !== "pea-service.xsd" || namespace !== "urn:emseepea:pea-service") {
+      throw new Error("Blocked schema import");
+    }
+    return serviceSource;
+  });
+  const types = generateTypeScript(schema, {
+    exportAll: true,
+    header: "// Generated from the local SOAP XSD graph. Do not edit.",
+    typeMap: {
+      "{http://schemas.xmlsoap.org/soap/envelope/}SoapBody": "SoapBody",
+      "{http://schemas.xmlsoap.org/soap/envelope/}SoapEnvelope": "SoapEnvelope",
+      "{urn:emseepea:pea-service}PeaType": "PeaType",
+      "{urn:emseepea:pea-service}PeaVariety": "PeaVariety",
+    },
+  });
+  return {
+    model: `${JSON.stringify(schema.toJSON(), null, 2)}\n`,
+    types: `${types.trim()}\n`,
+  };
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const generated = await generatedArtifacts();
+  await Promise.all([
+    writeFile(new URL("../src/generated/pea-service.ts", import.meta.url), generated.types),
+    writeFile(new URL("../src/generated/pea-service.schema-model.json", import.meta.url), generated.model),
+  ]);
+}

package/initializer-dist/template/src/app.ts

@@ -0,0 +1,26 @@
+import { fileURLToPath } from "node:url";
+import { createEmseepea, discoverCapabilities } from "@emseepea/server";
+import { createClientAsync } from "soap";
+import { z } from "zod";
+import { loadSoapEnvelopeSchema } from "./soap-schema.js";
+import { ValidatingHttpClient } from "./validating-http-client.js";
+
+export async function createSoapExample(endpointValue: string) {
+  const endpoint = new URL(z.string().url().parse(endpointValue));
+  if (!["http:", "https:"].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.hash) {
+    throw new Error("SOAP endpoint must be an HTTP address without credentials or a fragment");
+  }
+  const schema = await loadSoapEnvelopeSchema();
+  const client = await createClientAsync(
+    fileURLToPath(new URL("../contracts/pea-service.wsdl", import.meta.url)),
+    { disableCache: true, httpClient: new ValidatingHttpClient(endpoint, schema), strict: true },
+    endpoint.href,
+  );
+  const app = createEmseepea({
+    name: "emseepea-soap-backed-server",
+    version: "0.0.0",
+    instructions: "Retrieve pea variety details from a legacy SOAP service.",
+    ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), { client }),
+  });
+  return { app };
+}

package/initializer-dist/template/src/capabilities/context.ts

@@ -0,0 +1,5 @@
+import type { Client } from "soap";
+
+export interface SoapExampleContext {
+  readonly client: Client;
+}

package/initializer-dist/template/src/capabilities/tool.get-pea-variety.ts

@@ -0,0 +1,41 @@
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { z } from "zod";
+import type { GetPeaRequest, GetPeaResponse } from "../generated/pea-service.js";
+import type { SoapExampleContext } from "./context.js";
+
+const inputSchema = z.object({
+  name: z.string().trim().min(1).max(100).describe("Name of the pea variety to retrieve."),
+});
+const outputSchema = z.object({
+  name: z.string().min(1).max(100).describe("Name of the pea variety."),
+  peaType: z.string().min(1).max(40).describe("Type of pea."),
+  daysToMaturity: z.number().int().positive().describe("Typical number of days from sowing to harvest."),
+  note: z.string().max(500).optional().describe("Optional growing note."),
+  traits: z.array(z.string().max(100)).max(5).describe("Growing or eating traits."),
+});
+
+export default (({ client }) => defineTool({
+  name: "get-pea-variety",
+  access: "public",
+  description: "Get details about one pea variety.",
+  inputSchema,
+  outputSchema,
+  async handler({ name }, { signal }) {
+    signal.throwIfAborted();
+    const request: GetPeaRequest = { name };
+    const [response] = await client.GetPeaAsync(request, { signal });
+    signal.throwIfAborted();
+    return { data: outputSchema.parse(mapResponse(response)) };
+  },
+})) satisfies CapabilityModuleFactory<SoapExampleContext>;
+
+function mapResponse(response: GetPeaResponse): z.input<typeof outputSchema> {
+  return {
+    name: response.name,
+    peaType: response.peaType,
+    // node-soap returns validated XSD numeric text as a string.
+    daysToMaturity: Number(response.daysToMaturity),
+    note: response.note,
+    traits: response.trait ?? [],
+  };
+}