Custom JS Tools Easy

Create custom tools without modifying plugin source code.

Overview

Custom JS tools are stored in data/tools/ directory with hot reload support.

Quick Start

1. Create .js file in data/tools/
2. Export tool definition
3. Tool is automatically available

Directory Structure

data/tools/
├── example_tool.js    # Example tool
├── my_weather.js      # Custom weather tool
└── README.md          # Documentation

Tool Template

// data/tools/my_tool.js
export const tools = [
  {
    name: 'my_custom_tool',
    description: 'What this tool does',
    
    inputSchema: {
      type: 'object',
      properties: {
        param1: {
          type: 'string',
          description: 'Parameter description'
        }
      },
      required: ['param1']
    },
    
    handler: async (args, context) => {
      const { param1 } = args
      
      // Your logic here
      return {
        success: true,
        result: `Processed: ${param1}`
      }
    }
  }
]

export default tools

Context Access

Access runtime context via second parameter:

handler: async (args, context) => {
  const { userId, groupId, event } = context
  
  // Use context info
  return { userId, groupId }
}

Examples

Simple Calculator

export const tools = [{
  name: 'calculate',
  description: 'Perform arithmetic calculation',
  
  inputSchema: {
    type: 'object',
    properties: {
      expression: {
        type: 'string',
        description: 'Math expression like "2 + 2"'
      }
    },
    required: ['expression']
  },
  
  handler: async ({ expression }) => {
    try {
      // Safe eval for simple math
      const result = Function(`return ${expression}`)()
      return { result: String(result) }
    } catch {
      return { error: 'Invalid expression' }
    }
  }
}]

Web Fetch

export const tools = [{
  name: 'fetch_url',
  description: 'Fetch content from URL',
  
  inputSchema: {
    type: 'object',
    properties: {
      url: { type: 'string', description: 'URL to fetch' }
    },
    required: ['url']
  },
  
  handler: async ({ url }) => {
    const response = await fetch(url)
    const text = await response.text()
    return { 
      status: response.status,
      content: text.slice(0, 1000)
    }
  }
}]

Hot Reload

Auto Reload

Files in data/tools/ are watched. Changes apply automatically without restart.

To manually reload:

#ai重载配置

Best Practices

Practice	Description
Clear naming	Use descriptive snake_case names
Good descriptions	Help AI understand when to use
Error handling	Always handle exceptions
Input validation	Validate parameters
Limit output	Keep responses concise

Next Steps

• Built-in Tools - Core tool reference
• MCP Server - External MCP integration
• Security - Permission control