Watch

Tadas Antanavicius 774a0df592

Add validation tools for server.json schemas and examples (#176 )

This is a first PR for #159 - adding some validation scripts. I want to
get to a place where we are confident that making schema changes is in
sync with the rest of our code. Step one is making sure the schemas are
in sync with our examples. Step two will be making sure the schemas are
in sync with our actual Registry implementation code.

This is just for the JSON right now; if we're feeling good about this
approach I'll do an analogous change for the OpenAPI schemas as well.

I'll also follow with adding usage of these scripts to our CI pipeline
so we have automated checks on them with every change.

## Summary
- Added CLI validation tools for JSON schemas and examples in
`docs/server-json/`
- Fixed some minor validation errors found in `examples.md`
- Ensures schema consistency and example validity in CI/CD pipelines

## Changes

### New Validation Tools
1. **`tools/validate-schemas`** - Validates that `schema.json` and
`registry-schema.json` are valid JSON Schema documents
2. **`tools/validate-examples`** - Validates all JSON examples in
`examples.md` against both schemas

### Key Features
- ✅ Validates JSON schema syntax and structure
- ✅ Validates all examples against both base and registry schemas
- ✅ Tracks validation counts to prevent silent failures
- ✅ Proper exit codes for CI integration
- ✅ Clear error messages for debugging

### Fixes to examples.md
- Added missing `repository.id` field in NuGet example
- Changed `repository.source` from "gitlab" to "github" in Docker
example

### Usage
```bash
# From repository root
./tools/validate-schemas.sh
./tools/validate-examples.sh
```

## Testing

I ran these scripts locally with minor (breaking) changes, which they
each correctly reported. As submitted, they are both passing.

🤖 Co-authored with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Charles Lowell <10964656+chlowell@users.noreply.github.com>

2025-07-15 11:32:54 -07:00

2.1 KiB

Raw Blame History

server.json file

There are a variety of use cases where a static representation of an MCP server is necessary:

Discoverability on a centralized registry (i.e. our official Registry work)
Discoverability on a decentralized .well-known endpoint
As a response to an initialization call, so the client knows information about the MCP server to which it is connecting
As an input into crafting a DXT file
Packaged in with the source code of an MCP server, so as to have a structured way to identify a server given just its source code

All of these scenarios (and more) would benefit from an agreed-upon, standardized format that makes it easy to port around and maintain a consistent experience for consumers and developers working with the data. At the end of the day, it's all the same data (or a subset of it). MCP server maintainers should have to manage one copy of this file, and all these use cases can serve that file (or a programmatic derivative/subset of it).

Please note: this is different from the file commonly referred to as mcp.json, which is an MCP client's configuration file for running a specific set of MCP servers. See this issue.

References:

schema.json - The official JSON schema specification for this representation
examples.md - Example manifestations of the JSON schema
registry-schema.json - A more constrained version of schema.json that the official registry supports

Validation Tools

Two validation tools are provided in the repository's tools/ directory:

validate-schemas - Validates that schema.json and registry-schema.json are valid JSON Schema documents
validate-examples - Validates that all JSON examples in examples.md conform to both schemas

Usage

From the repository root:

Validate JSON Schemas

./tools/validate-schemas.sh

Validate Examples

./tools/validate-examples.sh

2.1 KiB Raw Blame History