mcp-integration-harness 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Willi Thiel
+
+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

@@ -0,0 +1,126 @@
+# mcp-integration-harness
+
+[![npm version](https://img.shields.io/npm/v/mcp-integration-harness)](https://www.npmjs.com/package/mcp-integration-harness)
+[![node](https://img.shields.io/node/v/mcp-integration-harness)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/mcp-integration-harness)](LICENSE)
+
+Run your built [Model Context Protocol](https://modelcontextprotocol.io) server
+as a real process, against a real backend in Docker, and fail the build unless
+**every** tool was either exercised or excused in writing.
+
+```ts
+const harness = await startServer({
+  env: { WIKIJS_URL: backendUrl, WIKIJS_TOKEN: token },
+  elicit: 'accept',
+});
+
+const page = await harness.call('create_page', {
+  path: 'test',
+  content: '# hi',
+});
+await harness.call('get_page', { path: 'test' });
+await harness.confirmed('delete_page', { id });
+
+it('exercises every tool in the catalogue', () => {
+  expectEveryToolExercised(harness, ALL_TOOLS, {
+    get_page_conflict: 'needs two concurrent edits; see the conflict test',
+    reset_user_password: 'needs a local user and a working mail transport',
+  });
+});
+```
+
+## Why not the in-memory transport you already have
+
+Because it answers a different question. A unit suite links server to client
+with `InMemoryTransport` and replaces `fetch` underneath, which tests whether
+the server does what you believe the remote API does — not whether the API does
+it. Every genuinely surprising bug in this family was found by hand against a
+running instance: a `limit` parameter that counts join rows rather than pages,
+an empty `files` entry that deletes, a `filter` that is silently ignored. A
+stub cannot find those, because the stub encodes the same belief the code does.
+
+Four things are additionally untouched by any in-process test: `src/index.ts`,
+`loadConfig` reading a real environment, the stdio transport's framing, and
+elicitation across a **process boundary**. This spawns the built artifact, so
+all four are on the path.
+
+## `expectEveryToolExercised`
+
+The part worth copying even if you write the rest yourself.
+
+`skipped` is a `Record<tool, reason>`, never a `string[]`. A bare list lets a
+tool leave the suite by adding six characters, and nothing afterwards
+distinguishes a deliberate omission from a forgotten one. A reason has to be
+written by a person — a small cost, in exactly the place a small cost is
+useful.
+
+It fails in three directions, not one:
+
+1. **A tool neither called nor excused.** The gap everyone expects.
+2. **An excused tool that _was_ called.** The reason is now false, and a false
+   reason is worse than none: the next person reads it and believes the tool
+   cannot be tested.
+3. **An excused tool that no longer exists.** Renamed or removed, its excuse
+   left behind, quietly making the exception list look longer than the real one.
+
+All three are reported together, so a fourteen-repository rollout is one
+afternoon rather than fourteen CI rounds.
+
+## `assertLoopback`
+
+The guard that matters more than the tests it protects.
+
+An integration suite calls every tool, deletes included, and the machine it is
+written on is usually the same machine that has the _real_ servers configured —
+a wiki people write in, a CI instance that builds things, a VPN. One inherited
+`WIKIJS_URL` is all it takes.
+
+So: a **hard throw**, never a skip. A skipped test reports "nothing to do
+here", which is the wrong sentence when the reason is "this was pointed at
+production". Hosts are compared numerically via
+[`mcp-internal-hosts`](https://www.npmjs.com/package/mcp-internal-hosts), so
+`[::ffff:127.0.0.1]` and `localhost.` count and `127.example.com` — a hostname
+anybody can register — does not.
+
+`startServer` is the same idea as a property: the child gets `PATH` and the
+variables you passed. Nothing is inherited, so nothing can be inherited by
+accident.
+
+## API
+
+| Export                     | What it does                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| `startServer(options)`     | Spawns `dist/index.js` over real stdio and returns a `LiveHarness`              |
+| `harness.call(name, args)` | Calls a tool, records it for coverage, returns the joined text parts            |
+| `harness.raw(name, args)`  | The same, returning the whole result — for a tool that answers with an image    |
+| `harness.confirmed(…)`     | Drives **both halves** of the two-call token, for the no-dialog fallback path   |
+| `harness.prompts`          | Every message the server put in front of the user, in order                     |
+| `harness.stderr()`         | Everything the server wrote to stderr, including before the handshake completed |
+| `expectEveryToolExercised` | The three-way coverage assertion above                                          |
+| `toolCoverage`             | The same comparison without asserting, for printing the numbers                 |
+| `assertLoopback(url)`      | Throws unless the URL is on this machine                                        |
+| `waitForHttp(url, opts)`   | Polls until an HTTP backend is ready, and says what the last attempt got        |
+| `waitForTcp(host, port)`   | The same for a backend that is not HTTP — IMAP, SMTP — optionally on a greeting |
+
+`elicit: 'accept' | 'decline' | 'cancel'` makes the harness declare the
+elicitation capability and answer the dialog, which is the path a real client
+takes. **Omitting** it declares no capability at all, which is what makes a
+guarded tool fall back to the token — so `confirmed()` only works on a harness
+started without `elicit`, and says so when it does not.
+
+## Requirements
+
+Node 22 or newer, and `@modelcontextprotocol/client` 2.x as a peer. Both belong
+in `devDependencies`: this is test infrastructure and has no business in a
+server's runtime tree.
+
+## Related
+
+- [`mcp-approval`](https://www.npmjs.com/package/mcp-approval) — the
+  human-in-the-loop guard whose two paths this drives
+- [`mcp-internal-hosts`](https://www.npmjs.com/package/mcp-internal-hosts) —
+  the SSRF host classifier the loopback guard is built on
+
+## Licence
+
+MIT

package/dist/coverage.d.ts

@@ -0,0 +1,56 @@
+import type { LiveHarness } from './harness.js';
+/**
+ * The reason a tool could not be exercised against a real backend.
+ *
+ * A `Record<tool, reason>` rather than a `string[]`, and that is the whole
+ * design. A bare list lets a tool be dropped from the suite by adding six
+ * characters, and nothing afterwards can tell a deliberate omission from a
+ * forgotten one. A reason has to be written by a person, which is a small cost
+ * exactly where a small cost is useful.
+ *
+ * Reasons that have earned their place look like:
+ *
+ *   list_listening_sessions: 'needs playback sessions; no tool can create one'
+ *   approve_pipeline:        'needs a fork pipeline blocked on approval'
+ *   get_page_conflict:       'needs two concurrent edits; see the conflict test'
+ *
+ * A reason that has not:
+ *
+ *   delete_everything: 'skipped'
+ */
+export type SkipReasons = Readonly<Record<string, string>>;
+export interface CoverageReport {
+    called: readonly string[];
+    skipped: readonly string[];
+    /** In the catalogue, neither called nor given a reason. */
+    missing: readonly string[];
+    /** Given a reason, but called anyway — the reason is stale. */
+    staleReasons: readonly string[];
+    /** Given a reason, but no longer a tool — the reason outlived its tool. */
+    unknownReasons: readonly string[];
+}
+/**
+ * Compares what ran against the catalogue, without asserting.
+ *
+ * Exported separately so a caller can print the numbers — "48 of 62 against a
+ * real backend, 14 skipped with reasons" is worth having in a CI log even on a
+ * green run.
+ */
+export declare function toolCoverage(harness: Pick<LiveHarness, 'called'>, allTools: readonly string[], skipped: SkipReasons): CoverageReport;
+/**
+ * Fails unless every tool in the catalogue was called or excused.
+ *
+ * Three directions, not one, because a coverage check that only looks for gaps
+ * rots from the other end:
+ *
+ *   1. A tool neither called nor excused — the gap everyone expects.
+ *   2. An excused tool that *was* called. The reason is now false, and a false
+ *      reason is worse than none: the next person reads it and believes the
+ *      tool cannot be tested.
+ *   3. An excused tool that no longer exists. The tool was renamed or removed
+ *      and its excuse stayed behind, quietly making the exception list look
+ *      longer than the real one.
+ *
+ * Throws rather than returning, so it reads as one line in a test.
+ */
+export declare function expectEveryToolExercised(harness: Pick<LiveHarness, 'called'>, allTools: readonly string[], skipped?: SkipReasons): void;

package/dist/coverage.js

@@ -0,0 +1,58 @@
+/**
+ * Compares what ran against the catalogue, without asserting.
+ *
+ * Exported separately so a caller can print the numbers — "48 of 62 against a
+ * real backend, 14 skipped with reasons" is worth having in a CI log even on a
+ * green run.
+ */
+export function toolCoverage(harness, allTools, skipped) {
+    const catalogue = new Set(allTools);
+    const reasons = Object.keys(skipped);
+    return {
+        called: [...harness.called].sort(),
+        skipped: reasons.sort(),
+        missing: allTools
+            .filter((tool) => !harness.called.has(tool) && !(tool in skipped))
+            .sort(),
+        staleReasons: reasons.filter((tool) => harness.called.has(tool)).sort(),
+        unknownReasons: reasons.filter((tool) => !catalogue.has(tool)).sort(),
+    };
+}
+/**
+ * Fails unless every tool in the catalogue was called or excused.
+ *
+ * Three directions, not one, because a coverage check that only looks for gaps
+ * rots from the other end:
+ *
+ *   1. A tool neither called nor excused — the gap everyone expects.
+ *   2. An excused tool that *was* called. The reason is now false, and a false
+ *      reason is worse than none: the next person reads it and believes the
+ *      tool cannot be tested.
+ *   3. An excused tool that no longer exists. The tool was renamed or removed
+ *      and its excuse stayed behind, quietly making the exception list look
+ *      longer than the real one.
+ *
+ * Throws rather than returning, so it reads as one line in a test.
+ */
+export function expectEveryToolExercised(harness, allTools, skipped = {}) {
+    const report = toolCoverage(harness, allTools, skipped);
+    const problems = [];
+    if (report.missing.length > 0) {
+        problems.push(`${report.missing.length} tool(s) never called and not excused: ` +
+            `${report.missing.join(', ')}. Call them, or give each a reason in the ` +
+            'skip map saying what a real backend cannot provide.');
+    }
+    if (report.staleReasons.length > 0) {
+        problems.push(`${report.staleReasons.length} excused tool(s) were called after all: ` +
+            `${report.staleReasons.join(', ')}. Remove the reason — it is no longer true.`);
+    }
+    if (report.unknownReasons.length > 0) {
+        problems.push(`${report.unknownReasons.length} reason(s) name a tool that no longer ` +
+            `exists: ${report.unknownReasons.join(', ')}.`);
+    }
+    if (problems.length > 0) {
+        throw new Error(`${report.called.length} of ${allTools.length} tools exercised, ` +
+            `${report.skipped.length} excused.\n\n${problems.join('\n\n')}`);
+    }
+}
+//# sourceMappingURL=coverage.js.map

package/dist/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAkCA;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAoC,EACpC,QAA2B,EAC3B,OAAoB;IAEpB,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO;QACL,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;QAClC,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;QACvB,OAAO,EAAE,QAAQ;aACd,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,IAAI,OAAO,CAAC,CAAC;aACjE,IAAI,EAAE;QACT,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE;QACvE,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE;KACtE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAoC,EACpC,QAA2B,EAC3B,OAAO,GAAgB,EAAE;IAEzB,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,QAAQ,CAAC,IAAI,CACX,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,yCAAyC;YAC/D,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,4CAA4C;YACxE,qDAAqD,CACxD,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnC,QAAQ,CAAC,IAAI,CACX,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,0CAA0C;YACrE,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,6CAA6C,CACjF,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,QAAQ,CAAC,IAAI,CACX,GAAG,MAAM,CAAC,cAAc,CAAC,MAAM,wCAAwC;YACrE,WAAW,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACjD,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,OAAO,QAAQ,CAAC,MAAM,oBAAoB;YAC/D,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,gBAAgB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAClE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/harness.d.ts

@@ -0,0 +1,88 @@
+import { Client } from '@modelcontextprotocol/client';
+/**
+ * Driving a built MCP server over real stdio, against a real backend.
+ *
+ * Every unit suite in this family links a server to a client with
+ * `InMemoryTransport` and replaces the network underneath. That is the right
+ * trade for a unit test, and it leaves four things untested in every repository:
+ * `src/index.ts`, `loadConfig` reading a real environment, the stdio transport's
+ * framing, and elicitation across a process boundary. This spawns the built
+ * artifact instead, so all four are on the path.
+ */
+/** How a client that can show a dialog answers it. */
+export type ElicitBehaviour = 'accept' | 'decline' | 'cancel';
+export interface StartServerOptions {
+    /** The built entry point. Relative paths resolve against `cwd`. */
+    entry?: string;
+    /** Where to run it. Defaults to the current working directory. */
+    cwd?: string;
+    /**
+     * The server's entire environment, `PATH` aside.
+     *
+     * Deliberately not merged with `process.env`. A `WIKIJS_URL` left in a shell
+     * is otherwise enough to point an integration run — deletes included — at
+     * whatever that variable happens to name. Nothing is inherited, so nothing
+     * can be inherited by accident.
+     */
+    env: Record<string, string>;
+    /**
+     * How the client answers a confirmation dialog. Omitted means the client
+     * declares no elicitation capability at all, which is what makes a guarded
+     * tool fall back to the two-call token — see {@link LiveHarness.confirmed}.
+     */
+    elicit?: ElicitBehaviour;
+    /** Seconds to wait for the handshake. Default 30. */
+    timeoutSeconds?: number;
+}
+export interface CallOptions {
+    /** Assert that the call fails. Refusals are behaviour worth pinning too. */
+    expectError?: boolean;
+}
+export interface ToolResult {
+    content?: {
+        type: string;
+        text?: string;
+        mimeType?: string;
+        data?: string;
+    }[];
+    isError?: boolean;
+}
+export interface LiveHarness {
+    client: Client;
+    /**
+     * Calls a tool, records it against the coverage set, returns the text.
+     *
+     * Throws when the outcome is not the expected one, with the server's own
+     * message attached — a failure here is nearly always the backend saying
+     * something the stubbed unit tests never had to say.
+     */
+    call(name: string, args?: Record<string, unknown>, options?: CallOptions): Promise<string>;
+    /**
+     * The same, returning the whole result rather than its text.
+     *
+     * For a tool that answers with an image or a resource — a cover, a QR code,
+     * an uploaded asset — where the parts are the point. Reaching for
+     * `harness.client` instead would skip the coverage bookkeeping, and the
+     * missing tool would then have to be added to `called` by hand, which is
+     * exactly the sort of thing that stops being done.
+     */
+    raw(name: string, args?: Record<string, unknown>, options?: CallOptions): Promise<ToolResult>;
+    /**
+     * Drives both halves of the two-call token for one guarded tool.
+     *
+     * Only meaningful on a harness started **without** `elicit`: with a dialog
+     * available the server refuses to offer a token at all, which is the whole
+     * point of the dialog. Use it to prove the fallback path still works.
+     */
+    confirmed(name: string, args?: Record<string, unknown>): Promise<string>;
+    /** Every message the server put in front of the user, in order. */
+    prompts: string[];
+    /** The tools that were called. What {@link expectEveryToolExercised} reads. */
+    called: ReadonlySet<string>;
+    /** Everything the server wrote to stderr, for a failure report. */
+    stderr(): string;
+    close(): Promise<void>;
+}
+/** Pulls the fallback token out of a refusal. */
+export declare function tokenOf(text: string): string;
+export declare function startServer(options: StartServerOptions): Promise<LiveHarness>;

package/dist/harness.js

@@ -0,0 +1,110 @@
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+/** Pulls the fallback token out of a refusal. */
+export function tokenOf(text) {
+    const match = /confirm_token="([0-9a-f]+)"/.exec(text);
+    if (!match?.[1]) {
+        throw new Error(`no confirm_token in the result — did the client declare elicitation? ` +
+            `Got: ${text.slice(0, 300)}`);
+    }
+    return match[1];
+}
+/** The text parts of a tool result, joined. */
+function textOf(result) {
+    const parts = (result.content ?? []);
+    return parts
+        .filter((part) => part.type === 'text')
+        .map((part) => part.text)
+        .join('\n');
+}
+export async function startServer(options) {
+    const entry = options.entry ?? 'dist/index.js';
+    const prompts = [];
+    const called = new Set();
+    const errors = [];
+    const client = new Client({ name: 'mcp-integration-harness', version: '0.1.0' }, options.elicit === undefined ? {} : { capabilities: { elicitation: {} } });
+    if (options.elicit !== undefined) {
+        const behaviour = options.elicit;
+        client.setRequestHandler('elicitation/create', (request) => {
+            // `message` is required by the elicitation schema, so no fallback: a
+            // server that omitted it should surface as an empty prompt in the
+            // assertion, not be papered over here.
+            prompts.push(request.params.message);
+            if (behaviour === 'cancel')
+                return { action: 'cancel' };
+            if (behaviour === 'decline')
+                return { action: 'decline' };
+            return { action: 'accept', content: { confirm: true } };
+        });
+    }
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [entry],
+        // PATH only. See the comment on StartServerOptions.env.
+        env: { PATH: process.env.PATH ?? '', ...options.env },
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        stderr: 'pipe',
+    });
+    // Attached before connect, not after: the startup banner and any refusal to
+    // start are written during the handshake, and a listener added afterwards
+    // has already missed them. The transport hands back a PassThrough
+    // immediately for exactly this reason.
+    transport.stderr?.on('data', (chunk) => {
+        errors.push(chunk.toString());
+    });
+    try {
+        await client.connect(transport);
+    }
+    catch (error) {
+        // A server that dies during the handshake reports "Connection closed" and
+        // nothing else, while the reason — a missing dist/, a config error, a
+        // refused credential — is sitting in the stderr just captured. Without this
+        // the most common first failure of a new suite is also the least legible.
+        throw new Error(`mcp-integration-harness: ${process.execPath} ${entry} did not start.\n` +
+            `${String(error)}\n\nIts stderr:\n${errors.join('') || '(nothing)'}`);
+    }
+    const raw = async (name, args = {}, callOptions = {}) => {
+        called.add(name);
+        let result;
+        try {
+            result = (await client.callTool({
+                name,
+                arguments: args,
+            }));
+        }
+        catch (error) {
+            // The same reasoning as at connect time, for the other moment a server
+            // can die: a crash mid-suite surfaces as a bare "Not connected" on the
+            // next call, while what actually happened is in the stderr captured
+            // since it started.
+            throw new Error(`mcp-integration-harness: calling ${name} failed at the transport.\n` +
+                `${String(error)}\n\nThe server's stderr so far:\n` +
+                `${errors.join('') || '(nothing)'}`);
+        }
+        const failed = result.isError === true;
+        if (failed !== (callOptions.expectError ?? false)) {
+            const text = textOf(result);
+            throw new Error(callOptions.expectError
+                ? `${name} was expected to fail and did not: ${text.slice(0, 500)}`
+                : `${name} failed: ${text.slice(0, 500)}`);
+        }
+        return result;
+    };
+    const call = async (name, args = {}, callOptions = {}) => textOf(await raw(name, args, callOptions));
+    return {
+        client,
+        call,
+        raw,
+        prompts,
+        called,
+        stderr: () => errors.join(''),
+        confirmed: async (name, args = {}) => {
+            const first = await call(name, args);
+            return call(name, { ...args, confirm_token: tokenOf(first) });
+        },
+        close: async () => {
+            await client.close();
+        },
+    };
+}
+//# sourceMappingURL=harness.js.map

package/dist/harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.js","sourceRoot":"","sources":["../src/harness.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { startServer, tokenOf, type CallOptions, type ElicitBehaviour, type LiveHarness, type StartServerOptions, type ToolResult, } from './harness.js';
+export { expectEveryToolExercised, toolCoverage, type CoverageReport, type SkipReasons, } from './coverage.js';
+export { assertLoopback, assertLoopbackHost } from './loopback.js';
+export { waitForHttp, waitForTcp, type TcpWaitOptions, type WaitOptions, } from './wait.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { startServer, tokenOf, } from './harness.js';
+export { expectEveryToolExercised, toolCoverage, } from './coverage.js';
+export { assertLoopback, assertLoopbackHost } from './loopback.js';
+export { waitForHttp, waitForTcp, } from './wait.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,OAAO,GAMR,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,wBAAwB,EACxB,YAAY,GAGb,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnE,OAAO,EACL,WAAW,EACX,UAAU,GAGX,MAAM,WAAW,CAAC"}

package/dist/loopback.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Refuses any backend that is not on this machine.
+ *
+ * This is the one guard that matters more than the tests it protects. An
+ * integration suite calls every tool, including the deletes, and the machine it
+ * is written on is usually the machine that also has the *real* servers
+ * configured — a wiki people write in, a CI instance that builds things, a VPN.
+ * Getting `WIKIJS_URL` from the ambient environment once is all it takes.
+ *
+ * So: a hard throw, never a skip. A skipped test reads as "nothing to do here",
+ * which is exactly the wrong report when the reason is "this was pointed at
+ * production". The suite must stop and say so.
+ *
+ * `internalHostKind` rather than a string comparison, so every spelling of the
+ * same address counts: `[::ffff:127.0.0.1]`, which `URL` canonicalises to
+ * `[::ffff:7f00:1]` before anything else sees it, and `localhost.` with its root
+ * label. A prefix check on `127.` would also call `127.example.com` local, which
+ * is a public hostname anyone can register.
+ */
+export declare function assertLoopbackHost(host: string): void;
+/** {@link assertLoopbackHost}, for a backend addressed by URL. */
+export declare function assertLoopback(url: string): void;

package/dist/loopback.js

@@ -0,0 +1,50 @@
+import { internalHostKind } from 'mcp-internal-hosts';
+/**
+ * Refuses any backend that is not on this machine.
+ *
+ * This is the one guard that matters more than the tests it protects. An
+ * integration suite calls every tool, including the deletes, and the machine it
+ * is written on is usually the machine that also has the *real* servers
+ * configured — a wiki people write in, a CI instance that builds things, a VPN.
+ * Getting `WIKIJS_URL` from the ambient environment once is all it takes.
+ *
+ * So: a hard throw, never a skip. A skipped test reads as "nothing to do here",
+ * which is exactly the wrong report when the reason is "this was pointed at
+ * production". The suite must stop and say so.
+ *
+ * `internalHostKind` rather than a string comparison, so every spelling of the
+ * same address counts: `[::ffff:127.0.0.1]`, which `URL` canonicalises to
+ * `[::ffff:7f00:1]` before anything else sees it, and `localhost.` with its root
+ * label. A prefix check on `127.` would also call `127.example.com` local, which
+ * is a public hostname anyone can register.
+ */
+export function assertLoopbackHost(host) {
+    if (internalHostKind(host) !== 'loopback') {
+        throw new Error(`mcp-integration-harness: refusing to talk to ${host} — the integration ` +
+            'suite calls every tool, deletes included, and may only ever talk to a ' +
+            'throwaway backend on this machine. Expected a loopback host; got one ' +
+            'that resolves somewhere else.');
+    }
+}
+/** {@link assertLoopbackHost}, for a backend addressed by URL. */
+export function assertLoopback(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`mcp-integration-harness: refusing to run against "${url}" — not a URL. ` +
+            'The backend URL must come from the throwaway compose stack.');
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        // `new URL('localhost:3000')` succeeds: protocol `localhost:`, hostname
+        // empty. Without this branch the next check rejects it for having no host,
+        // and the message reads "refusing to talk to " with a hole where the
+        // hostname should be — true, but no help at all to whoever forgot `http://`.
+        throw new Error(`mcp-integration-harness: refusing to run against "${url}" — not an ` +
+            'http(s) URL. A scheme-less "localhost:3000" parses as a URL whose ' +
+            'protocol is "localhost:", which is not the same thing as a backend.');
+    }
+    assertLoopbackHost(parsed.hostname);
+}
+//# sourceMappingURL=loopback.js.map

package/dist/loopback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.js","sourceRoot":"","sources":["../src/loopback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,qBAAqB;YACvE,wEAAwE;YACxE,uEAAuE;YACvE,+BAA+B,CAClC,CAAC;IACJ,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,qDAAqD,GAAG,iBAAiB;YACvE,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChE,wEAAwE;QACxE,2EAA2E;QAC3E,qEAAqE;QACrE,6EAA6E;QAC7E,MAAM,IAAI,KAAK,CACb,qDAAqD,GAAG,aAAa;YACnE,oEAAoE;YACpE,qEAAqE,CACxE,CAAC;IACJ,CAAC;IACD,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACtC,CAAC"}

package/dist/wait.d.ts

@@ -0,0 +1,49 @@
+export interface WaitOptions {
+    /** How long to keep trying. Default 120 s — a cold Postgres is slow. */
+    timeoutSeconds?: number;
+    /** Between attempts. Default 1 s. */
+    intervalMs?: number;
+    /** What counts as ready. Default: any response at all. */
+    ready?: (response: Response) => boolean;
+}
+/**
+ * Waits for a backend to answer, or explains why it never did.
+ *
+ * `docker compose up --wait` covers the services that declare a healthcheck,
+ * and most upstream images do not. The alternative people reach for is a fixed
+ * `sleep 30`, which is both too long on a warm machine and too short on a cold
+ * one — and when it is too short the failure surfaces as the first tool call
+ * returning ECONNREFUSED, which reads like a bug in the tool.
+ *
+ * The last error is kept and thrown, because "timed out" on its own does not
+ * distinguish "not listening yet" from "listening and answering 500".
+ *
+ * For a backend that does not speak HTTP, use {@link waitForTcp}. `fetch`
+ * against an IMAP or SMTP port does not resolve — the greeting is not an HTTP
+ * response, so it rejects, and this would report a timeout for a server that
+ * came up immediately.
+ */
+export declare function waitForHttp(url: string, options?: WaitOptions): Promise<void>;
+export interface TcpWaitOptions {
+    timeoutSeconds?: number;
+    intervalMs?: number;
+    /**
+     * Text the server must send unprompted, if it greets.
+     *
+     * IMAP answers `* OK`, SMTP answers `220`. Checking the greeting rather than
+     * only the connection is what tells "the port is open" from "the service
+     * behind it has finished starting" — Docker publishes the port before the
+     * process inside is listening on it, so a bare connect can succeed against
+     * nothing.
+     */
+    expect?: string;
+}
+/**
+ * Waits for a plain TCP service — IMAP, SMTP, anything not HTTP.
+ *
+ * Several backends in this family do not speak HTTP at all, and `fetch`
+ * against them rejects rather than answering: undici cannot parse an IMAP
+ * greeting as an HTTP response, so {@link waitForHttp} reports a timeout for a
+ * server that was ready in a second.
+ */
+export declare function waitForTcp(host: string, port: number, options?: TcpWaitOptions): Promise<void>;

package/dist/wait.js

@@ -0,0 +1,111 @@
+import { createConnection } from 'node:net';
+import { assertLoopback, assertLoopbackHost } from './loopback.js';
+/**
+ * Waits for a backend to answer, or explains why it never did.
+ *
+ * `docker compose up --wait` covers the services that declare a healthcheck,
+ * and most upstream images do not. The alternative people reach for is a fixed
+ * `sleep 30`, which is both too long on a warm machine and too short on a cold
+ * one — and when it is too short the failure surfaces as the first tool call
+ * returning ECONNREFUSED, which reads like a bug in the tool.
+ *
+ * The last error is kept and thrown, because "timed out" on its own does not
+ * distinguish "not listening yet" from "listening and answering 500".
+ *
+ * For a backend that does not speak HTTP, use {@link waitForTcp}. `fetch`
+ * against an IMAP or SMTP port does not resolve — the greeting is not an HTTP
+ * response, so it rejects, and this would report a timeout for a server that
+ * came up immediately.
+ */
+export async function waitForHttp(url, options = {}) {
+    assertLoopback(url);
+    const timeoutSeconds = options.timeoutSeconds ?? 120;
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    const interval = options.intervalMs ?? 1000;
+    const ready = options.ready ?? (() => true);
+    let last = 'no attempt completed';
+    for (;;) {
+        try {
+            const response = await fetch(url, {
+                signal: AbortSignal.timeout(5000),
+                redirect: 'manual',
+            });
+            if (ready(response))
+                return;
+            last = `HTTP ${response.status}`;
+        }
+        catch (error) {
+            // `String(error)` rather than `error.message`: the message alone is often
+            // just "fetch failed", and the constructor name is the half that says
+            // whether nothing was listening or the request timed out.
+            last = String(error);
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`mcp-integration-harness: ${url} did not become ready within ` +
+                `${timeoutSeconds}s. Last attempt: ${last}. ` +
+                'Is the compose stack up? `docker compose logs` usually says why.');
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+}
+/**
+ * Waits for a plain TCP service — IMAP, SMTP, anything not HTTP.
+ *
+ * Several backends in this family do not speak HTTP at all, and `fetch`
+ * against them rejects rather than answering: undici cannot parse an IMAP
+ * greeting as an HTTP response, so {@link waitForHttp} reports a timeout for a
+ * server that was ready in a second.
+ */
+export async function waitForTcp(host, port, options = {}) {
+    assertLoopbackHost(host);
+    const timeoutSeconds = options.timeoutSeconds ?? 120;
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    const interval = options.intervalMs ?? 1000;
+    let last = 'no attempt completed';
+    for (;;) {
+        try {
+            await attempt(host, port, options.expect);
+            return;
+        }
+        catch (error) {
+            last = String(error);
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`mcp-integration-harness: ${host}:${port} did not become ready within ` +
+                `${timeoutSeconds}s. Last attempt: ${last}. ` +
+                'Is the compose stack up? `docker compose logs` usually says why. ' +
+                'A service that binds 127.0.0.1 *inside* its container publishes a ' +
+                'port that reaches nothing — check what its log says it bound to.');
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+}
+function attempt(host, port, expect) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection({ host, port });
+        const done = (error) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        socket.setTimeout(5000, () => done(new Error('timed out')));
+        socket.on('error', done);
+        if (expect === undefined) {
+            socket.on('connect', () => done());
+            return;
+        }
+        let greeting = '';
+        socket.on('data', (chunk) => {
+            greeting += chunk.toString('utf8');
+            if (greeting.includes(expect))
+                done();
+            else if (greeting.length > 4096) {
+                done(new Error(`greeting did not contain ${expect}`));
+            }
+        });
+    });
+}
+//# sourceMappingURL=wait.js.map

package/dist/wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "mcp-integration-harness",
+  "version": "0.1.0-rc.1",
+  "description": "Drive an MCP server over real stdio against a real backend, and prove every tool was exercised",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "integration-testing",
+    "end-to-end",
+    "testing"
+  ],
+  "license": "MIT",
+  "author": "Willi Thiel",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ni-c/mcp-integration-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ni-c/mcp-integration-harness/issues"
+  },
+  "homepage": "https://github.com/ni-c/mcp-integration-harness#readme",
+  "funding": "https://github.com/sponsors/ni-c",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "lint": "oxlint --deny-warnings && prettier --check .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0"
+  },
+  "dependencies": {
+    "mcp-internal-hosts": "^0.2.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/core": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "@types/node": "^26.2.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "mcp-approval": "^0.7.0",
+    "oxlint": "^1.80.0",
+    "prettier": "^3.6.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3"
+  }
+}