Add optional subfolder field to Repository schema (#363)

Adds an optional `subfolder` field to the Repository object in
server.json schema to support MCP servers located within subdirectories
of monorepo structures.

## Motivation and Context

Addresses issue #360 .

The current MCP registry schema doesn't explicitly define how to
reference servers that are located within a subdirectory of a Git
repository (a "monorepo" structure). This is a common pattern (e.g.,
[microsoft/mcp](https://github.com/microsoft/mcp) &
[awslabs/mcp](https://github.com/awslabs/mcp).

## How Has This Been Tested?

- **Validator tests**: Added 6 new test cases covering valid subfolders
and security validation (path traversal, absolute paths, invalid
characters, etc.)
- **Schema validation**: All 11 examples in `examples.md` validate
successfully against both `server.schema.json` and
`registry-schema.json`
- **End-to-end validation**: Publisher tool (`mcp-publisher init`) works
correctly and generates valid templates without subfolder
- **Backward compatibility**: Existing server.json files without
subfolder continue to work unchanged

## Breaking Changes

**None.** This is a fully backward-compatible change:
- The `subfolder` field is optional (uses `omitempty` JSON tag)
- Existing server.json files work unchanged
- Publisher tools generate valid templates without subfolder by default
- All existing validation and schemas remain compatible

## Types of changes
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update

## Checklist
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed


### Implementation Details

**Schema Changes:**
- Added `subfolder` property to Repository definition in
`server.schema.json` and `openapi.yaml`
- Field is optional with description and example (`"src/everything"`)

**Go Model:**
- Added `Subfolder string` field to Repository struct with
`json:"subfolder,omitempty"` tag
- Maintains backward compatibility through omitempty behavior

**Security-Focused Validation:**
- Validates subfolder is a clean relative path (no leading `/`)
- Prevents path traversal attacks (no `..` sequences)
- Blocks malformed paths (no trailing `/`, empty segments, invalid
characters)
- Uses regex validation for allowed characters: `^[a-zA-Z0-9\-_./]+$`

**Documentation:**
- Added monorepo example to `examples.md` demonstrating subfolder usage
- Updated `repository_references.md` with concise subfolder
documentation
- Maintained consistency across all documentation with same example path

**Testing:**
- 6 new integration tests in validator covering security and format
validation
- Updated example count validation tool for new example
- All existing tests continue to pass

### Design Decisions

1. **Optional by design**: Most servers don't need subfolder
(single-repo pattern is common)
2. **Clean separation**: Repository URL stays clean, subfolder is
separate metadata
3. **Security first**: Comprehensive validation prevents common
path-based attacks
4. **Publisher tool unchanged**: Default templates don't include
subfolder to avoid confusion for typical use cases

This enables publishers with monorepo structures to clearly specify
server locations while maintaining simplicity for the common
single-repository case.

docs/server-json/examples.md

@@ -46,6 +46,47 @@
 }
 ```
 
+## Server in a Monorepo with Subfolder
+
+For MCP servers located within a subdirectory of a larger repository (monorepo structure), use the `subfolder` field to specify the relative path:
+
+```json
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
+  "name": "io.modelcontextprotocol/everything",
+  "description": "MCP server that exercises all the features of the MCP protocol",
+  "status": "active",
+  "repository": {
+    "url": "https://github.com/modelcontextprotocol/servers",
+    "source": "github",
+    "subfolder": "src/everything"
+  },
+  "version_detail": {
+    "version": "0.6.2"
+  },
+  "packages": [
+    {
+      "registry_type": "npm",
+      "registry_base_url": "https://registry.npmjs.org",
+      "identifier": "@modelcontextprotocol/everything",
+      "version": "0.6.2",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ],
+  "_meta": {
+    "publisher": {
+      "tool": "npm-publisher",
+      "version": "1.0.1",
+      "build_info": {
+        "timestamp": "2023-12-01T10:30:00Z"
+      }
+    }
+  }
+}
+```
+
 ## Constant (fixed) arguments needed to start the MCP server
 
 Suppose your MCP server application requires a `mcp start` CLI arguments to start in MCP server mode. Express these as positional arguments like this: