feat(core): add deprecate() warn-once helper for v1-compat shims

Author: felixweinberger

.changeset/deprecate-helper.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+Add internal `deprecate()` warn-once helper for v1-compat shims.

packages/core/src/index.ts

@@ -49,3 +49,4 @@ export * from './validators/fromJsonSchema.js';
 
 // Core types only - implementations are exported via separate entry points
 export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './validators/types.js';
+export { deprecate } from './util/deprecate.js';

packages/core/src/util/deprecate.ts

@@ -0,0 +1,22 @@
+const _warned = new Set<string>();
+
+/**
+ * Emits a one-time deprecation warning to stderr. Subsequent calls with the
+ * same `key` are no-ops for the lifetime of the process.
+ *
+ * Used by v1-compat shims to nudge consumers toward the v2-native API without
+ * spamming logs on hot paths (e.g. per-tool registration).
+ *
+ * @internal
+ */
+export function deprecate(key: string, msg: string): void {
+    if (_warned.has(key)) return;
+    _warned.add(key);
+    // eslint-disable-next-line no-console
+    console.warn(`[mcp-sdk] DEPRECATED: ${msg}`);
+}
+
+/** @internal exposed for tests */
+export function _resetDeprecationWarnings(): void {
+    _warned.clear();
+}

packages/core/test/util/deprecate.test.ts

@@ -0,0 +1,14 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { deprecate, _resetDeprecationWarnings } from '../../src/util/deprecate.js';
+
+describe('deprecate', () => {
+    afterEach(() => _resetDeprecationWarnings());
+    it('warns once per key', () => {
+        const spy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+        deprecate('k', 'msg');
+        deprecate('k', 'msg');
+        deprecate('other', 'msg2');
+        expect(spy).toHaveBeenCalledTimes(2);
+        spy.mockRestore();
+    });
+});