@llms-sdk/toolkit

A comprehensive tool collection for the LLMS SDK library, providing built-in tools and MCP (Model Context Protocol) server integration.

Features

• 🔧 Built-in Tools: File operations, shell commands, search, and productivity tools
• 🌐 MCP Integration: First-class support for MCP servers and tools
• ⚡ Tool Cancellation: Cancel long-running operations with AbortSignal
• 🎯 Type Safe: Full TypeScript support with Zod validation
• 📦 Modular: Import only the tools you need
• 🛡️ Secure: Input validation and safe execution patterns

Installation

npm install @llms-sdk/toolkit

Quick Start

import { createAnthropicClient, createContext } from "@llms-sdk/core";
import { getBuiltinTools } from "@llms-sdk/toolkit";

// Create client and context
const client = createAnthropicClient({ model: "claude-3-5-sonnet-20241022" });
const context = createContext();

// Add all built-in tools
const tools = getBuiltinTools();
tools.forEach((tool) => context.addTool(tool));

// Now your LLM has access to tools!
const result = await client.ask("List files in the current directory", { context });

Built-in Tools

File System Tools

• Read: Read files with line ranges and limits
• Write: Write content to files with safety checks
• Edit: Perform exact string replacements
• MultiEdit: Make multiple edits to a file atomically
• LS: List directory contents with filtering
• Glob: Fast file pattern matching
• Grep: Content search with regex support

Shell & System Tools

• Bash: Execute shell commands with timeout and cancellation
• Task: Launch sub-agents for complex operations

Productivity Tools

• TodoRead: Read todo lists for session management
• TodoWrite: Manage structured task lists

Notebook Tools

• NotebookRead: Read Jupyter notebooks
• NotebookEdit: Edit Jupyter notebook cells

Browser Automation (via MCP)

• mcppuppeteer*****: Browser navigation, screenshots, interaction

Usage Patterns

All Built-in Tools

import { getBuiltinTools, createToolRegistry } from "@llms-sdk/toolkit";

const registry = createToolRegistry();
const tools = getBuiltinTools();
tools.forEach((tool) => {
	registry.addTool(tool);
	context.addTool(tool);
});

Selective Tools

import { bashTool, readTool, writeTool, globTool } from "@llms-sdk/toolkit/builtin";

// Add only specific tools
context.addTool(bashTool);
context.addTool(readTool);
context.addTool(writeTool);
context.addTool(globTool);

MCP Integration

import { MCPRegistry } from "@llms-sdk/toolkit/mcp";

const mcpRegistry = new MCPRegistry();

// Register MCP servers
await mcpRegistry.registerServer("puppeteer", {
	command: "npx",
	args: ["@modelcontextprotocol/server-puppeteer"],
	timeout: 30000,
});

// Add MCP tools to context
const mcpTools = await mcpRegistry.getAvailableTools();
mcpTools.forEach((tool) => context.addTool(tool));

Tool Cancellation

import { ToolExecutionManager } from "@llms-sdk/toolkit";

const manager = new ToolExecutionManager(context);
const abortController = new AbortController();

// Cancel after 10 seconds
setTimeout(() => abortController.abort(), 10000);

try {
	const result = await client.ask("Run a long analysis", {
		context,
		signal: abortController.signal,
	});
} catch (error) {
	if (error.name === "AbortError") {
		console.log("Operation cancelled");
	}
}

Custom Tools

import { defineTool } from "@llms-sdk/toolkit";
import { z } from "zod";

const customTool = defineTool({
	name: "CustomTool",
	description: "My custom tool",
	category: "utility",
	schema: z.object({
		input: z.string(),
		options: z
			.object({
				verbose: z.boolean().default(false),
			})
			.optional(),
	}),
	execute: async (args, signal) => {
		// Custom implementation
		if (signal?.aborted) {
			throw new Error("Operation cancelled");
		}
		return { result: `Processed: ${args.input}` };
	},
});

context.addTool(customTool);

MCP Server Support

llm-composer-tools provides first-class support for MCP (Model Context Protocol) servers:

Supported MCP Servers

• @modelcontextprotocol/server-filesystem: File system operations
• @modelcontextprotocol/server-puppeteer: Browser automation
• @modelcontextprotocol/server-sqlite: Database operations
• @modelcontextprotocol/server-git: Git operations
• Any custom MCP server

MCP Configuration

const mcpConfig = {
	servers: {
		filesystem: {
			command: "npx",
			args: ["@modelcontextprotocol/server-filesystem", "/path/to/root"],
			timeout: 10000,
		},
		puppeteer: {
			command: "npx",
			args: ["@modelcontextprotocol/server-puppeteer"],
			timeout: 30000,
		},
	},
};

MCP Error Handling

try {
	await mcpRegistry.registerServer("myserver", config);
} catch (error) {
	console.log("MCP server registration failed:", error.message);
	// Graceful degradation - continue with built-in tools
}

Tool Categories

Tools are organized by category for easier management:

• filesystem: File and directory operations
• shell: Command execution and system interaction
• search: File and content search
• productivity: Task management and organization
• notebook: Jupyter notebook operations
• mcp: Tools from MCP servers
• custom: User-defined tools

API Reference

Core Classes

ToolRegistry

class ToolRegistry {
	addTool(tool: LlmsSdkTool): void;
	getTool(name: string): LlmsSdkTool | undefined;
	getToolsByCategory(category: string): LlmsSdkTool[];
	listAllTools(): LlmsSdkTool[];
}

MCPRegistry

class MCPRegistry {
	registerServer(name: string, config: MCPServerConfig): Promise<void>;
	unregisterServer(name: string): Promise<void>;
	getAvailableTools(): Promise<LlmsSdkTool[]>;
	shutdown(): Promise<void>;
}

ToolExecutionManager

class ToolExecutionManager {
	constructor(context: Context);
	executeWithCancellation(client: ChatClient, message: string): Promise<AskResult>;
	cancelCurrentOperation(): void;
}

Core Functions

getBuiltinTools()

Returns all built-in tools as an array.

createToolRegistry()

Creates a new tool registry instance.

defineTool(params)

Defines a new tool with Zod schema validation.

Tool Interface

interface LlmsSdkTool<T = Record<string, unknown>, R = unknown> {
	name: string;
	description: string;
	category: "filesystem" | "shell" | "web" | "productivity" | "notebook" | "mcp" | "custom";
	tags?: string[];
	version?: string;
	experimental?: boolean;
	schema: ZodSchema<T>;
	execute: (args: T, signal?: AbortSignal) => Promise<R>;
}

Configuration

Environment Variables

# Tool timeouts (milliseconds)
LLMS_SDK_TOOLS_TIMEOUT=30000

# MCP server configuration
LLMS_SDK_TOOLS_MCP_SERVERS=filesystem,puppeteer
LLMS_SDK_TOOLS_FILESYSTEM_ROOT=/path/to/root

# Security settings
LLMS_SDK_TOOLS_ALLOW_SHELL=true
LLMS_SDK_TOOLS_ALLOW_NETWORK=true

Programmatic Configuration

import { createFromConfig } from "@llms-sdk/toolkit";

const config = {
	builtinTools: ["bash", "read", "write", "glob"],
	mcpServers: ["filesystem", "puppeteer"],
	timeout: 30000,
	security: {
		allowShell: true,
		allowNetwork: true,
		allowFileWrite: true,
	},
};

const toolsConfig = createFromConfig(config);
await toolsConfig.initialize();
toolsConfig.addToContext(context);

Examples

See the examples/ directory for complete, runnable examples:

• 01-basic-setup.ts - Basic setup with all tools
• 02-selective-tools.ts - Selective tool loading
• 03-mcp-integration.ts - MCP server integration
• 04-tool-cancellation.ts - Cancellation handling
• 05-custom-tool.ts - Custom tool development
• 06-chat-app.ts - Complete chat application

Run any example with:

npx tsx examples/01-basic-setup.ts

Security Considerations

File System Access

• Tools respect file system permissions
• Use allowFileWrite: false to disable write operations
• Consider running in containers for additional isolation

Shell Execution

• Commands are executed in the current user context
• Use allowShell: false to disable shell tools
• Always validate and sanitize inputs

MCP Servers

• MCP servers run as separate processes
• Validate MCP server sources and permissions
• Use timeouts to prevent resource exhaustion

Error Handling

Tool Execution Errors

const result = await context.executeTool(toolCall);
if (!result.success) {
	console.log("Tool failed:", result.error.message);
	console.log("Error type:", result.error.type);
}

MCP Server Errors

try {
	const tools = await mcpRegistry.getAvailableTools();
} catch (error) {
	if (error.type === "mcp_error") {
		console.log("MCP server error:", error.message);
	}
}

Validation Errors

// Zod validation errors are automatically handled
// and converted to ToolError with type 'invalid_args'

Performance

Tool Loading

• Tools are loaded lazily when first used
• Use selective loading for better startup performance
• MCP servers are started on-demand

Caching

• File operations use intelligent caching
• MCP connections are pooled and reused

Cancellation

• All tools support cancellation via AbortSignal
• Client-side cancellation is immediate
• MCP server cancellation depends on server implementation

Contributing

Adding Built-in Tools

1. Create tool in src/builtin/
2. Add to exports in src/builtin/index.ts
3. Add tests in test/builtin/
4. Update documentation

Adding MCP Support

1. Test with MCP server
2. Add configuration examples
3. Document any special requirements
4. Add integration tests

Dependencies

• @llms-sdk/core: Core LLM client library
• @modelcontextprotocol/sdk: MCP protocol implementation
• zod: Schema validation
• zod-to-json-schema: Schema conversion
• json-schema-to-zod: Reverse schema conversion

License

MIT License - see LICENSE file for details.

Related Projects

• @llms-sdk/core - Core LLM client library
• @llms-sdk/terminal - Terminal UI components
• @llms-sdk/cli - CLI argument parsing