@mcp-layer/test-server 0.0.0 → 1.0.1

package/README.md

@@ -2,13 +2,24 @@
 
 `@mcp-layer/test-server` is a feature-complete MCP server used for integration tests and local experiments. It mirrors the tool, resource, prompt, sampling, elicitation, notification, and MCP Apps features expected by the official SDK so clients can validate end-to-end behavior against a single, real server.
 
-## Why this exists
 
 The rest of this workspace depends on a real MCP server to validate protocols. This server:
 - Runs over stdio (and optional HTTP/SSE transports)
 - Exercises all major MCP capabilities
 - Exposes stable fixtures for tests and demos
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [What it provides](#what-it-provides)
+- [Structure](#structure)
+- [Spec support matrix](#spec-support-matrix)
+- [Usage in tests](#usage-in-tests)
+- [Testing](#testing)
+- [Extending the server](#extending-the-server)
+- [Runtime Error Reference](#runtime-error-reference)
+
 ## Installation
 
 ```bash
@@ -133,6 +144,124 @@ When adding capabilities:
 2) Add or update a test in `test/index.test.js`.
 3) Document it in this README.
 
+## Runtime Error Reference
+
+This section is written for high-pressure debugging moments. These errors are intentionally emitted by the test server to exercise client and REST error-handling paths.
+
+<a id="error-56fd38"></a>
+### Protocol failure
+
+Thrown from: `registerCrash.crashTool`
+
+This error is intentionally thrown by the `crash` tool. It simulates an MCP tool that fails at protocol/runtime level so downstream layers can validate error mapping and HTTP problem responses.
+
+Step-by-step resolution:
+1. Confirm you actually invoked the `crash` tool (`tools crash exec`) and not a production tool.
+2. If this appeared unexpectedly, verify test fixture/tool name selection.
+3. In integration tests, assert the expected failure shape (`isError`/problem details) instead of treating it as an infra bug.
+4. Use a non-crashing test tool when validating success paths.
+
+<details>
+<summary>Fix Example: separate crash-path tests from success-path tests</summary>
+
+```js
+await t.test('error mapping', async function errorCase() {
+  await assert.rejects(client.callTool({ name: 'crash', arguments: {} }));
+});
+
+await t.test('success path', async function successCase() {
+  const result = await client.callTool({ name: 'slow', arguments: {} });
+  assert.equal(result.isError, false);
+});
+```
+
+</details>
+
+<a id="error-990eaa"></a>
+### first failure
+
+Thrown from: `registerFlap.flapTool`
+
+This error is intentionally thrown on the first invocation of the `flap` tool. The second and later calls succeed, which is useful for circuit-breaker recovery tests.
+
+Step-by-step resolution:
+1. Confirm this is the first call in the process lifetime; first-call failure is expected behavior.
+2. If you need deterministic success, warm up the tool once before the measured assertion.
+3. For resilience tests, assert both phases: failure first, success next.
+4. Reset server state between test cases when first-call semantics matter.
+
+<details>
+<summary>Fix Example: account for flap tool's first-call failure contract</summary>
+
+```js
+await assert.rejects(client.callTool({ name: 'flap', arguments: {} }));
+const ok = await client.callTool({ name: 'flap', arguments: {} });
+assert.equal(ok.isError, false);
+```
+
+</details>
+
+<a id="error-d1ff05"></a>
+### progress tool aborted
+
+Thrown from: `registerProgress.progressTool`
+
+This error is raised when the progress tool sees `extra.signal.aborted` before or during loop processing. It represents explicit cancellation of long-running MCP work.
+
+Step-by-step resolution:
+1. Check client/request timeout and cancellation behavior for this call.
+2. Confirm you did not pass an already-aborted signal into the tool execution context.
+3. Increase timeout or delay cancellation if you expect completion.
+4. For cancellation tests, assert abort behavior explicitly instead of treating this as unexpected.
+
+<details>
+<summary>Fix Example: avoid premature cancellation for progress runs</summary>
+
+```js
+const controller = new AbortController();
+const result = await client.callTool({
+  name: 'progress',
+  arguments: { steps: 3, delayMs: 20 },
+  signal: controller.signal
+});
+assert.equal(result.isError, false);
+```
+
+</details>
+
+<a id="error-c9d511"></a>
+### progress tool aborted
+
+Thrown from: `registerProgress.progressTool.sleep`
+
+This error is raised when cancellation occurs while `progress` is sleeping between step notifications. It is the mid-flight cancellation branch of the same tool.
+
+Step-by-step resolution:
+1. Correlate abort timing with `delayMs` and `steps` in the progress request.
+2. If completion is required, avoid cancelling during the sleep interval.
+3. If cancellation is expected, assert this specific branch so tests remain intentional.
+4. Tune `delayMs` in tests to make cancel timing deterministic.
+
+<details>
+<summary>Fix Example: deterministic cancellation test for sleep-abort path</summary>
+
+```js
+const controller = new AbortController();
+const pending = client.callTool({
+  name: 'progress',
+  arguments: { steps: 5, delayMs: 100 },
+  signal: controller.signal
+});
+
+setTimeout(function abortLater() {
+  controller.abort();
+}, 30);
+
+await assert.rejects(pending);
+```
+
+</details>
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@mcp-layer/test-server",
-  "version": "0.0.0",
+  "version": "1.0.1",
   "description": "Feature-rich MCP server for integration testing and local development.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/3rd-Eden/mcp-layer"
+  },
   "type": "module",
   "keywords": [
     "mcp",
@@ -10,9 +14,6 @@
     "integration",
     "model-context-protocol"
   ],
-  "scripts": {
-    "test": "node --test --experimental-test-coverage ./test/**/*.js"
-  },
   "bin": {
     "mcp-test-server": "src/bin.js",
     "mcp-test-server-http": "src/http.js"
@@ -35,6 +36,10 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",
     "express": "^5.0.1",
-    "zod": "^3.25.76"
+    "zod": "^3.25.76",
+    "@mcp-layer/error": "0.2.0"
+  },
+  "scripts": {
+    "test": "node --test --experimental-test-coverage ./test/**/*.js"
   }
-}
+}

package/src/data/manual.js

@@ -12,6 +12,10 @@ export const manual = [
   '- progress: emits notifications/progress updates tied to request tokens.',
   '- note-update: mutates note:// resources and emits notifications/resources/updated.',
   '- rebalance: toggles tool registrations to showcase notification debouncing.',
+  '- fail-gracefully: returns isError true for REST error handling tests.',
+  '- crash: throws a protocol error to exercise error mapping.',
+  '- slow: delays responses to trigger circuit breaker timeouts.',
+  '- flap: fails once then succeeds to validate breaker recovery.',
   '',
   '## Resources',
   '- resource://manual exposes this manual.',

package/src/index.js

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { debouncedNotifications, info, instructions } from './config.js';
+import { debouncedNotifications, info as defaultInfo, instructions } from './config.js';
 import { manual } from './data/manual.js';
 import { notes } from './data/notes.js';
 import { references } from './data/references.js';
@@ -12,9 +12,14 @@ import { registerTools } from './tools/index.js';
 
 /**
  * Build an MCP server instance pre-configured with tools, resources, and prompts.
+ *
+ * targeted metadata overrides (name/version) without custom servers.
+ *
+ * @param {{ info?: { name?: string, version?: string } }} [opts] - Optional metadata overrides.
  * @returns {McpServer}
  */
-export function build() {
+export function build(opts = {}) {
+  const info = opts.info ? { ...defaultInfo, ...opts.info } : defaultInfo;
   const server = new McpServer(info, {
     instructions,
     debouncedNotificationMethods: debouncedNotifications,
@@ -40,11 +45,14 @@ export function build() {
 
 /**
  * Start the test server using stdio transport for integration scenarios.
- * @param {{ server?: McpServer, transport?: StdioServerTransport }} [opts]
+ *
+ * exercising the standard test-server surface.
+ *
+ * @param {{ server?: McpServer, transport?: StdioServerTransport, info?: { name?: string, version?: string } }} [opts] - Optional overrides for the server instance, transport, or metadata.
  * @returns {Promise<{ server: McpServer, transport: StdioServerTransport }>}
  */
 export async function start(opts = {}) {
-  const server = opts.server ?? build();
+  const server = opts.server ?? build(opts);
   const transport = opts.transport ?? new StdioServerTransport();
 
   // Use stdio transport so callers can spawn this server as a subprocess during tests.

package/src/prompts/index.js

@@ -2,7 +2,7 @@ import { registerWelcomePrompt } from './welcome.js';
 
 /**
  * Register all prompts exposed by the server.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register prompts on.
  */
 export function registerPrompts(server) {
   registerWelcomePrompt(server);

package/src/prompts/welcome.js

@@ -6,7 +6,7 @@ const tones = ['casual', 'formal', 'cheerful'];
 
 /**
  * Register the welcome prompt with completable arguments.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the prompt on.
  */
 export function registerWelcomePrompt(server) {
   const argsSchema = {
@@ -27,7 +27,7 @@ export function registerWelcomePrompt(server) {
 
   /**
    * Produce a greeting message tailored to the provided tone.
-   * @param {{ name: string, tone: 'casual' | 'formal' | 'cheerful' }} args
+   * @param {{ name: string, tone: 'casual' | 'formal' | 'cheerful' }} args - Prompt arguments provided by the caller.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').GetPromptResult>}
    */
   async function welcomePrompt(args) {

package/src/resources/index.js

@@ -1,14 +1,16 @@
 import { registerManualResource } from './manual.js';
 import { registerNotesResource } from './notes.js';
+import { registerTemplateResource } from './templates.js';
 import { registerUi } from './ui.js';
 
 /**
  * Register all resources exposed by the server.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ manual: string, notes: Map<string, Record<string, string>> }} context
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register resources on.
+ * @param {{ manual: string, notes: Map<string, Record<string, string>> }} context - Shared data backing the resources.
  */
 export function registerResources(server, context) {
   registerManualResource(server, context);
   registerNotesResource(server, context);
+  registerTemplateResource(server);
   registerUi(server);
 }

package/src/resources/manual.js

@@ -1,12 +1,12 @@
 /**
  * Register the markdown manual resource.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ manual: string }} context
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the resource on.
+ * @param {{ manual: string }} context - Manual content backing the resource.
  */
 export function registerManualResource(server, context) {
   /**
    * Return a markdown manual describing server features.
-   * @param {URL} uri
+   * @param {URL} uri - Resource URI for the request.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').ReadResourceResult>}
    */
   async function manualRead(uri) {

package/src/resources/notes.js

@@ -2,8 +2,8 @@ import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 /**
  * Register the dynamic notes resource template with completions.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ notes: Map<string, Record<string, string>> }} context
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the resource on.
+ * @param {{ notes: Map<string, Record<string, string>> }} context - Notes data keyed by topic/detail.
  */
 export function registerNotesResource(server, context) {
   const template = new ResourceTemplate('note://{topic}/{detail}', {
@@ -39,8 +39,8 @@ export function registerNotesResource(server, context) {
 
   /**
    * Derive note topic and detail for a URI or template variable set.
-   * @param {URL} uri
-   * @param {{ topic?: string, detail?: string }} [variables]
+   * @param {URL} uri - Requested resource URI.
+   * @param {{ topic?: string, detail?: string }} [variables] - Template variables resolved from the request.
    * @returns {{ topic: string, detail: string }}
    */
   function noteParts(uri, variables = {}) {
@@ -52,8 +52,8 @@ export function registerNotesResource(server, context) {
 
   /**
    * Read a dynamic note resource for the requested topic/detail pair.
-   * @param {URL} uri
-   * @param {{ topic?: string, detail?: string }} [variables]
+   * @param {URL} uri - Requested resource URI.
+   * @param {{ topic?: string, detail?: string }} [variables] - Template variables resolved from the request.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').ReadResourceResult>}
    */
   async function noteRead(uri, variables = {}) {

package/src/resources/templates.js

@@ -0,0 +1,42 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Register a templated resource that expands a name into a note URI.
+ *
+ * surface to exercise dynamic routes.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register resources on.
+ */
+export function registerTemplateResource(server) {
+  const template = new ResourceTemplate('template://note/{name}', {});
+
+  /**
+   * Read a templated note resource.
+   * @param {URL} uri - Expanded resource URI.
+   * @param {{ name?: string }} variables - Template variables.
+   * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').ReadResourceResult>}
+   */
+  async function templateRead(uri, variables) {
+    const name = variables && typeof variables.name === 'string' ? variables.name : 'unknown';
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: `Template note for ${name}.`,
+          mimeType: 'text/plain'
+        }
+      ]
+    };
+  }
+
+  server.registerResource(
+    'note-template',
+    template,
+    {
+      title: 'Template Note',
+      description: 'Dynamic note template resource.',
+      mimeType: 'text/plain'
+    },
+    templateRead
+  );
+}

package/src/resources/ui.js

@@ -19,12 +19,12 @@ const uri = 'ui://dashboard/app.html';
 
 /**
  * Register the MCP App UI resource.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the resource on.
  */
 export function registerUi(server) {
   /**
    * Return HTML for the dashboard UI.
-   * @param {URL} url
+   * @param {URL} url - Requested resource URL.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').ReadResourceResult>}
    */
   async function ui(url) {

package/src/shared/capabilities.js

@@ -1,12 +1,12 @@
 /**
  * Build a capability checker bound to the current server connection.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server instance to read client capabilities from.
  * @returns {(capability: 'sampling' | 'elicitation' | 'roots') => boolean}
  */
 export function createCapabilityChecker(server) {
   /**
    * Determine whether the connected client declared the requested capability.
-   * @param {'sampling' | 'elicitation' | 'roots'} capability
+   * @param {'sampling' | 'elicitation' | 'roots'} capability - Capability name to check.
    * @returns {boolean}
    */
   function hasCapability(capability) {

package/src/subscriptions/resources.js

@@ -2,8 +2,8 @@ import { ErrorCode, McpError, SubscribeRequestSchema, UnsubscribeRequestSchema }
 
 /**
  * Configure basic resource subscriptions on the underlying server transport.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ isSubscribable: (uri: string) => boolean }} options
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register subscription handlers on.
+ * @param {{ isSubscribable: (uri: string) => boolean }} options - Subscription filters for allowed URIs.
  * @returns {{ notifyResourceUpdated: (uri: string) => Promise<void> }}
  */
 export function registerResourceSubscriptions(server, options) {
@@ -37,9 +37,7 @@ export function registerResourceSubscriptions(server, options) {
     const set = subscribers.get(sessionId);
     if (set) {
       set.delete(request.params.uri);
-      if (set.size === 0) {
-        subscribers.delete(sessionId);
-      }
+      if (set.size === 0) subscribers.delete(sessionId);
     }
     return {};
   });
@@ -50,7 +48,7 @@ export function registerResourceSubscriptions(server, options) {
 
   /**
    * Notify subscribed clients that a resource has been updated.
-   * @param {string} uri
+   * @param {string} uri - Resource URI that changed.
    * @returns {Promise<void>}
    */
   async function notifyResourceUpdated(uri) {

package/src/tools/add.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 /**
  * Register the add tool returning structured totals.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
  * @returns {ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>}
  */
 export function registerAdd(server) {
@@ -13,7 +13,7 @@ export function registerAdd(server) {
 
   /**
    * Sum two numbers to demonstrate structured responses.
-   * @param {{ first: number, second: number }} args
+   * @param {{ first: number, second: number }} args - Numeric operands provided by the caller.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function addTool(args) {

package/src/tools/annotated.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 /**
  * Register a tool that exercises annotations and _meta without output schema.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
  * @returns {ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>}
  */
 export function registerAnnotated(server) {
@@ -12,7 +12,7 @@ export function registerAnnotated(server) {
 
   /**
    * Return a plain text response for annotation coverage.
-   * @param {{ label: string }} args
+   * @param {{ label: string }} args - Label input used in the response text.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function annotatedTool(args) {

package/src/tools/batch.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 /**
  * Register a tool that accepts array/object inputs.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
  * @returns {ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>}
  */
 export function registerBatch(server) {
@@ -13,7 +13,7 @@ export function registerBatch(server) {
 
   /**
    * Summarize array/object inputs.
-   * @param {{ items: string[], meta: { tag: string } }} args
+   * @param {{ items: string[], meta: { tag: string } }} args - Batch input values.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function batchTool(args) {

package/src/tools/booking.js

@@ -2,8 +2,8 @@ import { z } from 'zod';
 
 /**
  * Register the booking tool that triggers elicitation workflows.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ hasCapability: (capability: 'elicitation') => boolean }} capabilities
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
+ * @param {{ hasCapability: (capability: 'elicitation') => boolean }} capabilities - Capability checker for elicitation support.
  */
 export function registerBooking(server, capabilities) {
   const inputSchema = {
@@ -14,7 +14,7 @@ export function registerBooking(server, capabilities) {
 
   /**
    * Demonstrate elicitation by asking for alternate booking dates.
-   * @param {{ restaurant: string, date: string, guests: number }} args
+   * @param {{ restaurant: string, date: string, guests: number }} args - Booking request inputs.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function bookingTool(args) {

package/src/tools/dashboard.js

@@ -6,7 +6,7 @@ const permissions = ['clipboard-read'];
 
 /**
  * Register a tool that declares an MCP App UI resource.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
  * @returns {ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>}
  */
 export function registerDashboard(server) {
@@ -16,7 +16,7 @@ export function registerDashboard(server) {
 
   /**
    * Return a simple payload while the host renders the UI resource.
-   * @param {{ name: string }} args
+   * @param {{ name: string }} args - Request input used for the response payload.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function dashboardTool(args) {

package/src/tools/echo.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 /**
  * Register the echo tool that optionally uppercases responses.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
  * @returns {ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>}
  */
 export function registerEcho(server) {
@@ -13,7 +13,7 @@ export function registerEcho(server) {
 
   /**
    * Repeat supplied text and optionally uppercase the response.
-   * @param {{ text: string, loud: boolean }} args
+   * @param {{ text: string, loud: boolean }} args - Request input used to build the response.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function echoTool(args) {

package/src/tools/files.js

@@ -2,8 +2,8 @@ import { z } from 'zod';
 
 /**
  * Register the files tool that emits ResourceLinks referencing shared assets.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ references: Array<{ uri: string, name: string, description: string, mimeType: string }> }} context
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
+ * @param {{ references: Array<{ uri: string, name: string, description: string, mimeType: string }> }} context - Reference data backing the responses.
  */
 export function registerFiles(server, context) {
   const inputSchema = {
@@ -13,7 +13,7 @@ export function registerFiles(server, context) {
 
   /**
    * Emit ResourceLinks referencing manual and note resources.
-   * @param {{ filter: string, limit: number }} args
+   * @param {{ filter: string, limit: number }} args - Filtering and limit inputs for the listing.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function filesTool(args) {

package/src/tools/index.js

@@ -12,12 +12,14 @@ import { registerPresent } from './present.js';
 import { registerRebalance } from './rebalance.js';
 import { registerRoots } from './roots.js';
 import { registerSummaries } from './summaries.js';
+import { registerCrash, registerFailGracefully, registerFlap, registerSlow } from './testing.js';
 
 /**
  * Register all server tools.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ references: Array<{ uri: string, name: string, description: string, mimeType: string }> }} context
- * @param {{ hasCapability: (capability: 'sampling' | 'elicitation' | 'roots') => boolean }} capabilities
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register tools on.
+ * @param {{ references: Array<{ uri: string, name: string, description: string, mimeType: string }> }} context - Shared reference data for tools.
+ * @param {{ hasCapability: (capability: 'sampling' | 'elicitation' | 'roots') => boolean }} capabilities - Capability checker for tool behavior.
+ * @param {{ notifyResourceUpdated: (uri: string) => Promise<void> }} notifier - Notifier for resource update events.
  */
 export function registerTools(server, context, capabilities, notifier) {
   const echoHandle = registerEcho(server);
@@ -34,4 +36,8 @@ export function registerTools(server, context, capabilities, notifier) {
   registerPresent(server);
   registerProgress(server);
   registerRebalance(server, { echo: echoHandle, add: addHandle });
+  registerFailGracefully(server);
+  registerCrash(server);
+  registerSlow(server);
+  registerFlap(server);
 }

package/src/tools/logs.js

@@ -5,7 +5,7 @@ const levels = LoggingLevelSchema.options;
 
 /**
  * Register the logs tool that emits notifications/message entries.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
  */
 export function registerLogs(server) {
   const inputSchema = {
@@ -16,7 +16,7 @@ export function registerLogs(server) {
 
   /**
    * Emit a logging notification honoring the client's configured level filter.
-   * @param {{ level: typeof levels[number], message: string, logger: string }} args
+   * @param {{ level: typeof levels[number], message: string, logger: string }} args - Logging payload inputs.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function logsTool(args) {

package/src/tools/note-update.js

@@ -2,9 +2,9 @@ import { z } from 'zod';
 
 /**
  * Register a tool that mutates note resources and emits update notifications.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ notes: Map<string, Record<string, string>> }} context
- * @param {{ notifyResourceUpdated: (uri: string) => Promise<void> }} notifier
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
+ * @param {{ notes: Map<string, Record<string, string>> }} context - Notes data store to mutate.
+ * @param {{ notifyResourceUpdated: (uri: string) => Promise<void> }} notifier - Resource update notifier.
  */
 export function registerNoteUpdate(server, context, notifier) {
   const inputSchema = {
@@ -15,7 +15,7 @@ export function registerNoteUpdate(server, context, notifier) {
 
   /**
    * Update the referenced note and broadcast notifications/resources/updated.
-   * @param {{ topic: string, detail: string, text: string }} args
+   * @param {{ topic: string, detail: string, text: string }} args - Update inputs for the note entry.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function updateNoteTool(args) {

package/src/tools/present.js

@@ -5,7 +5,7 @@ const WAV_BASE64 = 'UklGRiQAAABXQVZFZm10IBAAAAABAAEAESsAACJWAAACABAAZGF0YQAAAAA=
 
 /**
  * Register the present tool to emit mixed content types.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
  * @returns {ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>}
  */
 export function registerPresent(server) {
@@ -15,7 +15,7 @@ export function registerPresent(server) {
 
   /**
    * Emit markdown, image, audio, and resource link content items.
-   * @param {{ title: string }} args
+   * @param {{ title: string }} args - Presentation title supplied by the caller.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function presentTool(args) {

package/src/tools/progress.js

@@ -1,8 +1,9 @@
 import { z } from 'zod';
+import { LayerError } from '@mcp-layer/error';
 
 /**
  * Register the progress tool that emits notifications/progress updates.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
  */
 export function registerProgress(server) {
   const inputSchema = {
@@ -12,8 +13,8 @@ export function registerProgress(server) {
 
   /**
    * Wait between steps and emit progress notifications when requested.
-   * @param {{ steps: number, delayMs: number }} args
-   * @param {{ _meta?: { progressToken?: string | number }, signal: AbortSignal, sendNotification: (notification: any) => Promise<void> }} extra
+   * @param {{ steps: number, delayMs: number }} args - Progress configuration inputs.
+   * @param {{ _meta?: { progressToken?: string | number }, signal: AbortSignal, sendNotification: (notification: any) => Promise<void> }} extra - Tool execution context and notification helper.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function progressTool(args, extra) {
@@ -30,7 +31,11 @@ export function registerProgress(server) {
           'abort',
           () => {
             clearTimeout(timer);
-            reject(new Error('progress tool aborted'));
+            reject(new LayerError({
+              name: 'test-server',
+              method: 'registerProgress.progressTool.sleep',
+              message: 'progress tool aborted',
+            }));
           },
           { once: true }
         );
@@ -39,7 +44,11 @@ export function registerProgress(server) {
 
     for (let index = 1; index <= args.steps; index += 1) {
       if (extra.signal.aborted) {
-        throw new Error('progress tool aborted');
+        throw new LayerError({
+          name: 'test-server',
+          method: 'registerProgress.progressTool',
+          message: 'progress tool aborted',
+        });
       }
       await sleep();
       if (token) {

package/src/tools/rebalance.js

@@ -2,8 +2,8 @@ import { z } from 'zod';
 
 /**
  * Register the rebalance tool that toggles core tool registrations to exercise debounced notifications.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ echo: ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>, add: ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']> }} handles
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
+ * @param {{ echo: ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>, add: ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']> }} handles - Tool handles to enable/disable.
  */
 export function registerRebalance(server, handles) {
   const inputSchema = {
@@ -12,7 +12,7 @@ export function registerRebalance(server, handles) {
 
   /**
    * Toggle core tools repeatedly to demonstrate notification debouncing.
-   * @param {{ cycles: number }} args
+   * @param {{ cycles: number }} args - Number of enable/disable cycles to run.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function rebalanceTool(args) {

package/src/tools/roots.js

@@ -2,8 +2,8 @@ import { z } from 'zod';
 
 /**
  * Register the roots tool that calls roots/list on capable clients.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ hasCapability: (capability: 'roots') => boolean }} capabilities
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
+ * @param {{ hasCapability: (capability: 'roots') => boolean }} capabilities - Capability checker for roots support.
  */
 export function registerRoots(server, capabilities) {
   const inputSchema = {
@@ -12,7 +12,7 @@ export function registerRoots(server, capabilities) {
 
   /**
    * Request roots/list from the client to expose workspace locations.
-   * @param {{ includeMeta: boolean }} args
+   * @param {{ includeMeta: boolean }} args - Whether to include client root metadata.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function rootsTool(args) {

package/src/tools/summaries.js

@@ -2,8 +2,8 @@ import { z } from 'zod';
 
 /**
  * Register the summaries tool that delegates to sampling/createMessage.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {{ hasCapability: (capability: 'sampling') => boolean }} capabilities
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
+ * @param {{ hasCapability: (capability: 'sampling') => boolean }} capabilities - Capability checker for sampling support.
  */
 export function registerSummaries(server, capabilities) {
   const inputSchema = {
@@ -13,7 +13,7 @@ export function registerSummaries(server, capabilities) {
 
   /**
    * Request a summary via sampling/createMessage when supported.
-   * @param {{ text: string, maxTokens: number }} args
+   * @param {{ text: string, maxTokens: number }} args - Summary request inputs.
    * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
    */
   async function summaryTool(args) {

package/src/tools/testing.js

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { LayerError } from '@mcp-layer/error';
+
+/**
+ * Register a tool that always returns isError true.
+ *
+ * relying on custom servers.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
+ * @returns {ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>}
+ */
+export function registerFailGracefully(server) {
+  const inputSchema = { reason: z.string().optional() };
+
+  /**
+   * Return a tool error payload.
+   * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+   */
+  async function failGracefullyTool() {
+    return {
+      content: [{ type: 'text', text: 'Something went wrong' }],
+      isError: true
+    };
+  }
+
+  return server.registerTool(
+    'fail-gracefully',
+    {
+      title: 'Fail Gracefully',
+      description: 'Always returns isError true for REST error handling tests.',
+      inputSchema
+    },
+    failGracefullyTool
+  );
+}
+
+/**
+ * Register a tool that throws.
+ *
+ * exercises JSON-RPC error mapping.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
+ * @returns {ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>}
+ */
+export function registerCrash(server) {
+  const inputSchema = { reason: z.string().optional() };
+
+  /**
+   * Throw a protocol-level error.
+   * @throws {LayerError}
+   */
+  async function crashTool() {
+    throw new LayerError({
+      name: 'test-server',
+      method: 'registerCrash.crashTool',
+      message: 'Protocol failure',
+    });
+  }
+
+  return server.registerTool(
+    'crash',
+    {
+      title: 'Crash',
+      description: 'Throws an error to simulate protocol failures.',
+      inputSchema
+    },
+    crashTool
+  );
+}
+
+/**
+ * Register a tool that intentionally exceeds short timeouts.
+ *
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
+ * @returns {ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>}
+ */
+export function registerSlow(server) {
+  const inputSchema = { reason: z.string().optional() };
+
+  /**
+   * Resolve after a fixed delay.
+   * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+   */
+  async function slowTool() {
+    return new Promise(function wait(resolve) {
+      const timer = setTimeout(function done() {
+        resolve({ content: [{ type: 'text', text: 'late' }] });
+      }, 50);
+      timer.unref();
+    });
+  }
+
+  return server.registerTool(
+    'slow',
+    {
+      title: 'Slow',
+      description: 'Delays to trigger timeout behavior in clients.',
+      inputSchema
+    },
+    slowTool
+  );
+}
+
+/**
+ * Register a tool that fails once then succeeds.
+ *
+ * transition from failure to success.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server - MCP server to register the tool on.
+ * @returns {ReturnType<import('@modelcontextprotocol/sdk/server/mcp.js').McpServer['registerTool']>}
+ */
+export function registerFlap(server) {
+  const inputSchema = { reason: z.string().optional() };
+  let count = 0;
+
+  /**
+   * Throw on the first call, then return success.
+   * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').CallToolResult>}
+   */
+  async function flapTool() {
+    count += 1;
+    if (count === 1) {
+      throw new LayerError({
+        name: 'test-server',
+        method: 'registerFlap.flapTool',
+        message: 'first failure',
+      });
+    }
+    return { content: [{ type: 'text', text: 'ok' }] };
+  }
+
+  return server.registerTool(
+    'flap',
+    {
+      title: 'Flap',
+      description: 'Fails once, then succeeds to exercise breaker recovery.',
+      inputSchema
+    },
+    flapTool
+  );
+}

package/src/transport/http.js

@@ -5,7 +5,7 @@ import { build } from '../index.js';
 
 /**
  * Start an HTTP server that exposes Streamable HTTP and SSE transports.
- * @param {{ port?: number }} [opts]
+ * @param {{ port?: number }} [opts] - Optional port override for the HTTP server.
  * @returns {Promise<{ close: () => Promise<void> }>}
  */
 export async function startHttpServer(opts = {}) {