@vertesia/tools-sdk 0.24.0-dev.202601221707

package/src/server/tools.ts

@@ -0,0 +1,128 @@
+import { Context, Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { ToolCollection } from "../ToolCollection.js";
+import { ToolCollectionDefinition, ToolDefinition } from "../types.js";
+import { ToolContext, ToolServerConfig } from "./types.js";
+
+export function createToolsRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const { tools = [] } = config;
+
+    // Build a map of tool name -> collection for routing
+    const toolToCollection = new Map<string, ToolCollection>();
+    for (const coll of tools) {
+        for (const toolDef of coll.getToolDefinitions()) {
+            toolToCollection.set(toolDef.name, coll);
+        }
+    }
+
+    // GET /api/tools - Returns all tools from all collections
+    // Query params:
+    //   - defaultOnly=true: Only return tools with default !== false
+    //   - unlocked=tool1,tool2: Comma-separated list of unlocked tool names
+
+    app.get(basePath, (c) => {
+        const url = new URL(c.req.url);
+        const defaultOnly = c.req.query('defaultOnly') === 'true';
+        const unlockedParam = c.req.query('unlocked');
+        const unlockedTools = unlockedParam ? unlockedParam.split(',').map(t => t.trim()).filter(Boolean) : [];
+
+        const filterOptions = defaultOnly ? { defaultOnly, unlockedTools } : undefined;
+
+        const allTools: ToolDefinition[] = [];
+        let reserveToolCount = 0;
+
+        for (const coll of tools) {
+            allTools.push(...coll.getToolDefinitions(filterOptions));
+            if (defaultOnly) {
+                reserveToolCount += coll.getReserveTools(unlockedTools).length;
+            }
+        }
+
+        return c.json({
+            src: `${url.origin}${url.pathname}`,
+            title: 'All Tools',
+            description: 'All available tools across all collections',
+            tools: allTools,
+            reserveToolCount: defaultOnly ? reserveToolCount : undefined,
+            collections: tools.map(t => ({
+                name: t.name,
+                title: t.title,
+                description: t.description,
+            })),
+        } satisfies ToolCollectionDefinition & { collections: any[]; reserveToolCount?: number });
+    });
+
+    // POST /api/tools - Route to the correct collection based on tool_name
+    app.post(basePath, async (c) => {
+        const ctx = c as unknown as ToolContext;
+
+        // Payload is already parsed and validated by middleware
+        if (!ctx.payload) {
+            throw new HTTPException(400, {
+                message: 'Invalid or missing tool execution payload. Expected { tool_use: { id, tool_name, tool_input? }, metadata? }'
+            });
+        }
+
+        const toolName = ctx.payload.tool_use.tool_name;
+
+        // Find the collection for this tool
+        const collection = toolToCollection.get(toolName);
+        if (!collection) {
+            throw new HTTPException(404, {
+                message: `Tool not found: ${toolName}. Available tools: ${Array.from(toolToCollection.keys()).join(', ')}`
+            });
+        }
+
+        // Delegate to the collection's execute method with pre-parsed payload
+        return collection.execute(c, ctx.payload);
+    });
+
+    // Create tool collection endpoints
+    for (const coll of tools) {
+        app.route(`${basePath}/${coll.name}`, createToolEndpoints(coll));
+    }
+}
+
+function createToolEndpoints(coll: ToolCollection): Hono {
+    const endpoint = new Hono();
+
+    endpoint.post('/', (c: Context) => {
+        return coll.execute(c);
+    });
+
+    // GET /api/tools/{collection}
+    // Query params:
+    //   - import: Return import source URL instead of API URL
+    //   - defaultOnly=true: Only return tools with default !== false
+    //   - unlocked=tool1,tool2: Comma-separated list of unlocked tool names
+    endpoint.get('/', (c) => {
+        const importSourceUrl = c.req.query('import') != null;
+        const defaultOnly = c.req.query('defaultOnly') === 'true';
+        const unlockedParam = c.req.query('unlocked');
+        const unlockedTools = unlockedParam ? unlockedParam.split(',').map(t => t.trim()).filter(Boolean) : [];
+
+        const filterOptions = defaultOnly ? { defaultOnly, unlockedTools } : undefined;
+        const url = new URL(c.req.url);
+
+        const response: ToolCollectionDefinition & { reserveToolCount?: number } = {
+            src: importSourceUrl
+                ? `${url.origin}/libs/vertesia-tools-${coll.name}.js`
+                : `${url.origin}${url.pathname}`,
+            title: coll.title || coll.name,
+            description: coll.description || '',
+            tools: coll.getToolDefinitions(filterOptions)
+        };
+
+        // Include reserve count when filtering
+        if (defaultOnly) {
+            response.reserveToolCount = coll.getReserveTools(unlockedTools).length;
+        }
+
+        return c.json(response);
+    });
+
+    return endpoint;
+}
+
+
+

package/src/server/types.ts

@@ -0,0 +1,65 @@
+import { Context } from "hono";
+import { InteractionCollection } from "../InteractionCollection.js";
+import { SkillCollection } from "../SkillCollection.js";
+import { ToolCollection } from "../ToolCollection.js";
+import { ToolExecutionPayload } from "../types.js";
+
+/**
+ * Extended context with parsed payload for tool/skill execution
+ */
+export interface ToolContext extends Context {
+    /** The parsed request payload */
+    payload?: ToolExecutionPayload<any>;
+    /** The tool_use.id from the payload */
+    toolUseId?: string;
+    /** The tool_use.tool_name from the payload */
+    toolName?: string;
+}
+
+/**
+ * MCP Provider interface for server configuration
+ */
+export interface MCPProviderConfig {
+    name: string;
+    description?: string;
+    createMCPConnection: (session: any, config: Record<string, any>) => Promise<{
+        name: string;
+        url: string;
+        token: string;
+    }>;
+}
+
+/**
+ * Server configuration options
+ */
+export interface ToolServerConfig {
+    /**
+     * Server title for HTML pages (default: 'Tools Server')
+     */
+    title?: string;
+    /**
+     * API prefix (default: '/api')
+     */
+    prefix?: string;
+    /**
+     * Tool collections to expose
+     */
+    tools?: ToolCollection[];
+    /**
+     * Interaction collections to expose
+     */
+    interactions?: InteractionCollection[];
+    /**
+     * Skill collections to expose
+     */
+    skills?: SkillCollection[];
+    /**
+     * MCP providers to expose
+     */
+    mcpProviders?: MCPProviderConfig[];
+    /**
+     * Disable HTML pages (default: false)
+     */
+    disableHtml?: boolean;
+}
+

package/src/server/widgets.ts

@@ -0,0 +1,38 @@
+import { Hono } from "hono";
+import { ToolServerConfig } from "./types.js";
+
+export interface WidgetInfo {
+    collection: string;
+    skill: string;
+    url: string;
+}
+
+export function createWidgetsRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+
+    const { skills = [] } = config;
+
+    // GET /api/widgets - Returns all widgets from all skill collections
+    app.get(basePath, (c) => {
+        const url = new URL(c.req.url);
+
+        const widgets: Record<string, WidgetInfo> = {};
+        for (const coll of skills) {
+            const collWidgets = coll.getWidgets();
+            for (const widget of collWidgets) {
+                widgets[widget.name] = {
+                    collection: coll.name,
+                    skill: widget.skill,
+                    url: `${url.origin}/widgets/${widget.name}.js`,
+                }
+            }
+        }
+
+        return c.json({
+            title: 'All Widgets',
+            description: 'All available widgets across all skill collections',
+            widgets,
+        });
+
+    });
+
+}

package/src/server.ts

@@ -0,0 +1,160 @@
+import { Context, Hono } from "hono";
+import { cors } from "hono/cors";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+import { createInteractionsRoute } from "./server/interactions.js";
+import { createMcpRoute } from "./server/mcp.js";
+import { createSiteRoute } from "./server/site.js";
+import { createSkillsRoute } from "./server/skills.js";
+import { createToolsRoute } from "./server/tools.js";
+import { ToolContext, ToolServerConfig } from "./server/types.js";
+import { ToolExecutionPayload } from "./types.js";
+import { createWidgetsRoute } from "./server/widgets.js";
+
+// Schema for tool execution payload
+const ToolExecutionPayloadSchema = z.object({
+    tool_use: z.object({
+        id: z.string(),
+        tool_name: z.string(),
+        tool_input: z.record(z.string(), z.any()).default({}),
+    }),
+    metadata: z.record(z.string(), z.any()).optional(),
+});
+
+
+
+/**
+ * Create a Hono server for tools, interactions, and skills.
+ *
+ * @example
+ * ```typescript
+ * import { createToolServer, ToolCollection, SkillCollection } from "@vertesia/tools-sdk";
+ *
+ * const server = createToolServer({
+ *     tools: [myToolCollection],
+ *     skills: [mySkillCollection],
+ * });
+ *
+ * export default server;
+ * ```
+ */
+export function createToolServer(config: ToolServerConfig): Hono {
+    const {
+        prefix = '/api',
+        tools = [],
+        interactions = [],
+        skills = [],
+        mcpProviders = [],
+        disableHtml = false,
+    } = config;
+
+    const app = new Hono();
+
+    // Add CORS middleware globally
+    app.use('*', cors({ origin: '*', allowMethods: ['GET', 'POST', 'OPTIONS'] }));
+
+    // Middleware to parse and validate body, store on context for reuse
+    app.use('*', async (c, next) => {
+        const ctx = c as unknown as ToolContext;
+        if (c.req.method === 'POST') {
+            try {
+                const text = await c.req.text();
+                const body = JSON.parse(text);
+                const result = ToolExecutionPayloadSchema.safeParse(body);
+                if (result.success) {
+                    ctx.payload = result.data as ToolExecutionPayload<any>;
+                    ctx.toolUseId = result.data.tool_use.id;
+                    ctx.toolName = result.data.tool_use.tool_name;
+                }
+                // If validation fails, still store raw body for error reporting
+                // but don't set payload - handlers will return validation error
+            } catch {
+                // Ignore parsing errors - body might not be JSON
+            }
+        }
+        await next();
+    });
+
+    // HTML pages (unless disabled)
+    if (!disableHtml) {
+        createSiteRoute(app, '', config);
+    }
+
+    // Add base API route
+    app.get(prefix, (c) => {
+        // Skills are exposed as tools, so include them in the tools list
+        const allToolEndpoints = [
+            ...tools.map(col => `${prefix}/tools/${col.name}`),
+            ...skills.map(col => `${prefix}/skills/${col.name}`),
+        ];
+        return c.json({
+            message: 'Vertesia Tools API',
+            version: '1.0.0',
+            endpoints: {
+                tools: allToolEndpoints,
+                interactions: interactions.map(col => `${prefix}/interactions/${col.name}`),
+                mcp: mcpProviders.map(p => `${prefix}/mcp/${p.name}`),
+            }
+        });
+    });
+
+    createToolsRoute(app, `${prefix}/tools`, config);
+    createSkillsRoute(app, `${prefix}/skills`, config);
+    createWidgetsRoute(app, `${prefix}/widgets`, config);
+    createInteractionsRoute(app, `${prefix}/interactions`, config);
+    createMcpRoute(app, `${prefix}/mcp`, config);
+
+
+    // Global error handler - returns ToolExecutionResponseError format
+    app.onError((err, c) => {
+        const ctx = c as unknown as ToolContext;
+        const status = err instanceof HTTPException ? err.status : 500;
+        const errorMessage = err instanceof HTTPException ? err.message : 'Internal Server Error';
+
+        if (!(err instanceof HTTPException)) {
+            console.error('Uncaught Error:', err);
+        }
+
+        return c.json({
+            tool_use_id: ctx.toolUseId || 'unknown',
+            status,
+            error: errorMessage,
+            data: ctx.toolName ? { tool_name: ctx.toolName } : undefined,
+        }, status);
+    });
+
+    // Not found handler - returns ToolExecutionResponseError format
+    app.notFound((c) => {
+        const ctx = c as unknown as ToolContext;
+        return c.json({
+            tool_use_id: ctx.toolUseId || 'unknown',
+            status: 404,
+            error: `Not found: ${c.req.method} ${c.req.path}`,
+            data: ctx.toolName ? { tool_name: ctx.toolName } : undefined,
+        }, 404);
+    });
+
+    return app;
+}
+
+
+
+// ================== Server Utilities ==================
+
+/**
+ * Simple development server with static fimesale handling
+ * 
+ * @deprecated Use tools server template 
+ */
+export function createDevServer(config: ToolServerConfig & {
+    staticHandler?: (c: Context, next: () => Promise<void>) => Promise<Response | void>;
+}): Hono {
+    const app = createToolServer(config);
+
+    if (config.staticHandler) {
+        app.use('*', config.staticHandler);
+    }
+
+    return app;
+}
+