fix(server): behavior, clarity annotations

src/server.getResources.ts

@@ -91,6 +91,12 @@ const matchPackageVersion = (value: string | undefined, supportedVersions: strin
  * it as-is back to async and witness the unit tests fail. If it is moved back to async, it
  * should be thoroughly tested.
  *
+ * @note The traversal loop condition `while (currentDir !== root)` deliberately stops before
+ * inspecting the filesystem root directory (e.g. `/package.json` or `C:\package.json`).
+ * Because this function resolves consumer project dependencies from CLI/npx working directories
+ * (`process.cwd()`), inspecting the filesystem root is a hypothetical boundary condition
+ * and is currently unnecessary in general project workflows.
+ *
  * @param startPath - Directory to start searching from
  * @param options - Options object
  * @param options.resolvedPath - Set to `true` to return the absolute path, or `false` to return the relative path. Defaults to `true`.

src/server.helpers.ts

@@ -207,6 +207,10 @@ const isUrlObject = (obj: unknown, { allowedProtocols }: { allowedProtocols?: st
  * Be aware this helper is used to gate-keep tools-as-plugins. Consider additions carefully
  * since they may fall outside our use cases.
  *
+ * @note When `isStrict: true` (default), only schemes specified in `allowedProtocols` are
+ * accepted. When `isStrict: false`, `allowedProtocols` serves as a fast-path prefix check,
+ * falling back to `new URL()` to support open/custom schemes or empty protocol lists.
+ *
  * @param str - String or object to check
  * @param [options] - Options
  * @param [options.allowedProtocols] - List of allowed URL protocols. Default: `['file', 'http', 'https', 'data', 'node']`

src/server.search.ts

@@ -137,6 +137,12 @@ normalizeString.memo = memo(normalizeString, { cacheLimit: 50 });
  * @param {ClosestSearchOptions} options - Search configuration options
  * @returns Closest matching item from items.
  *
+ * @note The `items[itemIndex]` truthiness check in the distance branch intentionally guards
+ * against computing distance on empty or falsy values, as realistic MCP search datasets
+ * operate exclusively on non-empty identifiers (component names, CSS tokens, and resource URIs).
+ * Attempting to "correct" falsy values with logic additions, or removals, on the `items[itemIndex]`
+ * check may ironically end up returning the same results you intended to correct.
+ *
  * @example
  * ```typescript
  * const result = findClosest('button', ['Button', 'ButtonGroup', 'Badge']);