docs: add troubleshooting and migration guidance for Zod schema shape differences

[diveshs0801]

Clarify difference between Zod raw shapes and ZodObject across SDK v1 and v2, addressing silent empty inputSchema and tools/list crashes.

Fixes #2627

Motivation and Context

On SDK v1, passing z.object({...}) where a raw Zod shape ({ field: z.string() }) is expected leads to two failure modes:

1. Silent empty schema (v1 ≤ 1.26.0): Calling server.tool(...) with z.object({...}) publishes an empty schema ({"type":"object"}) with no properties, causing clients to silently strip tool arguments.
2. Crash on tools/list (v1 ≤ 1.21.0): Calling registerTool with z.object({...}) causes tools/list to fail with Cannot read properties of null (reading '_def').

Neither docs/troubleshooting.md nor docs/migration/upgrade-to-v2.md previously documented this pitfall. This PR adds a dedicated troubleshooting entry with side-by-side code snippets and a warning callout in the v2 migration guide to save developers hours of debugging.

How Has This Been Tested?

• Verified markdown rendering and consistency with existing documentation style in both docs/troubleshooting.md and docs/migration/upgrade-to-v2.md.
• Verified the code snippets against both v1 and v2 tool registration APIs.

Breaking Changes

None. This is a documentation-only update.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Resolves #2627.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 48734f6

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@2870

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@2870

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@2870

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@2870

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@2870

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@2870

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@2870

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@2870

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@2870

commit: 48734f6