Expose env-alias tier (substituteEnvVars / gatherUserConfig) publicly

Open
#86 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
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
typescript
Domain
api

Research direction

Start in packages/sdk-typescript/src/mpakSDK.ts and read the private static substituteEnvVars and gatherUserConfig methods, then check how prepareServer calls them. Decide which of the two proposed public API shapes best fits the existing SDK before changing the API. Done means hosts can use the env alias tier without prepareServer; verify the exported API and its behavior with the relevant SDK tests.

Written by the indexing model from the issue text.

Description

Context

Mpak.substituteEnvVars and Mpak.gatherUserConfig are private static in the mpak SDK (see packages/sdk-typescript/src/mpakSDK.ts ≈ lines 1036, 1160 in 0.5.0). prepareServer uses them to resolve ${user_config.*} placeholders against declared mcp_config.env aliases (the env-alias tier) and substitute into the spawn env.

Host runtimes that need substitution without going through prepareServer — e.g. because they load an unpacked bundle directory instead of a .mcpb archive — currently have to reimplement the tier themselves.

Prior art in NimbleBrain

NimbleBrainInc/nimblebrain#44 adds substituteUserConfigFromEnv() in src/bundles/startup.ts for the local-path branch of startBundleSource. It's a ~50-line inline replica of the SDK's env-alias tier + placeholder substitution. The helper's existence is explicitly documented as a duplication that should be deleted once the SDK exposes the tier publicly.

Proposal

One of:

  1. Expose substituteEnvVars as a public static on Mpak — takes (env: Record<string, string>, userConfigValues: Record<string, string>) => Record<string, string>. Hosts still compute userConfigValues themselves if they need different tiering.
  2. Expose a higher-level helper — Mpak.resolveEnv(manifest, userConfig, processEnv) that wraps the env-alias tier + substitution for hosts that want the full SDK resolution without the filesystem-cache/archive plumbing of prepareServer.

(1) is the smaller API surface; (2) is more useful but couples the shape to host use cases.

Impact

  • Unblocks deleting substituteUserConfigFromEnv from nimblebrain after the SDK bump
  • Other mpak host runtimes get the same benefit
  • No breaking change; additive public API

Related

  • NimbleBrainInc/nimblebrain#44 — contains the duplicated helper pending this API
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.