feat(cli): add validate command for static linting of tool, resource, and prompt files

[lzvxck]

Important: Please ensure your pull request is targeting the canary branch. PRs to other branches may be closed or require retargeting.

⚠️ If you are updating documentation or the site, please target the main branch instead of canary.

Summary

Adds xmcp validate, a CLI command that statically analyzes tool, resource, and prompt files for common structural issues before building or deploying.

Checks performed:

• error — missing export default (handler is required by the runtime)
• error — missing export const metadata (tool is undiscoverable without it)
• warning — missing export const schema (tools only; empty schema is valid but worth surfacing)
• warning — placeholder description ("TODO: Add description" left from xmcp create)

Exits with code 1 when errors are present, 0 for warnings-only — safe to run in CI. Reads xmcp.config.json/ts for directory paths; --tools, --resources, and --prompts flags override them per-run.

Also fixes two incomplete tool files in the http-transport example that were missing metadata, and adds a validate script to its package.json.

Type of Change

• Bug fixing
• Adding a feature
• Improving documentation
• Adding or updating examples
• Performance - bundle size improvement (if applicable)

Affected Packages

• xmcp (core framework)
• create-xmcp-app
• init-xmcp
• Documentation
• Examples

Screenshots/Examples

Running against the http-transport example:

 XMCP  Validating 9 files...

  ✗  src/tools/extra-arguments.ts
       warn   missing export const schema
  ✔  src/tools/greet.ts
  ✔  src/tools/hash-string.ts
  ✗  src/tools/random-number.ts
       warn   missing export const schema
  ✗  src/tools/structured-content.ts
       warn   missing export const schema
  ✔  src/resources/(config)/app.ts
  ✔  src/resources/(users)/[userId]/profile.ts
  ✔  src/prompts/review-code.ts
  ✔  src/prompts/team-greeting.ts

  3 warnings — 3 of 9 files have issues

The three warnings are intentional — those tools take no input parameters, so omitting schema is valid. The command exits 0 since there are no errors.

Usage:

xmcp validate
xmcp validate --tools src/tools --resources src/resources --prompts src/prompts

Related Issues

[vercel]

@lioarce01 is attempting to deploy a commit to the xmcp Team on Vercel.

A member of the Team first needs to authorize it.

[valebearzotti]

error — missing export const metadata (tool is undiscoverable without it)

Omitting metadata is valid cause we default it on the framework. Why would we error on that?

warning — missing export const schema (tools only; empty schema is valid but worth surfacing)

some tools don't need schemas and this only creates friction and incorrect warnings.

Overall I don't feel we need this custom validate script. We could be leveraging the failing of build into running a couple checks to prevent the server from crashing, like validating there's a default export with the handler (*the only required export)

[lzvxck]

Thanks for the review, you're right on all counts.

On metadata: agreed, removing that as an error. Flagging it as an error was wrong.

On schema: agreed. The framework defaults missing schema to {} and registers the tool with z.object({}), fully valid. Warning on every schemaless tool is friction without signal.

On the broader question: you're right, a custom validate script adds unnecessary complexity. I'll drop it and instead hook the export default check directly into the build step, so the server is protected from crashing without needing a separate command. I'll open a follow-up PR for that.

Thanks again for the direction.