How TPMJS Works

The complete journey from npm package to AI-powered tool execution

What is TPMJS?

TPMJS (Tool Package Manager for JavaScript) is a registry and execution platform that automatically discovers, catalogs, and runs AI tools from the npm ecosystem.

It acts as a bridge between AI agents (powered by frameworks like Vercel AI SDK, LangChain, and LlamaIndex) and reusable tool packages published to npm.

🔍

Automatic Discovery

Tools appear on tpmjs.com within 2-15 minutes of publishing to npm

📊

Quality Scoring

Automatic scoring based on documentation, downloads, and metadata completeness

⚡

Instant Execution

AI agents can discover and execute tools through a unified API

For Tool Developers

Publishing a tool to TPMJS is as simple as publishing to npm with a standardized metadata field.

Add metadata to package.json

{
  "name": "@yourname/awesome-tool",
  "version": "1.0.0",
  "keywords": ["tpmjs-tool"],
  "tpmjs": {
    "category": "text-analysis",
    "frameworks": ["vercel-ai"],
    "tools": [{
      "name": "analyzeSentiment",
      "description": "Analyze sentiment of text and return positive/negative/neutral"
    }]
  }
}

Parameters are automatically extracted from your tool code - no need to list them manually!

Publish to npm

npm publish --access public

That's it! TPMJS will automatically discover your tool within 2-15 minutes.

For AI Agents

AI agents can search, discover, and execute tools through the TPMJS API.

Search & Filter

# Search tools by query
GET /api/tools?q=sentiment&category=text-analysis

# Filter by health status
GET /api/tools?importHealth=HEALTHY&executionHealth=HEALTHY

# Get official tools only
GET /api/tools?official=true

Execute Tools

import { streamText } from 'ai';
import { analyzeSentiment } from '@yourname/awesome-tool';

const result = await streamText({
  model: openai('gpt-4'),
  prompt: 'Analyze the sentiment of: I love this product!',
  tools: {
    analyzeSentiment,  // Just import and use alongside your other tools
    // ... your other tools
  },
});

Test in Playground

Try tools interactively before integrating them into your AI agent.

The Magic Behind the Scenes

1. Automatic Discovery

TPMJS uses three parallel mechanisms to discover tools from npm:

Changes Feed

Monitors npm's real-time changes stream

Every 2 minutes

Keyword Search

Searches npm for "tpmjs-tool" keyword

Every 15 minutes

Manual Curation

Curated list of high-quality tools

Updated regularly

2. Validation & Schema Extraction

Every discovered package is validated and its schema is automatically extracted:

✓Valid category from predefined list
✓Description between 20-500 characters
✓inputSchema auto-extracted from tool code via sandboxed executor
✓Parameters derived from JSON Schema for display
✓Fallback to author-provided parameters if extraction fails

3. Quality Scoring

Every tool receives a quality score (0.00 to 1.00) based on:

Tier (Metadata Completeness)40-60%

Downloads (Popularity)up to 20%

GitHub Starsup to 10%

AI-Friendly Metadataup to 10%

Higher quality scores = better visibility in search results and featured sections

4. Health Checks

Every tool is tested to ensure it works correctly:

Import Health

• Can the package be imported?
• Does the export exist?
• Is it in AI SDK format?

Execution Health

• Can test parameters be generated?
• Does the tool execute without errors?
• Does it return valid results?

5. Indexing

Tools are stored in a PostgreSQL database with rich metadata:

→Package-level: Version, README, repository, category, downloads, stars
→Tool-level: Export name, description, parameters, return type, AI guidance
→Metrics: Quality score, health status, execution history

System Architecture

From Publish to Execution

Developer publishes to npm

Package with tpmjs-tool keyword

~1 second

TPMJS discovers package

Changes feed or keyword search picks it up

2-15 minutes

Validation & indexing

Schema validation, database insertion, health checks

~5 seconds

Tool appears on tpmjs.com

Searchable, browsable, and executable in playground

Instant

Quality score calculated

Based on tier, downloads, stars, and metadata

Within 1 hour

AI agents can discover & execute

Available via API for search and execution

Ongoing

🧪 Beta

Dynamic Tool Loading

Our playground demonstrates the future of AI agents: tools that discover and load themselves dynamically based on conversation context.

🔍 BM25 Search + Context Awareness

When you chat in the playground, your messages are analyzed using the BM25 ranking algorithm to find the most relevant tools from the entire registry.

// The playground automatically searches for relevant tools
const relevantTools = await searchTpmjsTools({
  query: userMessage,
  limit: 5,
  recentMessages: lastThreeMessages  // Context matters!
});

// Tools are ranked by:
// - BM25 relevance score (keyword matching)
// - Quality score (documentation, downloads)
// - Download popularity (logarithmic boost)
// Result: The right tools, at the right time

⚡ Zero-Config Dynamic Loading

Found tools are loaded on-demand from esm.sh and executed in a sandboxed Deno environment on Railway.

// Traditional approach: Static tool imports
import { weatherTool } from '@acme/weather';
import { searchTool } from '@acme/search';
// Problem: Must know tools ahead of time ❌

// TPMJS approach: Dynamic tool loading
import { streamText } from 'ai';
import { searchTpmjsToolsTool } from '@tpmjs/search-registry';

const result = await streamText({
  model: openai('gpt-4'),
  messages,
  tools: {
    // This meta-tool lets the AI discover its own tools!
    searchTpmjsTools: searchTpmjsToolsTool,
  },
});

// Agent decides: "I need weather data"
//   → Searches registry → Finds @acme/weather
//   → Loads from esm.sh → Executes in Deno sandbox ✅

🏝️ Sandboxed Execution

All dynamically loaded tools execute in an isolated Deno runtime on Railway, ensuring security and reliability.

Network Imports

Deno loads packages directly from esm.sh with --experimental-network-imports

Automatic Health Checks

Failed imports or executions trigger health status updates in the registry

Process-Level Caching

Tools are cached per conversation to avoid redundant network requests

🎯 Coming Soon: Collections

Imagine pre-configured tool bundles (mini sub-agents) that you can reference by name:

// Future API concept (not yet implemented)
const result = await streamText({
  model: openai('gpt-4'),
  messages,
  tools: await tpmjs.loadToolsFor(messages, {
    collections: ['web-scraping', 'data-analysis'],
    // Loads curated tool sets optimized for specific tasks
    // Collections can be public (official) or private (your own)
  }),
});

// Example collections:
// - 'web-scraping': puppeteer, cheerio, readability tools
// - 'data-analysis': pandas-like tools, plotting, statistics
// - 'ecommerce': payment, inventory, shipping tools
// - Or build your own custom collections!

Why collections? They let you compose specialized sub-agents without manually curating tool lists. Think of them as “skill packs” for your AI.

Try It in the Playground

Ask the playground agent to “search for tools about X” and watch it discover, load, and execute tools dynamically!

Ready to Get Started?

Whether you're building AI tools or integrating them into your agent, TPMJS makes it simple.