public exports - no wildcard exports; header instructions; update CLAUDE.md

Author: KKonstantinov

CLAUDE.md

@@ -62,6 +62,19 @@ The SDK is organized into three main layers:
     - `Server` (`packages/server/src/server/server.ts`) - Server implementation extending Protocol with request handler registration
     - `McpServer` (`packages/server/src/server/mcp.ts`) - High-level server API with simplified resource/tool/prompt registration
 
+### Public API Exports
+
+The SDK has a two-layer export structure to separate internal code from the public API:
+
+- **`@modelcontextprotocol/core`** (main entry, `packages/core/src/index.ts`) — Internal barrel. Exports everything (including Zod schemas, Protocol class, stdio utils). Only consumed by sibling packages within the monorepo (`private: true`).
+- **`@modelcontextprotocol/core/public`** (`packages/core/src/exports/public/index.ts`) — Curated public API. Exports only TypeScript types, error classes, constants, and guards. Re-exported by client and server packages.
+- **`@modelcontextprotocol/client`** and **`@modelcontextprotocol/server`** (`packages/*/src/index.ts`) — Final public surface. Package-specific exports (named explicitly) plus re-exports from `core/public`.
+
+When modifying exports:
+- Use explicit named exports, not `export *`, in package `index.ts` files and `core/public`.
+- Adding a symbol to a package `index.ts` makes it public API — do so intentionally.
+- Internal helpers should stay in the core internal barrel and not be added to `core/public` or package index files.
+
 ### Transport System
 
 Transports (`packages/core/src/shared/transport.ts`) provide the communication layer:

packages/client/src/index.ts

@@ -1,4 +1,11 @@
-// Client-specific exports
+// Public API for @modelcontextprotocol/client.
+//
+// This file defines the complete public surface. It consists of:
+//   - Package-specific exports: listed explicitly below (named imports)
+//   - Protocol-level types: re-exported from @modelcontextprotocol/core/public
+//
+// Any new export added here becomes public API. Use named exports, not wildcards.
+
 export type {
     AddClientAuthentication,
     AuthResult,
@@ -53,7 +60,7 @@ export { StreamableHTTPClientTransport } from './client/streamableHttp.js';
 export { WebSocketClientTransport } from './client/websocket.js';
 
 // experimental exports
-export * from './experimental/index.js';
+export { ExperimentalClientTasks } from './experimental/tasks/client.js';
 
 // re-export curated public API from core
 export * from '@modelcontextprotocol/core/public';

packages/core/src/types/index.ts

@@ -1,5 +1,5 @@
 // Internal barrel — re-exports everything for use within the SDK packages.
-// External consumers should use exports/public/index.ts instead for a curated public API.
+// The public API is defined in @modelcontextprotocol/core/public (see exports/public/index.ts).
 export * from './constants.js';
 export * from './enums.js';
 export * from './errors.js';

packages/server/src/index.ts

@@ -1,4 +1,11 @@
-// Server-specific exports
+// Public API for @modelcontextprotocol/server.
+//
+// This file defines the complete public surface. It consists of:
+//   - Package-specific exports: listed explicitly below (named imports)
+//   - Protocol-level types: re-exported from @modelcontextprotocol/core/public
+//
+// Any new export added here becomes public API. Use named exports, not wildcards.
+
 export type { CompletableSchema, CompleteCallback } from './server/completable.js';
 export { completable, isCompletable } from './server/completable.js';
 export type {
@@ -32,7 +39,9 @@ export type {
 export { WebStandardStreamableHTTPServerTransport } from './server/streamableHttp.js';
 
 // experimental exports
-export * from './experimental/index.js';
+export type { CreateTaskRequestHandler, TaskRequestHandler, ToolTaskHandler } from './experimental/tasks/interfaces.js';
+export { ExperimentalMcpServerTasks } from './experimental/tasks/mcpServer.js';
+export { ExperimentalServerTasks } from './experimental/tasks/server.js';
 
 // re-export curated public API from core
 export * from '@modelcontextprotocol/core/public';