@cyanheads/mcp-ts-core 0.13.5 → 0.13.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 (157) hide show
  1. package/AGENTS.md +6 -6
  2. package/CLAUDE.md +6 -6
  3. package/README.md +55 -52
  4. package/biome.json +2 -2
  5. package/changelog/0.13.x/0.13.6.md +49 -0
  6. package/changelog/0.13.x/0.13.7.md +77 -0
  7. package/config/tsconfig.base.json +2 -2
  8. package/dist/config/index.d.ts.map +1 -1
  9. package/dist/config/index.js +42 -11
  10. package/dist/config/index.js.map +1 -1
  11. package/dist/core/app.d.ts.map +1 -1
  12. package/dist/core/app.js +21 -4
  13. package/dist/core/app.js.map +1 -1
  14. package/dist/core/context.d.ts +9 -1
  15. package/dist/core/context.d.ts.map +1 -1
  16. package/dist/core/context.js +4 -13
  17. package/dist/core/context.js.map +1 -1
  18. package/dist/core/worker.d.ts.map +1 -1
  19. package/dist/core/worker.js +7 -1
  20. package/dist/core/worker.js.map +1 -1
  21. package/dist/linter/rules/enrichment-rules.d.ts +5 -4
  22. package/dist/linter/rules/enrichment-rules.d.ts.map +1 -1
  23. package/dist/linter/rules/enrichment-rules.js +99 -22
  24. package/dist/linter/rules/enrichment-rules.js.map +1 -1
  25. package/dist/linter/rules/error-contract-rules.d.ts +46 -10
  26. package/dist/linter/rules/error-contract-rules.d.ts.map +1 -1
  27. package/dist/linter/rules/error-contract-rules.js +180 -27
  28. package/dist/linter/rules/error-contract-rules.js.map +1 -1
  29. package/dist/linter/rules/format-parity-rules.js +1 -1
  30. package/dist/linter/rules/format-parity-rules.js.map +1 -1
  31. package/dist/linter/rules/index.d.ts +1 -1
  32. package/dist/linter/rules/index.d.ts.map +1 -1
  33. package/dist/linter/rules/index.js +1 -1
  34. package/dist/linter/rules/index.js.map +1 -1
  35. package/dist/linter/rules/resource-rules.d.ts.map +1 -1
  36. package/dist/linter/rules/resource-rules.js +2 -1
  37. package/dist/linter/rules/resource-rules.js.map +1 -1
  38. package/dist/linter/rules/tool-rules.d.ts.map +1 -1
  39. package/dist/linter/rules/tool-rules.js +2 -1
  40. package/dist/linter/rules/tool-rules.js.map +1 -1
  41. package/dist/mcp-server/handlerContext.d.ts +6 -0
  42. package/dist/mcp-server/handlerContext.d.ts.map +1 -1
  43. package/dist/mcp-server/handlerContext.js +3 -0
  44. package/dist/mcp-server/handlerContext.js.map +1 -1
  45. package/dist/mcp-server/prompts/prompt-registration.d.ts.map +1 -1
  46. package/dist/mcp-server/prompts/prompt-registration.js +6 -3
  47. package/dist/mcp-server/prompts/prompt-registration.js.map +1 -1
  48. package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts.map +1 -1
  49. package/dist/mcp-server/tools/utils/toolHandlerFactory.js +5 -1
  50. package/dist/mcp-server/tools/utils/toolHandlerFactory.js.map +1 -1
  51. package/dist/mcp-server/transports/http/httpErrorHandler.d.ts.map +1 -1
  52. package/dist/mcp-server/transports/http/httpErrorHandler.js +15 -5
  53. package/dist/mcp-server/transports/http/httpErrorHandler.js.map +1 -1
  54. package/dist/storage/core/IStorageProvider.d.ts +5 -2
  55. package/dist/storage/core/IStorageProvider.d.ts.map +1 -1
  56. package/dist/storage/core/providerHelpers.d.ts +29 -8
  57. package/dist/storage/core/providerHelpers.d.ts.map +1 -1
  58. package/dist/storage/core/providerHelpers.js +49 -11
  59. package/dist/storage/core/providerHelpers.js.map +1 -1
  60. package/dist/storage/providers/cloudflare/d1Provider.js +4 -4
  61. package/dist/storage/providers/cloudflare/d1Provider.js.map +1 -1
  62. package/dist/storage/providers/cloudflare/kvProvider.d.ts +2 -0
  63. package/dist/storage/providers/cloudflare/kvProvider.d.ts.map +1 -1
  64. package/dist/storage/providers/cloudflare/kvProvider.js +11 -9
  65. package/dist/storage/providers/cloudflare/kvProvider.js.map +1 -1
  66. package/dist/storage/providers/cloudflare/r2Provider.d.ts.map +1 -1
  67. package/dist/storage/providers/cloudflare/r2Provider.js +8 -5
  68. package/dist/storage/providers/cloudflare/r2Provider.js.map +1 -1
  69. package/dist/storage/providers/fileSystem/fileSystemProvider.d.ts +1 -0
  70. package/dist/storage/providers/fileSystem/fileSystemProvider.d.ts.map +1 -1
  71. package/dist/storage/providers/fileSystem/fileSystemProvider.js +10 -8
  72. package/dist/storage/providers/fileSystem/fileSystemProvider.js.map +1 -1
  73. package/dist/storage/providers/inMemory/inMemoryProvider.d.ts +5 -0
  74. package/dist/storage/providers/inMemory/inMemoryProvider.d.ts.map +1 -1
  75. package/dist/storage/providers/inMemory/inMemoryProvider.js +9 -5
  76. package/dist/storage/providers/inMemory/inMemoryProvider.js.map +1 -1
  77. package/dist/storage/providers/supabase/supabaseProvider.d.ts.map +1 -1
  78. package/dist/storage/providers/supabase/supabaseProvider.js +5 -1
  79. package/dist/storage/providers/supabase/supabaseProvider.js.map +1 -1
  80. package/dist/testing/index.d.ts +6 -4
  81. package/dist/testing/index.d.ts.map +1 -1
  82. package/dist/testing/index.js +6 -4
  83. package/dist/testing/index.js.map +1 -1
  84. package/dist/types-global/errors.d.ts +18 -0
  85. package/dist/types-global/errors.d.ts.map +1 -1
  86. package/dist/utils/formatting/partialResult.d.ts +28 -2
  87. package/dist/utils/formatting/partialResult.d.ts.map +1 -1
  88. package/dist/utils/formatting/partialResult.js +46 -2
  89. package/dist/utils/formatting/partialResult.js.map +1 -1
  90. package/dist/utils/internal/error-handler/errorHandler.d.ts +8 -2
  91. package/dist/utils/internal/error-handler/errorHandler.d.ts.map +1 -1
  92. package/dist/utils/internal/error-handler/errorHandler.js +27 -16
  93. package/dist/utils/internal/error-handler/errorHandler.js.map +1 -1
  94. package/dist/utils/internal/error-handler/mappings.d.ts +1 -0
  95. package/dist/utils/internal/error-handler/mappings.d.ts.map +1 -1
  96. package/dist/utils/internal/error-handler/mappings.js +1 -0
  97. package/dist/utils/internal/error-handler/mappings.js.map +1 -1
  98. package/dist/utils/internal/performance.d.ts +5 -1
  99. package/dist/utils/internal/performance.d.ts.map +1 -1
  100. package/dist/utils/internal/performance.js +13 -8
  101. package/dist/utils/internal/performance.js.map +1 -1
  102. package/dist/utils/security/sanitization.d.ts +15 -15
  103. package/dist/utils/security/sanitization.d.ts.map +1 -1
  104. package/dist/utils/security/sanitization.js +108 -88
  105. package/dist/utils/security/sanitization.js.map +1 -1
  106. package/dist/utils/telemetry/instrumentation.d.ts +6 -2
  107. package/dist/utils/telemetry/instrumentation.d.ts.map +1 -1
  108. package/dist/utils/telemetry/instrumentation.js +23 -8
  109. package/dist/utils/telemetry/instrumentation.js.map +1 -1
  110. package/framework-skills/add-app-tool/SKILL.md +12 -18
  111. package/framework-skills/add-prompt/SKILL.md +3 -1
  112. package/framework-skills/add-provider/SKILL.md +14 -4
  113. package/framework-skills/add-resource/SKILL.md +3 -3
  114. package/framework-skills/add-service/SKILL.md +5 -2
  115. package/framework-skills/add-tool/SKILL.md +25 -8
  116. package/framework-skills/api-canvas/SKILL.md +2 -2
  117. package/framework-skills/api-config/SKILL.md +4 -3
  118. package/framework-skills/api-context/SKILL.md +8 -5
  119. package/framework-skills/api-errors/SKILL.md +25 -5
  120. package/framework-skills/api-linter/SKILL.md +95 -22
  121. package/framework-skills/api-telemetry/SKILL.md +9 -4
  122. package/framework-skills/api-testing/SKILL.md +21 -13
  123. package/framework-skills/api-utils/SKILL.md +3 -3
  124. package/framework-skills/api-utils/references/security.md +7 -6
  125. package/framework-skills/code-simplifier/SKILL.md +31 -18
  126. package/framework-skills/design-mcp-server/SKILL.md +62 -35
  127. package/framework-skills/git-wrapup/SKILL.md +16 -10
  128. package/framework-skills/maintenance/SKILL.md +2 -2
  129. package/framework-skills/orchestrations/SKILL.md +1 -1
  130. package/framework-skills/orchestrations/workflows/greenfield-build.md +15 -8
  131. package/framework-skills/polish-docs-meta/SKILL.md +2 -2
  132. package/framework-skills/polish-docs-meta/references/package-meta.md +1 -1
  133. package/framework-skills/polish-docs-meta/references/readme.md +3 -3
  134. package/framework-skills/release-and-publish/SKILL.md +6 -4
  135. package/framework-skills/release-pr-review/SKILL.md +18 -1
  136. package/framework-skills/report-issue-framework/SKILL.md +2 -2
  137. package/framework-skills/report-issue-local/SKILL.md +3 -3
  138. package/framework-skills/security-pass/SKILL.md +11 -3
  139. package/framework-skills/tool-defs-analysis/SKILL.md +3 -3
  140. package/package.json +16 -37
  141. package/scripts/lint-mcp.ts +43 -4
  142. package/templates/.env.example +3 -1
  143. package/templates/.github/ISSUE_TEMPLATE/feature_request.yml +1 -1
  144. package/templates/AGENTS.md +3 -3
  145. package/templates/CLAUDE.md +3 -3
  146. package/templates/Dockerfile +4 -4
  147. package/templates/devcheck.config.json +1 -0
  148. package/templates/package.json +4 -4
  149. package/templates/src/mcp-server/prompts/definitions/echo.prompt.ts +2 -4
  150. package/templates/src/mcp-server/resources/definitions/echo-app-ui.app-resource.ts +51 -14
  151. package/templates/src/mcp-server/resources/definitions/echo.resource.ts +1 -1
  152. package/templates/src/mcp-server/tools/definitions/echo-app.app-tool.ts +2 -3
  153. package/templates/src/mcp-server/tools/definitions/echo.tool.ts +8 -2
  154. package/dist/utils/telemetry/index.d.ts +0 -12
  155. package/dist/utils/telemetry/index.d.ts.map +0 -1
  156. package/dist/utils/telemetry/index.js +0 -12
  157. package/dist/utils/telemetry/index.js.map +0 -1
package/templates/src/mcp-server/resources/definitions/echo-app-ui.app-resource.ts CHANGED
@@ -18,31 +18,69 @@ const APP_HTML = `<!DOCTYPE html>
18
18
  <meta name="viewport" content="width=device-width, initial-scale=1" />
19
19
  <title>Echo App</title>
20
20
  <style>
21
+ /*
22
+ * Local tokens are the pre-connect baseline: light by default, dark when the
23
+ * OS prefers it, and pinned by the data-theme attribute applyDocumentTheme sets.
24
+ * Every rule reads the host's variable first (installed by applyHostStyleVariables)
25
+ * and falls back to the local token until host context arrives.
26
+ */
27
+ :root {
28
+ color-scheme: light dark;
29
+ --bg: #ffffff; --surface: #f8fafc; --fg: #0f172a; --muted: #64748b;
30
+ --border: #e2e8f0; --accent: #2563eb; --accent-fg: #ffffff;
31
+ }
32
+ @media (prefers-color-scheme: dark) {
33
+ :root:not([data-theme="light"]) {
34
+ --bg: #0f172a; --surface: #1e293b; --fg: #e2e8f0; --muted: #94a3b8;
35
+ --border: #334155; --accent: #3b82f6; --accent-fg: #ffffff;
36
+ }
37
+ }
38
+ :root[data-theme="dark"] {
39
+ --bg: #0f172a; --surface: #1e293b; --fg: #e2e8f0; --muted: #94a3b8;
40
+ --border: #334155; --accent: #3b82f6; --accent-fg: #ffffff;
41
+ }
21
42
  * { margin: 0; padding: 0; box-sizing: border-box; }
22
43
  body {
23
- font-family: system-ui, -apple-system, sans-serif;
24
- background: #0f172a; color: #e2e8f0;
44
+ font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
45
+ background: var(--color-background-primary, var(--bg));
46
+ color: var(--color-text-primary, var(--fg));
25
47
  padding: 1.5rem; min-height: 100vh;
26
48
  display: flex; flex-direction: column; align-items: center; gap: 1rem;
27
49
  }
28
- h1 { font-size: 1.25rem; font-weight: 600; }
50
+ h1 {
51
+ font-size: var(--font-heading-sm-size, 1.25rem);
52
+ font-weight: var(--font-weight-semibold, 600);
53
+ }
29
54
  .card {
30
- background: #1e293b; border: 1px solid #334155; border-radius: 0.5rem;
55
+ background: var(--color-background-secondary, var(--surface));
56
+ border: 1px solid var(--color-border-primary, var(--border));
57
+ border-radius: var(--border-radius-lg, 0.5rem);
31
58
  padding: 1rem 1.25rem; width: 100%; max-width: 480px;
32
59
  }
33
- .label { font-size: 0.75rem; color: #94a3b8; text-transform: uppercase; letter-spacing: 0.05em; }
34
- .value { font-size: 1rem; margin-top: 0.25rem; word-break: break-word; }
60
+ .label {
61
+ font-size: var(--font-text-xs-size, 0.75rem);
62
+ color: var(--color-text-secondary, var(--muted));
63
+ text-transform: uppercase; letter-spacing: 0.05em;
64
+ }
65
+ .value { font-size: var(--font-text-md-size, 1rem); margin-top: 0.25rem; word-break: break-word; }
35
66
  .controls { display: flex; gap: 0.5rem; width: 100%; max-width: 480px; }
36
67
  input[type="text"] {
37
- flex: 1; padding: 0.5rem 0.75rem; background: #1e293b; border: 1px solid #334155;
38
- border-radius: 0.375rem; color: #e2e8f0; font-size: 0.875rem; outline: none;
68
+ flex: 1; padding: 0.5rem 0.75rem;
69
+ background: var(--color-background-secondary, var(--surface));
70
+ border: 1px solid var(--color-border-primary, var(--border));
71
+ border-radius: var(--border-radius-md, 0.375rem);
72
+ color: var(--color-text-primary, var(--fg));
73
+ font: inherit; font-size: var(--font-text-sm-size, 0.875rem); outline: none;
39
74
  }
40
- input[type="text"]:focus { border-color: #3b82f6; }
75
+ input[type="text"]:focus { border-color: var(--color-ring-primary, var(--accent)); }
41
76
  button {
42
- padding: 0.5rem 1rem; background: #3b82f6; color: #fff; border: none;
43
- border-radius: 0.375rem; font-size: 0.875rem; cursor: pointer;
77
+ padding: 0.5rem 1rem; border: none;
78
+ background: var(--color-background-inverse, var(--accent));
79
+ color: var(--color-text-inverse, var(--accent-fg));
80
+ border-radius: var(--border-radius-md, 0.375rem);
81
+ font: inherit; font-size: var(--font-text-sm-size, 0.875rem); cursor: pointer;
44
82
  }
45
- button:hover { background: #2563eb; }
83
+ button:hover { opacity: 0.9; }
46
84
  button:disabled { opacity: 0.5; cursor: not-allowed; }
47
85
  </style>
48
86
  </head>
@@ -138,8 +176,7 @@ export const echoAppUiResource = appResource('ui://template-echo-app/app.html',
138
176
  name: 'echo-app-ui',
139
177
  title: 'Echo App UI',
140
178
  description:
141
- 'Interactive HTML app for the echo app tool. Displayed as a sandboxed iframe ' +
142
- 'by MCP Apps-capable hosts.',
179
+ 'Interactive HTML app for the echo app tool. Displayed as a sandboxed iframe by MCP Apps-capable hosts.',
143
180
  params: ParamsSchema,
144
181
  auth: ['resource:echo-app-ui:read'],
145
182
  _meta: {
package/templates/src/mcp-server/resources/definitions/echo.resource.ts CHANGED
@@ -9,7 +9,7 @@ import { resource, z } from '@cyanheads/mcp-ts-core';
9
9
  // Like tools, prefix names with your server name: template-echo, tasks-status, etc.
10
10
  export const echoResource = resource('echo://{message}', {
11
11
  name: 'template-echo-resource',
12
- description: 'Echoes a message from the URI. Replace this with your first real resource.',
12
+ description: 'Echo a message from the URI. Replace this with your first real resource.',
13
13
  mimeType: 'application/json',
14
14
  params: z.object({
15
15
  message: z.string().describe('The message to echo back.'),
package/templates/src/mcp-server/tools/definitions/echo-app.app-tool.ts CHANGED
@@ -15,15 +15,14 @@ export const echoAppTool = appTool('template_echo_app', {
15
15
  resourceUri: UI_RESOURCE_URI,
16
16
  title: 'Echo App',
17
17
  description:
18
- 'Echoes a message with an interactive UI. Demonstrates MCP Apps — hosts that support ' +
19
- 'the extension render an HTML interface; others receive a text fallback.',
18
+ 'Echo a message back with an interactive UI. Hosts that support MCP Apps render an HTML interface; other hosts receive a text fallback.',
20
19
  annotations: { readOnlyHint: true },
21
20
  input: z.object({
22
21
  message: z.string().describe('The message to echo.'),
23
22
  }),
24
23
  output: z.object({
25
24
  message: z.string().describe('The echoed message.'),
26
- timestamp: z.string().describe('ISO 8601 timestamp of the echo.'),
25
+ timestamp: z.iso.datetime().describe('ISO 8601 timestamp of the echo.'),
27
26
  }),
28
27
 
29
28
  handler(input, ctx) {
package/templates/src/mcp-server/tools/definitions/echo.tool.ts CHANGED
@@ -9,7 +9,7 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
9
9
  // Tool names are snake_case, prefixed with your server name to avoid collisions across servers.
10
10
  // e.g. for a "tasks" server: tasks_fetch_list, tasks_create_item.
11
11
  export const echoTool = tool('template_echo_message', {
12
- description: 'Echoes a message back. Replace this with your first real tool.',
12
+ description: 'Echo a message back. Replace this with your first real tool.',
13
13
  annotations: { readOnlyHint: true },
14
14
  input: z.object({
15
15
  message: z.string().describe('The message to echo back.'),
@@ -42,7 +42,13 @@ export const echoTool = tool('template_echo_message', {
42
42
 
43
43
  handler(input, ctx) {
44
44
  if (input.message.trim().length === 0) {
45
- throw ctx.fail('empty_message', 'Message must contain at least one non-whitespace character.');
45
+ // Spreading ctx.recoveryFor puts the declared recovery on the wire. Without
46
+ // it the hint reaches neither structuredContent nor content[].
47
+ throw ctx.fail(
48
+ 'empty_message',
49
+ 'Message must contain at least one non-whitespace character.',
50
+ { ...ctx.recoveryFor('empty_message') },
51
+ );
46
52
  }
47
53
  // Reaches both client surfaces with no format() plumbing.
48
54
  ctx.enrich({ characterCount: input.message.length });
package/dist/utils/telemetry/index.d.ts DELETED
@@ -1,12 +0,0 @@
1
- /**
2
- * @fileoverview Barrel for telemetry utilities.
3
- * Provides OpenTelemetry instrumentation, MCP attribute keys, trace helpers,
4
- * and metrics creation utilities for observability.
5
- *
6
- * @module src/utils/telemetry
7
- */
8
- export * from './attributes.js';
9
- export * from './instrumentation.js';
10
- export * from './metrics.js';
11
- export * from './trace.js';
12
- //# sourceMappingURL=index.d.ts.map
package/dist/utils/telemetry/index.d.ts.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}
package/dist/utils/telemetry/index.js DELETED
@@ -1,12 +0,0 @@
1
- /**
2
- * @fileoverview Barrel for telemetry utilities.
3
- * Provides OpenTelemetry instrumentation, MCP attribute keys, trace helpers,
4
- * and metrics creation utilities for observability.
5
- *
6
- * @module src/utils/telemetry
7
- */
8
- export * from './attributes.js';
9
- export * from './instrumentation.js';
10
- export * from './metrics.js';
11
- export * from './trace.js';
12
- //# sourceMappingURL=index.js.map
package/dist/utils/telemetry/index.js.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}