typescript-sdk/examples/CONTRIBUTING.md

Contributing an example

Each examples/<story>/ directory is a tiny @mcp-examples/<story> workspace package containing a server.ts / client.ts pair. The pair is a self-verifying e2e test: the client connects, asserts results, and exits non-zero on any mismatch. pnpm run:examples runs every story over its configured transport × era legs and is part of the per-PR CI gate.

Typical shape

Examples are compiled documentation. Every story shows the SDK transport setup inline — no helper hides serveStdio, createMcpHandler, Client, or transport construction. The duplication is the feature: when the public API changes, 25 compile errors flag 25 doc pages.

Only the part a reader is not here to learn — argv parsing — is shared, via parseExampleArgs / check / siblingPath from @mcp-examples/shared (a workspace package, so it reads as scaffolding, not part of the example). The demo OAuth provider and InMemoryEventStore live at the @mcp-examples/shared/auth subpath so the args-only root barrel does not pull better-auth/express/better-sqlite3 into every story.

Most stories follow the skeleton below; deviate freely when the story calls for it (HTTP-only auth, sessionful transports, framework adapters, etc.).

server.ts

import { createServer } from 'node:http';

import { parseExampleArgs } from '@mcp-examples/shared';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';

function buildServer(): McpServer {
    const server = new McpServer({ name: '<story>-example', version: '1.0.0' });
    // … register tools / resources / prompts here …
    return server;
}

const { transport, port } = parseExampleArgs();

if (transport === 'stdio') {
    void serveStdio(buildServer);
    console.error('[server] serving over stdio');
} else {
    const handler = createMcpHandler(buildServer);
    createServer(toNodeHandler(handler)).listen(port, () => {
        console.error(`[server] listening on http://127.0.0.1:${port}/mcp`);
    });
}

client.ts

import { check, parseExampleArgs, siblingPath } from '@mcp-examples/shared';
import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';

const { transport, url, era } = parseExampleArgs();

const client = new Client({ name: '<story>-example-client', version: '1.0.0' }, { versionNegotiation: { mode: era === 'modern' ? 'auto' : 'legacy' } });

await client.connect(transport === 'stdio' ? new StdioClientTransport({ command: 'npx', args: ['-y', 'tsx', siblingPath(import.meta.url, 'server.ts')] }) : new StreamableHTTPClientTransport(new URL(url)));

// … example body — drive the server and assert with `check.*` …

await client.close();

The body uses top-level await. A check.* failure throws, Node prints the error and exits 1; on success client.close() releases the last handle and Node exits 0. pnpm run:examples reports PASS/FAIL from the exit code (a timeout is reported as a hang — investigate it as a possible unclosed handle).

Import rules (lint-enforced)

Stories may import from:

• @modelcontextprotocol/{server,client,core,node,express,hono} and their published subpath exports (e.g. @modelcontextprotocol/server/stdio)
• @mcp-examples/shared (args/assert) and @mcp-examples/shared/auth (demo OAuth + InMemoryEventStore)
• third-party packages a consumer would npm install

Stories may not import from:

• @modelcontextprotocol/core-internal or @modelcontextprotocol/core-internal/* (internal barrel)
• @modelcontextprotocol/*/src/* or @modelcontextprotocol/*/dist/* (deep paths)
• @modelcontextprotocol/test-helpers
• any relative path that hides the SDK transport setup behind a shared helper

@mcp-examples/shared itself must never import from a story package (one-way).