[Roadmap] Publish and validate MCP Registry metadata

[mohanagy]

Summary

• add a checked-in MCP Registry server.json for the public @lubab/madar npm package
• add a repeatable npm run registry:validate command and run it in CI
• document the public-registry decision and the local-first trust boundary in README and release docs

Closes #433

Summary by CodeRabbit

• New Features

  • Added a public MCP registry entry and local stdio server metadata; included a validator to check registry metadata consistency.

• Chores

  • Integrated registry validation into CI and added npm script to run validation.

• Documentation

  • Updated README and release checklist with registry metadata location, validation instructions, and public-vs-local guidance.

• Tests

  • Added tests to enforce registry metadata matches package and to exercise the validator.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 13a7aa37-b415-4bdd-9cc4-edeee76539f0

📥 Commits

Reviewing files that changed from the base of the PR and between d4b8062 and 5fc3eef.

📒 Files selected for processing (2)

• .github/scripts/validate-mcp-registry.mjs
• tests/unit/mcp-registry-metadata.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• .github/scripts/validate-mcp-registry.mjs

---

📝 Walkthrough

Walkthrough

Adds a checked-in MCP registry manifest and a Node/Ajv validator, tests that assert manifest ↔ package.json alignment (including CLI args and env var), CI and npm script wiring for validation, and README/release docs updates describing the manifest and validation command.

Changes

MCP Registry Metadata Definition and Validation

Layer / File(s)	Summary
Registry manifest and validator docs/mcp-registry/server.json, .github/scripts/validate-mcp-registry.mjs	Adds the public MCP registry JSON entry and a Node script that compiles a Draft-07 JSON Schema with Ajv, validates the manifest, and asserts cross-file/content constraints (name/repo/version, single npm package wiring, madar serve --stdio <graph_path> positional arg, MADAR_TOOL_PROFILE).
Test suite and executable checks tests/unit/mcp-registry-metadata.test.ts	Adds Vitest tests that load package.json and server.json, validate schema/metadata alignment, run the validator executable, include a negative duplicate-packages test, and assert README/release.md mention the manifest path and validation command.
CI integration and scripts package.json, .github/workflows/ci.yml	Adds registry:validate and publish:dry-run scripts, pins ajv and ajv-formats devDependencies, and inserts a CI step that runs npm run registry:validate on ubuntu-latest/Node 22 after npm ci.
Documentation updates README.md, docs/release.md	Documents the checked-in docs/mcp-registry/server.json, how to validate it locally (npm run registry:validate), local stdio server flow, and updates the release checklist to include registry metadata verification.

Sequence Diagram

sequenceDiagram
  participant validate_mjs as validate-mcp-registry.mjs
  participant package_json as package.json
  participant server_json as docs/mcp-registry/server.json
  participant AJV as AJV
  participant Assertions as Assertions
  validate_mjs->>package_json: load package metadata
  validate_mjs->>server_json: load registry manifest
  validate_mjs->>AJV: compile Draft-07 schema
  validate_mjs->>AJV: validate server.json
  AJV-->>validate_mjs: validation result
  validate_mjs->>Assertions: run cross-file assertions
  Assertions-->>validate_mjs: assertions pass / throw on failure

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I checked the manifest, line by line,
AJV hummed softly, all tests align,
CI nods yes, docs point the way,
A tiny validator saves the day,
Madar hops forward — registry ready to play.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: publishing and validating MCP Registry metadata, which is exactly what this PR delivers.
Description check	✅ Passed	The description covers the key changes, links the resolved issue (#433), and references the required testing checklist framework, providing sufficient context.
Linked Issues check	✅ Passed	All requirements from issue #433 are met: server.json metadata file created [#433], validation command and CI step added [#433], and local-first trust boundary documented in README and release docs [#433].
Out of Scope Changes check	✅ Passed	All changes are scoped to issue #433 objectives: registry metadata file, validation script, CI integration, and documentation updates with no extraneous modifications.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-433-mcp-registry-metadata

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/scripts/validate-mcp-registry.mjs:
- Around line 63-66: The JSON schema allows multiple package entries (packages:
{ type: 'array', minItems: 1 }) but later code (the logic around the first
package handling referenced at the block handling items around the code that
reads the first package) assumes exactly one; add an explicit constraint to
enforce a single-entry array by adding maxItems: 1 to the packages schema (i.e.,
packages: { type: 'array', minItems: 1, maxItems: 1, items: { ... } }) and
update any validation message around the code that selects the first package
(the logic at the section that reads only the first item) to reflect the
enforced single package rule.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: eb4d02df-f001-412c-a4f3-048f39db6f8f

📥 Commits

Reviewing files that changed from the base of the PR and between c16b935 and d4b8062.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (7)

• .github/scripts/validate-mcp-registry.mjs
• .github/workflows/ci.yml
• README.md
• docs/mcp-registry/server.json
• docs/release.md
• package.json
• tests/unit/mcp-registry-metadata.test.ts