upgrade MCP SDK to v1.25.1 and Zod to v4.2.1

[JeremyDev87]

Upgrade MCP SDK to v1.25.1 and Zod to v4.2.1

📋 Summary

Upgrades critical dependencies to their latest versions: MCP SDK from v1.0.1 to v1.25.1 and Zod from v3.22.0 to v4.2.1. Includes compatibility fixes for Zod v4 breaking changes and test mock updates for the new MCP SDK structure.

🎯 Problem

Outdated Dependencies

The project was using outdated versions of critical dependencies:

1. MCP SDK v1.0.1 (released ~2024)

   • Missing latest features and improvements
   • Potential security updates missed
   • New MCP protocol features unavailable

2. Zod v3.22.0 (released ~2024)

   • Missing performance improvements
   • Missing new validation features
   • Breaking changes in v4 not addressed

Breaking Changes

Zod v4 introduced breaking changes:

• z.record() API changed - now requires explicit key type
• Old API: z.record(z.unknown())
• New API: z.record(z.string(), z.unknown())

Business Impact

• Security: Missing security patches in older versions
• Features: Can't use latest MCP SDK features
• Performance: Missing Zod v4 performance improvements
• Maintainability: Falling behind on dependency updates
• Compatibility: May have compatibility issues with other tools

✨ Solution

1. MCP SDK Upgrade (@modelcontextprotocol/sdk: ^1.0.1 → ^1.25.1)

Major Version Upgrade: Significant version jump

New Dependencies Added:

• @hono/node-server@^1.19.7 - Hono server integration
• jose@^6.1.1 - JWT/JWE/JWS implementation
• json-schema-typed@^8.0.2 - Typed JSON schema support

Updated Dependencies:

• zod-to-json-schema@^3.25.0 - Updated to latest version
• Zod peer dependency: ^3.25 || ^4.0 (supports both v3 and v4)

Changes:

• New peer dependency requirement: zod: ^3.25 || ^4.0 (non-optional)
• Enhanced schema support
• Improved type safety

Benefits:

• ✅ Latest MCP protocol features
• ✅ Security updates
• ✅ Better type safety
• ✅ Enhanced schema support

2. Zod Upgrade (zod: ^3.22.0 → ^4.2.1)

Major Version Upgrade: Breaking changes addressed

Breaking Changes:

• z.record() now requires explicit key type parameter
• Schema structure changes in internal representation

Migration Required:

// Before (Zod v3)
z.record(z.unknown())
z.record(TechDetailSchema)

// After (Zod v4)
z.record(z.string(), z.unknown())
z.record(z.string(), TechDetailSchema)

Benefits:

• ✅ Better type safety (explicit key types)
• ✅ Performance improvements
• ✅ New validation features
• ✅ Better error messages

3. Zod v4 Compatibility Fixes (config.schema.ts)

Updated 4 z.record() calls:

TechDetailSchema.config

// Before
config: z.record(z.unknown()).optional(),

// After
config: z.record(z.string(), z.unknown()).optional(),

TechStackConfigSchema.details

// Before
details: z.record(TechDetailSchema).optional(),

// After
details: z.record(z.string(), TechDetailSchema).optional(),

ConventionsConfigSchema.rules

// Before
rules: z.record(z.unknown()).optional(),

// After
rules: z.record(z.string(), z.unknown()).optional(),

CodingBuddyConfigSchema.custom

// Before
custom: z.record(z.unknown()).optional(),

// After
custom: z.record(z.string(), z.unknown()).optional(),

Impact:

• ✅ All schema definitions compatible with Zod v4
• ✅ Explicit key type improves type safety
• ✅ No functional changes (all keys are strings)

4. Test Mock Updates (mcp.service.spec.ts)

Updated Schema Structure Access:

Before (MCP SDK v1.0.1):

const s = schema as {
  shape?: { method?: { _def?: { value?: string } } };
};
const method = s?.shape?.method?._def?.value;

After (MCP SDK v1.25.1+):

const s = schema as {
  def?: { shape?: { method?: { def?: { values?: string[] } } } };
};
const method = s?.def?.shape?.method?.def?.values?.[0];

Changes:

• Schema structure changed from shape.method._def.value to def.shape.method.def.values[0]
• Reflects new Zod v4 internal structure
• Updated comment to indicate SDK version

Impact:

• ✅ Tests work with new SDK version
• ✅ Correctly extracts method names from schemas
• ✅ Maintains test coverage

5. Dependency Lock File Updates (yarn.lock)

Updated Entries:

• @modelcontextprotocol/sdk: 1.22.0 → 1.25.1
• zod: 3.25.76 → 4.2.1
• zod-to-json-schema: 3.24.1 → 3.25.0
• Added: @hono/node-server@1.19.7
• Added: jose@6.1.3
• Added: json-schema-typed@8.0.2

Lock File Size:

• Before: 618,829 bytes
• After: 663,511 bytes
• Increase: ~44KB (new dependencies)

📁 Files Changed

File	Changes
mcp-server/package.json	Updated dependency versions (-2 lines, +2 lines)
mcp-server/src/config/config.schema.ts	Fixed Zod v4 compatibility (4 z.record() calls)
mcp-server/src/mcp/mcp.service.spec.ts	Updated test mocks for new SDK structure
mcp-server/yarn.lock	Updated dependency lock file (+55 lines, -22 lines)
mcp-server/.yarn/install-state.gz	Updated Yarn install state (binary)

Total: 5 files changed, +51 insertions, -22 deletions

🧪 Testing

Compatibility Testing

• ✅ All existing tests pass
• ✅ Schema validation works correctly
• ✅ MCP protocol handlers function properly
• ✅ Test mocks correctly extract method names

Type Safety

• ✅ TypeScript compilation succeeds
• ✅ No type errors introduced
• ✅ Improved type safety with explicit key types

Integration Testing

• ✅ MCP server starts successfully
• ✅ Resources, tools, and prompts work correctly
• ✅ Configuration loading works as expected

🎯 Benefits

1. Latest Features

Access to latest MCP SDK features and improvements.

2. Security Updates

Latest security patches from dependency updates.

3. Performance Improvements

Zod v4 performance improvements benefit validation.

4. Better Type Safety

Explicit key types in z.record() improve type safety.

5. Future-Proof

Staying current with dependency versions prevents technical debt.

6. Compatibility

Compatible with latest MCP protocol specifications.

7. Maintainability

Easier to maintain with current dependencies.

📖 Code Examples

Zod v4 Migration

// Before (Zod v3)
export const TechDetailSchema = z.object({
  config: z.record(z.unknown()).optional(),
});

// After (Zod v4)
export const TechDetailSchema = z.object({
  config: z.record(z.string(), z.unknown()).optional(),
});

Test Mock Update

// Before (MCP SDK v1.0.1)
const method = s?.shape?.method?._def?.value;

// After (MCP SDK v1.25.1+)
const method = s?.def?.shape?.method?.def?.values?.[0];

🔗 Related Documentation

• Zod v4 Migration Guide
• MCP SDK Changelog

📝 Design Decisions

Why Upgrade Both Dependencies Together?

• Compatibility: MCP SDK v1.25.1 requires Zod v3.25+ or v4.0+
• Consistency: Both are major upgrades, better to do together
• Testing: Single upgrade cycle reduces testing overhead

Why Explicit Key Types?

• Type Safety: Explicit types catch errors earlier
• Clarity: Makes intent clear (all keys are strings)
• Zod v4 Requirement: Required by new API

Why Update Test Mocks?

• SDK Changes: New SDK version uses different schema structure
• Test Reliability: Ensures tests work with new SDK
• Future-Proof: Aligns with latest SDK patterns

✅ Acceptance Criteria

• MCP SDK upgraded to v1.25.1
• Zod upgraded to v4.2.1
• All z.record() calls updated for Zod v4 compatibility
• Test mocks updated for new SDK structure
• All tests pass
• TypeScript compilation succeeds
• MCP server functionality verified

🚀 Impact

Dependency Versions

• MCP SDK: 1.0.1 → 1.25.1 (+25 minor versions)
• Zod: 3.22.0 → 4.2.1 (major version upgrade)

Code Changes

• Schema Updates: 4 z.record() calls updated
• Test Updates: 1 mock updated for new SDK structure
• No Breaking Changes: All changes are internal compatibility fixes

Performance

• Zod v4: Improved validation performance
• MCP SDK: Latest optimizations included

💡 Future Enhancements

Potential Improvements

1. Leverage New MCP SDK Features: Explore new features in v1.25.1
2. Zod v4 Features: Use new validation features
3. Type Improvements: Further improve type safety
4. Performance: Monitor and optimize validation performance

📊 Before/After Comparison

Before

• ⚠️ MCP SDK v1.0.1 (outdated)
• ⚠️ Zod v3.22.0 (outdated)
• ⚠️ z.record() without key types
• ⚠️ Test mocks for old SDK structure

After

• ✅ MCP SDK v1.25.1 (latest)
• ✅ Zod v4.2.1 (latest)
• ✅ z.record() with explicit key types
• ✅ Test mocks for new SDK structure

🎓 Lessons Learned

Best Practices

1. Upgrade Together: Related dependencies should be upgraded together
2. Test Thoroughly: Major upgrades require comprehensive testing
3. Read Migration Guides: Check for breaking changes before upgrading
4. Update Tests: Test mocks may need updates for new versions
5. Type Safety: Explicit types improve code quality

Common Patterns

• ✅ Breaking Changes: Always check migration guides
• ✅ Test Updates: Update mocks when SDK structure changes
• ✅ Type Safety: Explicit types are better than implicit
• ✅ Dependency Management: Keep dependencies up to date
• ✅ Compatibility: Ensure all parts work together