toolcraft 0.0.3 → 0.0.5

package/README.md

@@ -285,8 +285,11 @@ defineGroup({
 
 - `tools` filters by upstream tool name.
 - `rename` remaps to dotted toolcraft paths; missing intermediate groups are created.
-- Discovery is cached at `<projectRoot>/.toolcraft/mcp/<group>.json` (project root = nearest ancestor with `package.json`).
+- Proxy discovery is eager for `runCLI` and `runMCP`: they resolve every `defineGroup({ mcp })` proxy in the root tree before routing, command execution, or CLI help rendering. SDK proxies resolve when the deferred SDK is awaited or first used.
+- On a first run without cached schemas, even `my-cli --help` or `my-cli some-group --help` may connect to every configured upstream MCP server.
+- Discovery is cached at `<projectRoot>/.toolcraft/mcp/<group>.json` (project root = nearest ancestor with `package.json`), so successful discovery avoids repeated upstream connects unless refreshed.
 - `TOOLCRAFT_MCP_REFRESH=1` refreshes all proxies; `TOOLCRAFT_MCP_REFRESH=github,linear` refreshes specific ones.
+- Selective or lazy discovery for only the requested command path is not currently supported. CLIs that wrap many MCP servers should expect first-run help to touch all of them.
 - Discovery output goes to stderr only.
 
 ## Human-in-loop approvals

package/dist/cli.js

@@ -7,6 +7,7 @@ import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
 import { invokeWithHumanInLoop } from "./human-in-loop/index.js";
 import { resolveMcpProxies } from "./mcp-proxy.js";
 import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
+import { findEntrypointPackageMetadata } from "./package-metadata.js";
 import { renderResult } from "./renderer.js";
 const RESERVED_SERVICE_NAMES = new Set(["params", "secrets", "fetch", "fs", "env", "progress"]);
 const NULL_OPTION_VALUE = Symbol("toolcraft.cli.null");
@@ -1990,6 +1991,7 @@ export async function runCLI(roots, options = {}) {
     const casing = options.casing ?? "kebab";
     const services = (options.services ?? {});
     const runtimeOptions = options.humanInLoop ?? {};
+    const version = options.version ?? findEntrypointPackageMetadata(process.argv[1])?.version;
     const servicesWithBuiltIns = {
         ...services,
         runtimeOptions,
@@ -2000,7 +2002,7 @@ export async function runCLI(roots, options = {}) {
     };
     validateServices(services);
     if (hasHelpFlag(process.argv)) {
-        await renderGeneratedHelp(root, process.argv, options);
+        await renderGeneratedHelp(root, process.argv, { ...options, version });
         return;
     }
     const program = new CommanderCommand();
@@ -2009,8 +2011,8 @@ export async function runCLI(roots, options = {}) {
     program.showHelpAfterError();
     program.addHelpCommand(false);
     addGlobalOptions(program);
-    if (options.version !== undefined) {
-        program.version(options.version, "--version");
+    if (version !== undefined) {
+        program.version(version, "--version");
     }
     let lastActionCommand;
     const execute = async (state) => {

package/dist/index.d.ts

@@ -179,5 +179,7 @@ export declare function defineGroup<TServices extends object = EmptyServices, TN
 export declare function getCommandSourcePath(command: Command<any, any, any, any>): string | undefined;
 export { S, toJsonSchema } from "toolcraft-schema";
 export { ApprovalDeclinedError, UserError };
+export { findPackageMetadata, packageMetadata } from "./package-metadata.js";
+export type { PackageMetadata } from "./package-metadata.js";
 export type { AnySchema, ArraySchema, BooleanSchema, EnumSchema, JsonSchema, NumberSchema, ObjectSchema, OptionalSchema, Static, StringSchema } from "toolcraft-schema";
 export type { HumanInLoopConfig, HumanInLoopPending, HumanInLoopRuntimeOptions };

package/dist/index.js

@@ -429,3 +429,4 @@ export function getCommandSourcePath(command) {
 }
 export { S, toJsonSchema } from "toolcraft-schema";
 export { ApprovalDeclinedError, UserError };
+export { findPackageMetadata, packageMetadata } from "./package-metadata.js";

package/dist/mcp.d.ts

@@ -7,7 +7,7 @@ type CmdkitServer = Omit<TinyServer, "connect"> & {
 };
 export interface RunMCPOptions<TServices extends object = Record<string, unknown>> {
     name: string;
-    version: string;
+    version?: string;
     humanInLoop?: HumanInLoopRuntimeOptions;
     /**
      * Optional allowlist of MCP tool names or group prefixes.

package/dist/mcp.js

@@ -6,6 +6,7 @@ import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
 import { ApprovalDeclinedError, invokeWithHumanInLoop, } from "./human-in-loop/index.js";
 import { hasMcpProxyGroups, resolveMcpProxies } from "./mcp-proxy.js";
 import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
+import { findEntrypointPackageMetadata } from "./package-metadata.js";
 import { filterSchemaForScope } from "./schema-scope.js";
 const RESERVED_SERVICE_NAMES = new Set(["params", "secrets", "fetch", "fs", "env", "progress"]);
 function normalizeRoots(roots) {
@@ -365,7 +366,8 @@ function createResolvedMCPServer(root, options) {
     };
     validateServices(services);
     const tools = enumerateTools(root, casing, options.tools);
-    const server = createServer({ name: options.name, version: options.version });
+    const version = resolveMCPVersion(options.version);
+    const server = createServer({ name: options.name, version });
     for (const tool of tools) {
         server.tool(tool.name, tool.description, tool.inputSchema, async (argumentsValue) => {
             try {
@@ -406,6 +408,13 @@ function createResolvedMCPServer(root, options) {
         },
     };
 }
+function resolveMCPVersion(version) {
+    const resolvedVersion = version ?? findEntrypointPackageMetadata(process.argv[1])?.version;
+    if (resolvedVersion === undefined) {
+        throw new Error("MCP version is required when no package.json version can be inferred from the entrypoint.");
+    }
+    return resolvedVersion;
+}
 function createDeferredMCPServer(root, options) {
     let serverPromise;
     const resolveServer = () => {

package/dist/package-metadata.d.ts

@@ -0,0 +1,10 @@
+export interface PackageMetadata {
+    name?: string;
+    path: string;
+    version?: string;
+}
+type PackageMetadataInput = string | URL;
+export declare function findPackageMetadata(from: PackageMetadataInput): PackageMetadata | undefined;
+export declare function packageMetadata(from?: PackageMetadataInput): PackageMetadata;
+export declare function findEntrypointPackageMetadata(entrypoint: string | undefined): PackageMetadata | undefined;
+export {};

package/dist/package-metadata.js

@@ -0,0 +1,62 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function pathFromInput(from) {
+    if (from instanceof URL) {
+        return fileURLToPath(from);
+    }
+    if (from.startsWith("file:")) {
+        return fileURLToPath(from);
+    }
+    return path.resolve(from);
+}
+function getSearchDirectory(from) {
+    const resolved = pathFromInput(from);
+    try {
+        return statSync(resolved).isDirectory() ? resolved : path.dirname(resolved);
+    }
+    catch {
+        return path.dirname(resolved);
+    }
+}
+function readPackageMetadata(packageJsonPath) {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    const metadata = { path: packageJsonPath };
+    if (typeof parsed.name === "string") {
+        metadata.name = parsed.name;
+    }
+    if (typeof parsed.version === "string") {
+        metadata.version = parsed.version;
+    }
+    return metadata;
+}
+export function findPackageMetadata(from) {
+    let current = getSearchDirectory(from);
+    while (true) {
+        const packageJsonPath = path.join(current, "package.json");
+        if (existsSync(packageJsonPath)) {
+            return readPackageMetadata(packageJsonPath);
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return undefined;
+        }
+        current = parent;
+    }
+}
+export function packageMetadata(from = process.cwd()) {
+    const metadata = findPackageMetadata(from);
+    if (metadata === undefined) {
+        throw new Error(`No package.json found from ${pathFromInput(from)}.`);
+    }
+    return metadata;
+}
+export function findEntrypointPackageMetadata(entrypoint) {
+    if (entrypoint === undefined || entrypoint.length === 0) {
+        return undefined;
+    }
+    if (!path.isAbsolute(entrypoint) && !entrypoint.startsWith("file:")) {
+        return undefined;
+    }
+    return findPackageMetadata(entrypoint);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -50,7 +50,7 @@
     "console-table-printer": "^2.15.0",
     "tiny-mcp-client": "*",
     "tiny-stdio-mcp-server": "^0.1.0",
-    "toolcraft-schema": "^0.0.3"
+    "toolcraft-schema": "^0.0.5"
   },
   "files": [
     "dist"