@cyanheads/mcp-ts-core 0.12.5 → 0.12.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/AGENTS.md +26 -14
  2. package/CLAUDE.md +26 -14
  3. package/README.md +124 -76
  4. package/biome.json +1 -1
  5. package/changelog/0.12.x/0.12.6.md +44 -0
  6. package/changelog/0.12.x/0.12.7.md +39 -0
  7. package/dist/core/app.d.ts +2 -2
  8. package/dist/core/app.js +2 -2
  9. package/dist/core/index.d.ts +5 -5
  10. package/dist/core/index.js +2 -2
  11. package/dist/core/worker.d.ts +2 -2
  12. package/dist/core/worker.d.ts.map +1 -1
  13. package/dist/core/worker.js +1 -1
  14. package/dist/core/worker.js.map +1 -1
  15. package/dist/mcp-server/apps/appBuilders.d.ts +2 -2
  16. package/dist/mcp-server/apps/appBuilders.js +2 -2
  17. package/dist/mcp-server/cacheHints.d.ts +1 -1
  18. package/dist/mcp-server/prompts/prompt-registration.d.ts +1 -1
  19. package/dist/mcp-server/prompts/prompt-registration.js +1 -1
  20. package/dist/mcp-server/resources/resource-registration.d.ts +3 -3
  21. package/dist/mcp-server/resources/resource-registration.js +1 -1
  22. package/dist/mcp-server/resources/resourceSubscriptions.d.ts +1 -1
  23. package/dist/mcp-server/resources/utils/resourceHandlerFactory.d.ts +2 -2
  24. package/dist/mcp-server/resources/utils/resourceHandlerFactory.js +4 -4
  25. package/dist/mcp-server/server.d.ts +4 -4
  26. package/dist/mcp-server/server.js +1 -1
  27. package/dist/mcp-server/tools/tool-registration.d.ts +3 -3
  28. package/dist/mcp-server/tools/tool-registration.d.ts.map +1 -1
  29. package/dist/mcp-server/tools/tool-registration.js +9 -3
  30. package/dist/mcp-server/tools/tool-registration.js.map +1 -1
  31. package/dist/mcp-server/tools/utils/deferredInputSchema.d.ts +39 -0
  32. package/dist/mcp-server/tools/utils/deferredInputSchema.d.ts.map +1 -0
  33. package/dist/mcp-server/tools/utils/deferredInputSchema.js +33 -0
  34. package/dist/mcp-server/tools/utils/deferredInputSchema.js.map +1 -0
  35. package/dist/mcp-server/tools/utils/disabled-tool.d.ts +1 -1
  36. package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts +11 -3
  37. package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts.map +1 -1
  38. package/dist/mcp-server/tools/utils/toolHandlerFactory.js +29 -7
  39. package/dist/mcp-server/tools/utils/toolHandlerFactory.js.map +1 -1
  40. package/dist/mcp-server/transports/auth/authFactory.d.ts +1 -1
  41. package/dist/mcp-server/transports/auth/authFactory.js +2 -2
  42. package/dist/mcp-server/transports/auth/authMiddleware.d.ts +1 -1
  43. package/dist/mcp-server/transports/auth/authMiddleware.js +1 -1
  44. package/dist/mcp-server/transports/auth/lib/authUtils.js +1 -1
  45. package/dist/mcp-server/transports/auth/lib/claimParser.d.ts +1 -1
  46. package/dist/mcp-server/transports/auth/strategies/authStrategy.d.ts +1 -1
  47. package/dist/mcp-server/transports/auth/strategies/jwtStrategy.d.ts +2 -2
  48. package/dist/mcp-server/transports/auth/strategies/jwtStrategy.js +1 -1
  49. package/dist/mcp-server/transports/auth/strategies/oauthStrategy.d.ts +2 -2
  50. package/dist/mcp-server/transports/auth/strategies/oauthStrategy.js +1 -1
  51. package/dist/mcp-server/transports/http/httpErrorHandler.d.ts +1 -1
  52. package/dist/mcp-server/transports/http/httpServer.d.ts +1 -1
  53. package/dist/mcp-server/transports/http/httpServer.js +1 -1
  54. package/dist/mcp-server/transports/http/httpTransport.d.ts +3 -3
  55. package/dist/mcp-server/transports/http/httpTransport.js +12 -12
  56. package/dist/mcp-server/transports/http/landing-page/handler.d.ts +1 -1
  57. package/dist/mcp-server/transports/http/sessionStore.js +1 -1
  58. package/dist/mcp-server/transports/manager.d.ts +2 -2
  59. package/dist/mcp-server/transports/manager.js +3 -3
  60. package/dist/services/llm/providers/openrouter.provider.d.ts +1 -1
  61. package/dist/services/speech/providers/whisper.provider.d.ts.map +1 -1
  62. package/dist/services/speech/providers/whisper.provider.js +4 -2
  63. package/dist/services/speech/providers/whisper.provider.js.map +1 -1
  64. package/dist/storage/core/StorageService.d.ts +1 -1
  65. package/dist/storage/core/StorageService.js +1 -1
  66. package/dist/storage/core/storageFactory.d.ts +2 -2
  67. package/dist/storage/core/storageFactory.js +6 -6
  68. package/dist/storage/core/storageValidation.d.ts.map +1 -1
  69. package/dist/storage/core/storageValidation.js +5 -3
  70. package/dist/storage/core/storageValidation.js.map +1 -1
  71. package/dist/storage/providers/cloudflare/d1Provider.d.ts +1 -1
  72. package/dist/storage/providers/cloudflare/d1Provider.js +1 -1
  73. package/dist/storage/providers/cloudflare/kvProvider.d.ts +1 -1
  74. package/dist/storage/providers/cloudflare/kvProvider.js +1 -1
  75. package/dist/storage/providers/cloudflare/r2Provider.d.ts +1 -1
  76. package/dist/storage/providers/cloudflare/r2Provider.js +1 -1
  77. package/dist/storage/providers/fileSystem/fileSystemProvider.d.ts +1 -1
  78. package/dist/storage/providers/fileSystem/fileSystemProvider.js +1 -1
  79. package/dist/storage/providers/inMemory/inMemoryProvider.d.ts +3 -1
  80. package/dist/storage/providers/inMemory/inMemoryProvider.d.ts.map +1 -1
  81. package/dist/storage/providers/inMemory/inMemoryProvider.js +11 -7
  82. package/dist/storage/providers/inMemory/inMemoryProvider.js.map +1 -1
  83. package/dist/storage/providers/supabase/supabaseProvider.d.ts +2 -2
  84. package/dist/storage/providers/supabase/supabaseProvider.js +1 -1
  85. package/dist/testing/fuzz.d.ts.map +1 -1
  86. package/dist/testing/fuzz.js +92 -53
  87. package/dist/testing/fuzz.js.map +1 -1
  88. package/dist/utils/formatting/diffFormatter.d.ts +2 -2
  89. package/dist/utils/formatting/diffFormatter.js +4 -4
  90. package/dist/utils/formatting/tableFormatter.d.ts +2 -2
  91. package/dist/utils/formatting/tableFormatter.js +3 -3
  92. package/dist/utils/formatting/treeFormatter.d.ts +3 -3
  93. package/dist/utils/formatting/treeFormatter.js +4 -4
  94. package/dist/utils/internal/error-handler/errorHandler.js +6 -6
  95. package/dist/utils/internal/error-handler/helpers.js +1 -1
  96. package/dist/utils/internal/error-handler/types.d.ts +1 -1
  97. package/dist/utils/internal/health.js +2 -2
  98. package/dist/utils/internal/lazyImport.js +1 -1
  99. package/dist/utils/internal/logger.d.ts +3 -3
  100. package/dist/utils/internal/logger.js +4 -4
  101. package/dist/utils/internal/performance.d.ts +1 -1
  102. package/dist/utils/internal/performance.js +6 -6
  103. package/dist/utils/internal/requestContext.d.ts +1 -1
  104. package/dist/utils/internal/requestContext.js +2 -2
  105. package/dist/utils/metrics/tokenCounter.d.ts +1 -1
  106. package/dist/utils/metrics/tokenCounter.js +2 -2
  107. package/dist/utils/network/fetchWithTimeout.d.ts +1 -1
  108. package/dist/utils/network/fetchWithTimeout.js +6 -6
  109. package/dist/utils/network/httpError.js +1 -1
  110. package/dist/utils/network/retry.d.ts +1 -1
  111. package/dist/utils/network/retry.js +1 -1
  112. package/dist/utils/pagination/pagination.d.ts +2 -2
  113. package/dist/utils/pagination/pagination.js +4 -4
  114. package/dist/utils/parsing/csvParser.d.ts +4 -4
  115. package/dist/utils/parsing/csvParser.js +6 -6
  116. package/dist/utils/parsing/dateParser.d.ts +3 -3
  117. package/dist/utils/parsing/dateParser.js +6 -6
  118. package/dist/utils/parsing/frontmatterParser.d.ts +2 -2
  119. package/dist/utils/parsing/frontmatterParser.js +3 -3
  120. package/dist/utils/parsing/htmlExtractor.d.ts +3 -3
  121. package/dist/utils/parsing/htmlExtractor.js +5 -5
  122. package/dist/utils/parsing/jsonParser.d.ts +4 -4
  123. package/dist/utils/parsing/jsonParser.js +6 -6
  124. package/dist/utils/parsing/pdfParser.d.ts +2 -2
  125. package/dist/utils/parsing/pdfParser.js +4 -4
  126. package/dist/utils/parsing/xmlParser.d.ts +4 -4
  127. package/dist/utils/parsing/xmlParser.js +5 -5
  128. package/dist/utils/parsing/yamlParser.d.ts +4 -4
  129. package/dist/utils/parsing/yamlParser.js +6 -6
  130. package/dist/utils/scheduling/scheduler.d.ts +3 -3
  131. package/dist/utils/scheduling/scheduler.js +5 -5
  132. package/dist/utils/security/rateLimiter.d.ts +2 -2
  133. package/dist/utils/security/rateLimiter.js +3 -3
  134. package/dist/utils/security/rateLimiter.js.map +1 -1
  135. package/dist/utils/security/sanitization.d.ts +3 -3
  136. package/dist/utils/security/sanitization.js +7 -7
  137. package/dist/utils/telemetry/instrumentation.d.ts.map +1 -1
  138. package/dist/utils/telemetry/instrumentation.js +7 -8
  139. package/dist/utils/telemetry/instrumentation.js.map +1 -1
  140. package/dist/utils/telemetry/trace.d.ts +1 -1
  141. package/dist/utils/telemetry/trace.js +1 -1
  142. package/package.json +33 -26
  143. package/scripts/check-framework-antipatterns.ts +4 -1
  144. package/scripts/devcheck.ts +309 -37
  145. package/scripts/lint-packaging.ts +28 -6
  146. package/skills/add-tool/SKILL.md +33 -1
  147. package/skills/api-errors/SKILL.md +2 -1
  148. package/skills/api-workers/SKILL.md +3 -3
  149. package/skills/design-mcp-server/SKILL.md +6 -1
  150. package/skills/field-test/SKILL.md +70 -30
  151. package/skills/git-wrapup/SKILL.md +4 -3
  152. package/templates/AGENTS.md +2 -2
  153. package/templates/CLAUDE.md +2 -2
  154. package/templates/package.json +6 -6
@@ -4,7 +4,7 @@
4
4
  * alignment, truncation, and formatting options.
5
5
  * @module src/utils/formatting/tableFormatter
6
6
  */
7
- import { type RequestContext } from '../../utils/internal/requestContext.js';
7
+ import { type RequestContext } from '../internal/requestContext.js';
8
8
  /**
9
9
  * Table output style options.
10
10
  *
@@ -227,7 +227,7 @@ export declare class TableFormatter {
227
227
  *
228
228
  * @example
229
229
  * ```typescript
230
- * import { tableFormatter } from '../../utils/formatting/tableFormatter.js';
230
+ * import { tableFormatter } from './tableFormatter.js';
231
231
  *
232
232
  * const data = [
233
233
  * { name: 'Alice', age: 30, role: 'Engineer' },
@@ -5,8 +5,8 @@
5
5
  * @module src/utils/formatting/tableFormatter
6
6
  */
7
7
  import { JsonRpcErrorCode, McpError, validationError } from '../../types-global/errors.js';
8
- import { logger } from '../../utils/internal/logger.js';
9
- import { requestContextService, withExtra, } from '../../utils/internal/requestContext.js';
8
+ import { logger } from '../internal/logger.js';
9
+ import { requestContextService, withExtra, } from '../internal/requestContext.js';
10
10
  /**
11
11
  * Utility class for formatting tabular data into various table styles.
12
12
  *
@@ -411,7 +411,7 @@ export class TableFormatter {
411
411
  *
412
412
  * @example
413
413
  * ```typescript
414
- * import { tableFormatter } from '../../utils/formatting/tableFormatter.js';
414
+ * import { tableFormatter } from './tableFormatter.js';
415
415
  *
416
416
  * const data = [
417
417
  * { name: 'Alice', age: 30, role: 'Engineer' },
@@ -3,7 +3,7 @@
3
3
  * Supports ASCII, Unicode box-drawing, and compact tree styles with icons and metadata.
4
4
  * @module src/utils/formatting/treeFormatter
5
5
  */
6
- import { type RequestContext } from '../../utils/internal/requestContext.js';
6
+ import { type RequestContext } from '../internal/requestContext.js';
7
7
  /**
8
8
  * Tree output style options.
9
9
  *
@@ -111,7 +111,7 @@ export interface TreeFormatterOptions {
111
111
  *
112
112
  * @example
113
113
  * ```typescript
114
- * import { treeFormatter } from '../../utils/formatting/treeFormatter.js';
114
+ * import { treeFormatter } from './treeFormatter.js';
115
115
  *
116
116
  * const tree: TreeNode = {
117
117
  * name: 'src',
@@ -294,7 +294,7 @@ export declare class TreeFormatter {
294
294
  *
295
295
  * @example
296
296
  * ```typescript
297
- * import { treeFormatter } from '../../utils/formatting/treeFormatter.js';
297
+ * import { treeFormatter } from './treeFormatter.js';
298
298
  *
299
299
  * // Simple directory tree
300
300
  * const tree = {
@@ -4,8 +4,8 @@
4
4
  * @module src/utils/formatting/treeFormatter
5
5
  */
6
6
  import { JsonRpcErrorCode, McpError, validationError } from '../../types-global/errors.js';
7
- import { logger } from '../../utils/internal/logger.js';
8
- import { requestContextService, withExtra, } from '../../utils/internal/requestContext.js';
7
+ import { logger } from '../internal/logger.js';
8
+ import { requestContextService, withExtra, } from '../internal/requestContext.js';
9
9
  /**
10
10
  * Utility class for formatting hierarchical data as tree structures.
11
11
  *
@@ -17,7 +17,7 @@ import { requestContextService, withExtra, } from '../../utils/internal/requestC
17
17
  *
18
18
  * @example
19
19
  * ```typescript
20
- * import { treeFormatter } from '../../utils/formatting/treeFormatter.js';
20
+ * import { treeFormatter } from './treeFormatter.js';
21
21
  *
22
22
  * const tree: TreeNode = {
23
23
  * name: 'src',
@@ -337,7 +337,7 @@ export class TreeFormatter {
337
337
  *
338
338
  * @example
339
339
  * ```typescript
340
- * import { treeFormatter } from '../../utils/formatting/treeFormatter.js';
340
+ * import { treeFormatter } from './treeFormatter.js';
341
341
  *
342
342
  * // Simple directory tree
343
343
  * const tree = {
@@ -7,12 +7,12 @@ import { SdkError, SdkErrorCode } from '@modelcontextprotocol/server';
7
7
  import { SpanStatusCode, trace } from '@opentelemetry/api';
8
8
  import { ZodError } from 'zod';
9
9
  import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
10
- import { logger } from '../../../utils/internal/logger.js';
11
- import { toCanonicalContext } from '../../../utils/internal/requestContext.js';
12
- import { generateUUID } from '../../../utils/security/idGenerator.js';
13
- import { sanitizeInputForLogging } from '../../../utils/security/sanitization.js';
14
- import { ATTR_MCP_ERROR_CLASSIFIED_CODE } from '../../../utils/telemetry/attributes.js';
15
- import { createCounter } from '../../../utils/telemetry/metrics.js';
10
+ import { logger } from '../logger.js';
11
+ import { toCanonicalContext } from '../requestContext.js';
12
+ import { generateUUID } from '../../security/idGenerator.js';
13
+ import { sanitizeInputForLogging } from '../../security/sanitization.js';
14
+ import { ATTR_MCP_ERROR_CLASSIFIED_CODE } from '../../telemetry/attributes.js';
15
+ import { createCounter } from '../../telemetry/metrics.js';
16
16
  import { extractErrorCauseChain, getErrorMessage, getErrorName } from './helpers.js';
17
17
  import { COMPILED_ERROR_PATTERNS, COMPILED_PROVIDER_PATTERNS, ERROR_TYPE_MAPPINGS, getCompiledPattern, } from './mappings.js';
18
18
  let errorClassifiedCounter;
@@ -5,7 +5,7 @@
5
5
  */
6
6
  import { ZodError } from 'zod';
7
7
  import { McpError } from '../../../types-global/errors.js';
8
- import { isAggregateError } from '../../../utils/types/guards.js';
8
+ import { isAggregateError } from '../../types/guards.js';
9
9
  /**
10
10
  * Formats a ZodError as a human-readable sentence.
11
11
  *
@@ -3,7 +3,7 @@
3
3
  * @module src/utils/internal/error-handler/types
4
4
  */
5
5
  import type { JsonRpcErrorCode } from '../../../types-global/errors.js';
6
- import type { RequestContext } from '../../../utils/internal/requestContext.js';
6
+ import type { RequestContext } from '../requestContext.js';
7
7
  /**
8
8
  * Request context attached to an error for logging and tracing.
9
9
  *
@@ -4,8 +4,8 @@
4
4
  * @module src/utils/internal/health
5
5
  */
6
6
  import { config } from '../../config/index.js';
7
- import { logger } from '../../utils/internal/logger.js';
8
- import { runtimeCaps } from '../../utils/internal/runtime.js';
7
+ import { logger } from './logger.js';
8
+ import { runtimeCaps } from './runtime.js';
9
9
  /**
10
10
  * Returns a lightweight, synchronous health snapshot of the running server.
11
11
  *
@@ -5,7 +5,7 @@
5
5
  * @module src/utils/internal/lazyImport
6
6
  */
7
7
  import { configurationError } from '../../types-global/errors.js';
8
- import { logger } from '../../utils/internal/logger.js';
8
+ import { logger } from './logger.js';
9
9
  /**
10
10
  * Creates a lazy loader for an optional peer dependency that caches both
11
11
  * successful and failed import results.
@@ -1,4 +1,4 @@
1
- import { type RequestContext } from '../../utils/internal/requestContext.js';
1
+ import { type RequestContext } from './requestContext.js';
2
2
  /**
3
3
  * RFC 5424 severity levels supported by the MCP logger, ordered from least to most severe.
4
4
  * These map internally to Pino levels for transport compatibility:
@@ -68,7 +68,7 @@ export declare class Logger {
68
68
  * @returns The singleton `Logger` instance.
69
69
  * @example
70
70
  * ```ts
71
- * import { Logger } from '../../utils/internal/logger.js';
71
+ * import { Logger } from './logger.js';
72
72
  * const log = Logger.getInstance();
73
73
  * ```
74
74
  */
@@ -358,7 +358,7 @@ export declare class Logger {
358
358
  *
359
359
  * @example
360
360
  * ```ts
361
- * import { logger } from '../../utils/internal/logger.js';
361
+ * import { logger } from './logger.js';
362
362
  *
363
363
  * // At startup:
364
364
  * await logger.initialize('debug', 'http');
@@ -1,7 +1,7 @@
1
1
  import pino from 'pino';
2
2
  import { config } from '../../config/index.js';
3
- import { requestContextService, toCanonicalContext, } from '../../utils/internal/requestContext.js';
4
- import { UNTHROTTLED_MESSAGES } from '../../utils/internal/telemetryMessages.js';
3
+ import { requestContextService, toCanonicalContext, } from './requestContext.js';
4
+ import { UNTHROTTLED_MESSAGES } from './telemetryMessages.js';
5
5
  const mcpToPinoLevel = {
6
6
  emerg: 'fatal',
7
7
  alert: 'fatal',
@@ -181,7 +181,7 @@ export class Logger {
181
181
  * @returns The singleton `Logger` instance.
182
182
  * @example
183
183
  * ```ts
184
- * import { Logger } from '../../utils/internal/logger.js';
184
+ * import { Logger } from './logger.js';
185
185
  * const log = Logger.getInstance();
186
186
  * ```
187
187
  */
@@ -823,7 +823,7 @@ export class Logger {
823
823
  *
824
824
  * @example
825
825
  * ```ts
826
- * import { logger } from '../../utils/internal/logger.js';
826
+ * import { logger } from './logger.js';
827
827
  *
828
828
  * // At startup:
829
829
  * await logger.initialize('debug', 'http');
@@ -5,7 +5,7 @@
5
5
  * symmetric instrumentation so dashboards and traces cover the full MCP surface.
6
6
  * @module src/utils/internal/performance
7
7
  */
8
- import { type RequestContext } from '../../utils/internal/requestContext.js';
8
+ import { type RequestContext } from './requestContext.js';
9
9
  /** Eagerly creates tool, resource, and prompt metric instruments so series exist from startup. */
10
10
  export declare function initHandlerMetrics(): void;
11
11
  /**
@@ -9,12 +9,12 @@ import { SpanStatusCode, trace } from '@opentelemetry/api';
9
9
  import { config } from '../../config/index.js';
10
10
  import { isInputRequiredSignal } from '../../mcp-server/inputRequired.js';
11
11
  import { McpError } from '../../types-global/errors.js';
12
- import { getErrorCategory } from '../../utils/internal/error-handler/mappings.js';
13
- import { logger } from '../../utils/internal/logger.js';
14
- import { withActiveSpan, withExtra } from '../../utils/internal/requestContext.js';
15
- import { TELEMETRY_LOG_MESSAGES } from '../../utils/internal/telemetryMessages.js';
16
- import { ATTR_CODE_FUNCTION_NAME, ATTR_CODE_NAMESPACE, ATTR_MCP_PROMPT_DURATION_MS, ATTR_MCP_PROMPT_ERROR_CATEGORY, ATTR_MCP_PROMPT_ERROR_CODE, ATTR_MCP_PROMPT_INPUT_BYTES, ATTR_MCP_PROMPT_INPUT_REQUIRED, ATTR_MCP_PROMPT_MESSAGE_COUNT, ATTR_MCP_PROMPT_NAME, ATTR_MCP_PROMPT_OUTPUT_BYTES, ATTR_MCP_PROMPT_SUCCESS, ATTR_MCP_RESOURCE_DURATION_MS, ATTR_MCP_RESOURCE_ERROR_CODE, ATTR_MCP_RESOURCE_INPUT_REQUIRED, ATTR_MCP_RESOURCE_MIME_TYPE, ATTR_MCP_RESOURCE_NAME, ATTR_MCP_RESOURCE_SIZE_BYTES, ATTR_MCP_RESOURCE_SUCCESS, ATTR_MCP_RESOURCE_URI, ATTR_MCP_TOOL_BATCH_FAILED, ATTR_MCP_TOOL_BATCH_SUCCEEDED, ATTR_MCP_TOOL_DURATION_MS, ATTR_MCP_TOOL_ERROR_CATEGORY, ATTR_MCP_TOOL_ERROR_CODE, ATTR_MCP_TOOL_INPUT_BYTES, ATTR_MCP_TOOL_INPUT_REQUIRED, ATTR_MCP_TOOL_NAME, ATTR_MCP_TOOL_OUTPUT_BYTES, ATTR_MCP_TOOL_PARTIAL_SUCCESS, ATTR_MCP_TOOL_SUCCESS, } from '../../utils/telemetry/attributes.js';
17
- import { createCounter, createHistogram, createUpDownCounter } from '../../utils/telemetry/metrics.js';
12
+ import { getErrorCategory } from './error-handler/mappings.js';
13
+ import { logger } from './logger.js';
14
+ import { withActiveSpan, withExtra } from './requestContext.js';
15
+ import { TELEMETRY_LOG_MESSAGES } from './telemetryMessages.js';
16
+ import { ATTR_CODE_FUNCTION_NAME, ATTR_CODE_NAMESPACE, ATTR_MCP_PROMPT_DURATION_MS, ATTR_MCP_PROMPT_ERROR_CATEGORY, ATTR_MCP_PROMPT_ERROR_CODE, ATTR_MCP_PROMPT_INPUT_BYTES, ATTR_MCP_PROMPT_INPUT_REQUIRED, ATTR_MCP_PROMPT_MESSAGE_COUNT, ATTR_MCP_PROMPT_NAME, ATTR_MCP_PROMPT_OUTPUT_BYTES, ATTR_MCP_PROMPT_SUCCESS, ATTR_MCP_RESOURCE_DURATION_MS, ATTR_MCP_RESOURCE_ERROR_CODE, ATTR_MCP_RESOURCE_INPUT_REQUIRED, ATTR_MCP_RESOURCE_MIME_TYPE, ATTR_MCP_RESOURCE_NAME, ATTR_MCP_RESOURCE_SIZE_BYTES, ATTR_MCP_RESOURCE_SUCCESS, ATTR_MCP_RESOURCE_URI, ATTR_MCP_TOOL_BATCH_FAILED, ATTR_MCP_TOOL_BATCH_SUCCEEDED, ATTR_MCP_TOOL_DURATION_MS, ATTR_MCP_TOOL_ERROR_CATEGORY, ATTR_MCP_TOOL_ERROR_CODE, ATTR_MCP_TOOL_INPUT_BYTES, ATTR_MCP_TOOL_INPUT_REQUIRED, ATTR_MCP_TOOL_NAME, ATTR_MCP_TOOL_OUTPUT_BYTES, ATTR_MCP_TOOL_PARTIAL_SUCCESS, ATTR_MCP_TOOL_SUCCESS, } from '../telemetry/attributes.js';
17
+ import { createCounter, createHistogram, createUpDownCounter } from '../telemetry/metrics.js';
18
18
  // OTel metric instruments for tool execution (lazy-initialized on first use)
19
19
  let toolCallCounter;
20
20
  let toolCallDuration;
@@ -203,7 +203,7 @@ export interface CreateRequestContextParams {
203
203
  *
204
204
  * @example
205
205
  * ```typescript
206
- * import { requestContextService } from '../../utils/internal/requestContext.js';
206
+ * import { requestContextService } from './requestContext.js';
207
207
  *
208
208
  * // Create a root context for an incoming request
209
209
  * const ctx = requestContextService.createRequestContext({ operation: 'handleRequest' });
@@ -22,7 +22,7 @@
22
22
  */
23
23
  import { isSpanContextValid, trace } from '@opentelemetry/api';
24
24
  import { authContext as alsAuthContext } from '../../mcp-server/transports/auth/lib/authContext.js';
25
- import { generateRequestContextId } from '../../utils/security/idGenerator.js';
25
+ import { generateRequestContextId } from '../security/idGenerator.js';
26
26
  /** Maps validated token info to the context-facing auth shape. */
27
27
  function toAuthContext(info) {
28
28
  return {
@@ -243,7 +243,7 @@ const requestContextServiceInstance = {
243
243
  *
244
244
  * @example
245
245
  * ```typescript
246
- * import { requestContextService } from '../../utils/internal/requestContext.js';
246
+ * import { requestContextService } from './requestContext.js';
247
247
  *
248
248
  * // Create a root context for an incoming request
249
249
  * const ctx = requestContextService.createRequestContext({ operation: 'handleRequest' });
@@ -1,4 +1,4 @@
1
- import type { RequestContext } from '../../utils/internal/requestContext.js';
1
+ import type { RequestContext } from '../internal/requestContext.js';
2
2
  /**
3
3
  * Minimal chat message shape used for token counting, intentionally provider-agnostic.
4
4
  * Covers the common subset of OpenAI-style chat message fields without depending on
@@ -5,8 +5,8 @@
5
5
  * @module src/utils/metrics/tokenCounter
6
6
  */
7
7
  import { JsonRpcErrorCode } from '../../types-global/errors.js';
8
- import { ErrorHandler } from '../../utils/internal/error-handler/errorHandler.js';
9
- import { logger } from '../../utils/internal/logger.js';
8
+ import { ErrorHandler } from '../internal/error-handler/errorHandler.js';
9
+ import { logger } from '../internal/logger.js';
10
10
  const DEFAULT_MODEL = 'gpt-4o';
11
11
  // Known heuristics; tweak as you calibrate
12
12
  const HEURISTICS = {
@@ -1,4 +1,4 @@
1
- import { type RequestContext } from '../../utils/internal/requestContext.js';
1
+ import { type RequestContext } from '../internal/requestContext.js';
2
2
  /** Eagerly creates the HTTP client duration histogram so the series exists from startup. */
3
3
  export declare function initHttpClientMetrics(): void;
4
4
  /**
@@ -4,12 +4,12 @@
4
4
  * @module src/utils/network/fetchWithTimeout
5
5
  */
6
6
  import { JsonRpcErrorCode, McpError, requestCancelled, serviceUnavailable, timeout, validationError, } from '../../types-global/errors.js';
7
- import { logger } from '../../utils/internal/logger.js';
8
- import { withExtra } from '../../utils/internal/requestContext.js';
9
- import { runtimeCaps } from '../../utils/internal/runtime.js';
10
- import { httpStatusRetryability, httpStatusToErrorCode } from '../../utils/network/httpError.js';
11
- import { readBoundedResponseText } from '../../utils/network/responseBody.js';
12
- import { createHistogram } from '../../utils/telemetry/metrics.js';
7
+ import { logger } from '../internal/logger.js';
8
+ import { withExtra } from '../internal/requestContext.js';
9
+ import { runtimeCaps } from '../internal/runtime.js';
10
+ import { httpStatusRetryability, httpStatusToErrorCode } from './httpError.js';
11
+ import { readBoundedResponseText } from './responseBody.js';
12
+ import { createHistogram } from '../telemetry/metrics.js';
13
13
  /** Default captured bytes of an upstream error response body. Keeps tool errors from poisoning the agent's context. */
14
14
  const ERROR_BODY_LIMIT = 500;
15
15
  /**
@@ -5,7 +5,7 @@
5
5
  * @module src/utils/network/httpError
6
6
  */
7
7
  import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
8
- import { readBoundedResponseText } from '../../utils/network/responseBody.js';
8
+ import { readBoundedResponseText } from './responseBody.js';
9
9
  /**
10
10
  * Maps an HTTP status code to a `JsonRpcErrorCode`. Covers the full client/server
11
11
  * 4xx/5xx range, with specific mappings for the codes most upstream APIs use to
@@ -1,4 +1,4 @@
1
- import type { RequestContext } from '../../utils/internal/requestContext.js';
1
+ import type { RequestContext } from '../internal/requestContext.js';
2
2
  /** Configuration for {@link withRetry}. */
3
3
  export interface RetryOptions {
4
4
  /**
@@ -5,7 +5,7 @@
5
5
  * @module src/utils/network/retry
6
6
  */
7
7
  import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
8
- import { logger } from '../../utils/internal/logger.js';
8
+ import { logger } from '../internal/logger.js';
9
9
  /**
10
10
  * Error codes considered transient — eligible for retry.
11
11
  * Matches the framework's error classification in `mappings.ts`.
@@ -11,7 +11,7 @@
11
11
  * @see {@link https://modelcontextprotocol.io/specification/2025-06-18/utils/pagination | MCP Pagination Spec}
12
12
  * @module src/utils/pagination/pagination
13
13
  */
14
- import { type RequestContext } from '../../utils/internal/requestContext.js';
14
+ import { type RequestContext } from '../internal/requestContext.js';
15
15
  /**
16
16
  * Generic pagination state that can be encoded into a cursor.
17
17
  * Implementations can extend this with additional fields as needed.
@@ -137,7 +137,7 @@ export declare function paginateArray<T>(items: T[], cursorStr: string | undefin
137
137
  * or defer to environment-variable-driven config parsed in the config module.
138
138
  *
139
139
  * @example
140
- * import { DEFAULT_PAGINATION_CONFIG, paginateArray } from '../../utils/pagination/pagination.js';
140
+ * import { DEFAULT_PAGINATION_CONFIG, paginateArray } from './pagination.js';
141
141
  * const result = paginateArray(
142
142
  * items,
143
143
  * cursorStr,
@@ -12,9 +12,9 @@
12
12
  * @module src/utils/pagination/pagination
13
13
  */
14
14
  import { invalidParams, JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
15
- import { base64ToString, stringToBase64 } from '../../utils/internal/encoding.js';
16
- import { logger } from '../../utils/internal/logger.js';
17
- import { withExtra } from '../../utils/internal/requestContext.js';
15
+ import { base64ToString, stringToBase64 } from '../internal/encoding.js';
16
+ import { logger } from '../internal/logger.js';
17
+ import { withExtra } from '../internal/requestContext.js';
18
18
  /**
19
19
  * Encodes pagination state into an opaque base64url cursor string.
20
20
  * Serializes `state` to JSON, then encodes as base64url (URL-safe, no padding).
@@ -171,7 +171,7 @@ export function paginateArray(items, cursorStr, defaultPageSize, maxPageSize, co
171
171
  * or defer to environment-variable-driven config parsed in the config module.
172
172
  *
173
173
  * @example
174
- * import { DEFAULT_PAGINATION_CONFIG, paginateArray } from '../../utils/pagination/pagination.js';
174
+ * import { DEFAULT_PAGINATION_CONFIG, paginateArray } from './pagination.js';
175
175
  * const result = paginateArray(
176
176
  * items,
177
177
  * cursorStr,
@@ -8,7 +8,7 @@
8
8
  * @module src/utils/parsing/csvParser
9
9
  */
10
10
  import type Papa from 'papaparse';
11
- import { type RequestContext } from '../../utils/internal/requestContext.js';
11
+ import { type RequestContext } from '../internal/requestContext.js';
12
12
  /**
13
13
  * Utility class for parsing CSV strings.
14
14
  *
@@ -40,7 +40,7 @@ export declare class CsvParser {
40
40
  * the `<think>` block, or if `papaparse` reports parse errors.
41
41
  * @example
42
42
  * ```typescript
43
- * import { csvParser } from '../../utils/parsing/csvParser.js';
43
+ * import { csvParser } from './csvParser.js';
44
44
  *
45
45
  * // Parse with header row — rows typed as objects
46
46
  * const result = await csvParser.parse<{ name: string; age: string }>(
@@ -64,14 +64,14 @@ export declare class CsvParser {
64
64
  *
65
65
  * @example
66
66
  * ```typescript
67
- * import { csvParser } from '../../utils/parsing/csvParser.js';
67
+ * import { csvParser } from './csvParser.js';
68
68
  *
69
69
  * // Parse with header row
70
70
  * const result = await csvParser.parse<{ a: string; b: string }>('a,b\n1,2', { header: true });
71
71
  * console.log(result.data[0]); // { a: '1', b: '2' }
72
72
  *
73
73
  * // With request context for correlated logging
74
- * import { requestContextService } from '../../utils/internal/requestContext.js';
74
+ * import { requestContextService } from '../internal/requestContext.js';
75
75
  * const ctx = requestContextService.createRequestContext({ operation: 'importData' });
76
76
  * const imported = await csvParser.parse(rawCsv, { header: true, dynamicTyping: true }, ctx);
77
77
  *
@@ -1,7 +1,7 @@
1
1
  import { validationError } from '../../types-global/errors.js';
2
- import { lazyImport } from '../../utils/internal/lazyImport.js';
3
- import { logger } from '../../utils/internal/logger.js';
4
- import { requestContextService, withExtra, } from '../../utils/internal/requestContext.js';
2
+ import { lazyImport } from '../internal/lazyImport.js';
3
+ import { logger } from '../internal/logger.js';
4
+ import { requestContextService, withExtra, } from '../internal/requestContext.js';
5
5
  import { thinkBlockRegex } from './thinkBlock.js';
6
6
  const importPapa = lazyImport(() => import('papaparse'), 'Install "papaparse" to use CSV parsing: bun add papaparse');
7
7
  let _papa;
@@ -44,7 +44,7 @@ export class CsvParser {
44
44
  * the `<think>` block, or if `papaparse` reports parse errors.
45
45
  * @example
46
46
  * ```typescript
47
- * import { csvParser } from '../../utils/parsing/csvParser.js';
47
+ * import { csvParser } from './csvParser.js';
48
48
  *
49
49
  * // Parse with header row — rows typed as objects
50
50
  * const result = await csvParser.parse<{ name: string; age: string }>(
@@ -108,14 +108,14 @@ export class CsvParser {
108
108
  *
109
109
  * @example
110
110
  * ```typescript
111
- * import { csvParser } from '../../utils/parsing/csvParser.js';
111
+ * import { csvParser } from './csvParser.js';
112
112
  *
113
113
  * // Parse with header row
114
114
  * const result = await csvParser.parse<{ a: string; b: string }>('a,b\n1,2', { header: true });
115
115
  * console.log(result.data[0]); // { a: '1', b: '2' }
116
116
  *
117
117
  * // With request context for correlated logging
118
- * import { requestContextService } from '../../utils/internal/requestContext.js';
118
+ * import { requestContextService } from '../internal/requestContext.js';
119
119
  * const ctx = requestContextService.createRequestContext({ operation: 'importData' });
120
120
  * const imported = await csvParser.parse(rawCsv, { header: true, dynamicTyping: true }, ctx);
121
121
  *
@@ -4,7 +4,7 @@
4
4
  * @module src/utils/parsing/dateParser
5
5
  */
6
6
  import type * as chrono from 'chrono-node';
7
- import { type RequestContext } from '../../utils/internal/requestContext.js';
7
+ import { type RequestContext } from '../internal/requestContext.js';
8
8
  /**
9
9
  * Parses a natural language date string into a JavaScript `Date` object.
10
10
  *
@@ -57,8 +57,8 @@ export declare function parseDateStringDetailed(text: string, context: RequestCo
57
57
  *
58
58
  * @example
59
59
  * ```typescript
60
- * import { dateParser } from '../../utils/parsing/dateParser.js';
61
- * import { requestContextService } from '../../utils/internal/requestContext.js';
60
+ * import { dateParser } from './dateParser.js';
61
+ * import { requestContextService } from '../internal/requestContext.js';
62
62
  *
63
63
  * const ctx = requestContextService.createRequestContext({ operation: 'myOp' });
64
64
  *
@@ -1,8 +1,8 @@
1
1
  import { JsonRpcErrorCode } from '../../types-global/errors.js';
2
- import { ErrorHandler } from '../../utils/internal/error-handler/errorHandler.js';
3
- import { lazyImport } from '../../utils/internal/lazyImport.js';
4
- import { logger } from '../../utils/internal/logger.js';
5
- import { withExtra } from '../../utils/internal/requestContext.js';
2
+ import { ErrorHandler } from '../internal/error-handler/errorHandler.js';
3
+ import { lazyImport } from '../internal/lazyImport.js';
4
+ import { logger } from '../internal/logger.js';
5
+ import { withExtra } from '../internal/requestContext.js';
6
6
  const getChrono = lazyImport(() => import('chrono-node'), 'Install "chrono-node" to use date parsing: bun add chrono-node');
7
7
  /**
8
8
  * Parses a natural language date string into a JavaScript `Date` object.
@@ -95,8 +95,8 @@ export async function parseDateStringDetailed(text, context, refDate) {
95
95
  *
96
96
  * @example
97
97
  * ```typescript
98
- * import { dateParser } from '../../utils/parsing/dateParser.js';
99
- * import { requestContextService } from '../../utils/internal/requestContext.js';
98
+ * import { dateParser } from './dateParser.js';
99
+ * import { requestContextService } from '../internal/requestContext.js';
100
100
  *
101
101
  * const ctx = requestContextService.createRequestContext({ operation: 'myOp' });
102
102
  *
@@ -1,4 +1,4 @@
1
- import { type RequestContext } from '../../utils/internal/requestContext.js';
1
+ import { type RequestContext } from '../internal/requestContext.js';
2
2
  import { type ParserInputBudgetOptions } from './inputBudget.js';
3
3
  /**
4
4
  * Result of parsing markdown with frontmatter.
@@ -63,7 +63,7 @@ export declare class FrontmatterParser {
63
63
  * @example
64
64
  * ```typescript
65
65
  * import { frontmatterParser } from './frontmatterParser.js';
66
- * import { requestContextService } from '../../utils/internal/requestContext.js';
66
+ * import { requestContextService } from '../internal/requestContext.js';
67
67
  *
68
68
  * const context = requestContextService.createRequestContext({ operation: 'ParseObsidianNote' });
69
69
  *
@@ -5,8 +5,8 @@
5
5
  * @module src/utils/parsing/frontmatterParser
6
6
  */
7
7
  import { McpError, validationError } from '../../types-global/errors.js';
8
- import { logger } from '../../utils/internal/logger.js';
9
- import { requestContextService, withExtra, } from '../../utils/internal/requestContext.js';
8
+ import { logger } from '../internal/logger.js';
9
+ import { requestContextService, withExtra, } from '../internal/requestContext.js';
10
10
  import { assertTextInputBudget } from './inputBudget.js';
11
11
  import { yamlParser } from './yamlParser.js';
12
12
  /**
@@ -129,7 +129,7 @@ export class FrontmatterParser {
129
129
  * @example
130
130
  * ```typescript
131
131
  * import { frontmatterParser } from './frontmatterParser.js';
132
- * import { requestContextService } from '../../utils/internal/requestContext.js';
132
+ * import { requestContextService } from '../internal/requestContext.js';
133
133
  *
134
134
  * const context = requestContextService.createRequestContext({ operation: 'ParseObsidianNote' });
135
135
  *
@@ -1,4 +1,4 @@
1
- import { type RequestContext } from '../../utils/internal/requestContext.js';
1
+ import { type RequestContext } from '../internal/requestContext.js';
2
2
  /**
3
3
  * Options for HTML article extraction.
4
4
  */
@@ -113,7 +113,7 @@ export declare class HtmlExtractor {
113
113
  *
114
114
  * @example
115
115
  * ```typescript
116
- * import { htmlExtractor } from '../../utils/parsing/htmlExtractor.js';
116
+ * import { htmlExtractor } from './htmlExtractor.js';
117
117
  *
118
118
  * const html = await fetch('https://example.com/article').then((r) => r.text());
119
119
  * const result = await htmlExtractor.extract(html, {
@@ -136,7 +136,7 @@ export declare class HtmlExtractor {
136
136
  *
137
137
  * @example
138
138
  * ```typescript
139
- * import { htmlExtractor } from '../../utils/parsing/htmlExtractor.js';
139
+ * import { htmlExtractor } from './htmlExtractor.js';
140
140
  *
141
141
  * const article = await htmlExtractor.extract(rawHtml, {
142
142
  * url: 'https://example.com/post',
@@ -1,7 +1,7 @@
1
1
  import { McpError, validationError } from '../../types-global/errors.js';
2
- import { lazyImport } from '../../utils/internal/lazyImport.js';
3
- import { logger } from '../../utils/internal/logger.js';
4
- import { requestContextService, withExtra, } from '../../utils/internal/requestContext.js';
2
+ import { lazyImport } from '../internal/lazyImport.js';
3
+ import { logger } from '../internal/logger.js';
4
+ import { requestContextService, withExtra, } from '../internal/requestContext.js';
5
5
  import { assertTextInputBudget } from './inputBudget.js';
6
6
  const getDefuddle = lazyImport(() => import('defuddle/node'), 'Install "defuddle" to use HTML article extraction: bun add defuddle linkedom');
7
7
  const getLinkedom = lazyImport(() => import('linkedom'), 'Install "linkedom" to use HTML article extraction: bun add defuddle linkedom');
@@ -53,7 +53,7 @@ export class HtmlExtractor {
53
53
  *
54
54
  * @example
55
55
  * ```typescript
56
- * import { htmlExtractor } from '../../utils/parsing/htmlExtractor.js';
56
+ * import { htmlExtractor } from './htmlExtractor.js';
57
57
  *
58
58
  * const html = await fetch('https://example.com/article').then((r) => r.text());
59
59
  * const result = await htmlExtractor.extract(html, {
@@ -151,7 +151,7 @@ export class HtmlExtractor {
151
151
  *
152
152
  * @example
153
153
  * ```typescript
154
- * import { htmlExtractor } from '../../utils/parsing/htmlExtractor.js';
154
+ * import { htmlExtractor } from './htmlExtractor.js';
155
155
  *
156
156
  * const article = await htmlExtractor.extract(rawHtml, {
157
157
  * url: 'https://example.com/post',
@@ -1,4 +1,4 @@
1
- import { type RequestContext } from '../../utils/internal/requestContext.js';
1
+ import { type RequestContext } from '../internal/requestContext.js';
2
2
  import { type ParserInputBudgetOptions } from './inputBudget.js';
3
3
  /**
4
4
  * Bit flags specifying which partial JSON types are permissible during parsing.
@@ -77,7 +77,7 @@ export declare class JsonParser {
77
77
  * @throws {McpError} With `ConfigurationError` if the `partial-json` package is not installed.
78
78
  * @example
79
79
  * ```typescript
80
- * import { jsonParser, Allow } from '../../utils/parsing/jsonParser.js';
80
+ * import { jsonParser, Allow } from './jsonParser.js';
81
81
  *
82
82
  * // Parse complete JSON
83
83
  * const obj = await jsonParser.parse<{ key: string }>('{"key": "value"}');
@@ -99,8 +99,8 @@ export declare class JsonParser {
99
99
  *
100
100
  * @example
101
101
  * ```typescript
102
- * import { jsonParser, Allow } from '../../utils/parsing/jsonParser.js';
103
- * import { requestContextService } from '../../utils/internal/requestContext.js';
102
+ * import { jsonParser, Allow } from './jsonParser.js';
103
+ * import { requestContextService } from '../internal/requestContext.js';
104
104
  *
105
105
  * const ctx = requestContextService.createRequestContext({ operation: 'myOp' });
106
106
  *