@amalgm/tools 0.1.0 → 0.1.1

package/README.md

@@ -49,6 +49,22 @@ amalgm-tools connections
 `amalgm-tools-mcp` serves Toolbox management and enabled action tools over
 newline-delimited MCP stdio.
 
+## HTTP
+
+```js
+import { Toolbox } from '@amalgm/tools';
+import { createToolboxHttpServer } from '@amalgm/tools/http';
+
+const toolbox = new Toolbox({ stateDir: './.tools' });
+const server = createToolboxHttpServer({ toolbox });
+await server.listen(8083);
+```
+
+The read adapter serves the Engine-compatible `GET /toolbox`,
+`GET /toolbox/tools?id=...`, and `GET /toolbox/actions?id=...` routes over
+the same live Toolbox used by CLI and MCP consumers. Mutation routes return
+405 until their legacy record fields can be represented without data loss.
+
 ## Tool types
 
 - `cli`: executed directly with `spawn`; a shell is never involved.

package/dist/http.d.ts

@@ -0,0 +1,31 @@
+import { Toolbox } from './toolbox.js';
+import type { Catalog, ToolboxOptions } from './types.js';
+/**
+ * Toolbox read API.
+ *
+ * Route contract ported from Engine
+ * `runtime/scripts/amalgm-mcp/server/routes/toolbox.js` and
+ * `runtime/scripts/amalgm-mcp/toolbox/rest.js`:
+ *
+ * - `GET /toolbox` returns the whole catalog;
+ * - `GET /toolbox/tools?id=...` returns one tool and, by default, its actions;
+ * - `GET /toolbox/actions?id=...` returns one action;
+ * - domain errors are JSON with status 400; unknown routes are 404.
+ *
+ * Mutation routes remain deliberately absent until their engine record fields
+ * are represented losslessly by the SDK. Returning 405 is honest; translating
+ * them approximately would turn a visible parity gap into data loss.
+ */
+type Json = Record<string, unknown>;
+interface ToolboxHttpServer {
+    listen(port?: number, host?: string): Promise<{
+        port: number;
+    }>;
+    close(): Promise<void>;
+}
+declare function catalogDocument(catalog: Catalog): Json;
+declare function createToolboxHttpServer(options?: ToolboxOptions & {
+    toolbox?: Toolbox;
+}): ToolboxHttpServer;
+export { catalogDocument, createToolboxHttpServer };
+export type { ToolboxHttpServer };

package/dist/http.js

@@ -0,0 +1,115 @@
+import { createServer } from 'node:http';
+import { toolboxIndexDocument } from './artifacts.js';
+import { Toolbox } from './toolbox.js';
+function sourceWithoutType(source) {
+    const { type: _type, ...value } = source;
+    return value;
+}
+function toolDocument(tool) {
+    return {
+        ...tool,
+        type: tool.source.type,
+        source: sourceWithoutType(tool.source),
+    };
+}
+function actionDocument(action) {
+    return { ...action };
+}
+function catalogDocument(catalog) {
+    return toolboxIndexDocument(Object.fromEntries(catalog.tools.map((tool) => [tool.id, toolDocument(tool)])), Object.fromEntries(catalog.actions.map((action) => [action.id, actionDocument(action)])));
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(Buffer.from(chunk));
+    if (chunks.length === 0)
+        return {};
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+function createToolboxHttpServer(options = {}) {
+    const toolbox = options.toolbox ?? new Toolbox(options);
+    const ownsToolbox = options.toolbox === undefined;
+    const server = createServer((req, res) => {
+        void (async () => {
+            const method = req.method ?? 'GET';
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            const send = (status, body) => {
+                res.writeHead(status, { 'content-type': 'application/json' });
+                res.end(JSON.stringify(body));
+            };
+            try {
+                if (method !== 'GET') {
+                    if (url.pathname.startsWith('/toolbox')) {
+                        await readBody(req);
+                        send(405, { error: 'method not allowed' });
+                        return;
+                    }
+                    send(404, { error: 'not found' });
+                    return;
+                }
+                if (url.pathname === '/toolbox') {
+                    send(200, catalogDocument(toolbox.catalog()));
+                    return;
+                }
+                if (url.pathname === '/toolbox/tools') {
+                    const id = url.searchParams.get('id') || url.searchParams.get('toolId') || '';
+                    if (!id)
+                        throw new Error('id is required');
+                    const found = toolbox.get(id);
+                    if (!found)
+                        throw new Error(`Unknown tool: ${id}`);
+                    const includeActions = url.searchParams.get('include_actions') !== 'false'
+                        && url.searchParams.get('includeActions') !== 'false';
+                    send(200, {
+                        tool: toolDocument(found.tool),
+                        ...(includeActions
+                            ? { actions: found.actions.map(actionDocument) }
+                            : {}),
+                    });
+                    return;
+                }
+                if (url.pathname === '/toolbox/actions') {
+                    const id = url.searchParams.get('id') || url.searchParams.get('actionId') || '';
+                    if (!id)
+                        throw new Error('id is required');
+                    const action = toolbox.action(id);
+                    if (!action)
+                        throw new Error(`Unknown tool action: ${id}`);
+                    send(200, { action: actionDocument(action) });
+                    return;
+                }
+                send(404, { error: 'not found' });
+            }
+            catch (error) {
+                send(400, { error: error instanceof Error ? error.message : 'Failed to read Toolbox' });
+            }
+        })();
+    });
+    return {
+        listen(port = 0, host = '127.0.0.1') {
+            return new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(port, host, () => {
+                    server.off('error', reject);
+                    const address = server.address();
+                    if (!address || typeof address === 'string')
+                        throw new Error('Toolbox HTTP server has no port');
+                    resolve({ port: address.port });
+                });
+            });
+        },
+        close() {
+            return new Promise((resolve, reject) => {
+                server.close((error) => {
+                    if (ownsToolbox)
+                        toolbox.close();
+                    if (error)
+                        reject(error);
+                    else
+                        resolve();
+                });
+            });
+        },
+    };
+}
+export { catalogDocument, createToolboxHttpServer };

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { ArtifactFiles } from './artifact-files.js';
 export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, toolboxIndexDocument, userArtifactFileName, } from './artifacts.js';
 export type { ArtifactFileWrite, LegacyMigrationPlan, ToolArtifactDocument, ToolboxIndexDocument, } from './artifacts.js';
 export { defineTool, normalizeDefinition } from './definition.js';
+export { catalogDocument, createToolboxHttpServer } from './http.js';
+export type { ToolboxHttpServer } from './http.js';
 export { actionId, actionName, id, mcpName } from './ids.js';
 export { actionTools, callMcpTool, createMcpTools, findMcpTool, managementTools, } from './mcp.js';
 export { createMcpServer } from './mcp-server.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { ArtifactFiles } from './artifact-files.js';
 export { LEGACY_TOOLBOX_BACKUP_FILE_NAME, LEGACY_TOOLBOX_FILE_NAME, TOOL_ARTIFACT_KIND, TOOL_ARTIFACT_SCHEMA_VERSION, TOOLBOX_INDEX_FILE_NAME, artifactDocument, catalogIndexDocument, isToolArtifactDocument, legacyMigrationPlan, safeToolId, toolboxIndexDocument, userArtifactFileName, } from './artifacts.js';
 export { defineTool, normalizeDefinition } from './definition.js';
+export { catalogDocument, createToolboxHttpServer } from './http.js';
 export { actionId, actionName, id, mcpName } from './ids.js';
 export { actionTools, callMcpTool, createMcpTools, findMcpTool, managementTools, } from './mcp.js';
 export { createMcpServer } from './mcp-server.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/tools",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local-first tool definitions, Toolbox registry, and agent execution surfaces.",
   "license": "UNLICENSED",
   "private": false,
@@ -22,6 +22,10 @@
     "./mcp": {
       "types": "./dist/mcp.d.ts",
       "default": "./dist/mcp.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
     }
   },
   "bin": {