tpmjs/packages/tools/create-basic-tools

@tpmjs/create-basic-tools

CLI generator for scaffolding production-ready TPMJS tool packages. Just enter your package name and you're done!

Features

• ⚡ Super fast: Just asks for your package name, generates everything else
• 🎯 2 example tools: Start with working examples you can customize
• 🔧 Zod 4 schemas: Uses Zod directly (not jsonSchema wrapper)
• ⚡ AI SDK v6: Full compatibility with the latest AI SDK
• 📦 One file per tool: Clean src/tools/<toolName>.ts structure
• ✅ TPMJS validated: Auto-validates against official TPMJS schemas
• 📝 Complete setup: Generates package.json, tsconfig, tsup config, README, and more
• 🚀 Publish ready: Generated packages are ready to publish to npm immediately

Usage

Interactive Mode (Recommended)

pnpmx @tpmjs/create-basic-tools

The CLI asks for just your package name and uses sensible defaults for everything else:

• Description: Auto-generated from package name
• Tools: 2 example tools you can customize
• Category: utilities (generic)
• License: MIT
• Output: Derived from package name

Example Session

$ pnpmx @tpmjs/create-basic-tools

┌  create-tpmjs
│
◇  Package name
│  @myorg/content-tools
│
◆  Generating package...
│
└  ✓ Success! Created @myorg/content-tools at ./content-tools

   Files created:
     src/tools/exampleTool.ts
     src/tools/anotherTool.ts
     src/index.ts
     package.json

   Next steps:
     cd ./content-tools
     pnpm install
     pnpm build
     pnpm type-check
     pnpm publish

That's it! The generator creates 2 example tools you can rename and customize for your use case.

Generated Package Structure

content-tools/
├── src/
│   ├── tools/                # One file per tool
│   │   ├── exampleTool.ts
│   │   └── anotherTool.ts
│   └── index.ts              # Re-exports all tools
├── dist/                     # Build output (after pnpm build)
│   ├── index.js
│   └── index.d.ts
├── package.json              # With complete tpmjs field
├── tsconfig.json
├── tsup.config.ts
├── README.md
├── .gitignore
├── .npmignore
└── LICENSE

Simply rename exampleTool.ts and anotherTool.ts to match your use case, then customize the implementation.

Generated package.json tpmjs Field

The generator creates a properly formatted tpmjs field in your package.json:

{
  "name": "@myorg/content-tools",
  "keywords": ["tpmjs", "ai-sdk", "utilities"],
  "tpmjs": {
    "category": "utilities",
    "tools": [
      {
        "name": "exampleTool",
        "description": "An example tool - customize this for your use case"
      },
      {
        "name": "anotherTool",
        "description": "Another example tool - add your implementation here"
      }
    ]
  }
}

Important: The tools field must be an array of objects, not an object map:

// ✅ Correct - tools is an array
"tools": [
  { "name": "myTool", "description": "Does something useful" }
]

// ❌ Wrong - tools is an object (will fail validation)
"tools": {
  "myTool": { "description": "Does something useful" }
}

Minimal format: If you just want auto-discovery, only category is required:

{
  "tpmjs": {
    "category": "web"
  }
}

TPMJS will automatically discover and extract tool metadata from your package exports.

Generated Tool File Example

Each tool file follows this Zod-first pattern:

import { tool } from 'ai';
import { z } from 'zod';

const ExampleToolSchema = z.object({
  text: z.string().min(1, 'Text cannot be empty').describe('The input text to process.'),
  options: z.object({
    language: z.string().default('en').describe('Language code (e.g., en, es, fr).'),
    maxLength: z.number().int().positive().default(100).describe('Maximum length of output.'),
  }).default({ language: 'en', maxLength: 100 }).describe('Optional configuration.'),
});

export const exampleTool = tool({
  description: 'An example tool - customize this for your use case',
  inputSchema: ExampleToolSchema,
  async execute(input: z.infer<typeof ExampleToolSchema>) {
    // Defensive check: Validate required parameters
    // This prevents crashes when tools are called with missing/empty params
    if (!input.text || input.text.trim().length === 0) {
      return {
        success: false,
        error: 'Missing required parameter: text',
        message: 'The "text" parameter is required and cannot be empty.',
      };
    }

    // TODO: Implement the tool logic here
    console.log('exampleTool called with:', input);

    return {
      success: true,
      message: 'Tool executed successfully. Replace this with your implementation.',
      input,
    };
  },
});

Why Defensive Parameter Validation?

Generated tools include defensive checks for required parameters. While Zod validates the schema, these checks prevent crashes in edge cases where:

• Tools are called with empty/missing parameters during AI exploration
• Parameters are undefined due to serialization issues
• The LLM makes initial "probe" calls to understand tool capabilities

Best Practice: Always validate critical required parameters before using them, especially when:

• The parameter is used in string operations (.toLowerCase(), .trim(), etc.)
• The parameter is required for the tool's core functionality
• Missing the parameter would cause a runtime error

This defensive approach ensures tools return helpful error messages instead of crashing.

After Generation

Once the package is generated:

cd content-tools

# Install dependencies
pnpm install

# Build the package
pnpm build

# Type-check
pnpm type-check

# Publish to npm
pnpm publish --access public

Your tools will appear on tpmjs.com within 2-15 minutes after publishing!

TPMJS Categories

The generator validates against these official TPMJS categories:

Core categories:

• research - Research and information gathering tools
• web - Web scraping, fetching, and browser automation
• data - Data processing and transformation
• documentation - Documentation generation and management
• engineering - Software engineering and development tools
• security - Security analysis and vulnerability scanning
• statistics - Statistical analysis and calculations
• ops - DevOps and infrastructure tools
• agent - AI agent orchestration and management
• sandbox - Code execution and sandboxing
• utilities - General-purpose utility tools
• html - HTML generation and manipulation
• compliance - Compliance and regulatory tools

Legacy categories (still supported):

• web-scraping, data-processing, file-operations, communication, database, api-integration, image-processing, text-analysis, automation, ai-ml, monitoring

Requirements

• Node.js 18+
• pnpm (recommended)

Development

This is a generator package itself. To work on it:

# Install dependencies
pnpm install

# Build
pnpm build

# Type-check
pnpm type-check

# Test locally
node dist/index.js

License

MIT