toolcraft 0.0.7 → 0.0.9

package/README.md

@@ -444,17 +444,20 @@ If you have an existing MCP server you want to keep running, use the MCP proxy:
 - `presets?: boolean` — enables `--preset <path>` for loading parameter defaults from JSON files.
 - `apiVersion?: string` — for `requires.apiVersion`.
 - `humanInLoop?: HumanInLoopRuntimeOptions`
+- `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`).
 
 ### `createSDK(root, options)`
 
 - `casing?: "camel"` — generated SDK member style.
 - `services?` / `humanInLoop?` / `apiVersion?`
+- `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`).
 
 ### `createMCPServer(root, options)` / `runMCP(root, options)`
 
 - `name: string`
 - `version: string`
 - `services?` / `humanInLoop?` / `apiVersion?`
+- `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`).
 - `tools?: string[]` — allowlist of MCP tool names or group prefixes. Tool names are `__`-joined snake_case path segments (`root__bot__create`); a prefix like `root__bot` includes every descendant tool.
 - `casing?: "snake" | "camel"` — affects MCP **input-schema property names** only. Tool names always stay `__`-joined snake_case.
 

package/dist/cli.d.ts

@@ -5,6 +5,7 @@ export interface RunCLIOptions<TServices extends object = Record<string, unknown
     apiVersion?: string;
     casing?: Casing;
     humanInLoop?: HumanInLoopRuntimeOptions;
+    projectRoot?: string;
     rootDisplayName?: string;
     rootUsageName?: string;
     services?: TServices;

package/dist/cli.js

@@ -714,20 +714,36 @@ function formatSecretDescription(secret) {
     }
     return secret.optional === true ? "Optional secret" : "Required secret";
 }
-function formatCommandRowName(node, depth) {
-    const name = node.aliases.length === 0 ? node.name : `${node.name} (${node.aliases.join(", ")})`;
+function wrapOptionalCommandParameterToken(token, optional) {
+    return optional ? `[${token}]` : token;
+}
+function formatCommandDynamicParameterTokens(field, casing) {
+    const optional = field.optional || field.hasDefault;
+    return formatDynamicHelpFields(field, casing).map((row) => wrapOptionalCommandParameterToken(row.flags, optional));
+}
+function formatCommandParameterTokens(command, casing, globalLongOptionFlags) {
+    const collected = collectFields(command.params, casing, globalLongOptionFlags);
+    const fields = assignPositionals(collected.fields, command.positional);
+    return fields
+        .map((field) => wrapOptionalCommandParameterToken(formatHelpFieldFlags(field, globalLongOptionFlags), field.positionalIndex === undefined && (field.optional || field.hasDefault)))
+        .concat(collected.dynamicFields.flatMap((field) => formatCommandDynamicParameterTokens(field, casing)));
+}
+function formatCommandRowName(node, depth, casing, globalLongOptionFlags) {
+    const baseName = node.aliases.length === 0 ? node.name : `${node.name} (${node.aliases.join(", ")})`;
+    const parameterTokens = node.kind === "command" ? formatCommandParameterTokens(node, casing, globalLongOptionFlags) : [];
+    const name = parameterTokens.length === 0 ? baseName : `${baseName} ${parameterTokens.join(" ")}`;
     return `${"  ".repeat(depth)}${name}`;
 }
-function formatCommandRows(group, scope, depth = 0) {
+function formatCommandRows(group, scope, casing, globalLongOptionFlags, depth = 0) {
     return getVisibleChildren(group, scope).flatMap((child) => {
         const row = {
-            name: formatCommandRowName(child, depth),
+            name: formatCommandRowName(child, depth, casing, globalLongOptionFlags),
             description: child.description ?? "",
         };
         if (child.kind === "command") {
             return [row];
         }
-        return [row, ...formatCommandRows(child, scope, depth + 1)];
+        return [row, ...formatCommandRows(child, scope, casing, globalLongOptionFlags, depth + 1)];
     });
 }
 function formatGlobalOptionRows(showVersion, presetsEnabled) {
@@ -766,9 +782,10 @@ function buildUsageLine(breadcrumb, rootUsageName, suffix) {
     const subPath = breadcrumb.slice(1).join(" ");
     return subPath ? `${rootUsageName} ${subPath} ${suffix}` : `${rootUsageName} ${suffix}`;
 }
-function renderGroupHelp(group, breadcrumb, scope, showVersion, presetsEnabled, rootUsageName) {
+function renderGroupHelp(group, breadcrumb, scope, casing, showVersion, presetsEnabled, rootUsageName) {
     const sections = [];
-    const commandRows = formatCommandRows(group, scope);
+    const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled);
+    const commandRows = formatCommandRows(group, scope, casing, globalLongOptionFlags);
     if (commandRows.length > 0) {
         sections.push(`${text.section("Commands:")}\n${formatCommandList(commandRows)}`);
     }
@@ -833,7 +850,7 @@ async function renderGeneratedHelp(root, argv, options) {
     const casing = options.casing ?? "kebab";
     await withOutputFormat(output, async () => {
         const rendered = target.node.kind === "group"
-            ? renderGroupHelp(target.node, target.breadcrumb, "cli", options.version !== undefined, options.presets === true, options.rootUsageName)
+            ? renderGroupHelp(target.node, target.breadcrumb, "cli", casing, options.version !== undefined, options.presets === true, options.rootUsageName)
             : renderLeafHelp(target.node, target.breadcrumb, casing, options.presets === true, options.rootUsageName);
         process.stdout.write(rendered);
     });
@@ -2003,7 +2020,7 @@ function handleRunError(error, verbose) {
 }
 export async function runCLI(roots, options = {}) {
     const root = mergeApprovalsGroup(normalizeRoots(roots, process.argv));
-    await resolveMcpProxies(root);
+    await resolveMcpProxies(root, { projectRoot: options.projectRoot });
     const casing = options.casing ?? "kebab";
     const services = (options.services ?? {});
     const runtimeOptions = options.humanInLoop ?? {};

package/dist/mcp-proxy.d.ts

@@ -1,8 +1,11 @@
 import type { McpServerConfig } from "@poe-code/agent-mcp-config";
 import { McpClient } from "tiny-mcp-client";
 import type { Group } from "./index.js";
+export interface ResolveMcpProxyOptions {
+    projectRoot?: string;
+}
 export declare function hasMcpProxyGroups(root: Group<any>): boolean;
 export declare function resolveCachePath(name: string, projectRoot?: string): string;
 export declare function parseRefreshEnv(value: string | undefined): "all" | Set<string> | undefined;
 export declare function dialUpstream(name: string, config: McpServerConfig): Promise<McpClient>;
-export declare function resolveMcpProxies(root: Group<any>): Promise<void>;
+export declare function resolveMcpProxies(root: Group<any>, options?: ResolveMcpProxyOptions): Promise<void>;

package/dist/mcp-proxy.js

@@ -268,7 +268,7 @@ function isRefreshRequested(name, refresh) {
     }
     return refresh?.has(name) === true;
 }
-async function resolveSingleProxy(group) {
+async function resolveSingleProxy(group, options) {
     const internal = getInternalGroupConfig(group);
     const config = internal.mcp;
     if (config === undefined) {
@@ -276,7 +276,7 @@ async function resolveSingleProxy(group) {
     }
     const name = group.name;
     try {
-        const cachePath = resolveCachePath(name);
+        const cachePath = resolveCachePath(name, options.projectRoot);
         const refresh = parseRefreshEnv(process.env.TOOLCRAFT_MCP_REFRESH);
         let cache;
         if (isRefreshRequested(name, refresh)) {
@@ -377,7 +377,7 @@ export async function dialUpstream(name, config) {
     await client.connect(transport);
     return client;
 }
-export async function resolveMcpProxies(root) {
+export async function resolveMcpProxies(root, options = {}) {
     const groups = collectProxyGroups(root);
-    await Promise.all(groups.map((group) => resolveSingleProxy(group)));
+    await Promise.all(groups.map((group) => resolveSingleProxy(group, options)));
 }

package/dist/mcp.d.ts

@@ -9,6 +9,7 @@ export interface RunMCPOptions<TServices extends object = Record<string, unknown
     name: string;
     version?: string;
     humanInLoop?: HumanInLoopRuntimeOptions;
+    projectRoot?: string;
     /**
      * Optional allowlist of MCP tool names or group prefixes.
      *

package/dist/mcp.js

@@ -419,7 +419,7 @@ function createDeferredMCPServer(root, options) {
     let serverPromise;
     const resolveServer = () => {
         serverPromise ??= (async () => {
-            await resolveMcpProxies(root);
+            await resolveMcpProxies(root, { projectRoot: options.projectRoot });
             return createResolvedMCPServer(root, options);
         })();
         return serverPromise;
@@ -449,7 +449,7 @@ export function createMCPServer(roots, options) {
 }
 export async function runMCP(roots, options) {
     const root = mergeApprovalsGroup(normalizeRoots(roots));
-    await resolveMcpProxies(root);
+    await resolveMcpProxies(root, { projectRoot: options.projectRoot });
     const server = createResolvedMCPServer(root, options);
     await server.listen();
 }

package/dist/sdk.d.ts

@@ -63,6 +63,7 @@ export interface CreateSDKOptions<TServices extends object = Record<string, unkn
     services?: TServices;
     casing?: "camel";
     humanInLoop?: HumanInLoopRuntimeOptions;
+    projectRoot?: string;
 }
 export declare function createSDK<TRootInfo, TServices extends object = Record<string, unknown>>(root: Group<any> & {
     readonly __agentKitGroupTypeInfo: TRootInfo;

package/dist/sdk.js

@@ -234,7 +234,7 @@ function createDeferredSDK(root, options) {
     let sdkPromise;
     const resolveSDK = () => {
         sdkPromise ??= (async () => {
-            await resolveMcpProxies(root);
+            await resolveMcpProxies(root, { projectRoot: options.projectRoot });
             return createResolvedSDK(root, options);
         })();
         return sdkPromise;

package/node_modules/tiny-mcp-client/README.md

@@ -0,0 +1,97 @@
+# tiny-mcp-client
+
+`tiny-mcp-client` is a lightweight Model Context Protocol client used by tests, fixtures, and package integrations. It supports stdio transports, streamable HTTP transports, in-memory test pairs, JSON-RPC helpers, and OAuth metadata discovery for OAuth-protected MCP HTTP servers.
+
+## Usage
+
+```ts
+import { HttpTransport, McpClient } from "tiny-mcp-client";
+
+const client = new McpClient({
+  clientInfo: { name: "demo", version: "0.1.0" },
+});
+
+await client.connect(new HttpTransport({ url: "http://127.0.0.1:3000/mcp" }));
+const tools = await client.listTools();
+console.log(tools);
+await client.close();
+```
+
+## Transports
+
+| Transport | Description |
+|-----------|-------------|
+| `StdioTransport` | Spawns an MCP server process and communicates over stdio. |
+| `HttpTransport` | Connects to streamable HTTP MCP endpoints, including session IDs, SSE GET streams, and session termination. |
+| `createInMemoryTransportPair()` | Creates paired streams for in-process tests. |
+
+## OAuth HTTP support
+
+`HttpTransport` accepts `oauth` options from `mcp-oauth`. When a protected server returns a Bearer `WWW-Authenticate` challenge, the transport discovers protected-resource metadata, loads authorization-server metadata, lets the OAuth provider handle authorization, and retries the request when credentials are available.
+
+```ts
+import { HttpTransport, createDefaultOAuthClientProvider } from "tiny-mcp-client";
+
+const transport = new HttpTransport({
+  url: "https://mcp.example.com/mcp",
+  oauth: {
+    provider: createDefaultOAuthClientProvider({
+      client: {
+        mode: "dynamic",
+        metadata: {
+          clientName: "tiny-client",
+        },
+      },
+      browser: {
+        openBrowser: async (url) => {
+          console.log(`Open ${url}`);
+        },
+      },
+    }),
+  },
+});
+```
+
+You can also call `discoverOAuthMetadata(resourceUrl, options)` directly, or instantiate `OAuthMetadataDiscovery` with a custom `fetch` implementation and shared cache.
+
+## Testing helpers
+
+- `createTestPair()` and `createSdkTestPair()` create paired client/server fixtures.
+- `createInMemoryTransportPair()` is useful for fast unit tests without opening sockets or spawning processes.
+- JSON-RPC error constants are exported for assertions: `ERROR_PARSE`, `ERROR_INVALID_REQUEST`, `ERROR_METHOD_NOT_FOUND`, `ERROR_INVALID_PARAMS`, and `ERROR_INTERNAL`.
+
+## Config options
+
+### `McpClientOptions`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `clientInfo` | `{ name: string; version: string }` | Required client identity sent during initialize. |
+| `capabilities` | `ClientCapabilities` | Optional MCP client capabilities. |
+| `onToolsChanged`, `onResourcesChanged`, `onPromptsChanged` | callbacks | Optional notification handlers. |
+| `onResourceUpdated`, `onLog`, `onProgress` | callbacks | Optional resource/log/progress handlers. |
+| `onSamplingRequest`, `onRootsList` | callbacks | Optional server-to-client request handlers. |
+
+### `HttpTransportOptions`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `url` | `string` | MCP HTTP endpoint URL. |
+| `headers` | `HeadersInit` | Static headers added to requests. |
+| `fetch` | `(input, init?) => Promise<Response>` | Custom fetch implementation. |
+| `oauth` | `OAuthClientProviderOptions` | Enables OAuth authorization handling. |
+| `oauthDiscoveryCache` | `OAuthDiscoveryCache` | Optional shared metadata cache. |
+
+### `StdioTransportOptions`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `command` | `string` | Server executable. |
+| `args` | `string[]` | Server args. |
+| `cwd` | `string` | Server working directory. |
+| `env` | `NodeJS.ProcessEnv` | Server environment. |
+| `spawn` | `StdioSpawn` | Custom spawn function for tests. |
+
+## Environment variables
+
+This package does not expose public environment variables. Pass process environment explicitly through `StdioTransportOptions.env` when a spawned MCP server needs it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -45,7 +45,7 @@
     "commander": "^14.0.3",
     "console-table-printer": "^2.15.0",
     "tiny-stdio-mcp-server": "^0.1.0",
-    "toolcraft-schema": "^0.0.7"
+    "toolcraft-schema": "^0.0.9"
   },
   "files": [
     "dist"