@feniix/bridgekit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Otaegui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# BridgeKit
+
+BridgeKit provides reusable TypeBox-backed tool definitions and adapters for exposing one tool implementation through pi, MCP, and other hosts.
+
+## Runtime support
+
+This package is ESM-only and supports Node.js 22.19.0 or newer. Published modules are import-passive and marked as side-effect free; tools are registered or servers are started only when the exported adapter functions are called.
+
+## For coding agents
+
+Read these files in order:
+
+1. `README.md` — public API, contracts, and best practices.
+2. `llms.txt` — compact agent-facing usage rules and anti-patterns.
+3. `examples/README.md` — copyable layouts for shared tools, pi extensions, MCP stdio servers, and custom hosts.
+4. Published declarations such as `dist/src/index.d.ts`, `dist/src/pi.d.ts`, and `dist/src/mcp.d.ts` — canonical installed-package type contracts. In a source checkout, the matching `src/` files contain the same implementation context.
+
+## Entrypoints
+
+```ts
+import {
+  definePortableTool,
+  executePortableTool,
+  type PortableTool,
+  type PortableToolBuiltInHost,
+  type PortableToolContext,
+  type PortableToolHost,
+  type PortableToolResult,
+  type PortableValidationError,
+} from "@feniix/bridgekit";
+import { registerPiTools } from "@feniix/bridgekit/pi";
+import { createMcpServer, runMcpStdioServer } from "@feniix/bridgekit/mcp";
+```
+
+- Root entrypoint: host-neutral tool definitions, validation, and execution helpers.
+- `/pi`: pi adapter only.
+- `/mcp`: MCP server adapter only.
+
+Do not deep-import from `dist/` or `src/` in consuming packages.
+
+## Core tools
+
+Define tools once in host-neutral files:
+
+```ts
+import { Type } from "typebox";
+import { definePortableTool } from "@feniix/bridgekit";
+
+export const echoTool = definePortableTool({
+  name: "echo",
+  title: "Echo",
+  description: "Echo text.",
+  parameters: Type.Object({ text: Type.String() }),
+  execute(args, ctx) {
+    return {
+      text: args.text,
+      structuredContent: { text: args.text, host: ctx.host },
+    };
+  },
+});
+```
+
+Tool definition best practices:
+
+- Keep tool files host-neutral: no pi imports, no MCP SDK imports.
+- Use TypeBox `Type.Object(...)` schemas so MCP can expose input schemas directly.
+- Return `text` for model-visible output and `structuredContent` for machine-readable data.
+- Use `isError: true` for expected/domain failures that should be represented as tool output.
+- Throw only for unexpected programmer, adapter, or runtime failures.
+- 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.
+
+## pi adapter
+
+```ts
+import { registerPiTools } from "@feniix/bridgekit/pi";
+import { echoTool } from "./tools.js";
+
+export default function extension(pi: Parameters<typeof registerPiTools>[0]) {
+  registerPiTools(pi, [echoTool]);
+}
+```
+
+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.
+
+## 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.",
+});
+```
+
+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`.
+
+## Custom host typing
+
+Default portable tools accept the built-in host union:
+
+```ts
+type BuiltIn = "pi" | "mcp" | "test";
+```
+
+Custom adapters opt in explicitly:
+
+```ts
+import { Type } from "typebox";
+import { definePortableTool, type PortableToolHost } from "@feniix/bridgekit";
+
+const params = Type.Object({ text: Type.String() });
+
+type CustomHost = "custom-runtime";
+
+export const customTool = definePortableTool<typeof params, CustomHost>({
+  name: "custom_echo",
+  title: "Custom Echo",
+  description: "Echoes text in a custom runtime.",
+  parameters: params,
+  execute(args, ctx) {
+    const host: CustomHost = ctx.host;
+    return { text: `${host}: ${args.text}` };
+  },
+});
+
+const hostValue: PortableToolHost<CustomHost> = "custom-runtime";
+void hostValue;
+```
+
+Use `PortableToolHost<CustomHost>` for values that may be either a built-in host or your extension. Use the `PortableTool`/`PortableToolContext` generic when a tool or adapter is custom-host-only.
+
+## Package and release checklist
+
+- Publish compiled JavaScript plus generated `.d.ts` declarations, not source as runtime code.
+- 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.
+- 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.
+
+See `examples/README.md` for complete copyable examples.

package/dist/src/adapters/mcp-signal.d.ts

@@ -0,0 +1 @@
+export declare function signalFromExtra(extra: unknown): AbortSignal | undefined;

package/dist/src/adapters/mcp-signal.js

@@ -0,0 +1,7 @@
+export function signalFromExtra(extra) {
+    if (!extra || typeof extra !== "object" || !("signal" in extra)) {
+        return undefined;
+    }
+    const signal = extra.signal;
+    return signal instanceof AbortSignal ? signal : undefined;
+}

package/dist/src/adapters/mcp.d.ts

@@ -0,0 +1,11 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { TObject } from "typebox";
+import type { PortableTool } from "../core/define-tool.js";
+export interface CreateMcpServerOptions {
+    name: string;
+    version: string;
+    tools: readonly PortableTool<TObject>[];
+    instructions?: string;
+}
+export declare function createMcpServer(options: CreateMcpServerOptions): Server;
+export declare function runMcpStdioServer(options: CreateMcpServerOptions): Promise<void>;

package/dist/src/adapters/mcp.js

@@ -0,0 +1,55 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { executePortableTool } from "../core/execute-tool.js";
+import { signalFromExtra } from "./mcp-signal.js";
+function toMcpResult(result) {
+    return {
+        content: [{ type: "text", text: result.text }],
+        structuredContent: result.structuredContent ?? result.details,
+        isError: result.isError ?? false,
+    };
+}
+export function createMcpServer(options) {
+    const byName = new Map(options.tools.map((tool) => [tool.name, tool]));
+    const server = new Server({ name: options.name, version: options.version }, {
+        capabilities: { tools: { listChanged: false } },
+        instructions: options.instructions,
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: options.tools.map((tool) => ({
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.parameters,
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const tool = byName.get(request.params.name);
+        if (!tool) {
+            return {
+                content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await executePortableTool(tool, request.params.arguments ?? {}, {
+                host: "mcp",
+                signal: signalFromExtra(extra),
+            });
+            return toMcpResult(result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: "text", text: message }],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}
+export async function runMcpStdioServer(options) {
+    const server = createMcpServer(options);
+    await server.connect(new StdioServerTransport());
+}

package/dist/src/adapters/pi.d.ts

@@ -0,0 +1,31 @@
+import type { TSchema } from "typebox";
+import type { PortableTool, PortableToolResult } from "../core/define-tool.js";
+type PiContent = {
+    type: "text";
+    text: string;
+};
+type PiToolUpdate = {
+    content: PiContent[];
+    details: Record<string, unknown>;
+};
+type PiToolResult = {
+    content: PiContent[];
+    details: Record<string, unknown>;
+};
+type PiToolDefinition = {
+    name: string;
+    label: string;
+    description: string;
+    parameters: TSchema;
+    execute(toolCallId: string, params: unknown, signal?: AbortSignal, onUpdate?: (update: PiToolUpdate) => void, ctx?: unknown): Promise<PiToolResult>;
+};
+export type PiToolRegistration = {
+    registerTool(tool: PiToolDefinition): unknown;
+};
+export declare class PortableToolExecutionError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(result: PortableToolResult);
+}
+export declare function isPortableToolExecutionError(error: unknown): error is PortableToolExecutionError;
+export declare function registerPiTools(pi: PiToolRegistration, tools: readonly PortableTool<TSchema>[]): void;
+export {};

package/dist/src/adapters/pi.js

@@ -0,0 +1,44 @@
+import { executePortableTool } from "../core/execute-tool.js";
+function toPiDetails(result) {
+    return result.structuredContent ?? result.details ?? {};
+}
+export class PortableToolExecutionError extends Error {
+    details;
+    constructor(result) {
+        super(result.text);
+        this.name = "PortableToolExecutionError";
+        this.details = toPiDetails(result);
+    }
+}
+export function isPortableToolExecutionError(error) {
+    return error instanceof PortableToolExecutionError;
+}
+export function registerPiTools(pi, tools) {
+    for (const tool of tools) {
+        pi.registerTool({
+            name: tool.name,
+            label: tool.title,
+            description: tool.description,
+            parameters: tool.parameters,
+            async execute(_toolCallId, params, signal, onUpdate, _ctx) {
+                const result = await executePortableTool(tool, params, {
+                    host: "pi",
+                    signal,
+                    progress(update) {
+                        onUpdate?.({
+                            content: [{ type: "text", text: update.text }],
+                            details: toPiDetails(update),
+                        });
+                    },
+                });
+                if (result.isError) {
+                    throw new PortableToolExecutionError(result);
+                }
+                return {
+                    content: [{ type: "text", text: result.text }],
+                    details: toPiDetails(result),
+                };
+            },
+        });
+    }
+}

package/dist/src/core/define-tool.d.ts

@@ -0,0 +1,26 @@
+import type { Static, TSchema } from "typebox";
+export interface PortableToolResult {
+    /** Plain text sent back to the model in every host. */
+    text: string;
+    /** Structured data for hosts that support it. Preferred by both pi and MCP adapters. */
+    structuredContent?: Record<string, unknown>;
+    /** Legacy/adapter debug details used only when structuredContent is absent. */
+    details?: Record<string, unknown>;
+    /** Tool-level error flag. Throw for unexpected adapter/runtime failures. */
+    isError?: boolean;
+}
+export type PortableToolBuiltInHost = "pi" | "mcp" | "test";
+export type PortableToolHost<TExtension extends string = never> = PortableToolBuiltInHost | TExtension;
+export interface PortableToolContext<THost extends string = PortableToolBuiltInHost> {
+    host: THost;
+    signal?: AbortSignal;
+    progress?: (update: PortableToolResult) => void;
+}
+export interface PortableTool<TParams extends TSchema = TSchema, THost extends string = PortableToolBuiltInHost> {
+    name: string;
+    title: string;
+    description: string;
+    parameters: TParams;
+    execute: (args: Static<TParams>, ctx: PortableToolContext<THost>) => PortableToolResult | Promise<PortableToolResult>;
+}
+export declare function definePortableTool<TParams extends TSchema, THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TParams, THost>): PortableTool<TParams, THost>;

package/dist/src/core/define-tool.js

@@ -0,0 +1,3 @@
+export function definePortableTool(tool) {
+    return tool;
+}

package/dist/src/core/execute-tool.d.ts

@@ -0,0 +1,15 @@
+import type { TSchema } from "typebox";
+import type { PortableTool, PortableToolBuiltInHost, PortableToolContext, PortableToolResult } from "./define-tool.js";
+type NoInferPortable<T> = [T][T extends unknown ? 0 : never];
+export interface PortableValidationError {
+    path: string;
+    message: string;
+}
+export declare function validatePortableToolArgs<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown): {
+    ok: true;
+} | {
+    ok: false;
+    errors: PortableValidationError[];
+};
+export declare function executePortableTool<THost extends string = PortableToolBuiltInHost>(tool: PortableTool<TSchema, THost>, args: unknown, ctx: PortableToolContext<NoInferPortable<THost>>): Promise<PortableToolResult>;
+export {};

package/dist/src/core/execute-tool.js

@@ -0,0 +1,29 @@
+import { Check, Errors } from "typebox/value";
+export function validatePortableToolArgs(tool, args) {
+    if (Check(tool.parameters, args)) {
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        errors: [...Errors(tool.parameters, args)].map((error) => ({
+            path: error.instancePath || "/",
+            message: error.message,
+        })),
+    };
+}
+export async function executePortableTool(tool, args, ctx) {
+    const validation = validatePortableToolArgs(tool, args);
+    if (!validation.ok) {
+        return {
+            text: `Invalid arguments for ${tool.name}: ${validation.errors
+                .map((error) => `${error.path} ${error.message}`)
+                .join("; ")}`,
+            structuredContent: {
+                tool: tool.name,
+                validationErrors: validation.errors,
+            },
+            isError: true,
+        };
+    }
+    return tool.execute(args, ctx);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { definePortableTool, type PortableTool, type PortableToolBuiltInHost, type PortableToolContext, type PortableToolHost, type PortableToolResult, } from "./core/define-tool.js";
+export { executePortableTool, type PortableValidationError, validatePortableToolArgs, } from "./core/execute-tool.js";

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { definePortableTool, } from "./core/define-tool.js";
+export { executePortableTool, validatePortableToolArgs, } from "./core/execute-tool.js";

package/dist/src/mcp.d.ts

@@ -0,0 +1 @@
+export { type CreateMcpServerOptions, createMcpServer, runMcpStdioServer, } from "./adapters/mcp.js";

package/dist/src/mcp.js

@@ -0,0 +1 @@
+export { createMcpServer, runMcpStdioServer, } from "./adapters/mcp.js";

package/dist/src/pi.d.ts

@@ -0,0 +1 @@
+export { isPortableToolExecutionError, type PiToolRegistration, PortableToolExecutionError, registerPiTools, } from "./adapters/pi.js";

package/dist/src/pi.js

@@ -0,0 +1 @@
+export { isPortableToolExecutionError, PortableToolExecutionError, registerPiTools, } from "./adapters/pi.js";

package/examples/README.md

@@ -0,0 +1,193 @@
+# BridgeKit examples
+
+These examples show the recommended layout for defining portable tools once and wiring them into pi and MCP hosts.
+
+## Recommended package layout
+
+```text
+my-tools-package/
+  package.json
+  src/
+    tools.ts          # host-neutral portable tools
+    pi-extension.ts   # pi adapter wiring
+    mcp-server.ts     # MCP stdio server wiring
+```
+
+Keep `src/tools.ts` free of pi and MCP imports. Host-specific imports belong only in adapter entrypoints.
+
+---
+
+## 1. Define shared portable tools
+
+```ts
+// src/tools.ts
+import { Type } from "typebox";
+import { definePortableTool } from "@feniix/bridgekit";
+
+const reverseParams = Type.Object({
+  text: Type.String({ description: "Text to reverse." }),
+});
+
+export const reverseTextTool = definePortableTool({
+  name: "reverse_text",
+  title: "Reverse Text",
+  description: "Reverse the supplied text.",
+  parameters: reverseParams,
+  execute(args, ctx) {
+    if (ctx.signal?.aborted) {
+      return {
+        text: "Reverse text was cancelled.",
+        structuredContent: { cancelled: true },
+        isError: true,
+      };
+    }
+
+    const output = [...args.text].reverse().join("");
+    return {
+      text: output,
+      structuredContent: {
+        input: args.text,
+        output,
+        host: ctx.host,
+      },
+    };
+  },
+});
+
+export const tools = [reverseTextTool];
+```
+
+Best practices shown here:
+
+- The schema is the single source of truth for argument validation.
+- The handler returns portable `{ text, structuredContent }` data.
+- The handler observes `ctx.signal` without importing a host SDK.
+- The file has no import-time registration or server startup.
+
+---
+
+## 2. Register tools in a pi extension
+
+```ts
+// src/pi-extension.ts
+import { registerPiTools } from "@feniix/bridgekit/pi";
+import { tools } from "./tools.js";
+
+export default function extension(pi: Parameters<typeof registerPiTools>[0]) {
+  registerPiTools(pi, tools);
+}
+```
+
+In `package.json`:
+
+```json
+{
+  "type": "module",
+  "pi": {
+    "extensions": ["./dist/src/pi-extension.js"]
+  }
+}
+```
+
+pi behavior:
+
+- Valid portable results become pi tool results.
+- Portable results with `isError: true` reject with `PortableToolExecutionError`.
+- Progress updates from `ctx.progress?.(...)` map to pi updates.
+
+---
+
+## 3. Serve the same tools over MCP stdio
+
+```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.",
+});
+```
+
+In `package.json`:
+
+```json
+{
+  "type": "module",
+  "bin": {
+    "my-tools-mcp": "./dist/src/mcp-server.js"
+  }
+}
+```
+
+MCP behavior:
+
+- `tools/list` exposes TypeBox schemas directly as JSON Schema.
+- `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.
+
+---
+
+## 4. Use custom host typing for custom adapters
+
+Default portable tools accept only built-in hosts: `"pi" | "mcp" | "test"`.
+
+If you are writing a custom adapter, opt in explicitly so the handler can safely narrow `ctx.host`:
+
+```ts
+import { Type } from "typebox";
+import {
+  definePortableTool,
+  executePortableTool,
+  type PortableTool,
+  type PortableToolContext,
+  type PortableToolHost,
+} from "@feniix/bridgekit";
+
+const params = Type.Object({ text: Type.String() });
+
+type CustomHost = "custom-runtime";
+type CustomTool = PortableTool<typeof params, CustomHost>;
+
+const customTool = definePortableTool<typeof params, CustomHost>({
+  name: "custom_echo",
+  title: "Custom Echo",
+  description: "Echoes text in a custom runtime.",
+  parameters: params,
+  execute(args, ctx) {
+    const host: CustomHost = ctx.host;
+    return { text: `${host}: ${args.text}` };
+  },
+});
+
+async function runCustomTool(tool: CustomTool, text: string) {
+  const ctx: PortableToolContext<CustomHost> = { host: "custom-runtime" };
+  return executePortableTool(tool, { text }, ctx);
+}
+
+const hostValue: PortableToolHost<CustomHost> = "custom-runtime";
+void hostValue;
+void customTool;
+```
+
+Use `PortableToolHost<CustomHost>` for values that can be either a built-in host or your custom extension. Use `PortableToolContext<CustomHost>` or `PortableTool<Schema, CustomHost>` when a tool is custom-host-only.
+
+---
+
+## 5. Package checklist
+
+For publishable tool packages:
+
+- Compile to JavaScript and declarations before packing.
+- Use `exports` to expose only supported entrypoints.
+- Keep runtime imports in `dependencies`, not only dev dependencies.
+- 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.
+- 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

@@ -0,0 +1,88 @@
+# @feniix/bridgekit
+
+Use this package when you need to define a tool once and expose it through both pi and MCP hosts.
+
+## Read order for agents
+
+1. `README.md` — public API, contracts, best practices, packaging notes.
+2. `llms.txt` — compact agent-facing usage rules and anti-patterns.
+3. `examples/README.md` — copyable end-to-end layouts for shared tools, pi extension wiring, MCP stdio server wiring, and custom hosts.
+4. Published declarations such as `dist/src/index.d.ts`, `dist/src/pi.d.ts`, and `dist/src/mcp.d.ts` — canonical installed-package type contracts. In a source checkout, the matching `src/` files contain implementation context.
+
+## Import map
+
+```ts
+import { definePortableTool, executePortableTool } from "@feniix/bridgekit";
+import { registerPiTools } from "@feniix/bridgekit/pi";
+import { createMcpServer, runMcpStdioServer } from "@feniix/bridgekit/mcp";
+```
+
+- Root entrypoint: host-neutral tool definitions, validation, and execution helpers.
+- `/pi`: pi adapter only.
+- `/mcp`: MCP server adapter only.
+
+Do not deep-import from `dist/` or `src/` in consumer code. Reading published declarations for documentation is fine; imports should use the package entrypoints above.
+
+## Core pattern
+
+```ts
+import { Type } from "typebox";
+import { definePortableTool } from "@feniix/bridgekit";
+
+export const echoTool = definePortableTool({
+  name: "echo",
+  title: "Echo",
+  description: "Echo text.",
+  parameters: Type.Object({ text: Type.String() }),
+  execute(args, ctx) {
+    return {
+      text: args.text,
+      structuredContent: { text: args.text, host: ctx.host },
+    };
+  },
+});
+```
+
+## Best practices
+
+- Keep portable tools host-neutral. Do not import pi or MCP SDKs from files that define tool behavior.
+- Use TypeBox `Type.Object(...)` schemas for MCP-compatible tools.
+- Return `{ text, structuredContent }` for successful results.
+- Use `isError: true` for domain/tool-level failures that should reach the model as tool output.
+- Throw only for unexpected programmer, adapter, or runtime failures.
+- 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 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.
+- 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.
+
+## Custom host typing
+
+Default tools accept only built-in hosts: `"pi" | "mcp" | "test"`.
+For a custom adapter, opt in explicitly:
+
+```ts
+const customTool = definePortableTool<typeof params, "custom-host">({
+  // ...
+  execute(args, ctx) {
+    const host: "custom-host" = ctx.host;
+    return { text: host };
+  },
+});
+```
+
+Use `PortableToolHost<"custom-host">` when a value may be either a built-in host or that extension.
+
+## 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 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

@@ -0,0 +1,78 @@
+{
+  "name": "@feniix/bridgekit",
+  "version": "0.2.0",
+  "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
+  "keywords": [
+    "pi",
+    "mcp",
+    "bridgekit",
+    "portable-tools",
+    "typebox"
+  ],
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/feniix/bridgekit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/feniix/bridgekit/issues"
+  },
+  "homepage": "https://github.com/feniix/bridgekit#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./pi": {
+      "types": "./dist/src/pi.d.ts",
+      "import": "./dist/src/pi.js"
+    },
+    "./mcp": {
+      "types": "./dist/src/mcp.d.ts",
+      "import": "./dist/src/mcp.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "check": "npm run lint && npm run typecheck",
+    "clean": "node scripts/clean-package-dist.mjs",
+    "typecheck": "tsc -b tsconfig.json --pretty false",
+    "build": "npm run clean && tsc -b tsconfig.json",
+    "test": "npm run build && node scripts/run-built-tests.mjs",
+    "test:coverage": "npm run build && node scripts/run-built-tests-coverage.mjs",
+    "verify:dist": "node scripts/verify-bridgekit-dist.mjs",
+    "pack:dry-run": "npm pack --dry-run --json",
+    "package-smoke": "node scripts/smoke-package.mjs",
+    "prepack": "npm run build && npm run verify:dist"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/*.test.*",
+    "!dist/**/*.typecheck.*",
+    "!dist/**/*.map",
+    "!dist/tsconfig.tsbuildinfo",
+    "README.md",
+    "llms.txt",
+    "examples/README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "typebox": "^1.1.31"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.10",
+    "@total-typescript/shoehorn": "^0.1.2",
+    "@types/node": "^22.19.17",
+    "typescript": "^5.5.0"
+  },
+  "license": "MIT"
+}