From 251442f1d4617ca4a692ade9c1018d7d7bc42d59 Mon Sep 17 00:00:00 2001 From: Ajax Davis Date: Mon, 1 Dec 2025 04:47:21 +1000 Subject: [PATCH] feat: add comprehensive TPMJS specification page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create /spec page with complete technical reference for TPMJS metadata - Document all three tiers (Minimal, Basic, Rich) with field explanations - Include field reference table with types and requirements - Explain quality scoring algorithm and discovery mechanisms - Add cross-links to /publish page for complementary content - Update AppHeader to include Spec link in navigation (Tools > Playground > Spec > GitHub > Publish) The spec page provides a balanced technical reference while the publish page remains the practical how-to guide. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- apps/web/src/app/spec/page.tsx | 973 ++++++++++++++++++++++++++ apps/web/src/components/AppHeader.tsx | 5 + 2 files changed, 978 insertions(+) create mode 100644 apps/web/src/app/spec/page.tsx diff --git a/apps/web/src/app/spec/page.tsx b/apps/web/src/app/spec/page.tsx new file mode 100644 index 0000000..504c39c --- /dev/null +++ b/apps/web/src/app/spec/page.tsx @@ -0,0 +1,973 @@ +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 { TPMJS_CATEGORIES } from '@tpmjs/types/tpmjs'; +import Link from 'next/link'; +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.', +}; + +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-tool 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 with three tiers of metadata. Higher tiers receive better visibility + and quality scores. +

+ + {/* Tier 1: Minimal */} +
+
+ + Tier 1: Minimal + + Required fields only +
+ + +
+
+

+ category * +

+

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

+
+ {TPMJS_CATEGORIES.map((cat) => ( + + {cat} + + ))} +
+
+ +
+

+ description * +

+

+ Clear description of what the tool does. Must be 20-500 characters. This + appears in search results and tool listings. +

+
+ +
+

+ example * +

+

+ Code example showing basic usage. Minimum 10 characters. Helps developers + understand how to use your tool. +

+
+
+ +
+
Example:
+ +
+ + +
+ + {/* Tier 2: Basic */} +
+
+ + Tier 2: Basic + + + + Parameter and return type documentation + +
+ + +
+
+

+ parameters +

+

+ Array of parameter objects describing function inputs. Each parameter has: +

+
    +
  • + name - Parameter name +
    • +
  • + type - TypeScript type +
    • +
  • + description - What it does +
    • +
  • + required - Boolean +
    • +
  • + default - Default value + (optional) +
    • +
+
+ +
+

+ returns +

+

+ Object describing the return value: +

+
    +
  • + type - Return type +
    • +
  • + description - What is returned +
    • +
+
+
+ +
+
Example:
+ +
+ + +
+ + {/* Tier 3: Rich */} +
+
+ + Tier 3: Rich + + + + Complete metadata for maximum visibility + +
+ + +
+
+

+ authentication +

+

+ Authentication requirements. Fields: +

+
    +
  • + required - Boolean +
    • +
  • + type - "api-key", "oauth", + "basic-auth", or "custom" +
    • +
  • + envVar - Environment variable + name (optional) +
    • +
  • + docsUrl - Auth documentation URL + (optional) +
    • +
+
+ +
+

+ pricing +

+

+ Pricing information. Fields: +

+
    +
  • + model - "free", "freemium", + "paid", or "enterprise" +
    • +
  • + freeLimit - Description of free + tier limits (optional) +
    • +
  • + paidUrl - Pricing page URL + (optional) +
    • +
+
+ +
+

+ frameworks +

+

+ Array of compatible AI frameworks. Supported values: +

+
+ {['vercel-ai', 'langchain', 'llamaindex', 'haystack', 'semantic-kernel'].map( + (fw) => ( + + {fw} + + ) + )} +
+
+ +
+

+ links +

+

+ External links. Optional fields: +

+
    +
  • + documentation - Full + documentation URL +
    • +
  • + playground - Interactive demo URL +
    • +
  • + repository - Source code URL +
    • +
  • + homepage - Project website +
    • +
+
+ +
+

+ tags +

+

+ Array of additional tags for searchability. Maximum 10 tags, each 2-30 + characters. +

+
+ +
+

+ status +

+

+ Tool maturity level. One of: +

+
+ {['experimental', 'beta', 'stable', 'deprecated'].map((status) => ( + + {status} + + ))} +
+
+ +
+

+ aiAgent +

+

+ AI agent integration guidance. Helps LLMs understand when and how to use + your tool: +

+
    +
  • + useCase - When to use this tool + (min 10 chars, required) +
    • +
  • + limitations - Known constraints + (optional) +
    • +
  • + examples - Array of example use + cases (optional) +
    • +
+
+
+ +
+
+ Complete Example: +
+ +
+ + +
+
+ + {/* Field Reference Table */} +
+

Field Reference

+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeTierRequiredDescription
+ category + string + + Minimal + + + Yes + Tool category from predefined list
+ description + string + + Minimal + + + Yes + Tool description (20-500 chars)
+ example + string + + Minimal + + + Yes + Usage example code (min 10 chars)
+ parameters + array + + Basic + + NoFunction parameter definitions
+ returns + object + + Basic + + NoReturn type definition
+ authentication + object + + Rich + + NoAuth requirements
+ pricing + object + + Rich + + NoPricing model and details
+ frameworks + array + + Rich + + NoCompatible AI frameworks
+ links + object + + Rich + + NoExternal resource URLs
+ tags + array + + Rich + + NoAdditional search tags (max 10)
+ status + string + + Rich + + NoMaturity level
+ aiAgent + object + + Rich + + NoAI agent integration guidance
+
+ + +
+ + {/* 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. +

+ + +
+ + +

Formula:

+ + + +
+ + {/* 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-tool 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 +
    • +
  • + Example too short: Example must be + at least 10 characters +
    • +
  • + Invalid authentication type: Type + must be "api-key", "oauth", "basic-auth", or "custom" +
    • +
  • + Too many tags: Maximum 10 tags + allowed +
    • +
  • + Invalid URL: Links must be valid + HTTP(S) URLs +
    • +
+ + +
+ + {/* Publishing Your Tool */} +
+

Publishing Your Tool

+

+ Publishing a tool to TPMJS is simple: +

+
+ + +
1️⃣
+

+ Add tpmjs-tool 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 + + + +
+
+ +
+ + {/* Footer */} +
+ +
+

+ TPMJS is an open standard. Contribute on{' '} + + GitHub + +

+
+ +
+
+ ); +} diff --git a/apps/web/src/components/AppHeader.tsx b/apps/web/src/components/AppHeader.tsx index 735eb5a..1381287 100644 --- a/apps/web/src/components/AppHeader.tsx +++ b/apps/web/src/components/AppHeader.tsx @@ -33,6 +33,11 @@ export function AppHeader(): React.ReactElement { Playground + + +