@feniix/bridgekit 0.2.2 → 0.4.0

package/README.md

@@ -58,6 +58,10 @@ export const echoTool = definePortableTool({
     };
   },
 });
+
+export function createTools() {
+  return [echoTool];
+}
 ```
 
 Tool definition best practices:
@@ -70,37 +74,60 @@ Tool definition best practices:
 - Respect `ctx.signal` in long-running tools.
 - Use `ctx.progress?.(...)` for incremental updates.
 - Keep modules import-passive; do not register tools or start servers at import time.
+- For stateful tools, export a `createTools()` factory instead of a module-level singleton so each host runtime gets isolated state.
+- TypeBox validation happens before `execute`; use a permissive schema plus domain validation if you need custom guidance for structurally invalid input.
 
 ## pi adapter
 
 ```ts
 import { registerPiTools } from "@feniix/bridgekit/pi";
-import { echoTool } from "./tools.js";
+import { createTools } from "./tools.js";
 
 export default function extension(pi: Parameters<typeof registerPiTools>[0]) {
-  registerPiTools(pi, [echoTool]);
+  registerPiTools(pi, createTools());
 }
 ```
 
-Portable validation failures reject with `PortableToolExecutionError` in pi so the host sees a native tool failure. Progress updates from `ctx.progress?.(...)` map to pi tool updates.
+Portable validation failures and portable results with `isError: true` reject with `PortableToolExecutionError` in pi so the host sees a native tool failure. The error message is the portable `text`, and `.details` is populated from `structuredContent` or `details`. Progress updates from `ctx.progress?.(...)` map to pi tool updates.
 
 ## MCP adapter
 
 ```ts
-import { runMcpStdioServer } from "@feniix/bridgekit/mcp";
-import { echoTool } from "./tools.js";
-
-await runMcpStdioServer({
-  name: "my-tools",
-  version: "0.1.0",
-  tools: [echoTool],
-  instructions: "Use these tools when text needs processing.",
-});
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type CreateMcpServerOptions, runMcpStdioServer } from "@feniix/bridgekit/mcp";
+import { createTools } from "./tools.js";
+
+export function createMcpServerOptions(): CreateMcpServerOptions {
+  return {
+    name: "my-tools",
+    version: "0.1.0",
+    tools: createTools(),
+    instructions: "Use these tools when text needs processing.",
+  };
+}
+
+export async function runServer(): Promise<void> {
+  await runMcpStdioServer(createMcpServerOptions());
+}
+
+function realpathIfPossible(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+if (process.argv[1] && realpathIfPossible(resolve(process.argv[1])) === realpathIfPossible(fileURLToPath(import.meta.url))) {
+  await runServer();
+}
 ```
 
 The MCP adapter uses low-level `tools/list` and `tools/call` handlers so TypeBox schemas are exposed as JSON Schema directly. It intentionally does not expose a high-level `registerMcpTools` helper.
 
-MCP invalid input and portable `isError: true` results return `CallToolResult` with `isError: true`.
+MCP invalid input and portable `isError: true` results return `CallToolResult` with `isError: true`. Exporting a server-options factory keeps MCP entrypoints import-passive and easy to test without starting stdio.
 
 ## Custom host typing
 
@@ -139,11 +166,14 @@ Use `PortableToolHost<CustomHost>` for values that may be either a built-in host
 
 ## Package and release checklist
 
-- Publish compiled JavaScript plus generated `.d.ts` declarations, not source as runtime code.
+- Publish compiled JavaScript plus generated `.d.ts` declarations for runtime entrypoints.
 - Keep `exports`, `main`, and `types` aligned with built files.
 - Keep runtime imports in `dependencies`.
 - Avoid `workspace:` or `file:` dependency ranges in publishable packages.
 - Avoid dangling `sourceMappingURL` comments: publish maps and useful sources together, or disable source maps for package builds.
+- For MCP stdio bins, ensure the emitted JavaScript starts with a Node shebang, has executable mode (`chmod +x` or equivalent), and is included by `npm pack --dry-run --json`.
+- If a package keeps a source-loaded host entrypoint (for example a pi extension source file), use a package-local MCP build for the npm-launched bin and narrow that build to the MCP entrypoint plus shared host-neutral modules.
+- Declare a compatible Node engine (`>=22.19.0`) in downstream packages that expose BridgeKit-powered MCP bins.
 - Run `npm run check`, `npm run test`, `npm run pack:dry-run`, and `npm run package-smoke` before publishing.
 - Treat `docs/releasing.md` as the future release handoff; this repository is not configured for automated publish yet.
 

package/examples/README.md

@@ -15,6 +15,18 @@ my-tools-package/
 
 Keep `src/tools.ts` free of pi and MCP imports. Host-specific imports belong only in adapter entrypoints.
 
+Some packages have a host that intentionally loads TypeScript source directly, while MCP clients launched from npm need compiled JavaScript. For that mixed mode, keep the same boundaries but use a package-local MCP build:
+
+```text
+my-pi-extension-package/
+  package.json
+  extensions/
+    tools.ts          # host-neutral portable tools
+    index.ts          # source-loaded pi adapter wiring
+    mcp-server.ts     # compiled MCP stdio server wiring
+  tsconfig.mcp.json   # emits mcp-server.ts + shared modules to dist/
+```
+
 ---
 
 ## 1. Define shared portable tools
@@ -54,14 +66,17 @@ export const reverseTextTool = definePortableTool({
   },
 });
 
-export const tools = [reverseTextTool];
+export function createTools() {
+  return [reverseTextTool];
+}
 ```
 
 Best practices shown here:
 
-- The schema is the single source of truth for argument validation.
+- The schema is the single source of truth for structural argument validation.
 - The handler returns portable `{ text, structuredContent }` data.
 - The handler observes `ctx.signal` without importing a host SDK.
+- The `createTools()` factory gives stateful tools a fresh runtime per host instance; stateless packages may still return the same definitions.
 - The file has no import-time registration or server startup.
 
 ---
@@ -71,10 +86,10 @@ Best practices shown here:
 ```ts
 // src/pi-extension.ts
 import { registerPiTools } from "@feniix/bridgekit/pi";
-import { tools } from "./tools.js";
+import { createTools } from "./tools.js";
 
 export default function extension(pi: Parameters<typeof registerPiTools>[0]) {
-  registerPiTools(pi, tools);
+  registerPiTools(pi, createTools());
 }
 ```
 
@@ -92,7 +107,7 @@ In `package.json`:
 pi behavior:
 
 - Valid portable results become pi tool results.
-- Portable results with `isError: true` reject with `PortableToolExecutionError`.
+- Portable results with `isError: true` reject with `PortableToolExecutionError`; tests should assert a rejected execution plus error `.details`.
 - Progress updates from `ctx.progress?.(...)` map to pi updates.
 
 ---
@@ -102,15 +117,42 @@ pi behavior:
 ```ts
 #!/usr/bin/env node
 // src/mcp-server.ts
-import { runMcpStdioServer } from "@feniix/bridgekit/mcp";
-import { tools } from "./tools.js";
-
-await runMcpStdioServer({
-  name: "my-tools",
-  version: "0.1.0",
-  tools,
-  instructions: "Use these tools when text needs lightweight transformation.",
-});
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type CreateMcpServerOptions, runMcpStdioServer } from "@feniix/bridgekit/mcp";
+import { createTools } from "./tools.js";
+
+export function createMcpServerOptions(): CreateMcpServerOptions {
+  return {
+    name: "my-tools",
+    version: "0.1.0",
+    tools: createTools(),
+    instructions: "Use these tools when text needs lightweight transformation.",
+  };
+}
+
+export async function runServer(): Promise<void> {
+  await runMcpStdioServer(createMcpServerOptions());
+}
+
+function realpathIfPossible(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function isMainModule(): boolean {
+  const entrypoint = process.argv[1];
+  if (!entrypoint) return false;
+  return realpathIfPossible(resolve(entrypoint)) === realpathIfPossible(fileURLToPath(import.meta.url));
+}
+
+if (isMainModule()) {
+  await runServer();
+}
 ```
 
 In `package.json`:
@@ -120,6 +162,43 @@ In `package.json`:
   "type": "module",
   "bin": {
     "my-tools-mcp": "./dist/src/mcp-server.js"
+  },
+  "scripts": {
+    "build": "tsc -b && chmod +x dist/src/mcp-server.js",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@feniix/bridgekit": "^0.2.2",
+    "typebox": "^1.1.31"
+  }
+}
+```
+
+For mixed source-loaded pi + compiled MCP packages, keep the pi source entrypoint and point only the npm `bin` at emitted JavaScript:
+
+```json
+{
+  "type": "module",
+  "pi": {
+    "extensions": ["./extensions/index.ts"]
+  },
+  "bin": {
+    "my-tools-mcp": "./dist/extensions/mcp-server.js"
+  },
+  "files": ["extensions/", "dist/", "README.md", "LICENSE"],
+  "scripts": {
+    "build:mcp": "tsc --project tsconfig.mcp.json && chmod +x dist/extensions/mcp-server.js",
+    "prepack": "npm run build:mcp"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "@feniix/bridgekit": "^0.2.2",
+    "typebox": "^1.1.31"
   }
 }
 ```
@@ -130,6 +209,7 @@ MCP behavior:
 - `tools/call` validates arguments before invoking handlers.
 - Invalid arguments and portable `isError: true` results return MCP tool results with `isError: true`.
 - Unexpected thrown errors become MCP tool errors with text content.
+- The module stays import-passive and testable: tests can import `createMcpServerOptions()` without starting stdio.
 
 ---
 
@@ -183,11 +263,14 @@ Use `PortableToolHost<CustomHost>` for values that can be either a built-in host
 
 For publishable tool packages:
 
-- Compile to JavaScript and declarations before packing.
+- Compile runtime entrypoints to JavaScript and declarations before packing.
 - Use `exports` to expose only supported entrypoints.
 - Keep runtime imports in `dependencies`, not only dev dependencies.
+- Declare Node `>=22.19.0` when publishing BridgeKit-powered MCP bins.
 - Avoid `workspace:` or `file:` ranges in publishable package dependencies.
 - Avoid dangling `sourceMappingURL` comments: either publish maps and useful sources, or disable source maps for package builds.
+- Ensure MCP bin output starts with a shebang, is executable (`chmod +x` or equivalent), and appears in `npm pack --dry-run --json` with executable mode.
+- If only the MCP bin needs compiled output, narrow its tsconfig to the MCP entrypoint and shared host-neutral modules instead of compiling unrelated host adapters.
 - Add a packed-install smoke test that installs tarballs into a temporary project.
 - For BridgeKit itself, run `npm run check`, `npm run test`, `npm run pack:dry-run`, and `npm run package-smoke` before release.
 - Keep imports side-effect free; registration and server startup should happen only in explicit entrypoints.

package/llms.txt

@@ -41,6 +41,10 @@ export const echoTool = definePortableTool({
     };
   },
 });
+
+export function createTools() {
+  return [echoTool];
+}
 ```
 
 ## Best practices
@@ -53,12 +57,15 @@ export const echoTool = definePortableTool({
 - Respect `ctx.signal` in long-running tools.
 - Use `ctx.progress?.(...)` for incremental progress updates when the host supports them.
 - Wire hosts explicitly: pi registration and MCP server startup are separate adapter calls.
-- Keep modules import-passive. Do not register tools or start servers at import time.
+- Keep modules import-passive. Do not register tools, start servers, read package metadata, read env vars, or touch files at import time.
+- For stateful tools, export a `createTools()` factory instead of a module-level `tools` singleton so each pi extension instance or MCP stdio process gets isolated state.
+- TypeBox validation runs before the portable handler. If you need custom guidance for missing fields or wrong primitive types, use a permissive schema plus domain validation; otherwise accept BridgeKit's structural validation result.
+- MCP stdio entrypoints should be testable: export a server-options factory and a run function, then start stdio only when executed as the package bin.
 - Keep package runtime Node >=22.19.0 and ESM-only.
 
 ## Host behavior
 
-- pi invalid arguments and portable `isError: true` results throw `PortableToolExecutionError`, because pi expects native tool failures.
+- pi invalid arguments and portable `isError: true` results throw `PortableToolExecutionError`, because pi expects native tool failures. Tests should assert rejected execution plus `.details`, not a returned `{ isError: true }` object.
 - MCP invalid arguments and portable `isError: true` results return `CallToolResult` with `isError: true`.
 - MCP preserves `structuredContent`; pi maps `structuredContent` into the pi `details` field. Both adapters fall back to `details` for legacy/debug payloads when `structuredContent` is absent.
 
@@ -79,10 +86,22 @@ const customTool = definePortableTool<typeof params, "custom-host">({
 
 Use `PortableToolHost<"custom-host">` when a value may be either a built-in host or that extension.
 
+## Mixed source-loaded hosts and compiled MCP bins
+
+Some hosts, such as pi in source-extension packages, may intentionally load TypeScript source while MCP clients launched from npm need compiled JavaScript. In that case:
+
+- Keep the host source entrypoint if that is the package convention, e.g. `pi.extensions: ["./extensions/index.ts"]`.
+- Add a package-local MCP build whose `bin` points at emitted JavaScript, e.g. `./dist/extensions/mcp-server.js`.
+- Narrow the MCP build to the MCP entrypoint and shared host-neutral modules; avoid compiling pi adapter entrypoints into the standalone MCP path.
+- Put runtime imports used by the compiled MCP bin in `dependencies`, not only peers or dev dependencies.
+- Declare BridgeKit's Node engine requirement in the downstream package (`>=22.19.0`).
+- Ensure the built MCP bin is executable (`chmod +x` or equivalent) and verify the mode with `npm pack --dry-run --json`.
+
 ## Anti-patterns
 
 - Do not create a separate pi implementation and MCP implementation for the same logic.
 - Do not make tool files read package metadata, environment variables, files, or network resources at import time.
+- Do not start MCP stdio at module top level in files that tests need to import.
 - Do not expose unsupported high-level MCP helpers such as `registerMcpTools` unless tests prove compatibility with the installed MCP SDK.
 - Do not return host-specific response shapes from portable tool handlers.
 - Do not use `workspace:` or `file:` dependency ranges for packages intended to install from npm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",