Align mpak-schemas with canonical MCPB v0.4 user_config spec
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
- Tighten `UserConfigFieldSchema` with `.strict()` + required fields + new type variants
- Bump `mpak-schemas` 0.2.0 → 0.3.0 (breaking)
- Bump `mpak-sdk` to pick up new schemas + publish
- Sweep all internal test fixtures (mpak repo + nimblebrain repo)
- Audit and update every bundle manifest we control, republish each
Clean, but every unmigrated bundle breaks until it's republished.
Soft deprecation
- Same schema tightening BUT `.describe` + runtime warning in SDK when fields are missing, not rejection
- Ship warning release, give bundle authors a cycle to add missing fields
- 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
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from NimbleBrainInc/mpak
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
NimbleBrainInc/mpak#180 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
NimbleBrainInc/mpak#175 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
NimbleBrainInc/mpak#159 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
NimbleBrainInc/mpak#120 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
NimbleBrainInc/mpak#112 ·
All issues in NimbleBrainInc/mpak
Similar issues
-
bug documentation
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Potential Bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Comfy-Org/ComfyUI_frontend#23773 ·
Maintainers usually reply within 1 day
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 85/100
lingdojo/kana-dojo#34301 · 1 comment · 5 reactions ·
Maintainers usually reply within 1 day
-
code-quality refactoring
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
github/gh-aw-firewall#11797 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
code-yeongyu/senpi#7007 ·
Maintainers usually reply within 1 day