@novorb/mcp-core 2.1.1 → 3.0.0

package/docs/tools.md

@@ -0,0 +1,88 @@
+# Tools
+
+- `registerTools(server, tools, { env?, enabled?, prefix?, serverName?, mapError? })` registers every
+  definition through `McpServer.registerTool`: the SDK builds `tools/list`, validates input (a failure is
+  an isError result `Input validation error: ... <field>: <message>`), validates `structuredContent`
+  against `outputSchema`, and answers an unknown tool with ProtocolError `-32602`. Returns the SDK handles.
+- Write each definition with `defineTool({...})` so the handler's arguments are typed from its own
+  `inputSchema` (a zod 4 object, or `fromJsonSchema(...)`); `annotations` is required. Every SDK `Tool`
+  field reaches the wire: `name`, `title`, `description`, `inputSchema`, `outputSchema`, `annotations`,
+  `icons`, `_meta`. Results go through the SDK's output validation and era projection (nothing bypasses
+  `registerTool`); an unknown or `disable()`d tool is the SDK's own ProtocolError `-32602`, unwrapped.
+- Per call: `logToolCall` / `logToolResult` with the duration (shape only, never values). A thrown error
+  becomes `toolError(mapError(err).message)` (default: the message only, secret parameters redacted, never
+  a stack or a raw error object; with a `code`, `<code>: <message>`); a thrown zod / Standard Schema error
+  becomes `Invalid arguments: <path>: <message>; ...`. A returned legacy `{ success: false, error }`
+  envelope becomes `isError: true` (text = the envelope JSON); `{ success: true, data }` keeps its text,
+  with `data` as `structuredContent` when the tool has an `outputSchema`.
+- Degraded mode: a tool whose `requires` keys are not configured is still listed, and answers
+  `<serverName> is not configured: set <KEYS>`. `requires` keys must be declared in the env schema.
+- `ToolContext`: `signal` (pass it to outbound calls so cancellation stops upstream work), `authInfo`,
+  `cursor` (the `cursor` argument when it is a non-empty string), `era` (`modern` | `legacy`),
+  `clientCapabilities`, `logger`, `progress(progress, total?, message?)`, `elicit`, `elicitUrl`,
+  `sample`, `listRoots` (see [Protocol features](protocol-features.md)), `credentials` (the call's credential scope, see
+  [Credential health](credentials.md)), `tool`, `sdk` (the raw SDK context).
+- `registerTools` option `credentials` picks the registry (default the process registry); every result
+  that touched a credential carries the credential report.
+- `toolResult(data, { text? })`: a string is the text; an object is pretty JSON plus `structuredContent`.
+  `toolError(message, details?)`: `isError: true`, details as a second JSON text block.
+- Client-bound error text is masked like the log files: `toolError`, the `mapError` output, thrown
+  errors, schema-issue text, the degraded-mode message and any isError result a handler returns go
+  through `maskClientText` (secret query/userinfo/Basic parameters redacted, every registered secret
+  value as `[SECRET]`).
+- SDK protocol errors keep their code: a handler throwing `UrlElicitationRequiredError` (`-32042`, the
+  2025 URL-elicitation path) reaches the client as that JSON-RPC error, exactly as the SDK's own
+  `tools/call` rethrows it; every other throw becomes an isError result (the SDK does the same). An SDK
+  input-required result (`inputRequired(...)`, `resultType: 'input_required'`) is passed through
+  untouched.
+- `scopeChallenge` (for example `requireScopes('write')`) is forwarded to `registerTool`.
+
+## Response limits and pagination
+
+Every tool result is capped centrally (defaults; env in `CORE_ENV_SCHEMA`; `RegisterToolsOptions.limits`
+for the server; `ToolDefinition.limits` per tool, which wins):
+
+| Cap | Env | Default |
+|-----|-----|---------|
+| Items in a list-shaped result | `MCP_MAX_RESULT_ITEMS` | 100 |
+| Serialized bytes per result | `MCP_MAX_RESULT_BYTES` | 262144 (256 KiB) |
+
+- **List-shaped** = `structuredContent` of the `PagedResult` shape `{ items, nextCursor?, total? }`
+  (`toolResult(page)`, `pagedResultSchema(z, Item)`). A result with more items than the cap (or than the
+  client's `limit`, itself capped) is cut and carries an opaque `nextCursor`; the text block is
+  regenerated from the cut page, so it never carries the full dump. The cursor resumes where the page
+  stopped: it records the tool, a fingerprint of the other arguments, the offset inside the handler's
+  page and the handler's own cursor for that page. The next call re-runs the handler with its own
+  cursor (as `args.cursor` and `ctx.cursor`; `args.limit` arrives capped) and mcp-core serves the next
+  slice, or wraps the handler's own `nextCursor` once its page is used up. Stateless: nothing is stored.
+- **Never trusted:** a cursor for another tool or other arguments, a malformed one, or an out-of-range
+  offset is refused with `Invalid cursor: ...` (isError). An edited offset can only address the caller's
+  own result set. `paginated: true` on a definition makes cursor handling strict (only mcp-core cursors)
+  and requires `cursor` and `limit` in its input schema (checked at registration):
+  `inputSchema: z.object({ ..., cursor: z.string().optional(), limit: z.number().int().positive().optional() })`.
+  A tool returning a `PagedResult` without `paginated` is paged too and passes foreign cursors (its own,
+  from a non-paged result) through to the handler.
+- **`limit` is clamped on every tool.** An argument named `limit` that is a number is clamped to
+  `1..MCP_MAX_RESULT_ITEMS` before the handler sees it, on every registered tool, paginated or not; a tool
+  whose own `limit` means something else must name it differently. The limits are read from the `env`
+  passed to `registerTools` (its loaded env, file and defaults included) and fall back to `process.env`
+  only when no env is passed.
+- **Foreign cursors arrive raw.** On a tool that is not `paginated`, a cursor mcp-core did not issue is
+  passed to the handler untouched as `args.cursor`; the handler must validate it as untrusted input
+  (digits only for a page number, origin and path checks for a URL).
+- **Byte cap:** a list-shaped result is first paged smaller (halving until it fits); anything still over
+  the cap, and any other result, becomes an actionable isError (`<tool>: the result is N bytes, over the M
+  byte limit per response; narrow the request ... or use cursor/limit`). Never a truncated body, invalid
+  JSON or schema-breaking `structuredContent`. `RegisterToolsOptions.onOversize(info)` may return a
+  replacement instead (the seam for a resource link once resources exist).
+- **Envelope tools:** `envelope: { key: 'data', hint: '...' }` on a definition says the payload sits under
+  `structuredContent.data`. The item cap then applies to that payload (an array, or a PagedResult) and
+  refuses rather than pages (`<tool>: the result has N items, over the M item limit per response; <hint>`),
+  since such a tool has no mcp-core cursor; a text block that only repeats the payload is counted once in
+  the byte cap; `hint` names the caller's real lever (for example its own `limit`/`offset` arguments).
+- Enforcement is logged by shape only: `Tool result paged: <tool>` with `{ tool, items, served, limit }`,
+  `Tool result over the byte limit: <tool>` with `{ tool, bytes, maxBytes }`; never content.
+- Handlers must be deterministic for a given cursor (list reads are). `paginate().collect()` in the HTTP
+  client is capped at the same `MCP_MAX_RESULT_ITEMS` by default (an explicit `maxItems` up to
+  `HARD_MAX_COLLECT_ITEMS`, 100000), so a tool cannot pull an unbounded upstream list into memory;
+  `collect()` reports `truncated`.

package/docs/transport.md

@@ -0,0 +1,85 @@
+# Transport and Express adapter
+
+## Transport
+
+Unified transport that selects between stdio (`serveStdio`) and stateless streamable HTTP (`createMcpHandler` + `toNodeHandler`) based on the `MCP_TRANSPORT` environment variable. HTTP mode is fail-closed (refuses to start without auth unless explicitly disabled) and supports Bearer-token auth, body-size caps, and opt-in DNS-rebinding protection.
+
+```typescript
+import { startMcpServer } from '@novorb/mcp-core/transport';
+
+// Factory (required for HTTP, recommended for stdio):
+await startMcpServer(() => createServer(services));
+
+// Server instance (stdio only; HTTP mode throws):
+await startMcpServer(server);
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
+| `PORT` | `8080` | HTTP listen port |
+| `MCP_HTTP_HOST` | `0.0.0.0` | Bind address (`127.0.0.1` for local-only) |
+| `MCP_API_KEY` | none | Bearer token for HTTP auth (required in HTTP mode unless disabled) |
+| `MCP_AUTH_DISABLED` | `false` | Set `true` to run HTTP without auth (only behind a fronting gateway) |
+| `MCP_MAX_BODY_BYTES` | 4 MiB | Max accepted POST body size |
+| `MCP_ALLOWED_HOSTS` | none | Comma-separated Host allowlist, matched by hostname (port ignored); enables DNS-rebinding protection |
+| `MCP_ALLOWED_ORIGINS` | none | Comma-separated Origin allowlist, matched by hostname (port ignored; a full-origin entry's scheme is ignored); a lowercase `<scheme>://*` entry admits that whole scheme, `http://*` / `https://*` are never honoured; enables DNS-rebinding protection |
+
+An unknown `MCP_TRANSPORT` value throws. Explicit options (`mode`, `port`, `host`, `apiKey`, `auth`,
+`maxBodyBytes`, `allowedHosts`, `allowedOrigins`) win over the env; `runMcpServer` passes the values of
+the loaded env (`transportFromEnv`). The handle's `closed` promise resolves when the transport ends
+(`close()`, or a stdio client closing stdin).
+
+### HTTP auth
+
+The Bearer gate is the SDK's resource-server path: `verifyBearerToken` (header parse, verifier,
+`expectedResource`, `requiredScopes`, expiry) and `bearerAuthChallengeResponse` (401 `invalid_token` /
+403 `insufficient_scope` with `WWW-Authenticate: Bearer ...`, `resource_metadata` when configured). The
+verified `AuthInfo` is set as `req.auth`; the SDK forwards it to the factory (`RequestContext.authInfo`)
+and to handlers (`ctx.http.authInfo`, `ToolContext.authInfo`), so per-tool `scopeChallenge:
+requireScopes('write')` works.
+
+- Static key: `MCP_API_KEY` (or `apiKey`) becomes `apiKeyVerifier(key, { clientId?, scopes?, ttlSeconds? })`:
+  a constant-time compare (SHA-256 of both sides, `timingSafeEqual`) answering
+  `{ token: '[api-key]', clientId: 'api-key', scopes: [], expiresAt: now + 3600 }`. The real key never
+  reaches `AuthInfo`. Set its scopes with `auth: { apiKey: { clientId, scopes } }`.
+- Pluggable: `auth: { verifier }` takes any `OAuthTokenVerifier` (for example an OAuth JWT
+  verifier); it replaces the static key and always enforces auth. `requiredScopes`,
+  `resourceMetadataUrl` and `expectedResource` pass through to the SDK.
+- Fail-closed is unchanged: no key, no verifier and no explicit disable refuses to start. Guard order
+  is unchanged: `/health`, Bearer (401/403), path (404), Host/Origin (403), content type (415, the SDK's
+  media-type essence compare: `application/json` with parameters, any case; `application/json-seq` is
+  refused), body size (413), parse (400 `-32700`), dispatch.
+
+## Express adapter (`@novorb/mcp-core/express`)
+
+For hosts that already run Express: the same stateless handler, factory and
+`RequestContext` semantics as `startMcpServer`'s HTTP mode, built on `@modelcontextprotocol/express`
+(`requireBearerAuth`, `hostHeaderValidation`, `originValidation`). Install `express` (`^4.18 || ^5`) and
+`@modelcontextprotocol/express` (`~2.0.2`); without them the import throws `ExpressAdapterUnavailableError`.
+
+```typescript
+import express from 'express';
+import { mountMcpServer } from '@novorb/mcp-core/express';
+
+const app = express();
+const mcp = mountMcpServer(app, (req) => buildServer(req.authInfo), {
+  auth: { verifier: keycloakVerifier, requiredScopes: ['mcp'] },   // or apiKey / MCP_API_KEY
+  allowedHosts: ['gateway.internal'],
+});
+app.listen(8080);
+// shutdown: await mcp.close();
+```
+
+Options: `path` (`/mcp`), `health` (`/health`; `false` disables, a string moves it), `apiKey` (default
+`MCP_API_KEY`; `null` runs open), `auth` (as for the transport), `maxBodyBytes`, `allowedHosts`,
+`allowedOrigins`, `env`, `bus` (the change-event bus, default the process bus), `onError` (receives every
+SDK and adapter request error, including an authenticator fault that answers 500; default the mcp-core
+logger), `authenticateRequest`
+(for a host whose own middleware already authenticated the request: `(req) => AuthInfo` replaces the
+Bearer gate, `apiKey` and `auth.verifier`, since a token verifier never sees `req`; it must throw for an
+unauthenticated request, and a throw answers the SDK challenge, an `OAuthError` its 401/403 and anything
+else 500; combining it with `apiKey` or `auth.verifier` throws at construction). Guard order: health > Bearer (401/403 SDK challenge, `req.auth` set) >
+Host/Origin (403) > 415 > 413 > 400 `-32700` > dispatch; fail-closed like the transport. A body already
+parsed by an app-level `express.json()` is used as is (then that parser's limit applies).
+`createMcpRouter(factory, options)` returns the router without mounting it.

package/examples/testing/tools.integration.test.example.ts

@@ -0,0 +1,312 @@
+/**
+ * Example INTEGRATION suite for an MCP server built on @novorb/mcp-core.
+ *
+ * Copy to `tests/integration/tools.integration.test.ts` in your server and edit ONLY the
+ * "SERVER UNDER TEST" block and the case table. The suite starts the BUILT server (`node dist/index.js`)
+ * as a child process, in stdio AND http mode, with an explicit env and per-run temp dirs, and drives it
+ * with the real v2 client. No mocks: real server process, real downstream API, real client.
+ *
+ * Gating (environment of the test run, never of the server):
+ *   MCP_IT_TARGET=test|live   default test. LIVE runs read cases only; write/destructive need TEST.
+ *   MCP_IT_ALLOW_COSTLY=true  costly cases (they spend quota or money) run only with this opt-in.
+ * A case whose credentials are absent is skipped with a printed `[SKIP]` line: a skipped case protects
+ * nothing, so read the skip list in the output.
+ *
+ * mcp-core runs this exact file against its own echo fixture, so it cannot drift from the harness.
+ * Jest is used here (`@jest/globals`); the harness itself is runner-agnostic, so vitest works the same.
+ */
+
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { afterAll, beforeAll, describe, expect, it } from '@jest/globals';
+import {
+  assertToolCoverage,
+  type BuiltServer,
+  callToolJson,
+  collectStrings,
+  createIsolatedDirs,
+  expectSchemaRejection,
+  expectToolError,
+  expectUnknownTool,
+  findLeaks,
+  type HarnessMode,
+  type IsolatedDirs,
+  initializeRequestBody,
+  listToolNames,
+  logLevels,
+  mcpPostHeaders,
+  rawHttp,
+  readLogFiles,
+  type StartBuiltServerOptions,
+  startBuiltServer,
+  type ToolJsonResult,
+} from '@novorb/mcp-core/testing';
+
+// ---- SERVER UNDER TEST -----------------------------------------------------------------------------
+/** The name your server passes to initLogger (the main log file is `<name>.log`). */
+const SERVER_NAME = 'echo-fixture';
+/** Text of the INFO line your server logs at startup. */
+const STARTUP_LINE = 'echo-fixture started';
+/** Your built entry: `fileURLToPath(new URL('../../dist/index.js', import.meta.url))`. */
+const ENTRY = fileURLToPath(new URL('../../tests/fixtures/echo-server.ts', import.meta.url));
+/** Node arguments before the entry: `[]` for a built `dist/index.js` (the fixture is TypeScript). */
+const NODE_ARGS = ['--import', pathToFileURL(createRequire(import.meta.url).resolve('tsx')).href];
+/**
+ * EVERY provider/credential variable the server reads, '' when not supplied, so a developer `.env` or a
+ * dotenv load can never fill a gap. Use exactly the names your credentials spec gives the operator.
+ */
+const CREDENTIALS: Record<string, string> = { ECHO_UPSTREAM_TOKEN: process.env.ECHO_UPSTREAM_TOKEN ?? '' };
+/** A deliberately wrong credential set, for the "downstream auth error surfaces as an error" case. */
+const WRONG_CREDENTIALS: Record<string, string> = { ECHO_UPSTREAM_TOKEN: 'bad-token-mcpit-adverse' };
+/** Extra per-run dirs the server needs, by env var name (DATA_PATH is mcp-core's data store directory). */
+const stateEnv = (dirs: IsolatedDirs): Record<string, string> => ({ DATA_PATH: dirs.state });
+// ---------------------------------------------------------------------------------------------------
+
+const TARGET = process.env.MCP_IT_TARGET === 'live' ? 'live' : 'test';
+const ALLOW_COSTLY = process.env.MCP_IT_ALLOW_COSTLY === 'true';
+const RUN_ID = `mcpit-${Date.now().toString(36)}`;
+/** A PII fixture sent as an argument value: it must never reach a log file unmasked. */
+const PII_EMAIL = 'mcpit.person@example.com';
+
+type Kind = 'read' | 'write' | 'destructive' | 'costly';
+
+/** Everything a case touches, so the log assertions can scan for it afterwards. */
+interface RunContext {
+  client: BuiltServer['client'];
+  /** Every string VALUE sent as a tool argument. */
+  sent: string[];
+  /** Every result text received. */
+  received: string[];
+  /** Tools called at least once. */
+  called: Set<string>;
+}
+
+async function call<T = unknown>(
+  ctx: RunContext,
+  name: string,
+  args: Record<string, unknown> = {},
+): Promise<ToolJsonResult<T>> {
+  collectStrings(args, ctx.sent);
+  ctx.called.add(name);
+  const result = await callToolJson<T>(ctx.client, name, args);
+  if (result.text) ctx.received.push(result.text);
+  return result;
+}
+
+interface Case {
+  tool: string;
+  kind: Kind;
+  /** Credential variables the case needs (skipped with [SKIP] when any is empty). */
+  needs?: string[];
+  run(ctx: RunContext): Promise<void>;
+}
+
+/** One case per registered tool, real call, assert the real response shape and a meaningful value. */
+const CASES: Case[] = [
+  {
+    tool: 'echo',
+    kind: 'read',
+    run: async (ctx) => {
+      const r = await call(ctx, 'echo', { text: `${RUN_ID} ${PII_EMAIL}` });
+      expect(r.isError).toBe(false);
+      expect(r.text).toBe(`echo: ${RUN_ID} ${PII_EMAIL}`);
+    },
+  },
+  {
+    tool: 'echo_json',
+    kind: 'read',
+    run: async (ctx) => {
+      const r = await call<{ text: string; length: number }>(ctx, 'echo_json', { text: `${RUN_ID}-json` });
+      expect(r.body).toEqual({ text: `${RUN_ID}-json`, length: `${RUN_ID}-json`.length });
+    },
+  },
+  {
+    tool: 'boom',
+    kind: 'read',
+    // Pins the CURRENT error envelope: a tool-level failure is `isError: true`, not a thrown error.
+    run: async (ctx) => {
+      expectToolError(await call(ctx, 'boom'), 'boom: failed');
+    },
+  },
+  {
+    tool: 'upstream_status',
+    kind: 'read',
+    needs: ['ECHO_UPSTREAM_TOKEN'],
+    run: async (ctx) => {
+      expect((await call(ctx, 'upstream_status')).body).toEqual({ authenticated: true });
+    },
+  },
+  {
+    tool: 'paid_lookup',
+    kind: 'costly',
+    run: async (ctx) => {
+      expect((await call(ctx, 'paid_lookup', { query: RUN_ID })).body).toEqual({ query: RUN_ID, charged: 1 });
+    },
+  },
+  {
+    tool: 'note_create',
+    kind: 'write',
+    // Writes create their own uniquely named objects and clean them up.
+    run: async (ctx) => {
+      const name = `${RUN_ID}-create`;
+      expect((await call(ctx, 'note_create', { name, body: `${RUN_ID} body` })).body).toEqual({ name, created: true });
+      expect((await call(ctx, 'note_delete', { name })).isError).toBe(false);
+    },
+  },
+  {
+    tool: 'note_list',
+    kind: 'read',
+    run: async (ctx) => {
+      const r = await call<{ names: string[] }>(ctx, 'note_list', { prefix: `${RUN_ID}-none` });
+      expect(r.body).toEqual({ names: [] });
+    },
+  },
+  {
+    tool: 'note_delete',
+    kind: 'destructive',
+    // Destructive tools only act on objects the test created.
+    run: async (ctx) => {
+      const name = `${RUN_ID}-delete`;
+      await call(ctx, 'note_create', { name, body: 'to delete' });
+      expect((await call(ctx, 'note_delete', { name })).body).toEqual({ name, deleted: true });
+      const after = await call<{ names: string[] }>(ctx, 'note_list', { prefix: name });
+      expect(after.body).toEqual({ names: [] });
+    },
+  },
+];
+
+function skipReason(c: Case): string | undefined {
+  if (c.kind === 'costly' && !ALLOW_COSTLY) return 'costly; set MCP_IT_ALLOW_COSTLY=true to run it';
+  if ((c.kind === 'write' || c.kind === 'destructive' || c.kind === 'costly') && TARGET === 'live') {
+    return `${c.kind} cases run only with MCP_IT_TARGET=test`;
+  }
+  const missing = (c.needs ?? []).filter((v) => !CREDENTIALS[v]);
+  if (missing.length > 0) return `missing credential ${missing.join(', ')}`;
+  return undefined;
+}
+
+function serverOptions(
+  mode: HarnessMode,
+  dirs: IsolatedDirs,
+  extra: Record<string, string> = {},
+): StartBuiltServerOptions {
+  return {
+    entry: ENTRY,
+    nodeArgs: NODE_ARGS,
+    mode,
+    cwd: dirs.cwd,
+    env: { ...dirs.env(), ...stateEnv(dirs), ...CREDENTIALS, LOG_LEVEL: 'DEBUG', LOG_CONSOLE: 'false', ...extra },
+    // MCP_ENV_FILE=none: the server's env loader never reads a developer `.env`.
+    envFile: 'none',
+  };
+}
+
+describe.each<HarnessMode>(['stdio', 'http'])('tools over %s (integration)', (mode) => {
+  let dirs: IsolatedDirs;
+  let srv: BuiltServer;
+  let ctx: RunContext;
+
+  beforeAll(async () => {
+    dirs = createIsolatedDirs(`mcpit-${mode}`);
+    srv = await startBuiltServer(serverOptions(mode, dirs));
+    ctx = { client: srv.client, sent: [], received: [], called: new Set() };
+  });
+
+  afterAll(async () => {
+    // Prefix sweep: remove anything this run created that a failed case left behind (TEST only).
+    if (srv && TARGET === 'test') {
+      try {
+        const left = await callToolJson<{ names: string[] }>(srv.client, 'note_list', { prefix: RUN_ID });
+        for (const name of left.body?.names ?? []) await callToolJson(srv.client, 'note_delete', { name });
+      } catch {
+        // the server may already be stopped by the log test
+      }
+    }
+    await srv?.stop();
+    dirs?.cleanup();
+  });
+
+  it('has exactly one case per registered tool (both directions)', async () => {
+    assertToolCoverage(
+      await listToolNames(srv.client),
+      CASES.map((c) => c.tool),
+    );
+  });
+
+  for (const c of CASES) {
+    const reason = skipReason(c);
+    if (reason) console.log(`[SKIP] ${mode} ${c.tool}: ${reason} (a skipped case protects nothing)`);
+    (reason ? it.skip : it)(`${c.tool} (${c.kind})`, async () => {
+      await c.run(ctx);
+    });
+  }
+
+  it('adverse: invalid arguments are rejected by the schema', async () => {
+    ctx.called.add('echo');
+    await expectSchemaRejection(srv.client, 'echo', { text: 42 });
+    await expectSchemaRejection(srv.client, 'note_delete', { name: '../../etc' });
+  });
+
+  it('adverse: an unknown tool is refused', async () => {
+    const refused = await expectUnknownTool(srv.client, `${RUN_ID}_no_such_tool`);
+    expect(refused.via).toBe('protocol-error');
+  });
+
+  it('adverse: a not-found id is an error result', async () => {
+    expectToolError(await call(ctx, 'note_delete', { name: `${RUN_ID}-missing` }), 'note not found');
+  });
+
+  it('adverse: a wrong credential surfaces the downstream auth error as an error result', async () => {
+    const wrongDirs = createIsolatedDirs(`mcpit-${mode}-wrong`);
+    const wrong = await startBuiltServer(serverOptions(mode, wrongDirs, WRONG_CREDENTIALS));
+    try {
+      const r = await callToolJson(wrong.client, 'upstream_status');
+      expectToolError(r, /401/);
+    } finally {
+      await wrong.stop();
+      wrongDirs.cleanup();
+    }
+  });
+
+  if (mode === 'http') {
+    it('adverse http: 401 without the key, 413 oversized body, 415 wrong content type', async () => {
+      const url = srv.url ?? '';
+      expect((await rawHttp(url, { headers: mcpPostHeaders(), body: initializeRequestBody() })).status).toBe(401);
+      const big = await rawHttp(url, { headers: mcpPostHeaders(srv.apiKey), body: 'x'.repeat(5 * 1024 * 1024) });
+      expect(big.status).toBe(413);
+      const wrongType = { ...mcpPostHeaders(srv.apiKey), 'content-type': 'text/plain' };
+      expect((await rawHttp(url, { headers: wrongType, body: initializeRequestBody() })).status).toBe(415);
+    });
+  }
+
+  it('logs: startup + per-tool lines in the main log, level-pure side files, no leaked values', async () => {
+    await srv.stop();
+    const logs = readLogFiles(dirs.logs, SERVER_NAME);
+    expect(logs.main).toContain(STARTUP_LINE);
+    for (const tool of ctx.called) {
+      expect(logs.main).toContain(`Tool call: ${tool}`);
+      expect(logs.main).toContain(`Tool result: ${tool}`);
+    }
+    expect(logLevels(logs.exceptions).length).toBeGreaterThan(0);
+    expect(new Set(logLevels(logs.exceptions))).toEqual(new Set(['ERROR']));
+    expect(new Set(logLevels(logs.debug))).toEqual(new Set(['DEBUG']));
+    const needles = [...Object.values(CREDENTIALS), srv.apiKey ?? '', ...ctx.sent, ...ctx.received, PII_EMAIL];
+    const leaks = findLeaks([logs.main, logs.exceptions, logs.debug, srv.stdout()], needles);
+    expect(leaks).toEqual([]);
+  });
+});
+
+describe('log switches (integration)', () => {
+  it('a sink switched off writes no file', async () => {
+    const dirs = createIsolatedDirs('mcpit-switch');
+    const srv = await startBuiltServer(serverOptions('stdio', dirs, { LOG_FILE_DEBUG: 'false' }));
+    try {
+      await callToolJson(srv.client, 'echo', { text: RUN_ID });
+    } finally {
+      await srv.stop();
+    }
+    const logs = readLogFiles(dirs.logs, SERVER_NAME);
+    expect(logs.exists).toEqual({ main: true, exceptions: false, debug: false });
+    dirs.cleanup();
+  });
+});

package/examples/testing/tools.unit.test.example.ts

@@ -0,0 +1,149 @@
+/**
+ * Example UNIT suite for an MCP server built on @novorb/mcp-core.
+ *
+ * Copy to `tests/unit/tools.unit.test.ts` in your server and edit ONLY the "SERVER UNDER TEST" block.
+ * Everything runs in process: the real server factory over the SDK's in-memory transport (no child
+ * process, no network), plus direct handler calls through a recording server. Unit tests MAY mock
+ * your downstream clients; the integration example must not.
+ *
+ * mcp-core runs this exact file against its own echo fixture, so it cannot drift from the harness.
+ * Jest is used here (`@jest/globals`); the harness itself is runner-agnostic, so vitest works the same.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from '@jest/globals';
+import type { McpServer } from '@novorb/mcp-core/server';
+import {
+  assertToolCoverage,
+  callToolInMemory,
+  callToolJson,
+  connectInMemory,
+  expectSchemaRejection,
+  expectToolError,
+  expectToolSuccess,
+  expectUnknownTool,
+  type InMemoryConnection,
+  listToolNames,
+  makeRecordingServer,
+  withInMemoryClient,
+} from '@novorb/mcp-core/testing';
+
+// ---- SERVER UNDER TEST: replace with your server's factory and register function -----------------
+import { buildEchoServer, registerEchoTools } from '../../tests/fixtures/echo-tools.js';
+
+const buildServer: () => McpServer = buildEchoServer;
+const registerTools: (server: McpServer) => void = registerEchoTools;
+// ---------------------------------------------------------------------------------------------------
+
+const RUN_ID = `mcpunit-${Date.now().toString(36)}`;
+
+/** One case per registered tool: call it in memory and assert a meaningful value, not just "no error". */
+interface UnitCase {
+  tool: string;
+  args: Record<string, unknown>;
+  check(body: unknown, text: string): void;
+}
+
+const CASES: UnitCase[] = [
+  { tool: 'echo', args: { text: 'hello' }, check: (_b, text) => expect(text).toBe('echo: hello') },
+  {
+    tool: 'echo_json',
+    args: { text: 'abcd' },
+    check: (body) => expect(body).toEqual({ text: 'abcd', length: 4 }),
+  },
+  { tool: 'boom', args: {}, check: (_b, text) => expect(text).toBe('boom: failed') },
+  { tool: 'upstream_status', args: {}, check: (_b, text) => expect(text).toMatch(/authenticated|401/) },
+  { tool: 'paid_lookup', args: { query: 'q' }, check: (body) => expect(body).toEqual({ query: 'q', charged: 1 }) },
+  {
+    tool: 'note_create',
+    args: { name: `${RUN_ID}-a`, body: 'note body' },
+    check: (body) => expect(body).toEqual({ name: `${RUN_ID}-a`, created: true }),
+  },
+  {
+    tool: 'note_list',
+    args: { prefix: RUN_ID },
+    check: (body) => expect((body as { names: string[] }).names).toContain(`${RUN_ID}-a`),
+  },
+  {
+    tool: 'note_delete',
+    args: { name: `${RUN_ID}-a` },
+    check: (body) => expect(body).toEqual({ name: `${RUN_ID}-a`, deleted: true }),
+  },
+];
+
+describe('tools (unit, in memory)', () => {
+  // One connection for the ordered cases (create -> list -> delete share the server's state).
+  let conn: InMemoryConnection;
+
+  beforeAll(async () => {
+    conn = await connectInMemory(buildServer);
+  });
+
+  afterAll(async () => {
+    await conn?.close();
+  });
+
+  it('has exactly one case per registered tool (both directions)', async () => {
+    const names = await listToolNames(conn.client);
+    expect(
+      assertToolCoverage(
+        names,
+        CASES.map((c) => c.tool),
+      ).ok,
+    ).toBe(true);
+  });
+
+  it.each(CASES.map((c) => [c.tool, c] as const))('%s', async (_name, c) => {
+    const result = await callToolJson(conn.client, c.tool, c.args);
+    c.check(result.body, result.text);
+  });
+});
+
+describe('tools (unit, adverse)', () => {
+  it('a one-shot call decodes success and error results', async () => {
+    const ok = await callToolInMemory<{ text: string; length: number }>(buildServer, 'echo_json', { text: 'xy' });
+    expect(expectToolSuccess(ok)).toEqual({ text: 'xy', length: 2 });
+    const failed = await callToolInMemory(buildServer, 'boom');
+    expect(expectToolError(failed, /failed/)).toBe('boom: failed');
+  });
+
+  it('rejects arguments that break the input schema', async () => {
+    await withInMemoryClient(buildServer, async (client) => {
+      const wrongType = await expectSchemaRejection(client, 'echo', { text: 5 });
+      expect(wrongType.message).toMatch(/Input validation error/);
+      await expectSchemaRejection(client, 'echo', {});
+      await expectSchemaRejection(client, 'note_create', { name: '../escape', body: 'x' });
+    });
+  });
+
+  it('refuses an unknown tool', async () => {
+    await withInMemoryClient(buildServer, async (client) => {
+      const refused = await expectUnknownTool(client, 'no_such_tool');
+      expect(refused).toEqual({ via: 'protocol-error', message: expect.stringMatching(/not found/) });
+    });
+  });
+
+  it('answers a not-found id with an error result', async () => {
+    const missing = await callToolInMemory(buildServer, 'note_delete', { name: `${RUN_ID}-missing` });
+    expectToolError(missing, 'note not found');
+  });
+});
+
+describe('tools (unit, recording server: handlers called directly)', () => {
+  const rec = makeRecordingServer();
+  registerTools(rec.asMcpServer());
+
+  it('registers every tool with a description and an input schema', () => {
+    expect([...rec.tools.keys()].sort()).toEqual(CASES.map((c) => c.tool).sort());
+    for (const tool of rec.tools.values()) {
+      expect(typeof tool.config.description).toBe('string');
+      expect(tool.config.inputSchema).toBeDefined();
+    }
+  });
+
+  it('invokes a handler without the protocol (no schema validation on this path)', async () => {
+    const echo = rec.tools.get('echo');
+    if (!echo) throw new Error('echo was not registered');
+    const result = await echo.handler({ text: 'direct' });
+    expect(result.content).toEqual([{ type: 'text', text: 'echo: direct' }]);
+  });
+});