feat: add zod tools validation support

[kushalshit27]

Changes

This pull request includes several updates to the codebase, primarily focusing on the integration of the zod library for schema validation and the removal of outdated comments. The most important changes include the conversion of input schemas to use zod and the addition of the zod-to-json-schema utility for schema transformation.

Integration of zod for Schema Validation:

• [src/tools/] Updated input schemas for application tools to use zod for validation, replacing the previous JSON schema definitions.

Addition of zod-to-json-schema Utility:

• src/server.ts: Added the zod-to-json-schema utility to convert zod schemas to JSON schemas, facilitating schema transformation and validation. [1] [2]

Code Cleanup:

• src/index.ts: Removed outdated comments related to debug logs, improving code readability.

These changes collectively improve the maintainability and robustness of the codebase by leveraging the zod library for schema validation and ensuring that schemas are consistently defined and transformed.

References

Please include relevant links supporting this change such as a:

• support ticket
• community post
• StackOverflow post
• support forum thread

Testing

Please describe how this can be tested by reviewers. Be specific about anything not tested and reasons why. If this library has unit and/or integration testing, tests should be added for new functionality and existing tests should complete without errors.

• This change adds unit test coverage
• This change adds integration test coverage

Checklist

• I have read the Auth0 general contribution guidelines
• I have read the Auth0 Code of Conduct
• All existing and new tests complete without errors

[Copilot]

Copilot reviewed 17 out of 17 changed files in this pull request and generated no comments.

Comments suppressed due to low confidence (2)

src/utils/types.ts:3

• The imported 'ToolSchema' is later shadowed by a custom type alias with the same name. Consider renaming the custom type alias to avoid confusion.

import { ToolSchema } from '@modelcontextprotocol/sdk/types';

src/server.ts:45

• Consider handling potential conversion errors from zodToJsonSchema to ensure that an invalid or unexpected inputSchema does not cause runtime failures.

const toolSchema = zodToJsonSchema(tool.inputSchema as ZodSchema) as ToolSchema;

[btiernay]

I think we should do this processing outside the request handler in a processTools helper to prevent it from happening on each request. I know, I introduced this pattern, my bad!

[btiernay]

Great addition. One thing that stood out is that while the code converts Zod schemas to JSON Schema, it doesn't really deal with validation errors in a consistent way. It might be helpful to add some middleware that catches those errors and returns a clear message that makes sense to whoever's consuming the API.

On a related note, many schemas seem to repeat similar patterns, like pagination. Pulling those into shared schemas could reduce duplication and make things easier to maintain over time.

Have we considered using Auth0's official OpenAPI specification directly instead of recreating these schemas? This could ensure your schemas stay in sync with Auth0's API changes and potentially reduce maintenance overhead. In the future we will likely generate these tools using Fern / OAS.

Since you're using Zod, you could export TypeScript types directly from the schemas. That way, the validation logic and the types used across the codebase stay in sync, which is always nice. Adding some JSDoc comments to the schemas would help too, just a quick note about what each field expects or why a rule exists can really help someone coming in fresh.

As for testing, the current coverage looks decent for basic validation, but it might be worth checking how the schemas behave with edge cases, or even testing the actual JSON Schema output after transformation. That would give you more confidence things are working as expected.

Zod's default error messages can be a bit generic, so customizing them might give developers more helpful feedback when something goes wrong. And depending on how often schema conversion is happening, caching that step could improve performance, especially if the same tool is used frequently.