agent-tool-hub 1.0.1 → 1.0.3

package/README.md

@@ -1,216 +1,35 @@
 # Agent Tool Hub
 
-Agent Tool Hub is a multi-protocol tool registry + PTC runtime that unifies discovery, governance, and execution for tools across MCP, LangChain, n8n, SKILL, and built-in core tools.
+**One registry, many protocols** — discover and run tools from MCP, LangChain, n8n, ComfyUI, and SKILL through a single PTC runtime.
 
-## What We Support
-
-### Protocols / Tool Types
-
-| Type | How it’s discovered/connected | Typical use |
-| --- | --- | --- |
-| MCP | `mcp.json` (stdio or SSE/HTTP) | Remote tool servers / ecosystem tools |
-| LangChain Tool | `index.js/.mjs` or `langchain/` directory | Local code tools |
-| n8n Workflow | `workflow.json` | Automation workflows |
-| SKILL (Anthropic) | `SKILL.md` (optional `handler.js/.mjs`) | Instructional skills / subflows |
-| Core Tools (built-in) | `roots: coreTools` | Safe FS / HTTP / Utils |
-
-### Core Capabilities
-
-- Unified ToolSpec abstraction with JSON Schema
-- PTC runtime: validation, policy gating, budgets/retries, evidence
-- Multi-root discovery with namespaces and optional hot-reload
-- Security baseline: sandbox paths, allowlists, SSRF protections
-- Observability: events, metrics, tracing
-- Async workflows for n8n
-
-## Quick Start
-
-### Install
+## Install
 
 ```bash
-npm i agent-tool-hub
-```
-
-- Node >= 18
-- Optional peers: `@langchain/core`, `@modelcontextprotocol/sdk`
-
-### Configure via `toolhub.yaml`
-
-Agent Tool Hub is configured by a YAML file. Keep it simple:
-
-```yaml
-discovery:
-  roots:
-    - path: ./tools
-      namespace: app
-    - path: coreTools
-      namespace: core
-      config:
-        sandboxRoot: /tmp/toolhub-sandbox
-        allowedHosts:
-          - api.github.com
-          - "*.example.com"
-
-adapters:
-  n8n:
-    mode: api
-    api:
-      apiBaseUrl: http://localhost:5678
-      apiKey: ""
+npm install agent-tool-hub
 ```
 
-Your framework can load this config and initialize Agent Tool Hub accordingly.
+Node 18+ required.
 
-### Initialize from a config file path
-
-```ts
-import { createAgentToolHub } from "agent-tool-hub";
-
-const hub = await createAgentToolHub("./toolhub.yaml");
-```
+## Use
 
-### List tools
+**CLI** — add a `toolhub.yaml` in your project, then:
 
-```ts
-const tools = hub.listToolMetadata();
-// [{ name, description }, ...]
+```bash
+npx agent-tool-hub scan    # load tools from configured roots
+npx agent-tool-hub verify  # scan and exit 1 on errors
+npx agent-tool-hub list    # list discovered tools
 ```
 
-### Invoke a tool
+**In code** — load from config, init, then invoke:
 
 ```ts
-const result = await hub.invokeTool(
-  "core/http.fetchJson",
-  { url: "https://api.github.com" },
-  {
-    permissions: ["network", "read:web"],
-    budget: { timeoutMs: 10_000, maxRetries: 1 },
-  },
-);
-
-if (!result.ok) {
-  console.error(result.error);
-}
-```
-
-## Tool Discovery Rules
-
-- All subdirectories under each `roots` entry are scanned.
-- Tool kind is inferred by marker files:
-  `SKILL.md` / `workflow.json` / `mcp.json` / `index.js(.mjs)`
-- Avoid mixing multiple marker files in the same folder.
-
-Example structure:
-
-```
-tools/
-  weather/
-    mcp.json
-  notify/
-    workflow.json
-```
-
-## Add a New Tool (Recommended)
-
-### 1) Create a tool folder
-
-```
-./tools/my-tool/
-```
-
-### 2) Add the tool implementation by kind
+import { createToolHubAndInitFromConfig } from "agent-tool-hub";
 
-#### MCP tool
-
-Add `mcp.json`:
-
-```json
-{ "command": "npx", "args": ["-y", "your-mcp-server"] }
-```
-
-or remote:
-
-```json
-{ "url": "https://mcp.example.com" }
-```
-
-#### LangChain tool
-
-Create `index.js/.mjs` that implements LangChain's interface (e.g., `StructuredTool`):
-
-```js
-import { StructuredTool } from "@langchain/core/tools";
-import { z } from "zod";
-
-class CalculatorTool extends StructuredTool {
-  name = "calculator";
-  description = "Evaluates simple arithmetic expressions";
-
-  schema = z.object({
-    expression: z.string(),
-  });
-
-  async _call({ expression }) {
-    const sanitized = expression.replace(/[^0-9+\\-*/().% ]/g, "");
-    if (sanitized !== expression) {
-      throw new Error("Invalid characters in expression");
-    }
-    const result = Function(`\"use strict\"; return (${sanitized})`)();
-    return String(result);
-  }
-}
-
-export default new CalculatorTool();
-```
-
-#### n8n workflow
-
-Add `workflow.json` with a `nodes` array:
-
-```json
-{ "id": "wf-123", "name": "send-slack", "nodes": [] }
-```
-
-- Set `adapters.n8n.mode: api | local` in `toolhub.yaml`.
-- Local mode auto-imports/syncs workflows.
-
-#### SKILL
-
-Add `SKILL.md` (Anthropic Skills format):
-
-```md
----
-name: send-email
-description: Sends a confirmation email when user completes checkout.
----
-
-Instructions go here.
+const hub = await createToolHubAndInitFromConfig("toolhub.yaml");
+const result = await hub.invokeTool("utils.calculator", { expression: "1 + 2" });
+// result.ok, result.data, result.error, etc.
 ```
 
-Optional `handler.js/.mjs` can provide executable logic.
-
-## Core Tools (Built-in)
-
-- FS: `core/fs.readText`, `core/fs.writeText`, `core/fs.listDir`, `core/fs.searchText`, `core/fs.sha256`, `core/fs.deletePath`
-- HTTP: `core/http.fetchText`, `core/http.fetchJson`, `core/http.downloadFile`, `core/http.head`
-- Utils: `core/util.jsonSelect`, `core/util.truncate`, `core/util.hashText`, `core/util.now`, `core/util.templateRender`
-
-Enable via `roots` entry `coreTools` and provide `sandboxRoot` + `allowedHosts`.
-
-## Permissions and Capabilities
-
-Common capabilities:
-
-- `read:web`, `network`
-- `read:fs`, `write:fs`
-- `read:db`, `write:db`
-- `workflow`, `gpu`
-- `danger:destructive`
-
-Pass `permissions` when invoking tools to satisfy policy gates.
-
-## Publishing (maintainers)
-
-Releases are automated via GitHub Actions (`.github/workflows/release.yml`). On push to `master`, tests and build run, then [semantic-release](https://github.com/semantic-release/semantic-release) publishes to npm (patch-only).
+Or build the hub yourself: `createToolHub(options)` → `await hub.initAllTools()`; run tools with `hub.invokeTool(name, args, options)`.
 
-**Required:** Add `NPM_TOKEN` in the repo’s **Settings → Secrets and variables → Actions**. The token must be a [granular access token](https://docs.npmjs.com/creating-and-viewing-access-tokens) with **“bypass 2fa”** (or an automation token) so CI can publish; otherwise npm returns 403.
+See `toolhub.yaml` for config and `examples/` for tool layouts.

package/dist/chunk-57LVNNHL.js

@@ -0,0 +1,19 @@
+import { createToolHub, loadToolHubConfig } from './chunk-HPDQEW2P.js';
+
+// src/toolhub-runtime.ts
+async function createToolHubAndInit(options) {
+  const hub = createToolHub(options);
+  await hub.initAllTools();
+  return hub;
+}
+async function createToolHubAndInitFromConfig(configPath) {
+  const { options } = await loadToolHubConfig(configPath);
+  return createToolHubAndInit(options);
+}
+async function createAgentToolHub(configPath) {
+  return createToolHubAndInitFromConfig(configPath);
+}
+
+export { createAgentToolHub, createToolHubAndInit, createToolHubAndInitFromConfig };
+//# sourceMappingURL=chunk-57LVNNHL.js.map
+//# sourceMappingURL=chunk-57LVNNHL.js.map

package/dist/chunk-57LVNNHL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/toolhub-runtime.ts"],"names":[],"mappings":";;;AAKA,eAAsB,qBACpB,OAAA,EACA;AACA,EAAA,MAAM,GAAA,GAAM,cAAc,OAAO,CAAA;AACjC,EAAA,MAAM,IAAI,YAAA,EAAa;AACvB,EAAA,OAAO,GAAA;AACT;AAEA,eAAsB,+BAA+B,UAAA,EAAoB;AACvE,EAAA,MAAM,EAAE,OAAA,EAAQ,GAAI,MAAM,kBAAkB,UAAU,CAAA;AACtD,EAAA,OAAO,qBAAqB,OAAO,CAAA;AACrC;AAEA,eAAsB,mBAAmB,UAAA,EAAoB;AAC3D,EAAA,OAAO,+BAA+B,UAAU,CAAA;AAClD","file":"chunk-57LVNNHL.js","sourcesContent":["import { ToolHub, createToolHub } from \"./tool-hub/ToolHub.js\";\nimport { loadToolHubConfig } from \"./config/ToolHubConfig.js\";\nexport { ToolHub, createToolHub };\nexport type { ToolHubInitOptions, InvokeOptions } from \"./tool-hub/ToolHub.js\";\n\nexport async function createToolHubAndInit(\n  options: import(\"./tool-hub/ToolHub.js\").ToolHubInitOptions,\n) {\n  const hub = createToolHub(options);\n  await hub.initAllTools();\n  return hub;\n}\n\nexport async function createToolHubAndInitFromConfig(configPath: string) {\n  const { options } = await loadToolHubConfig(configPath);\n  return createToolHubAndInit(options);\n}\n\nexport async function createAgentToolHub(configPath: string) {\n  return createToolHubAndInitFromConfig(configPath);\n}\n"]}

package/dist/chunk-6QTWECRD.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+var chunkTIKHPRMB_cjs = require('./chunk-TIKHPRMB.cjs');
+
+// src/toolhub-runtime.ts
+async function createToolHubAndInit(options) {
+  const hub = chunkTIKHPRMB_cjs.createToolHub(options);
+  await hub.initAllTools();
+  return hub;
+}
+async function createToolHubAndInitFromConfig(configPath) {
+  const { options } = await chunkTIKHPRMB_cjs.loadToolHubConfig(configPath);
+  return createToolHubAndInit(options);
+}
+async function createAgentToolHub(configPath) {
+  return createToolHubAndInitFromConfig(configPath);
+}
+
+exports.createAgentToolHub = createAgentToolHub;
+exports.createToolHubAndInit = createToolHubAndInit;
+exports.createToolHubAndInitFromConfig = createToolHubAndInitFromConfig;
+//# sourceMappingURL=chunk-6QTWECRD.cjs.map
+//# sourceMappingURL=chunk-6QTWECRD.cjs.map

package/dist/chunk-6QTWECRD.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/toolhub-runtime.ts"],"names":["createToolHub","loadToolHubConfig"],"mappings":";;;;;AAKA,eAAsB,qBACpB,OAAA,EACA;AACA,EAAA,MAAM,GAAA,GAAMA,gCAAc,OAAO,CAAA;AACjC,EAAA,MAAM,IAAI,YAAA,EAAa;AACvB,EAAA,OAAO,GAAA;AACT;AAEA,eAAsB,+BAA+B,UAAA,EAAoB;AACvE,EAAA,MAAM,EAAE,OAAA,EAAQ,GAAI,MAAMC,oCAAkB,UAAU,CAAA;AACtD,EAAA,OAAO,qBAAqB,OAAO,CAAA;AACrC;AAEA,eAAsB,mBAAmB,UAAA,EAAoB;AAC3D,EAAA,OAAO,+BAA+B,UAAU,CAAA;AAClD","file":"chunk-6QTWECRD.cjs","sourcesContent":["import { ToolHub, createToolHub } from \"./tool-hub/ToolHub.js\";\nimport { loadToolHubConfig } from \"./config/ToolHubConfig.js\";\nexport { ToolHub, createToolHub };\nexport type { ToolHubInitOptions, InvokeOptions } from \"./tool-hub/ToolHub.js\";\n\nexport async function createToolHubAndInit(\n  options: import(\"./tool-hub/ToolHub.js\").ToolHubInitOptions,\n) {\n  const hub = createToolHub(options);\n  await hub.initAllTools();\n  return hub;\n}\n\nexport async function createToolHubAndInitFromConfig(configPath: string) {\n  const { options } = await loadToolHubConfig(configPath);\n  return createToolHubAndInit(options);\n}\n\nexport async function createAgentToolHub(configPath: string) {\n  return createToolHubAndInitFromConfig(configPath);\n}\n"]}