@zclaudia/agent-tool-bridge

Provider-neutral MCP bridge for standalone external-agent hosts.

The package starts an authenticated loopback tool service and returns a standard provider MCP entry that launches the bundled stdio proxy. Hosts supply a ToolCatalog; the bridge has no dependency on ZClaudia routes or registries.

Use createPortableToolBridgeHost for a long-lived host process. It starts one authenticated loopback service and creates any number of session-specific MCP entries. The convenience createPortableToolBridge function remains suitable for a single run.

Install

pnpm add @zclaudia/agent-tool-bridge @zclaudia/plugin-sdk

Expose host tools to an agent

import { createPortableToolBridgeHost } from '@zclaudia/agent-tool-bridge';

const bridge = await createPortableToolBridgeHost({
  catalog: {
    listTools: () => [
      {
        name: 'echo',
        description: 'Echo text',
        inputSchema: {
          type: 'object',
          properties: { text: { type: 'string' } },
          required: ['text'],
        },
      },
    ],
    callTool: (_name, args) => String(args.text),
  },
});

const mcpEntry = bridge.createEntry({ sessionId: 'session-1' });
// Return mcpEntry from the plugin SDK host's createToolBridge implementation.

await bridge.close();

The bridge binds to loopback, creates a random bearer token, and passes the URL and credentials only to its bundled stdio MCP proxy. The host controls tool discovery and execution through ToolCatalog; session identity is supplied separately for each MCP entry.

Design boundary

This package translates MCP stdio calls into a small host-neutral ToolCatalog. It does not know about ZClaudia routes, registries, persistence, or UI state. Agent execution belongs in @zclaudia/agent-runtime, while provider-facing contracts live in @zclaudia/plugin-sdk.

Development

pnpm install
pnpm check

Node.js 22.19 or newer is required.

Release

The Publish to npm workflow uses npm trusted publishing. Create a GitHub release whose tag exactly matches v${package.json.version} (for example, v0.1.0) after configuring this repository as a trusted publisher for @zclaudia/agent-tool-bridge.