@usemcpkit/core 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -440,8 +440,10 @@ export declare interface StdioUpstream {
440
440
  command: string;
441
441
  /** May contain `{repo}`, the folder of `repo`'s clone. */
442
442
  args?: readonly string[];
443
- /** Names of credentials (the manifest's `auth` env names) handed to the child as environment variables. */
443
+ /** Names of credentials (the manifest's `auth` env names) handed to the child as environment variables; a missing one is an error. */
444
444
  forwardEnv?: readonly string[];
445
+ /** Names handed to the child when set, in the client's env or the secret store; the upstream decides what a missing one means. */
446
+ optionalEnv?: readonly string[];
445
447
  /** When set, the program is run from this repository, cloned and set up on first use. */
446
448
  repo?: UpstreamRepo;
447
449
  /** How the upstream's tool names become catalog names; tools no rule matches are named `tools:<snake_case>`. */
@@ -601,7 +603,10 @@ export declare interface UpstreamNameRule {
601
603
  /** A git repository the upstream server is run from, cloned on first use into `~/.mcpkit/repos/<category>/<name>`. */
602
604
  export declare interface UpstreamRepo {
603
605
  url: string;
604
- /** Tag or commit to check out; pin a commit, since the checkout is run as code. */
606
+ /**
607
+ * Commit, tag or branch to check out. A commit is pinned and never compared; a tag or branch is compared with the
608
+ * remote on use and the clone rebuilt when it moved. The checkout is run as code, so pin a commit unless you trust the ref.
609
+ */
605
610
  ref: string;
606
611
  /** Run in order in the clone once, after checkout, with no credentials in the environment. */
607
612
  setup?: readonly RepoSetupStep[];
@@ -457,7 +457,7 @@ var validateUpstreamRepo = (repo) => {
457
457
  if (!isJsonObject(repo)) return ["upstream.repo must be an object"];
458
458
  const errors = [];
459
459
  if (!isHttpsUrl(repo.url)) errors.push("upstream.repo.url must be an https:// URL");
460
- if (typeof repo.ref !== "string" || !REF_PATTERN.test(repo.ref)) errors.push("upstream.repo.ref must be a tag or commit, not starting with '-'");
460
+ if (typeof repo.ref !== "string" || !REF_PATTERN.test(repo.ref)) errors.push("upstream.repo.ref must be a commit, tag or branch, not starting with '-'");
461
461
  if (repo.setup !== void 0) {
462
462
  if (Array.isArray(repo.setup)) errors.push(...repo.setup.flatMap(validateSetupStep));
463
463
  else errors.push("upstream.repo.setup must be a list of steps");
@@ -473,6 +473,7 @@ var validateStdio = (upstream) => {
473
473
  if (typeof upstream.command !== "string" || !PROGRAM_NAME_PATTERN.test(upstream.command)) errors.push("upstream.command must be a program name on PATH, not a path");
474
474
  if (upstream.args !== void 0 && !isStringList(upstream.args)) errors.push("upstream.args must be a list of strings");
475
475
  if (upstream.forwardEnv !== void 0 && !isStringList(upstream.forwardEnv)) errors.push("upstream.forwardEnv must be a list of strings");
476
+ if (upstream.optionalEnv !== void 0 && !isStringList(upstream.optionalEnv)) errors.push("upstream.optionalEnv must be a list of strings");
476
477
  if (upstream.repo !== void 0) errors.push(...validateUpstreamRepo(upstream.repo));
477
478
  return errors;
478
479
  };
@@ -2113,17 +2114,19 @@ var nameUpstreamTool = (rules, upstreamName) => {
2113
2114
  };
2114
2115
  //#endregion
2115
2116
  //#region src/execution/upstream/read-forwarded-env.ts
2116
- /** Each forwarded credential from its env var, else from the secret store. */
2117
- var readForwardedEnv = async (manifest, { forwardEnv = [] }, domain, context) => {
2117
+ /** Each forwarded credential from its env var, else from the secret store; an optional one is left out when unset. */
2118
+ var readForwardedEnv = async (manifest, { forwardEnv = [], optionalEnv = [] }, domain, context) => {
2118
2119
  const owner = {
2119
2120
  name: manifest.name,
2120
2121
  category: manifest.category,
2121
2122
  domain
2122
2123
  };
2123
- const entries = await Promise.all(forwardEnv.map(async (name) => [name, context.env[name] || await context.secretStore?.get(owner, name)]));
2124
- const missing = entries.filter(([, value]) => !value).map(([name]) => name);
2124
+ const read = async (name) => [name, context.env[name] || await context.secretStore?.get(owner, name)];
2125
+ const required = await Promise.all(forwardEnv.map(read));
2126
+ const missing = required.filter(([, value]) => !value).map(([name]) => name);
2125
2127
  if (missing.length > 0) throw new AuthError(`${manifest.name}: missing credential, set ${missing.join(", ")} in the client's env for mcpkit`);
2126
- return Object.fromEntries(entries.map(([name, value]) => [name, value ?? ""]));
2128
+ const optional = (await Promise.all(optionalEnv.map(read))).filter(([, value]) => value);
2129
+ return Object.fromEntries([...required, ...optional].map(([name, value]) => [name, value ?? ""]));
2127
2130
  };
2128
2131
  //#endregion
2129
2132
  //#region src/execution/upstream/with-upstream-access.ts
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@usemcpkit/core",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Manifest-driven MCP tool execution: manifest validation, HTTP execution, response mapping, auth and the server SDK.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -35,7 +35,7 @@
35
35
  "devDependencies": {
36
36
  "@biomejs/biome": "2.5.15",
37
37
  "@microsoft/api-extractor": "^7.59.4",
38
- "@usemcpkit/testing": "0.6.0",
38
+ "@usemcpkit/testing": "0.7.0",
39
39
  "typescript": "^5.9.0",
40
40
  "vite": "^8.0.0",
41
41
  "vite-plugin-dts": "5.1.2",