@cyanheads/mcp-ts-core 0.10.3 → 0.10.4

package/skills/api-testing/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Testing patterns for MCP tool/resource handlers using `createMockContext` and Vitest. Covers mock context options, handler testing, McpError assertions, format testing, Vitest config setup, and test isolation conventions.
 metadata:
   author: cyanheads
-  version: "1.3"
+  version: "1.4"
   audience: external
   type: reference
 ---
@@ -311,6 +311,22 @@ Use `.rejects.toThrow(McpError)` to assert type only. Use `.rejects.toMatchObjec
 
 ---
 
+## Output schema assertions
+
+`expect.schemaMatching` (Vitest 4, Standard Schema) validates a value against any Zod schema — including the definition's own `output`. Use it to assert schema conformance without duplicating the shape in the test:
+
+```ts
+it('output conforms to the declared output schema', async () => {
+  const ctx = createMockContext();
+  const result = await myTool.handler(myTool.input.parse({ query: 'x' }), ctx);
+  expect(result).toEqual(expect.schemaMatching(myTool.output));
+});
+```
+
+It composes as an asymmetric matcher anywhere a value is expected — e.g. `toHaveBeenCalledWith(expect.schemaMatching(schema))`. Prefer exact-value assertions when the expected output is fully known; reach for `schemaMatching` when the output is dynamic (timestamps, generated IDs) or the schema itself is the contract under test.
+
+---
+
 ## Testing handlers with `errors[]` (typed contract)
 
 Tools and resources that declare an `errors[]` contract receive a typed `ctx.fail` helper at runtime. Pass the definition's own `errors` to `createMockContext` and the mock wires `fail` the same way the production handler factory does:

package/templates/Dockerfile

@@ -114,5 +114,8 @@ ENV MCP_FORCE_CONSOLE_LOGGING="true"
 # Expose the port the server listens on
 EXPOSE ${MCP_HTTP_PORT}
 
+# Health check using a bun-native fetch (slim image ships no curl/wget)
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD bun -e "fetch('http://localhost:'+(process.env.MCP_HTTP_PORT??'3010')+'/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
 # The command to start the server
 CMD ["bun", "run", "dist/index.js"]

package/templates/package.json

@@ -62,12 +62,12 @@
     "zod": "{{ZOD_VERSION}}"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.7",
-    "@types/node": "^25.6.0",
+    "@biomejs/biome": "2.4.16",
+    "@types/node": "25.9.3",
     "depcheck": "^1.4.7",
     "ignore": "^7.0.5",
-    "tsc-alias": "^1.8.16",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.0"
+    "tsc-alias": "^1.8.17",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
   }
 }

package/templates/tests/tools/echo.tool.test.ts

@@ -15,6 +15,13 @@ describe('echoTool', () => {
     expect(result).toEqual({ message: 'hello world' });
   });
 
+  it('output conforms to the declared output schema', async () => {
+    const ctx = createMockContext();
+    const input = echoTool.input.parse({ message: 'hello world' });
+    const result = await echoTool.handler(input, ctx);
+    expect(result).toEqual(expect.schemaMatching(echoTool.output));
+  });
+
   it('formats output as text content', () => {
     const blocks = echoTool.format!({ message: 'hello world' });
     expect(blocks).toEqual([{ type: 'text', text: 'hello world' }]);

package/tsconfig.base.json

@@ -20,7 +20,6 @@
     "declarationMap": true,
     "sourceMap": true,
 
-    "importHelpers": true,
     "incremental": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,

package/dist/logs/combined.log

@@ -1,4 +0,0 @@
-{"level":40,"time":1781133231939,"env":"testing","version":"0.10.3","pid":80401,"transport":"http","requestId":"PAZLD-YA82Z","timestamp":"2026-06-10T23:13:51.938Z","operation":"TransportManager.start","component":"HttpTransportSetup","msg":"MCP_ALLOWED_ORIGINS is not set — CORS is wildcard for CLI clients; browser Origin headers are restricted to loopback. Set MCP_ALLOWED_ORIGINS for production deployments accepting remote browser origins."}
-{"level":40,"time":1781133233685,"env":"testing","version":"0.10.3","pid":80401,"component":"HttpTransport","requestId":"2ISX1-LS2V4","timestamp":"2026-06-10T23:13:53.685Z","operation":"HttpRpcRequest","sessionId":"not-a-real-session-1781133233685","msg":"Session validation failed - invalid or hijacked session"}
-{"level":50,"time":1781133237889,"env":"testing","version":"0.0.0-test","pid":80550,"requestId":"RD4D8-H3QV1","timestamp":"2026-06-10T23:13:57.888Z","operation":"HandleToolRequest","critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"b6c3787ad9d5f6d3b11827959b7c06d08b23e57c3b1f8aee6dc7dbdb5d6ffa55","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"errorData":{"sessionId":"b6c3787ad9d5f6d3b11827959b7c06d08b23e57c3b1f8aee6dc7dbdb5d6ffa55","toolName":"scoped_echo","requestId":"RD4D8-H3QV1","timestamp":"2026-06-10T23:13:57.888Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n    at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n    at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:68:15)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:283:17)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n    at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:170:23)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:324:26)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}
-{"level":50,"time":1781133237899,"env":"testing","version":"0.0.0-test","pid":80550,"requestId":"GBWGR-X2TSW","timestamp":"2026-06-10T23:13:57.899Z","operation":"HandleToolRequest","critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"d540d7df1cdbaf04f12a646d555d508ac0db2e191d0a5282980a2327f57f727f","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["openid","email","profile","offline_access"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"errorData":{"sessionId":"d540d7df1cdbaf04f12a646d555d508ac0db2e191d0a5282980a2327f57f727f","toolName":"scoped_echo","requestId":"GBWGR-X2TSW","timestamp":"2026-06-10T23:13:57.899Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["openid","email","profile","offline_access"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n    at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n    at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:68:15)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:283:17)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n    at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:170:23)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:324:26)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}

package/dist/logs/error.log

@@ -1,2 +0,0 @@
-{"level":50,"time":1781133237889,"env":"testing","version":"0.0.0-test","pid":80550,"requestId":"RD4D8-H3QV1","timestamp":"2026-06-10T23:13:57.888Z","operation":"HandleToolRequest","critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"b6c3787ad9d5f6d3b11827959b7c06d08b23e57c3b1f8aee6dc7dbdb5d6ffa55","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"errorData":{"sessionId":"b6c3787ad9d5f6d3b11827959b7c06d08b23e57c3b1f8aee6dc7dbdb5d6ffa55","toolName":"scoped_echo","requestId":"RD4D8-H3QV1","timestamp":"2026-06-10T23:13:57.888Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n    at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n    at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:68:15)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:283:17)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n    at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:170:23)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:324:26)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}
-{"level":50,"time":1781133237899,"env":"testing","version":"0.0.0-test","pid":80550,"requestId":"GBWGR-X2TSW","timestamp":"2026-06-10T23:13:57.899Z","operation":"HandleToolRequest","critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"d540d7df1cdbaf04f12a646d555d508ac0db2e191d0a5282980a2327f57f727f","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["openid","email","profile","offline_access"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"errorData":{"sessionId":"d540d7df1cdbaf04f12a646d555d508ac0db2e191d0a5282980a2327f57f727f","toolName":"scoped_echo","requestId":"GBWGR-X2TSW","timestamp":"2026-06-10T23:13:57.899Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["openid","email","profile","offline_access"],"clientId":"authz-client","tenantId":"authz-tenant","token":"[REDACTED]"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n    at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n    at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:68:15)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:283:17)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n    at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:170:23)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:324:26)\n    at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n    at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n    at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}