docs: add {@link} and @see tags to JSDoc comments (#1490)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/client/src/client/auth.ts

@@ -654,7 +654,8 @@ export function extractResourceMetadataUrl(res: Response): URL | undefined {
 }
 
 /**
- * Looks up RFC 9728 OAuth 2.0 Protected Resource Metadata.
+ * Looks up {@link https://datatracker.ietf.org/doc/html/rfc9728 | RFC 9728}
+ * OAuth 2.0 Protected Resource Metadata.
  *
  * If the server returns a 404 for the well-known endpoint, this function will
  * return `undefined`. Any other errors will be thrown as exceptions.
@@ -872,8 +873,11 @@ export function buildDiscoveryUrls(authorizationServerUrl: string | URL): { url:
 }
 
 /**
- * Discovers authorization server metadata with support for RFC 8414 OAuth 2.0 Authorization Server Metadata
- * and OpenID Connect Discovery 1.0 specifications.
+ * Discovers authorization server metadata with support for
+ * {@link https://datatracker.ietf.org/doc/html/rfc8414 | RFC 8414} OAuth 2.0
+ * Authorization Server Metadata and
+ * {@link https://openid.net/specs/openid-connect-discovery-1_0.html | OpenID Connect Discovery 1.0}
+ * specifications.
  *
  * This function implements a fallback strategy for authorization server discovery:
  * 1. Attempts RFC 8414 OAuth metadata discovery first
@@ -1269,7 +1273,8 @@ export async function fetchToken(
 }
 
 /**
- * Performs OAuth 2.0 Dynamic Client Registration according to RFC 7591.
+ * Performs OAuth 2.0 Dynamic Client Registration according to
+ * {@link https://datatracker.ietf.org/doc/html/rfc7591 | RFC 7591}.
  */
 export async function registerClient(
     authorizationServerUrl: string | URL,

packages/client/src/client/authExtensions.ts

@@ -223,7 +223,8 @@ export interface PrivateKeyJwtProviderOptions {
  * OAuth provider for client_credentials grant with private_key_jwt authentication.
  *
  * This provider is designed for machine-to-machine authentication where
- * the client authenticates using a signed JWT assertion (RFC 7523 Section 2.2).
+ * the client authenticates using a signed JWT assertion
+ * ({@link https://datatracker.ietf.org/doc/html/rfc7523#section-2.2 | RFC 7523 Section 2.2}).
  *
  * @example
  * ```typescript

packages/core/src/auth/errors.ts

@@ -1,7 +1,8 @@
 import type { OAuthErrorResponse } from '../shared/auth.js';
 
 /**
- * OAuth error codes as defined by RFC 6749 and extensions.
+ * OAuth error codes as defined by {@link https://datatracker.ietf.org/doc/html/rfc6749#section-5.2 | RFC 6749}
+ * and extensions.
  */
 export enum OAuthErrorCode {
     /**

packages/core/src/experimental/tasks/interfaces.ts

@@ -97,6 +97,7 @@ export interface QueuedError extends BaseQueuedMessage {
  * All methods are async to support external storage implementations.
  * All data in QueuedMessage must be JSON-serializable.
  *
+ * @see {@linkcode InMemoryTaskMessageQueue} for a reference implementation
  * @experimental
  */
 export interface TaskMessageQueue {
@@ -157,6 +158,7 @@ export interface CreateTaskOptions {
  * Similar to Transport, this allows pluggable task storage implementations
  * (in-memory, database, distributed cache, etc.).
  *
+ * @see {@linkcode InMemoryTaskStore} for a reference implementation
  * @experimental
  */
 export interface TaskStore {

packages/core/src/shared/auth.ts

@@ -71,7 +71,8 @@ export const OAuthMetadataSchema = z.looseObject({
 
 /**
  * OpenID Connect Discovery 1.0 Provider Metadata
- * see: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
+ *
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
  */
 export const OpenIdProviderMetadataSchema = z.looseObject({
     issuer: z.string(),

packages/core/src/shared/authUtils.ts

@@ -4,7 +4,8 @@
 
 /**
  * Converts a server URL to a resource URL by removing the fragment.
- * RFC 8707 section 2 states that resource URIs "MUST NOT include a fragment component".
+ * {@link https://datatracker.ietf.org/doc/html/rfc8707#section-2 | RFC 8707 section 2}
+ * states that resource URIs "MUST NOT include a fragment component".
  * Keeps everything else unchanged (scheme, domain, port, path, query).
  */
 export function resourceUrlFromServerUrl(url: URL | string): URL {

packages/core/src/shared/toolNameValidation.ts

@@ -6,6 +6,8 @@
  * Allowed characters: uppercase and lowercase ASCII letters (A-Z, a-z), digits
  * (0-9), underscore (_), dash (-), and dot (.).
  * Tool names SHOULD NOT contain spaces, commas, or other special characters.
+ *
+ * @see {@link https://github.com/modelcontextprotocol/modelcontextprotocol/issues/986 | SEP-986: Specify Format for Tool Names}
  */
 
 /**

packages/core/src/validation/ajvProvider.ts

@@ -33,6 +33,8 @@ function createDefaultAjvInstance(): Ajv {
  * const ajv = new Ajv({ strict: true, allErrors: true });
  * const validator = new AjvJsonSchemaValidator(ajv);
  * ```
+ *
+ * @see {@linkcode CfWorkerJsonSchemaValidator} for an edge-runtime-compatible alternative
  */
 export class AjvJsonSchemaValidator implements jsonSchemaValidator {
     private _ajv: Ajv;

packages/core/src/validation/cfWorkerProvider.ts

@@ -4,6 +4,8 @@
  * This provider uses @cfworker/json-schema for validation without code generation,
  * making it compatible with edge runtimes like Cloudflare Workers that restrict
  * eval and new Function.
+ *
+ * @see {@linkcode AjvJsonSchemaValidator} for the Node.js alternative
  */
 
 import { Validator } from '@cfworker/json-schema';

packages/server/src/server/completable.ts

@@ -20,6 +20,8 @@ export type CompletableSchema<T extends AnySchema> = T & {
 
 /**
  * Wraps a Zod type to provide autocompletion capabilities. Useful for, e.g., prompt arguments in MCP.
+ *
+ * @see {@linkcode server/mcp.McpServer.registerPrompt | McpServer.registerPrompt} for using completable schemas in prompt argument definitions
  */
 export function completable<T extends AnySchema>(schema: T, complete: CompleteCallback<T>): CompletableSchema<T> {
     Object.defineProperty(schema as object, COMPLETABLE_SYMBOL, {