diff --git a/apps/web/src/app/spec/layout.tsx b/apps/web/src/app/spec/layout.tsx new file mode 100644 index 0000000..1963179 --- /dev/null +++ b/apps/web/src/app/spec/layout.tsx @@ -0,0 +1,21 @@ +import type { Metadata } from 'next'; + +export const metadata: Metadata = { + title: 'TPMJS Specification', + description: + 'The open standard for AI tool discovery. Complete schema reference for package.json configuration.', + openGraph: { + title: 'TPMJS Specification', + description: + 'The open standard for AI tool discovery. Complete schema reference for package.json configuration.', + images: [{ url: '/api/og/spec', width: 1200, height: 630 }], + }, + twitter: { + card: 'summary_large_image', + images: ['/api/og/spec'], + }, +}; + +export default function SpecLayout({ children }: { children: React.ReactNode }) { + return children; +} diff --git a/apps/web/src/app/spec/page.tsx b/apps/web/src/app/spec/page.tsx index d202fca..923b180 100644 --- a/apps/web/src/app/spec/page.tsx +++ b/apps/web/src/app/spec/page.tsx @@ -1,887 +1,433 @@ +'use client'; + import { TPMJS_CATEGORIES } from '@tpmjs/types/tpmjs'; import { Badge } from '@tpmjs/ui/Badge/Badge'; -import { Button } from '@tpmjs/ui/Button/Button'; -import { Card, CardContent, CardHeader, CardTitle } from '@tpmjs/ui/Card/Card'; import { CodeBlock } from '@tpmjs/ui/CodeBlock/CodeBlock'; import { Container } from '@tpmjs/ui/Container/Container'; -import Link from 'next/link'; +import { useState } from 'react'; import { AppHeader } from '~/components/AppHeader'; -export const metadata = { - title: 'TPMJS Specification | The Open Standard for AI Tool Discovery', - description: - 'Complete technical reference for the TPMJS specification - field definitions, validation rules, and integration guide for AI tool developers.', - openGraph: { - title: 'TPMJS Specification | The Open Standard for AI Tool Discovery', - description: - 'Complete technical reference for the TPMJS specification - field definitions, validation rules, and integration guide for AI tool developers.', - images: [{ url: '/api/og/spec', width: 1200, height: 630 }], - }, - twitter: { - card: 'summary_large_image' as const, - images: ['/api/og/spec'], - }, -}; +type ViewMode = 'spec' | 'example'; -export default function SpecPage(): React.ReactElement { - return ( -
- - -
- - {/* Hero */} -
-

- TPMJS Specification -

-

- The open standard for AI tool discovery and integration -

-
- - {/* What is TPMJS */} -
-

- What is TPMJS? -

-
-

- TPMJS (Tool Package Manager for JavaScript) is an open standard and registry for AI - tool discovery and integration. It solves the problem of fragmented AI tool - ecosystems by providing: -

-
    -
  • - Automatic Discovery - Tools are - automatically indexed from NPM based on keywords -
    • -
  • - Standardized Metadata - A unified - specification for describing tool capabilities -
    • -
  • - Quality Scoring - Algorithmic ranking - based on documentation completeness and community adoption -
    • -
  • - AI Agent Integration - Structured - metadata optimized for LLM tool selection -
    • -
-
-
- - {/* How it Works */} -
-

- How it Works -

-
- - -
📦
- 1. Publish to NPM - - -

- Add the tpmjs{' '} - keyword and a{' '} - tpmjs metadata - field to your package.json -

- - - - - -
🔍
- 2. Automatic Discovery - - -

- TPMJS monitors NPM every 2 minutes for new tools and updates the registry - automatically -

- - - - - -
⚡
- 3. Instant Availability - - -

- Your tool appears on tpmjs.com within 15 minutes, searchable by AI agents and - developers -

- - -
-
- - {/* The Specification */} -
-

- The Specification -

-

- The TPMJS specification defines a{' '} - tpmjs field in - package.json. TPMJS automatically extracts parameter schemas from your tool code, so - you only need to provide basic metadata. -

- - {/* Auto-extraction callout */} -
-
-
✨
-
-

- Automatic Schema Extraction -

-

- TPMJS automatically extracts your tool's input schema (parameters) by - analyzing your code when it syncs. You no longer need to manually document - parameters, returns, or AI agent guidance in package.json. -

-
-
- inputSchema -

- Auto-extracted from your Zod schema -

-
-
- parameters -

- Derived from inputSchema automatically -

-
-
- Tool page -

- Shows extracted schema with source badge -

-
-
-
-
-
- - {/* Required Fields */} -
-
- - Required Fields - - What you need to provide -
- - -
-
-

- category * -

-

- Tool category for organization. Must be one of the following: -

-
- {TPMJS_CATEGORIES.map((cat) => ( - - {cat} - - ))} -
-
-
- -
-
- Minimal Example (auto-discovery): -
- -

- That's it! TPMJS will automatically discover your exported tools and - extract their schemas. -

-
- - -
+}`; - {/* Auto-Discovery */} -
-
-
🔍
-
-

- Auto-Discovery of Tools -

-

- When you omit the tools array, TPMJS - automatically scans your package exports and registers any export that looks - like an AI SDK tool (has description{' '} - and execute properties). -

-
-
- Automatic -

- Works with any AI SDK compatible tool -

-
-
- Override -

- Add explicit tools to control what gets registered -

-
-
-
-
-
- - {/* Optional Fields */} -
-
- - Optional Fields - - - Additional metadata for better visibility - -
- - -
-
-

- tools -

-

- Array of tools to register. If omitted, tools are auto-discovered. Each tool - has: -

-
    -
  • - name - The exported function name - (required) -
    • -
  • - description - What the tool does - (optional, auto-extracted if omitted) -
    • -
-
- -
-

- env -

-

- Array of environment variables required by the tool. Each variable has: -

-
    -
  • - name - Environment variable name - (e.g., "OPENAI_API_KEY") -
    • -
  • - description - What the variable - is used for -
    • -
  • - required - Boolean (defaults to - true) -
    • -
-
- -
-

- frameworks -

-

- Array of compatible AI frameworks. Supported values: -

-
- {[ - 'vercel-ai', - 'langchain', - 'llamaindex', - 'haystack', - 'semantic-kernel', - ].map((fw) => ( - - {fw} - - ))} -
-
-
- -
-
- Example with explicit tools: -
- -
- - -
+}`; - {/* Auto-Extracted Fields */} -
-
- - Auto-Extracted - - - No need to specify (kept for backward compatibility) - -
- - -

- The following fields are automatically extracted from your tool code. You can - optionally provide them to override the extracted values: -

-
    -
  • - - description - - → Auto-extracted from tool's description property -
    • -
  • - - parameters - - → Auto-extracted from tool's Zod inputSchema -
    • -
  • - returns - → Auto-extracted from tool definition -
    • -
  • - aiAgent - → Auto-extracted from tool metadata -
    • -
-

- If auto-extraction fails, TPMJS will fall back to any manually provided values. -

- - -
-
+const TOOL_CODE_EXAMPLE = `import { tool } from 'ai'; +import { z } from 'zod'; - {/* Schema Extraction */} -
-

- Schema Extraction -

-

- When TPMJS syncs your package, it automatically extracts your tool's inputSchema - by loading and inspecting your tool in a sandboxed environment. -

-
- - -
🔄
- During Sync - - -

- Schema is extracted automatically when your package is discovered or updated -

- - +export const analyzeSentiment = tool({ + description: 'Analyze text sentiment with emotion breakdown', + parameters: z.object({ + text: z.string().describe('The text to analyze'), + language: z.string().optional().describe('ISO language code'), + includeEmotions: z.boolean().default(true).describe('Include emotion breakdown'), + }), + execute: async ({ text, language, includeEmotions }) => { + // Your implementation here + return { + sentiment: 'positive', + confidence: 0.92, + emotions: includeEmotions ? { + joy: 0.7, + trust: 0.2, + anticipation: 0.1, + } : undefined, + }; + }, +}); - - -
🏷️
- Source Badge - - -

- Tool pages show whether schema was "Auto-extracted" or - "Author-provided" -

- - +export const batchAnalyze = tool({ + description: 'Analyze multiple texts in parallel', + parameters: z.object({ + texts: z.array(z.string()).describe('Array of texts to analyze'), + }), + execute: async ({ texts }) => { + // Batch implementation + return texts.map(text => ({ text, sentiment: 'neutral' })); + }, +});`; - - -
🔁
- Manual Re-extract - - -

- Users can trigger re-extraction from the tool page if needed -

- - -
- - -

How It Works:

-
    -
  1. Your tool is loaded in a Deno sandbox via esm.sh
    2. -
  2. - The inputSchema property is read from - your exported tool -
    3. -
  3. The JSON Schema is stored in our database
    4. -
  4. Parameters are derived from the schema for display
    5. -
- - -
+export default function SpecPage(): React.ReactElement { + const [view, setView] = useState('spec'); - {/* Field Reference Table */} -
-

- Field Reference -

- - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeRequiredDescription
- category - string - Yes - Tool category from predefined list
- tools - arrayNo - Array of tool definitions (name + description). Auto-discovered if - omitted. -
- env - arrayNoRequired environment variables
- frameworks - arrayNoCompatible AI frameworks
- parameters - array - - Deprecated - - - Auto-extracted from tool -
- returns - object - - Deprecated - - - Auto-extracted from tool -
- aiAgent - object - - Deprecated - - - Auto-extracted from tool -
+ return ( +
+ + +
+ {/* Hero */} +
+ +
+
+
+ + v1.0 + + package.json
- - -
+

+ TPMJS Specification +

+
- {/* Quality Score */} -
-

- Quality Score -

-

- Tools are ranked by quality score, calculated from three factors: -

-
- - - Tier Multiplier - - -
    -
  • - Rich: 4x multiplier -
    • -
  • - Basic: 2x multiplier -
    • -
  • - Minimal: 1x multiplier -
    • -
- - - - - - NPM Downloads - - -

- Logarithmic scale based on monthly downloads. More downloads = higher score. -

- - - - - - GitHub Stars - - -

- Logarithmic scale based on repository stars. Community validation boosts - visibility. -

- - + {/* View Toggle */} +
+ + +
- - -

Formula:

- + - return Math.min(1.0, tierScore + downloadsScore + starsScore); -}`} - /> - - -
- - {/* Discovery & Sync */} -
-

- Discovery & Sync -

-

- TPMJS automatically discovers and updates tools using three strategies: -

-
- - - Changes Feed - - -

- Monitors NPM's real-time changes feed every 2 minutes -

- - Real-time - - - - - - - Keyword Search - - -

- Searches for{' '} - tpmjs keyword - every 15 minutes -

- - Every 15 min - - - - - - - Metrics Update - - -

- Updates download stats and quality scores hourly -

- - Hourly - - - -
-
- - {/* Validation */} -
-

- Validation -

-

- The TPMJS specification is validated using Zod schemas. The validation logic is - available in the{' '} - - @tpmjs/types - {' '} - package. -

- - -

- Common Validation Errors: -

-
    -
  • - Invalid category: Category must be - one of the 12 predefined values -
    • -
  • - Description too short/long:{' '} - Description must be 20-500 characters -
    • -
  • - Invalid env: Each environment - variable must have a name and description -
    • -
- - -
- - {/* Publishing Your Tool */} -
-

- Publishing Your Tool -

-

- Publishing a tool to TPMJS is simple: -

-
- - -
1️⃣
-

- Add tpmjs{' '} - keyword -

- - - - -
2️⃣
-

- Add tpmjs field -

- - - - -
3️⃣
-

Publish to NPM

- - - - -
✅
-

- Appears on tpmjs.com in 15 min -

- - -
-
- - - -
-
- - {/* Support & Resources */} -
-

- Support & Resources -

-
- - - Documentation - - - - → Publishing Guide - - - → GitHub Repository - - - → TypeScript Types Package - - - - - - - Examples - - - - → Browse All Tools - - - → Try the Playground - - - → Report Issues or Ask Questions - - - -
-
+ {/* Content */} + + {view === 'spec' ? : } - - {/* Footer */} - + + ); +} + +function SpecificationView(): React.ReactElement { + return ( +
+ {/* Main Content */} +
+ {/* Minimal Required */} +
+
+
+ 1 +
+

Minimal Configuration

+
+

+ Add the tpmjs{' '} + keyword and field to your package.json. Tools are auto-discovered from your exports. +

+ +
+ + {/* Category Field */} +
+
+
+ * +
+

+ category (required) +

+
+

+ One of the following predefined categories: +

+
+ {TPMJS_CATEGORIES.map((cat) => ( + + {cat} + + ))} +
+
+ + {/* Tools Array */} +
+
+
+ ? +
+

+ tools (optional) +

+
+

+ Explicit tool definitions. If omitted, tools are auto-discovered from your exports. +

+ +
+ + {/* Env Array */} +
+
+
+ ? +
+

+ env (optional) +

+
+

+ Environment variables required by your tools: +

+ +
+ + {/* Frameworks Array */} +
+
+
+ ? +
+

+ frameworks{' '} + (optional) +

+
+

Compatible AI frameworks:

+
+ {['vercel-ai', 'langchain', 'llamaindex', 'haystack', 'semantic-kernel'].map((fw) => ( + + {fw} + + ))} +
+
+
+ + {/* Sidebar - Schema Reference */} + +
+ ); +} + +function ExampleView(): React.ReactElement { + return ( +
+ {/* Package.json Example */} +
+
+
+ 📦 +
+
+

package.json

+

Complete TPMJS configuration

+
+
+
+
+
+
+
+
+
+ package.json +
+ +
+
+ + {/* Tool Code Example */} +
+
+
+ ⚡ +
+
+

src/index.ts

+

+ Tool implementation with Vercel AI SDK +

+
+
+
+
+
+
+
+
+
+ src/index.ts +
+ +
+
+ + {/* What Happens */} +
+
+
1️⃣
+

Publish to npm

+

+ Run npm publish to + publish your package +

+
+
+
2️⃣
+

Auto-Discovery

+

+ TPMJS detects your package and extracts tool schemas automatically +

+
+
+
3️⃣
+

Live on Registry

+

+ Your tools appear on tpmjs.com, searchable by AI agents +

+
+
); }