@mcp-layer/test-server 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arnout Kazemier
+
+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,138 @@
+# @mcp-layer/test-server
+
+`@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
+
+## Installation
+
+```bash
+# npm
+npm install @mcp-layer/test-server
+# pnpm
+pnpm add @mcp-layer/test-server
+# yarn
+yarn add @mcp-layer/test-server
+```
+
+Requirements: Node.js 20+ (or Deno/Bun with Node compatibility).
+
+## Quick start
+
+### Stdio transport
+
+```bash
+npx mcp-test-server
+```
+
+### Streamable HTTP + SSE transport
+
+```bash
+npx mcp-test-server-http --port 3333
+```
+
+This exposes:
+- Streamable HTTP on `/mcp`
+- SSE compatibility on `/sse` and `/sse/messages`
+
+## What it provides
+
+### Tools
+
+- `echo` -- returns text, structured output
+- `add` -- arithmetic + structured output
+- `annotated` -- tool annotations + `_meta` coverage
+- `dashboard` -- MCP Apps UI metadata via `_meta.ui`
+- `files` -- emits `resource_link` payloads
+- `present` -- mixed content types (text/markdown/image/audio/resource/resource_link)
+- `summaries` -- sampling support
+- `booking` -- elicitation support
+- `roots` -- roots capability
+- `note-update` -- mutable resources
+- `logs` -- logging notifications
+- `progress` -- progress notifications
+- `rebalance` -- debounced list updates
+
+### Resources
+
+- `resource://manual` -- markdown manual
+- `note://{topic}/{detail}` -- template-backed resources with completions
+- `ui://dashboard/app.html` -- MCP Apps HTML UI
+
+### Prompts
+
+- `welcome` -- prompt arguments with completions
+
+### MCP Apps
+
+- `dashboard` tool advertises `_meta.ui.resourceUri`
+- `ui://dashboard/app.html` serves HTML and `_meta.ui` settings (`csp`, `permissions`)
+
+## Structure
+
+- `src/tools/*` -- tool implementations
+- `src/resources/*` -- resource + template handlers
+- `src/prompts/*` -- prompt definitions
+- `src/data/*` -- shared manual text and fixtures
+- `src/shared/*` -- utilities and capability checks
+
+## Spec support matrix
+
+| Feature | Status | Notes |
+| --- | --- | --- |
+| Tools (structured outputs, resource links) | yes | `echo`, `add`, `files`, `summaries`, `booking`, `roots`, `logs`, `progress`, `rebalance`. |
+| Tool annotations + metadata | yes | `annotated` exposes `annotations` + `_meta`. |
+| MCP Apps (UI resources) | yes | `dashboard` tool exposes `_meta.ui.resourceUri`, `ui://dashboard/app.html` serves HTML. |
+| Mixed content outputs | yes | `present` emits text/markdown/image/audio/resource/resource_link. |
+| Resources & dynamic templates | yes | `resource://manual`, `note://{topic}/{detail}` with completions. |
+| Prompts & completion API | yes | `welcome` prompt + `completion/complete`. |
+| Sampling (`sampling/createMessage`) | yes | `summaries` tool proxies sampling and validates responses. |
+| Elicitation (`elicitation/create`) | yes | `booking` tool requests alternate booking info. |
+| Roots (`roots/list`) | yes | `roots` tool lists file URIs from capable clients. |
+| Resource subscriptions/updates | yes | `resources/subscribe` + `note-update` tool emit `notifications/resources/updated`. |
+| Logging notifications | yes | `logs` tool emits `notifications/message`. |
+| Progress notifications | yes | `progress` tool streams `notifications/progress`. |
+| Debounced list notifications | yes | `rebalance` tool coalesces updates. |
+| Alternate transports (Streamable HTTP / SSE) | yes | `mcp-test-server-http` bootstraps both. |
+| Auth/OAuth proxying | no | Out of scope for this fixture. |
+
+## Usage in tests
+
+Use it as the real server target for integration tests:
+
+```js
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const transport = new StdioClientTransport({
+  command: process.execPath,
+  args: [require.resolve('@mcp-layer/test-server/src/bin.js')]
+});
+
+const client = new Client({ name: 'demo', version: '0.0.0' });
+await client.connect(transport);
+```
+
+## Testing
+
+```bash
+pnpm test --filter @mcp-layer/test-server
+```
+
+The suite boots the real binary, exercises all tools/resources/prompts, verifies notifications, and asserts MCP Apps metadata so this fixture remains trustworthy.
+
+## Extending the server
+
+When adding capabilities:
+1) Implement the feature in `src/*`.
+2) Add or update a test in `test/index.test.js`.
+3) Document it in this README.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mcp-layer/test-server",
+  "version": "0.0.0",
+  "description": "Feature-rich MCP server for integration testing and local development.",
+  "type": "module",
+  "keywords": [
+    "mcp",
+    "server",
+    "testing",
+    "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"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2",
+    "express": "^5.0.1",
+    "zod": "^3.25.76"
+  }
+}

package/src/bin.js

@@ -0,0 +1,14 @@
+import { start } from './index.js';
+
+/**
+ * Launch the test MCP server over stdio.
+ * @returns {Promise<void>}
+ */
+async function main() {
+  await start();
+}
+
+main().catch(function handle(error) {
+  console.error(error);
+  process.exitCode = 1;
+});

package/src/config.js

@@ -0,0 +1,12 @@
+export const info = { name: 'mcp-test-server', version: '0.1.0' };
+
+export const instructions = [
+  'MCP test server exercises tools, resources, prompts, completions, sampling, elicitation, roots, and debounced notifications',
+  'so every integration path described in the TypeScript SDK README is available for automated verification.'
+].join(' ');
+
+export const debouncedNotifications = [
+  'notifications/tools/list_changed',
+  'notifications/resources/list_changed',
+  'notifications/prompts/list_changed'
+];

package/src/data/manual.js

@@ -0,0 +1,22 @@
+export const manual = [
+  '# MCP Test Server Manual',
+  '',
+  '## Tools',
+  '- echo: text echo with loud mode for uppercase coverage.',
+  '- add: deterministic math returning structured totals.',
+  '- files: emits ResourceLinks for manual and note resources.',
+  '- summaries: requests sampling/createMessage from the client.',
+  '- booking: demonstrates elicitation/create workflows.',
+  '- roots: requests roots/list from capable clients.',
+  '- logs: streams notifications/message entries at configurable levels.',
+  '- 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.',
+  '',
+  '## Resources',
+  '- resource://manual exposes this manual.',
+  '- note://{topic}/{detail} template lists summaries and usage guidance for every feature.',
+  '',
+  '## Prompts',
+  '- welcome prompt provides name and tone completions for guided prompting.'
+].join('\n');

package/src/data/notes.js

@@ -0,0 +1,72 @@
+export const notes = new Map([
+  [
+    'echo',
+    {
+      summary: 'Echo repeats provided text and can force uppercase responses with the loud flag.',
+      usage: 'Call echo with loud true to validate structured responses stay in sync with text output.'
+    }
+  ],
+  [
+    'add',
+    {
+      summary: 'Add combines two numbers and reports totals inside structuredContent for schema validation demos.',
+      usage: 'Use add to confirm numeric handling prior to driving more complex tools.'
+    }
+  ],
+  [
+    'files',
+    {
+      summary: 'Files returns resource_link entries so clients can lazily fetch manual and note content.',
+      usage: 'Provide a filter string to narrow which ResourceLinks appear in the response.'
+    }
+  ],
+  [
+    'summaries',
+    {
+      summary: 'Summaries requests sampling/createMessage and relays the returned completion back to the caller.',
+      usage: 'Declare sampling capability before connecting so the server can proxy summarization requests.'
+    }
+  ],
+  [
+    'booking',
+    {
+      summary: 'Booking elicits alternate dates when the requested reservation is full.',
+      usage: 'Clients respond to elicitation/create by echoing confirmAlternate and alternateDate fields.'
+    }
+  ],
+  [
+    'roots',
+    {
+      summary: 'Roots fetches file:// locations from the client by issuing roots/list.',
+      usage: 'Declare roots capability and provide a handler that returns accessible filesystem URIs.'
+    }
+  ],
+  [
+    'logs',
+    {
+      summary: 'Logs forwards structured payloads via notifications/message respecting client log levels.',
+      usage: 'Set logging/setLevel before invoking logs to ensure notifications arrive.'
+    }
+  ],
+  [
+    'progress',
+    {
+      summary: 'Progress sends notifications/progress tied to supplied request tokens during long tasks.',
+      usage: 'Call the progress tool with a _meta.progressToken to observe incremental updates.'
+    }
+  ],
+  [
+    'note-update',
+    {
+      summary: 'Note-update mutates note resources and triggers notifications/resources/updated.',
+      usage: 'Subscribe to note:// URIs before calling this tool to receive updates.'
+    }
+  ],
+  [
+    'rebalance',
+    {
+      summary: 'Rebalance flips tool registrations repeatedly to prove notification debouncing works.',
+      usage: 'Expect only one notifications/tools/list_changed message even if multiple toggles run.'
+    }
+  ]
+]);

package/src/data/references.js

@@ -0,0 +1,20 @@
+export const references = [
+  {
+    uri: 'resource://manual',
+    name: 'manual',
+    description: 'Server manual covering every feature.',
+    mimeType: 'text/markdown'
+  },
+  {
+    uri: 'note://echo/summary',
+    name: 'echo-note',
+    description: 'Echo behavior summary.',
+    mimeType: 'text/plain'
+  },
+  {
+    uri: 'note://summaries/usage',
+    name: 'sampling-note',
+    description: 'Instructions for sampling-aware clients.',
+    mimeType: 'text/plain'
+  }
+];

package/src/http.js

@@ -0,0 +1,6 @@
+import { startHttpServer } from './transport/http.js';
+
+startHttpServer().catch(error => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/src/index.js

@@ -0,0 +1,54 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { debouncedNotifications, info, instructions } from './config.js';
+import { manual } from './data/manual.js';
+import { notes } from './data/notes.js';
+import { references } from './data/references.js';
+import { registerPrompts } from './prompts/index.js';
+import { registerResources } from './resources/index.js';
+import { createCapabilityChecker } from './shared/capabilities.js';
+import { registerResourceSubscriptions } from './subscriptions/resources.js';
+import { registerTools } from './tools/index.js';
+
+/**
+ * Build an MCP server instance pre-configured with tools, resources, and prompts.
+ * @returns {McpServer}
+ */
+export function build() {
+  const server = new McpServer(info, {
+    instructions,
+    debouncedNotificationMethods: debouncedNotifications,
+    capabilities: {
+      logging: {}
+    }
+  });
+
+  const context = { manual, notes, references };
+  const hasCapability = createCapabilityChecker(server);
+  const subscriptions = registerResourceSubscriptions(server, {
+    isSubscribable(uri) {
+      return uri.startsWith('note://');
+    }
+  });
+
+  registerTools(server, context, { hasCapability }, subscriptions);
+  registerResources(server, context);
+  registerPrompts(server);
+
+  return server;
+}
+
+/**
+ * Start the test server using stdio transport for integration scenarios.
+ * @param {{ server?: McpServer, transport?: StdioServerTransport }} [opts]
+ * @returns {Promise<{ server: McpServer, transport: StdioServerTransport }>}
+ */
+export async function start(opts = {}) {
+  const server = opts.server ?? build();
+  const transport = opts.transport ?? new StdioServerTransport();
+
+  // Use stdio transport so callers can spawn this server as a subprocess during tests.
+  await server.connect(transport);
+
+  return { server, transport };
+}

package/src/prompts/index.js

@@ -0,0 +1,9 @@
+import { registerWelcomePrompt } from './welcome.js';
+
+/**
+ * Register all prompts exposed by the server.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ */
+export function registerPrompts(server) {
+  registerWelcomePrompt(server);
+}

package/src/prompts/welcome.js

@@ -0,0 +1,63 @@
+import { completable } from '@modelcontextprotocol/sdk/server/completable.js';
+import { z } from 'zod';
+
+const greeters = ['Ada', 'Casey', 'Echo', 'Mira'];
+const tones = ['casual', 'formal', 'cheerful'];
+
+/**
+ * Register the welcome prompt with completable arguments.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ */
+export function registerWelcomePrompt(server) {
+  const argsSchema = {
+    name: completable(z.string().min(1, 'Name is required'), function completeName(value) {
+      const match = value.toLowerCase();
+      return greeters.filter(function filterGreeters(entry) {
+        return entry.toLowerCase().startsWith(match);
+      });
+    }),
+    tone: completable(z.enum(tones).default('casual'), function completeTone(value, context) {
+      const focus = context?.arguments?.name?.toLowerCase();
+      const pool = focus === 'ada' ? ['formal', 'casual'] : tones;
+      return pool.filter(function filterTone(entry) {
+        return entry.startsWith(value);
+      });
+    })
+  };
+
+  /**
+   * Produce a greeting message tailored to the provided tone.
+   * @param {{ name: string, tone: 'casual' | 'formal' | 'cheerful' }} args
+   * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').GetPromptResult>}
+   */
+  async function welcomePrompt(args) {
+    const base =
+      args.tone === 'formal'
+        ? `Greetings ${args.name}, welcome to the MCP test server.`
+        : args.tone === 'cheerful'
+          ? `Hi ${args.name}! Enjoy the feature-complete MCP test server!`
+          : `Hey ${args.name}! Enjoy exploring the test server.`;
+
+    return {
+      messages: [
+        {
+          role: 'assistant',
+          content: {
+            type: 'text',
+            text: base
+          }
+        }
+      ]
+    };
+  }
+
+  server.registerPrompt(
+    'welcome',
+    {
+      title: 'Welcome Prompt',
+      description: 'Generate a greeting message with customizable tone and completions.',
+      argsSchema
+    },
+    welcomePrompt
+  );
+}

package/src/resources/index.js

@@ -0,0 +1,14 @@
+import { registerManualResource } from './manual.js';
+import { registerNotesResource } from './notes.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
+ */
+export function registerResources(server, context) {
+  registerManualResource(server, context);
+  registerNotesResource(server, context);
+  registerUi(server);
+}

package/src/resources/manual.js

@@ -0,0 +1,43 @@
+/**
+ * Register the markdown manual resource.
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {{ manual: string }} context
+ */
+export function registerManualResource(server, context) {
+  /**
+   * Return a markdown manual describing server features.
+   * @param {URL} uri
+   * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').ReadResourceResult>}
+   */
+  async function manualRead(uri) {
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text: context.manual
+        }
+      ]
+    };
+  }
+
+  server.registerResource(
+    'manual',
+    'resource://manual',
+    {
+      title: 'Server Manual',
+      description: 'Describes how to interact with the test server.',
+      mimeType: 'text/markdown',
+      icons: [
+        {
+          src: 'https://example.test/assets/manual.png',
+          mimeType: 'image/png',
+          sizes: ['48x48']
+        }
+      ],
+      _meta: {
+        owner: 'mcp-layer-schema'
+      }
+    },
+    manualRead
+  );
+}

package/src/resources/notes.js

@@ -0,0 +1,104 @@
+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
+ */
+export function registerNotesResource(server, context) {
+  const template = new ResourceTemplate('note://{topic}/{detail}', {
+    list: async function listNotes() {
+      return {
+        resources: Array.from(context.notes.entries()).flatMap(function mapNotes([topic, detailSet]) {
+          return Object.keys(detailSet).map(function mapDetail(detail) {
+            return {
+              uri: `note://${topic}/${detail}`,
+              name: `${topic}-${detail}`,
+              description: `Notes covering ${topic} (${detail}).`
+            };
+          });
+        })
+      };
+    },
+    complete: {
+      topic: async function completeTopic(value) {
+        const match = value.toLowerCase();
+        return Array.from(context.notes.keys()).filter(function filterTopics(topic) {
+          return topic.startsWith(match);
+        });
+      },
+      detail: async function completeDetail(value, completionContext) {
+        const topic = completionContext?.arguments?.topic;
+        const pool = topic && context.notes.get(topic) ? Object.keys(context.notes.get(topic)) : ['summary', 'usage'];
+        return pool.filter(function filterDetail(entry) {
+          return entry.startsWith(value);
+        });
+      }
+    }
+  });
+
+  /**
+   * Derive note topic and detail for a URI or template variable set.
+   * @param {URL} uri
+   * @param {{ topic?: string, detail?: string }} [variables]
+   * @returns {{ topic: string, detail: string }}
+   */
+  function noteParts(uri, variables = {}) {
+    const topic = variables.topic ?? uri.hostname ?? uri.pathname.replace(/^\//, '');
+    const rawDetail = variables.detail ?? uri.pathname.replace(/^\//, '');
+    const detail = rawDetail || 'summary';
+    return { topic, detail };
+  }
+
+  /**
+   * Read a dynamic note resource for the requested topic/detail pair.
+   * @param {URL} uri
+   * @param {{ topic?: string, detail?: string }} [variables]
+   * @returns {Promise<import('@modelcontextprotocol/sdk/types.js').ReadResourceResult>}
+   */
+  async function noteRead(uri, variables = {}) {
+    const parts = noteParts(uri, variables);
+    const topicNotes = context.notes.get(parts.topic);
+    const text = topicNotes?.[parts.detail];
+    if (!text) {
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            text: `No ${parts.detail} note is available for ${parts.topic}.`
+          }
+        ]
+      };
+    }
+
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          text
+        }
+      ]
+    };
+  }
+
+  server.registerResource(
+    'notes',
+    template,
+    {
+      title: 'Feature Notes',
+      description: 'Dynamic notes for each feature, including summaries and usage guidance.',
+      mimeType: 'text/plain',
+      icons: [
+        {
+          src: 'https://example.test/assets/notes.svg',
+          mimeType: 'image/svg+xml',
+          sizes: ['any']
+        }
+      ],
+      _meta: {
+        owner: 'mcp-layer-schema'
+      }
+    },
+    noteRead
+  );
+}