change fields related to server json struct to follow camelCase instead of snake_case

[pree-dew]

Motivation and Context

Aligns with issue #428
To bring consistency across naming convention

How Has This Been Tested?

• Locally test cases are tested

Breaking Changes

• Yes, they have to update the server fields

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

[tadasant]

Heads up we should also open a PR with the new schema here and bump the version number on it to today's date: https://github.com/modelcontextprotocol/static/tree/main/schemas

[tadasant]

@claude can you do a PR review please

[claude]

Claude encountered an error —— View job

Failed with exit code 128

---

I'll analyze this and get back to you.

[tadasant]

@pree-dew I'm not sure the migration commit is totally necessary -- we should be able to support multiple versions of server.json schemas, and in general I'd like to prioritize maintaining our "server.json is immutable" invariant

[tadasant]

Oops (re: Claude^^)

Review from Claude Code on local

Code Review: PR #488 - Change fields to camelCase instead of snake_case

🎯 Overview

This PR systematically converts JSON field names from snake_case to camelCase across the entire MCP Registry codebase. The changes are comprehensive and affect API schemas, documentation, seed data, tests, and validation logic.

✅ Strengths

1. Comprehensive Coverage: The changes are thorough, touching all relevant files including:

   • Go struct tags in pkg/model/types.go
   • JSON Schema definitions in docs/reference/server-json/server.schema.json
   • Seed data in data/seed.json
   • Documentation examples across multiple guides
   • Test files and validation scripts

2. Consistent Implementation: All field name conversions follow the same pattern:

   • registry_type → registryType
   • registry_base_url → registryBaseUrl
   • file_sha256 → fileSha256
   • runtime_hint → runtimeHint
   • runtime_arguments → runtimeArguments
   • package_arguments → packageArguments
   • environment_variables → environmentVariables
   • is_required → isRequired
   • is_secret → isSecret
   • is_repeated → isRepeated
   • value_hint → valueHint

3. Passes All Tests: The build and test suite passes successfully, indicating the changes maintain functional correctness.

4. Proper Schema Updates: The JSON schema is correctly updated with the new field names, which ensures validation continues to work properly.

⚠️ Critical Issues

Breaking Change Impact

This is a significant breaking change that will affect:

• Existing publishers: All existing server.json files using the old snake_case fields will fail validation
• API consumers: Any tools or scripts parsing the registry API responses will break
• Documentation synchronization: While most docs are updated, this represents a major API version change

Missing Transport Field

I notice one commit adds "transport" as compulsory, but this seems separate from the camelCase conversion and may not be intentional for this PR's scope.

🔍 Technical Review

Code Quality: ⭐⭐⭐⭐⭐

• Clean, consistent field name conversions
• Proper Go struct tag updates
• No logic changes, only field name updates

Test Coverage: ⭐⭐⭐⭐⭐

• All existing tests pass
• Test data properly updated to use new field names
• Validation examples correctly updated

Documentation: ⭐⭐⭐⭐⭐

• Comprehensive documentation updates across all guides
• Schema documentation properly updated
• API reference correctly reflects new field names

📝 Recommendations

1. Version Bump Consideration: This breaking change should likely be accompanied by a major version increment to clearly signal the breaking nature of the changes.

2. Migration Guide: Consider providing a migration guide or script to help existing publishers convert their server.json files from snake_case to camelCase.

3. Deprecation Period: If possible, consider supporting both formats temporarily with a deprecation warning before making this a hard breaking change.

4. Transport Field Clarification: The addition of mandatory transport field should be clarified - is this intentional for this PR or should it be a separate change?

🚀 Conclusion

Recommendation: ✅ APPROVE with considerations

This is a well-executed, comprehensive refactoring that successfully converts the API from snake_case to camelCase. The implementation is thorough, consistent, and maintains all functionality. However, given the breaking nature of this change, careful consideration should be given to:

• Communicating the breaking change clearly to users
• Providing migration assistance
• Potentially coordinating with a major version release

The code quality is excellent and the change aligns with JavaScript/JSON conventions where camelCase is more idiomatic than snake_case.

All looks good; nothing from Claude.

[tadasant]

Looking great! Main feedback is:

• We shouldn't migrate the old data; we should be able to support multiple schema versions in the table and server.json should remain immutable
• Let's make sure we have a PR on the static repository ready to go with a new 2025-09-16 version
• As such, we should also update everything across this codebase to use the new version instead of 2025-07-09
• Let's start a changelog of sorts for the server.json schema somewhere in the docs. Make it clear what the changes are as we bump the version here

[pree-dew]

@tadasant It was mentioned in todo #428 (comment) to have migration for historical data. If it is not required, will remove it. I will create a PR for static repo.

[tadasant]

@tadasant It was mentioned in todo #428 (comment) to have migration for historical data. If it is not required, will remove it. I will create a PR for static repo.

Oh fair - let's see what @domdomegg thinks - but I still think we should pull back on that and simply allow for the possibility that our database isn't only serving the latest schema version of server.json. In fact I could see a future in GA where we would want to allow both publishing and reading of different schema versions. Probably something we should cut an Issue for.

announce this change to people. maybe it would be ideal if we could provide a command to automigrate the old format to the new one to avoid thrash? or do this automatically in the publisher cli on publish for a short while (e.g. 7 days) with a big noisy warning? this is definitely optional though, only if it's easy and neat.

At the very least I think we should add a warning with a link pointing to the changelog so folks can update it themselves. I think the ideal here would be some sort of mcp-publisher update-server-json 2025-09-16 ./server.json type of command, which we could implement long term but in the interest of getting this out sooner I think we can punt that.

[pree-dew]

Raised a PR for static modelcontextprotocol/static#5

• I will make changes for updating 2025-07-09 to 2025-09-16 new version.

I agree with the point that we should be able to support multiple version of schema and also agree with changelog idea, it's important for consumers to understand what exactly has changed in schema. I can create a new issue for that if we are looking to cover it in another issue.

[tadasant]

I agree with the point that we should be able to support multiple version of schema and also agree with changelog idea, it's important for consumers to understand what exactly has changed in schema. I can create a new issue for that if we are looking to cover it in another issue.

I think we should do the changelog in this PR so that as soon as it's live there are docs indicating the changelog (which folks can use as a defacto migration guide). Doesn't need to be anything fancy -- I expect a single prompt to Claude Code (or equivalent) would make a good file for us here.

Separate issue on supporting multiple versions would be helpful 🙏

[pree-dew]

On it @tadasant for changelog.

[pree-dew]

Pushed:

• Changelog, (have kept the breaking changes as part of changelog, will change depending on are we going to support multiple versions from this release or going forward)
• Changes for updating 2025-07-09 to 2025-09-16 new version.
• PR for static reference add server schema for supporting camelcase static#5

Pending:

• Waiting for this comment to be resolved Refactor all server.json snake_case fields to camelCase #428 (comment)
• Resolution for migration of historical data as per this comment change fields related to server json struct to follow camelCase instead of snake_case #488 (comment)

[tadasant]

Thanks @pree-dew ! Looking good. I pushed some tweaks to how we manage the new CHANGELOG (I made one for the API and one for the server.json)

I think one more request besides what you laid out -- we should add a logic branch in the mcp-publisher that if we see someone trying to push a 2025-07-09 schema, we can error out and point them to the GitHub link with the server.json changelog (and the migration steps section within it).

[rdimitrov]

Pending:

• Waiting for this comment to be resolved Refactor all server.json snake_case fields to camelCase #428 (comment)

I think this got resolved so what's left is to be addressed 👍

• Resolution for migration of historical data as per this comment change fields related to server json struct to follow camelCase instead of snake_case #488 (comment)

Not for this PR:
@tadasant - Perhaps one todo item is to have a chat about this model and capture the reasoning better in the docs 👍 Since server.json is essentially an API (a contract between the publisher and the intended consumer) supporting different versions at the same time in the registry API also means being explicit that the same expectations carry over to registry clients. For example, if a property once called name later becomes serverName is effectively a breaking change.

[pree-dew]

@tadasant changes for camelCase of _meta fields are pushed.

Are we going ahead with migration? I will make changes for _meta fields also in that case in migration script. @rdimitrov this one is pending.

Regarding this:

I think one more request besides what you laid out -- we should add a logic branch in the mcp-publisher that if we see someone trying to push a 2025-07-09 schema, we can error out and point them to the GitHub link with the server.json changelog (and the migration steps section within it).

Do you want to cover this as part of this PR?

[tadasant]

Do you want to cover this as part of this PR?

I think we should, because when we land this PR, the breaking changes will be live. So I think it's easier to bake it in here rather than try to coordinate a fast follow while folks might be using the updated schemas.

Are we going ahead with migration? I will make changes for _meta fields also in that case in migration script. @rdimitrov this one is pending.

I'll ping Adam to see if we can get to alignment (I know he's busy with a number of things atm). If we don't hear from him by tomorrow AM let's remove the migration; guessing his list was meant to be comprehensive/helpful but not necessarily prescriptive.

[pree-dew]

@tadasant Changes for redirecting users to changelog on using deprecated schema is pushed. Noticed that seed.json was failing because of missing ServerId and VersionId field which was breaking the local setup to test, pushed that also.

[tadasant]

@pree-dew intentional change here?

[tadasant]

@pree-dew I think we should not support publishing under older versions at this time. My earlier reference to "I think we should support multiple versions" would be for the consumption side of the API - sorry, I was not clear earlier on the difference.

So we should support storing old schema versions that are already published, but we should require that new data being published use the latest schema version.

Maybe we can soften this in the future, but I think in Preview launch here it's fair to force publishers to adhere to the latest standard.

[tadasant]

Thank you @pree-dew for continuing to drive this! Sorry for this long tail of nits. I do think we should remove the migration (haven't heard from Adam yet), but almost there now.

[rdimitrov]

@pree-dew @tadasant - I think in the interest of not blocking this PR we can proceed without the migration and potentially have it as a follow up later once we get Adam to have a look at it, wdyt?

[pree-dew]

@tadasant No problem, I will address PR comments. I will remove the migration and will test it once. CC @rdimitrov

[domdomegg]

Heya, sorry for the late reply! I think my preference would be to migrate the old data, because otherwise consumers will have the pain of mapping both models into one. I think this will be very frustrating for clients. I appreciate we could offer utils or SDKs for consuming registry data, but then we have to do this for every language, and these need to be bundled by a bunch of people (and getting packages approved in enterprises is always a pain 😅).

Appreciate this is a little weird with the idea of server.json to be immutable. But conceptually I think the data itself is immutable, not necessarily the structure it is presented in, if that makes sense?

Perhaps I might be a little more cautious to make breaking changes / do data format migrations if we were GA, but I think it still being relatively recently in preview is another reason I'm okay with migrating all this data over.

[pree-dew]

@tadasant @rdimitrov Pushed the PR changes and removed the migration file. @domdomegg Sorry, pushed the changes before reading the message, can add it once we finalise our approach of dealing with mutability of server.json.