diff --git a/apps/playground/src/components/sidebar/ToolsSidebar.tsx b/apps/playground/src/components/sidebar/ToolsSidebar.tsx index 961f824..2e0c0ca 100644 --- a/apps/playground/src/components/sidebar/ToolsSidebar.tsx +++ b/apps/playground/src/components/sidebar/ToolsSidebar.tsx @@ -35,6 +35,16 @@ export function ToolsSidebar(): React.ReactElement { try { const response = await fetch('/api/tools'); const data = await response.json(); + console.log('🔍 [ToolsSidebar] Fetched tools:', data.tools?.length, 'tools'); + console.log('🔍 [ToolsSidebar] First tool sample:', data.tools?.[0]); + console.log('🔍 [ToolsSidebar] Health fields check:', { + hasImportHealth: 'importHealth' in (data.tools?.[0] || {}), + hasExecutionHealth: 'executionHealth' in (data.tools?.[0] || {}), + firstToolHealth: { + importHealth: data.tools?.[0]?.importHealth, + executionHealth: data.tools?.[0]?.executionHealth, + }, + }); if (data.success) { setTools(data.tools); } diff --git a/apps/web/src/app/how-it-works/page.tsx b/apps/web/src/app/how-it-works/page.tsx new file mode 100644 index 0000000..dcbf04f --- /dev/null +++ b/apps/web/src/app/how-it-works/page.tsx @@ -0,0 +1,536 @@ +import { Button } from '@tpmjs/ui/Button/Button'; +import { CodeBlock } from '@tpmjs/ui/CodeBlock/CodeBlock'; +import { Container } from '@tpmjs/ui/Container/Container'; +import Link from 'next/link'; +import { AppHeader } from '~/components/AppHeader'; + +export const metadata = { + title: 'How It Works | TPMJS', + description: 'Learn how TPMJS automatically discovers, indexes, and serves AI tools from npm', +}; + +export default function HowItWorksPage(): React.ReactElement { + return ( +
+ + +
+ + {/* Hero */} +
+

How TPMJS Works

+

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

+
+ + {/* Overview */} +
+

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 Developers */} +
+

For Tool Developers

+
+

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

+ + {/* Step 1 */} +
+
+ + 1 + +

+ Add metadata to package.json +

+
+ +
+ + {/* Step 2 */} +
+
+ + 2 + +

Publish to npm

+
+ +

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

+
+ +
+ + + +
+
+
+ + {/* For AI Agents */} +
+

For AI Agents

+
+

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

+ + {/* Search Tools */} +
+

Search & Filter

+ +
+ + {/* Execute Tools */} +
+

Execute Tools

+ { + // Tool execution handled by TPMJS + return await executeTpmjsTool('@yourname/awesome-tool', 'analyzeSentiment', { text }); + }, + }, + }, +});`} + /> +
+ + {/* Playground */} +
+

Test in Playground

+

+ Try tools interactively before integrating them into your AI agent. +

+ + + +
+
+
+ + {/* The Magic Behind the Scenes */} +
+

The Magic Behind the Scenes

+
+ {/* 1. Discovery */} +
+

+ 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 */} +
+

2. Validation

+

+ Every discovered package is validated against the TPMJS schema: +

+
    +
  • + ✓ + Valid category from predefined list +
    • +
  • + ✓ + Description between 20-500 characters +
    • +
  • + ✓ + Parameters follow type schema (string, number, boolean, etc.) +
    • +
  • + ✓ + Environment variables properly documented +
    • +
  • + ✓ + Supports legacy single-tool and modern multi-tool formats +
    • +
+
+ + {/* 3. Quality Scoring */} +
+

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 Stars + up to 10% +
+
+ AI-Friendly Metadata + up to 10% +
+
+
+

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

+
+
+
+ + {/* 4. Health Checks */} +
+

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 */} +
+

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 + +
    • +
+
+
+
+ + {/* Architecture Diagram */} +
+

System Architecture

+
+ 
+                {`┌─────────────────────────────────────────────────────────────────┐
+│                         NPM Registry                            │
+└────────────┬────────────────────────┬───────────────────────────┘
+             │                        │
+    ┌────────▼────────┐      ┌────────▼────────┐      ┌──────────────┐
+    │ Changes Feed    │      │ Keyword Search  │      │ Manual Tools │
+    │ Every 2 min     │      │ Every 15 min    │      │ As needed    │
+    └────────┬────────┘      └────────┬────────┘      └──────┬───────┘
+             │                        │                       │
+             └────────────────────────┴───────────────────────┘
+                                      │
+                              ┌───────▼────────┐
+                              │   Validation   │
+                              │ Schema Check   │
+                              └───────┬────────┘
+                                      │
+                    ┌─────────────────┴─────────────────┐
+                    │                                   │
+            ┌───────▼────────┐              ┌──────────▼──────────┐
+            │   PostgreSQL   │              │   Health Checks     │
+            │   Database     │              │ Import + Execution  │
+            └───────┬────────┘              └──────────┬──────────┘
+                    │                                   │
+                    └─────────────────┬─────────────────┘
+                                      │
+                              ┌───────▼────────┐
+                              │ Metrics Sync   │
+                              │ Quality Score  │
+                              │ Every hour     │
+                              └───────┬────────┘
+                                      │
+                    ┌─────────────────┴─────────────────┐
+                    │                                   │
+            ┌───────▼────────┐              ┌──────────▼──────────┐
+            │   Search API   │              │   Execution API     │
+            │  /api/tools    │              │ /api/tools/execute  │
+            └───────┬────────┘              └──────────┬──────────┘
+                    │                                   │
+                    └─────────────────┬─────────────────┘
+                                      │
+                              ┌───────▼────────┐
+                              │  Frontend UI   │
+                              │ Search, Detail │
+                              │  Playground    │
+                              └────────────────┘`}
+
+
+
+ + {/* Data Flow */} +
+

From Publish to Execution

+
+
+ + 1 + +
+

Developer publishes to npm

+

+ Package with{' '} + tpmjs-tool{' '} + keyword +

+
+ ~1 second +
+ +
+ + 2 + +
+

TPMJS discovers package

+

+ Changes feed or keyword search picks it up +

+
+ 2-15 minutes +
+ +
+ + 3 + +
+

Validation & indexing

+

+ Schema validation, database insertion, health checks +

+
+ ~5 seconds +
+ +
+ + 4 + +
+

Tool appears on tpmjs.com

+

+ Searchable, browsable, and executable in playground +

+
+ Instant +
+ +
+ + 5 + +
+

Quality score calculated

+

+ Based on tier, downloads, stars, and metadata +

+
+ Within 1 hour +
+ +
+ + 6 + +
+

+ AI agents can discover & execute +

+

+ Available via API for search and execution +

+
+ Ongoing +
+
+
+ + {/* CTA */} +
+

Ready to Get Started?

+

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

+
+ + + + + + + + + +
+
+ +
+
+ ); +} diff --git a/apps/web/src/components/AppHeader.tsx b/apps/web/src/components/AppHeader.tsx index 1381287..36f4280 100644 --- a/apps/web/src/components/AppHeader.tsx +++ b/apps/web/src/components/AppHeader.tsx @@ -28,6 +28,11 @@ export function AppHeader(): React.ReactElement { Tools + + +