Align mpak-schemas with canonical MCPB v0.4 user_config spec

Open
#84 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
typescript
Domain
backend

Research direction

Start with packages/schemas/src/manifest.ts and inspect UserConfigFieldSchema against the linked canonical MCPB v0.4 schema. Then grep controlled repositories for bundle manifests with user_config fields and count which need migration; use that audit to choose hard cut or soft deprecation. Done means the chosen migration is implemented and affected fixtures and manifests are updated.

Written by the indexing model from the issue text.

Description

Problem

`@nimblebrain/mpak-schemas` has drifted from the canonical MCPB v0.4 manifest schema on the `user_config` field definition. Our Zod schema is more permissive than canonical — manifests that validate against mpak would fail against the upstream MCPB validator. Any third party testing against the canonical schema would flag our bundles as non-conformant.

Drift inventory (`UserConfigFieldSchema` in `packages/schemas/src/manifest.ts`)

Canonical mpak-schemas today Gap
`type` enum includes `directory`, `file` Only `string|number|boolean` Missing 2 variants
`title` required `.optional()` Should be required
`description` required `.optional()` Should be required
`default` allows `string[]` Only primitives Should widen
`multiple: boolean` (optional) Not in schema Add
`min: number` (optional) Not in schema Add
`max: number` (optional) Not in schema Add
`additionalProperties: false` Zod default (permissive) Add `.strict()`

Top-level manifest also has canonical fields we ignore (`screenshots`, `icons[]`, `privacy_policies`, `compatibility`, `localization`, etc.) — harmless additive gaps, not blocking anything today. Primary concern is `user_config`.

Impact of fixing

Making `title` and `description` required is a breaking change — every bundle manifest without `description` on its user_config fields fails to validate. Known ripples:

  • Internal tests: ~20–30 fixture declarations in `packages/sdk-typescript/tests/mpak.test.ts` missing `description` (inherited pattern)
  • NimbleBrain tests: several integration fixtures in `products/nimblebrain/code/test/` inherit the same pattern
  • Real bundles: every published bundle that declares `user_config` needs audit. Audit candidates: `mcp-servers/`, `synapse-apps/`, `products//code/bundles/`, anything else in the ecosystem.

Proposed migration

Two options, pick one:

Hard cut
  1. Tighten `UserConfigFieldSchema` with `.strict()` + required fields + new type variants
  2. Bump `mpak-schemas` 0.2.0 → 0.3.0 (breaking)
  3. Bump `mpak-sdk` to pick up new schemas + publish
  4. Sweep all internal test fixtures (mpak repo + nimblebrain repo)
  5. Audit and update every bundle manifest we control, republish each

Clean, but every unmigrated bundle breaks until it's republished.

Soft deprecation
  1. Same schema tightening BUT `.describe` + runtime warning in SDK when fields are missing, not rejection
  2. Ship warning release, give bundle authors a cycle to add missing fields
  3. Flip to strict rejection in the following release

Gentler, 2x release effort.

Out of scope for this issue

  • Canonical top-level manifest fields we don't use (`screenshots`, `icons[]`, etc.) — add as needed, no hurry
  • SDK-side handling of new `directory` / `file` types beyond just accepting them in the schema (path resolution, existence checks, etc.) — can follow separately once the first bundle actually declares one

Context

Surfaced during QA review of `@nimblebrain/[email protected]` (env-aliases on MpakConfigError). New test fixtures in that PR were made canonical-conformant; pre-existing drift predates the PR and was flagged but kept out of scope.

Suggested first step

A grep sweep across controlled repos to count how many bundle manifests actually need updating — that determines whether hard-cut or soft-deprecation is the right path.

Dominant language
TypeScript
Stars
14
Forks
13
Avg merge
16m
Merged PRs (30d)
4

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from NimbleBrainInc/mpak

All issues in NimbleBrainInc/mpak

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.