tool-server-template 0.80.0

package/rollup.config.bundle.js

@@ -0,0 +1,60 @@
+/**
+ * Rollup Configuration for building tools as es bundles for import() usage
+ *
+ * Not used for now.
+ * 
+ * Creates browser-ready bundles for each tool collection in lib/tools
+ * Input: lib/tools/{TOOL_DIR}/index.js (already compiled from TypeScript)
+ * Output: dist/libs/tool-server-{name}.js (browser bundles)
+ */
+import { nodeResolve } from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import json from '@rollup/plugin-json';
+import { terser } from 'rollup-plugin-terser';
+import fs from 'fs';
+import path from 'path';
+
+const libToolCollectionsDir = './lib/tools';
+const outputDir = './dist/libs';
+
+// Ensure output directory exists
+if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+}
+
+// Get all directories in lib/tools with an index.js
+const entries = fs.existsSync(libToolCollectionsDir)
+    ? fs.readdirSync(libToolCollectionsDir).filter((name) => {
+        const dir = path.join(libToolCollectionsDir, name);
+        return (
+            fs.statSync(dir).isDirectory() &&
+            fs.existsSync(path.join(dir, 'index.js'))
+        );
+    })
+    : [];
+
+// Create a bundle configuration for each tool collection
+const browserBundles = entries.map((name) => ({
+    input: path.join(libToolCollectionsDir, name, 'index.js'),
+    output: {
+        file: path.join(outputDir, `tool-server-${name}.js`),
+        format: 'es',
+        sourcemap: true,
+        inlineDynamicImports: true
+    },
+    plugins: [
+        nodeResolve({
+            browser: true,
+            preferBuiltins: false
+        }),
+        json(),
+        commonjs(),
+        terser({
+            compress: {
+                drop_console: false
+            }
+        })
+    ]
+}));
+
+export default browserBundles;

package/rollup.config.js

@@ -0,0 +1,99 @@
+/**
+ * Rollup Configuration for Server Build
+ *
+ * This configuration handles:
+ * 1. TypeScript compilation (src → lib) with preserveModules
+ * 2. Raw file imports (?raw) for template files
+ *
+ * Browser bundles are in rollup.config.browser.js
+ */
+import json from '@rollup/plugin-json';
+import typescript from '@rollup/plugin-typescript';
+import fs from 'fs';
+import path from 'path';
+
+// ============================================================================
+// Raw Plugin - Supports ?raw imports for template files
+// ============================================================================
+function rawPlugin() {
+    return {
+        name: 'raw-loader',
+        resolveId(id, importer) {
+            if (id.endsWith('?raw')) {
+                const cleanId = id.slice(0, -4); // Remove '?raw'
+                if (cleanId.startsWith('.') && importer) {
+                    // Resolve relative path
+                    const resolved = path.resolve(path.dirname(importer), cleanId);
+                    return resolved + '?raw';
+                }
+                return id;
+            }
+        },
+        load(id) {
+            if (id.endsWith('?raw')) {
+                const filePath = id.slice(0, -4); // Remove '?raw'
+                const content = fs.readFileSync(filePath, 'utf-8');
+                return `export default ${JSON.stringify(content)}`;
+            }
+        }
+    };
+}
+
+// ============================================================================
+// Exit Plugin - Forces process exit after build completes
+// This prevents TypeScript plugin from keeping the process alive
+// ============================================================================
+function exitPlugin() {
+    return {
+        name: 'force-exit',
+        closeBundle() {
+            console.log('Tool server build Done');
+            // Force exit after bundle completes to prevent hanging
+            setImmediate(() => process.exit(0));
+        }
+    };
+}
+
+// ============================================================================
+// Server Build Configuration (TypeScript → JavaScript)
+// ============================================================================
+const serverBuild = {
+    input: {
+        server: './src/server.ts',
+        'server-node': './src/server-node.ts',
+        'build-site': './src/build-site.ts',
+        'copy-assets': './src/copy-assets.ts'
+    },
+    output: {
+        dir: 'lib',
+        format: 'es',
+        sourcemap: true,
+        preserveModules: true,
+        preserveModulesRoot: 'src',
+        entryFileNames: '[name].js'
+    },
+    external: (id) => {
+        // Keep relative imports as part of the bundle
+        if (id.startsWith('.') || id.startsWith('/')) {
+            return false;
+        }
+        // Externalize all node modules and absolute imports
+        return true;
+    },
+    plugins: [
+        rawPlugin(),
+        typescript({
+            tsconfig: './tsconfig.json',
+            declaration: true,
+            declarationDir: 'lib',
+            sourceMap: true
+        }),
+        json(),
+        exitPlugin()
+    ]
+};
+
+// ============================================================================
+// Export server build configuration only
+// ============================================================================
+export default serverBuild;

package/src/build-site.ts

@@ -0,0 +1,77 @@
+import {
+    indexPage,
+    interactionCollectionPage,
+    skillCollectionPage,
+    toolCollectionPage
+} from "@vertesia/tools-sdk";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { loadInteractions } from "./interactions/index.js";
+import { skills } from "./skills/index.js";
+import { tools } from "./tools/index.js";
+
+/**
+ * Generates static HTML pages for all tool collections, skills, and interactions
+ * This runs during the build process to create browsable documentation
+ */
+async function build(outDir: string) {
+    console.log(`Building static site to ${outDir}...`);
+
+    // Ensure output directory exists
+    mkdirSync(outDir, { recursive: true });
+
+    // Load interactions
+    const interactions = await loadInteractions();
+
+    // Create main index page
+    console.log('Creating index page...');
+    writeFileSync(
+        `${outDir}/index.html`,
+        indexPage(tools, skills, interactions, 'Tool Server Template')
+    );
+
+    // Create pages for each tool collection
+    console.log(`Creating ${tools.length} tool collection pages...`);
+    for (const coll of tools) {
+        const dir = `${outDir}/tools/${coll.name}`;
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(
+            `${dir}/index.html`,
+            toolCollectionPage(coll)
+        );
+    }
+
+    // Create pages for each skill collection
+    console.log(`Creating ${skills.length} skill collection pages...`);
+    for (const coll of skills) {
+        const dir = `${outDir}/skills/${coll.name}`;
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(
+            `${dir}/index.html`,
+            skillCollectionPage(coll)
+        );
+    }
+
+    // Create pages for each interaction collection
+    console.log(`Creating ${interactions.length} interaction collection pages...`);
+    for (const coll of interactions) {
+        const dir = `${outDir}/interactions/${coll.name}`;
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(
+            `${dir}/index.html`,
+            interactionCollectionPage(coll)
+        );
+    }
+
+    console.log('✓ Static site build complete!');
+}
+
+// Run the build
+const outDir = process.argv[2] || './dist';
+build(outDir)
+    .then(() => {
+        process.exit(0);
+    })
+    .catch(error => {
+        console.error('Build failed:', error);
+        process.exit(1);
+    });

package/src/copy-assets.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Copy runtime assets (skill files, prompt files, scripts) to dist folder
+ * These files are read from disk at runtime and need to be deployed with the app
+ *
+ * Usage:
+ *   npx tools-sdk-copy-assets [srcDir] [distDir]
+ *
+ * Or import and call directly:
+ *   import { copyRuntimeAssets } from '@vertesia/tools-sdk';
+ *   copyRuntimeAssets('./src', './dist');
+ */
+import { existsSync, readdirSync, statSync, mkdirSync, copyFileSync } from "fs";
+import { dirname, join } from "path";
+
+/**
+ * Recursively copy files matching a filter
+ */
+function copyFilesRecursive(src: string, dest: string, fileFilter: (filename: string) => boolean): void {
+    if (!existsSync(src)) return;
+
+    const entries = readdirSync(src);
+
+    for (const entry of entries) {
+        const srcPath = join(src, entry);
+        const destPath = join(dest, entry);
+        const stat = statSync(srcPath);
+
+        if (stat.isDirectory()) {
+            // Recurse into directories
+            copyFilesRecursive(srcPath, destPath, fileFilter);
+        } else if (fileFilter(entry)) {
+            // Copy matching files
+            mkdirSync(dirname(destPath), { recursive: true });
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+
+export interface CopyAssetsOptions {
+    /** Source directory (default: './src') */
+    srcDir?: string;
+    /** Destination directory (default: './dist') */
+    distDir?: string;
+    /** Whether to log progress (default: true) */
+    verbose?: boolean;
+}
+
+/**
+ * Copy runtime assets (skills, interactions) from src to dist
+ */
+export function copyRuntimeAssets(options: CopyAssetsOptions = {}): void {
+    const {
+        srcDir = './src',
+        distDir = './dist',
+        verbose = true
+    } = options;
+
+    if (verbose) {
+        console.log('Copying runtime assets to dist...');
+    }
+
+    // Copy skill files (SKILL.md, SKILL.jst, *.py)
+    const skillsSrc = join(srcDir, 'skills');
+    const skillsDest = join(distDir, 'skills');
+
+    if (existsSync(skillsSrc)) {
+        copyFilesRecursive(skillsSrc, skillsDest, (filename) => {
+            return filename === 'SKILL.md' ||
+                   filename === 'SKILL.jst' ||
+                   filename.endsWith('.py');
+        });
+        if (verbose) {
+            console.log('  ✓ Skills assets (SKILL.md, SKILL.jst, *.py)');
+        }
+    }
+
+    // Copy interaction prompt files (prompt.jst, prompt.md)
+    const interactionsSrc = join(srcDir, 'interactions');
+    const interactionsDest = join(distDir, 'interactions');
+
+    if (existsSync(interactionsSrc)) {
+        copyFilesRecursive(interactionsSrc, interactionsDest, (filename) => {
+            return filename === 'prompt.jst' ||
+                   filename === 'prompt.md';
+        });
+        if (verbose) {
+            console.log('  ✓ Interaction assets (prompt.jst, prompt.md)');
+        }
+    }
+
+    if (verbose) {
+        console.log('Runtime assets copied successfully!');
+    }
+}
+
+// CLI entry point
+if (typeof process !== 'undefined' && process.argv[1]?.includes('copy-assets')) {
+    const args = process.argv.slice(2);
+    const srcDir = args[0] || './src';
+    const distDir = args[1] || './dist';
+
+    copyRuntimeAssets({ srcDir, distDir });
+}

package/src/interactions/index.ts

@@ -0,0 +1,7 @@
+import { SummarizeInteractions } from "./summarize/index.js";
+
+export async function loadInteractions() {
+    return [
+        SummarizeInteractions
+    ];
+}

package/src/interactions/summarize/icon.svg.ts

@@ -0,0 +1,7 @@
+export default `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/>
+  <polyline points="14 2 14 8 20 8"/>
+  <line x1="16" y1="13" x2="8" y2="13"/>
+  <line x1="16" y1="17" x2="8" y2="17"/>
+  <polyline points="10 9 9 9 8 9"/>
+</svg>`;

package/src/interactions/summarize/index.ts

@@ -0,0 +1,11 @@
+import { InteractionCollection } from "@vertesia/tools-sdk";
+import textSummarizer from "./text_summarizer/index.js";
+import icon from "./icon.svg.js";
+
+export const SummarizeInteractions = new InteractionCollection({
+    name: "summarize",
+    title: "Summarization Interactions",
+    description: "A collection of interactions for summarizing and condensing text",
+    icon,
+    interactions: [textSummarizer]
+});

package/src/interactions/summarize/text_summarizer/index.ts

@@ -0,0 +1,53 @@
+import { PromptRole } from "@llumiverse/common";
+import { InteractionSpec, TemplateType } from "@vertesia/common";
+import PROMPT_CONTENT from "./prompt.jst?raw";
+
+export default {
+    name: "text_summarizer",
+    title: "Text Summarizer",
+    description: "Summarizes text according to specified parameters like style, length, and format.",
+    result_schema: {
+        type: "object",
+        properties: {
+            summary: {
+                type: "string",
+                description: "The generated summary"
+            },
+            word_count: {
+                type: "number",
+                description: "Number of words in the summary"
+            }
+        },
+        required: ["summary"]
+    },
+    prompts: [{
+        role: PromptRole.user,
+        content: PROMPT_CONTENT,
+        content_type: TemplateType.jst,
+        schema: {
+            type: "object",
+            properties: {
+                text: {
+                    type: "string",
+                    description: "The text to summarize"
+                },
+                style: {
+                    type: "string",
+                    enum: ["concise", "detailed", "bullet-points", "executive"],
+                    description: "The summary style"
+                },
+                maxLength: {
+                    type: "number",
+                    description: "Maximum length in words (optional)"
+                },
+                format: {
+                    type: "string",
+                    enum: ["paragraph", "bullet-points", "structured"],
+                    description: "Output format (optional)"
+                }
+            },
+            required: ["text"]
+        }
+    }],
+    tags: ["text", "summarization", "nlp", "content"]
+} satisfies InteractionSpec;

package/src/interactions/summarize/text_summarizer/prompt.jst

@@ -0,0 +1,31 @@
+return `
+# Text Summarization Request
+
+Please summarize the following text according to the specifications below.
+
+## Text to Summarize
+${text}
+
+## Summarization Parameters
+- **Style**: ${style || 'concise'}
+- **Max Length**: ${maxLength ? maxLength + ' words' : 'flexible'}
+${format ? `- **Output Format**: ${format}` : ''}
+
+## Instructions
+
+1. Read and understand the full text
+2. Identify the main points and key information
+3. Create a summary that:
+   - Captures the essential meaning
+   - Maintains accuracy
+   - Uses clear, simple language
+   - Follows the ${style} style
+   ${maxLength ? `- Stays within ${maxLength} words` : ''}
+   ${format ? `- Is formatted as ${format}` : ''}
+
+4. If the text contains multiple topics, organize your summary accordingly
+
+## Output
+
+Provide your summary below:
+`;

package/src/raw-imports.d.ts

@@ -0,0 +1,4 @@
+declare module "*?raw" {
+    const content: string;
+    export default content;
+}

package/src/server-node.ts

@@ -0,0 +1,24 @@
+/**
+ * Node.js HTTP Server Entry Point
+ *
+ * This file starts a standalone Node.js HTTP server using @hono/node-server.
+ * Use this for:
+ * - Local development and testing
+ * - Deploying to Cloud Run, Railway, Fly.io, etc.
+ * - Running in Docker containers
+ */
+import { serve } from '@hono/node-server';
+import server from './server.js';
+
+const port = parseInt(process.env.PORT || '3000', 10);
+
+console.log(`Starting Tool Server on port ${port}...`);
+console.log(`API endpoint: http://localhost:${port}/api`);
+console.log(`Web UI: http://localhost:${port}/`);
+
+serve({
+    fetch: server.fetch,
+    port
+}, (info) => {
+    console.log(`✓ Server is running at http://localhost:${info.port}`);
+});

package/src/server.ts

@@ -0,0 +1,22 @@
+import { createToolServer } from "@vertesia/tools-sdk";
+import { loadInteractions } from "./interactions/index.js";
+import { skills } from "./skills/index.js";
+import { tools } from "./tools/index.js";
+
+const CONFIG__SERVER_TITLE = "Tool Server Template";
+
+// Load interactions asynchronously
+const interactions = await loadInteractions();
+
+// Create server using tools-sdk
+const server = createToolServer({
+    title: CONFIG__SERVER_TITLE,
+    prefix: '/api',
+    tools,
+    interactions,
+    skills,
+    // Uncomment and configure MCP providers if needed
+    // mcpProviders: []
+});
+
+export default server;

package/src/skills/code-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: code-review
+title: Code Review Assistant
+keywords: code, review, quality, best-practices, refactoring
+---
+
+# Code Review Assistant
+
+You are a code review assistant. Your role is to analyze code and provide constructive feedback focusing on:
+
+## Review Areas
+
+1. **Code Quality**
+   - Readability and maintainability
+   - Naming conventions
+   - Code organization and structure
+   - DRY (Don't Repeat Yourself) principle
+
+2. **Best Practices**
+   - Language-specific idioms and patterns
+   - Error handling
+   - Edge cases
+   - Security considerations
+
+3. **Performance**
+   - Algorithmic efficiency
+   - Resource usage
+   - Potential bottlenecks
+
+4. **Testing**
+   - Test coverage
+   - Test quality and clarity
+   - Missing test cases
+
+## Review Format
+
+Structure your review as follows:
+
+### Strengths
+List what the code does well.
+
+### Issues
+For each issue found:
+- **Severity**: Critical | Major | Minor
+- **Location**: File and line number
+- **Description**: What the issue is
+- **Recommendation**: How to fix it
+- **Example**: Show improved code if applicable
+
+### Summary
+Provide an overall assessment and priority recommendations.
+
+## Guidelines
+
+- Be constructive and respectful
+- Explain the "why" behind suggestions
+- Provide specific, actionable feedback
+- Consider the context and requirements
+- Balance perfection with pragmatism

package/src/skills/index.ts

@@ -0,0 +1,12 @@
+import { SkillCollection, loadSkillsFromDirectory } from "@vertesia/tools-sdk";
+
+export const CodeReviewSkills = new SkillCollection({
+    name: "code-review",
+    title: "Code Review Skills",
+    description: "Skills for reviewing and analyzing code quality",
+    skills: loadSkillsFromDirectory(new URL("./code-review", import.meta.url).pathname)
+});
+
+export const skills = [
+    CodeReviewSkills
+];

package/src/tools/calculator/calculator.ts

@@ -0,0 +1,60 @@
+import { Tool, ToolExecutionContext, ToolExecutionPayload } from "@vertesia/tools-sdk";
+import manifest from "./manifest.js";
+import { ToolResultContent } from "@vertesia/common";
+
+interface CalculatorParams {
+    expression: string;
+}
+
+/**
+ * Safely evaluates a mathematical expression
+ * Supports: +, -, *, /, ^, parentheses, and decimal numbers
+ */
+function evaluateExpression(expr: string): number {
+    // Remove whitespace
+    expr = expr.replace(/\s+/g, '');
+
+    // Replace ^ with ** for exponentiation
+    expr = expr.replace(/\^/g, '**');
+
+    // Validate expression - only allow numbers, operators, parentheses, and decimal points
+    if (!/^[0-9+\-*/.()^]+$/.test(expr)) {
+        throw new Error('Invalid expression. Only numbers and operators (+, -, *, /, ^) are allowed.');
+    }
+
+    // Use Function constructor for safe evaluation (better than eval)
+    try {
+        const result = new Function(`'use strict'; return (${expr})`)();
+        if (typeof result !== 'number' || !isFinite(result)) {
+            throw new Error('Result is not a valid number');
+        }
+        return result;
+    } catch (error) {
+        throw new Error(`Failed to evaluate expression: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+
+async function calculate(
+    payload: ToolExecutionPayload<CalculatorParams>,
+    _context: ToolExecutionContext
+): Promise<ToolResultContent> {
+    try {
+        const { expression } = payload.tool_use.tool_input!;
+        const result = evaluateExpression(expression);
+
+        return {
+            is_error: false,
+            content: `Result: ${expression} = ${result}`
+        } satisfies ToolResultContent;
+    } catch (error) {
+        return {
+            is_error: true,
+            content: `Calculation error: ${error instanceof Error ? error.message : 'Unknown error'}`
+        } satisfies ToolResultContent;
+    }
+}
+
+export const CalculatorTool = {
+    ...manifest,
+    run: calculate
+} satisfies Tool<CalculatorParams>;

package/src/tools/calculator/icon.svg.ts

@@ -0,0 +1,7 @@
+export default `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <rect x="4" y="2" width="16" height="20" rx="2"/>
+  <line x1="8" y1="6" x2="16" y2="6"/>
+  <line x1="8" y1="10" x2="16" y2="10"/>
+  <line x1="8" y1="14" x2="16" y2="14"/>
+  <line x1="8" y1="18" x2="16" y2="18"/>
+</svg>`;

package/src/tools/calculator/index.ts

@@ -0,0 +1,11 @@
+import { ToolCollection } from "@vertesia/tools-sdk";
+import { CalculatorTool } from "./calculator.js";
+import icon from "./icon.svg.js";
+
+export const CalculatorTools = new ToolCollection({
+    name: "calculator",
+    title: "Calculator Tools",
+    description: "A collection of tools for performing mathematical calculations",
+    icon,
+    tools: [CalculatorTool]
+});

package/src/tools/calculator/manifest.ts

@@ -0,0 +1,16 @@
+import { ToolDefinition } from "@vertesia/tools-sdk";
+
+export default {
+    name: "calculator",
+    description: "Performs basic mathematical calculations. Supports addition (+), subtraction (-), multiplication (*), division (/), and exponentiation (^).",
+    input_schema: {
+        type: "object",
+        properties: {
+            expression: {
+                type: "string",
+                description: "A mathematical expression to evaluate (e.g., '2 + 2', '10 * 5 - 3', '2^8')"
+            }
+        },
+        required: ["expression"]
+    }
+} satisfies ToolDefinition;