docs: update documentation to reflect auto-extraction of inputSchema
- Update spec page to show simplified required fields (category, tools) - Mark parameters, returns, aiAgent as deprecated (now auto-extracted) - Add schema extraction section explaining the process - Update publish page with simplified examples - Update FAQ with schema extraction question - Update how-it-works with validation & schema extraction step - Update docs page with auto-extraction callout and simplified spec
This commit is contained in:
Ajax Davis
parent
06271e079f
commit
70d112982e
5 changed files with 319 additions and 374 deletions
|
|
@ -841,8 +841,16 @@ while (true) {
|
|||
<DocSection id="tpmjs-spec" title="TPMJS Specification">
|
||||
<p className="text-foreground-secondary mb-6">
|
||||
The <code className="text-primary">tpmjs</code> field in package.json describes your
|
||||
tool's capabilities.
|
||||
tool. TPMJS automatically extracts parameter schemas from your tool code, so you
|
||||
only need to provide basic metadata.
|
||||
</p>
|
||||
<div className="p-4 border border-primary/30 rounded-lg bg-primary/5 mb-6">
|
||||
<p className="text-sm text-foreground-secondary">
|
||||
<strong className="text-foreground">✨ Auto Schema Extraction:</strong> Parameters
|
||||
are automatically extracted from your tool's Zod inputSchema - no need to
|
||||
document them manually!
|
||||
</p>
|
||||
</div>
|
||||
<CodeBlock
|
||||
language="json"
|
||||
code={`{
|
||||
|
|
@ -855,19 +863,7 @@ while (true) {
|
|||
"tools": [
|
||||
{
|
||||
"exportName": "myTool",
|
||||
"description": "What your tool does (20-500 chars)",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "input",
|
||||
"type": "string",
|
||||
"description": "The input to process",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"returns": {
|
||||
"type": "string",
|
||||
"description": "The processed output"
|
||||
}
|
||||
"description": "What your tool does (20-500 chars)"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -880,42 +876,39 @@ while (true) {
|
|||
</div>
|
||||
</DocSection>
|
||||
|
||||
<DocSection id="metadata-tiers" title="Metadata Tiers">
|
||||
<DocSection id="metadata-tiers" title="Metadata Fields">
|
||||
<p className="text-foreground-secondary mb-6">
|
||||
There are three tiers of metadata. Higher tiers get better visibility and quality
|
||||
scores.
|
||||
TPMJS now auto-extracts parameter schemas, simplifying what you need to provide.
|
||||
</p>
|
||||
<div className="space-y-4">
|
||||
<div className="p-4 border border-border rounded-lg bg-surface">
|
||||
<div className="flex items-center gap-2 mb-2">
|
||||
<Badge variant="outline">Tier 1: Minimal</Badge>
|
||||
<span className="text-sm text-foreground-tertiary">1x multiplier</span>
|
||||
<Badge variant="default">Required</Badge>
|
||||
</div>
|
||||
<p className="text-sm text-foreground-secondary">
|
||||
Required fields only: <code className="text-primary">category</code>,{' '}
|
||||
<code className="text-primary">description</code>,{' '}
|
||||
<code className="text-primary">exportName</code>
|
||||
<code className="text-primary">category</code>,{' '}
|
||||
<code className="text-primary">tools</code> (with{' '}
|
||||
<code className="text-primary">exportName</code> +{' '}
|
||||
<code className="text-primary">description</code>)
|
||||
</p>
|
||||
</div>
|
||||
<div className="p-4 border border-border rounded-lg bg-surface">
|
||||
<div className="flex items-center gap-2 mb-2">
|
||||
<Badge variant="default">Tier 2: Basic</Badge>
|
||||
<span className="text-sm text-foreground-tertiary">2x multiplier</span>
|
||||
<Badge variant="success">Optional</Badge>
|
||||
</div>
|
||||
<p className="text-sm text-foreground-secondary">
|
||||
+ <code className="text-primary">parameters</code> and{' '}
|
||||
<code className="text-primary">returns</code> documentation
|
||||
<code className="text-primary">env</code> (API keys),{' '}
|
||||
<code className="text-primary">frameworks</code> (compatibility)
|
||||
</p>
|
||||
</div>
|
||||
<div className="p-4 border border-border rounded-lg bg-surface">
|
||||
<div className="flex items-center gap-2 mb-2">
|
||||
<Badge variant="success">Tier 3: Rich</Badge>
|
||||
<span className="text-sm text-foreground-tertiary">4x multiplier</span>
|
||||
<Badge variant="outline">Auto-extracted</Badge>
|
||||
</div>
|
||||
<p className="text-sm text-foreground-secondary">
|
||||
+ <code className="text-primary">env</code>,{' '}
|
||||
<code className="text-primary">frameworks</code>,{' '}
|
||||
<code className="text-primary">aiAgent</code> (useCase, limitations, examples)
|
||||
<code className="text-primary">parameters</code>,{' '}
|
||||
<code className="text-primary">returns</code>,{' '}
|
||||
<code className="text-primary">aiAgent</code> - extracted from your tool code
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -1087,6 +1080,10 @@ export TPMJS_EXECUTOR_URL=https://executor.mycompany.com`}
|
|||
q: 'How long does it take for my tool to appear?',
|
||||
a: 'Tools are discovered within 2-15 minutes of publishing to npm. Make sure you have the "tpmjs-tool" keyword in your package.json.',
|
||||
},
|
||||
{
|
||||
q: 'How does schema extraction work?',
|
||||
a: "TPMJS automatically loads your tool in a sandbox and extracts the inputSchema from your Zod definition. You don't need to manually document parameters.",
|
||||
},
|
||||
{
|
||||
q: 'Is TPMJS free to use?',
|
||||
a: 'Yes! TPMJS is free for public tools. We may introduce paid tiers for private registries and enterprise features in the future.',
|
||||
|
|
@ -1099,10 +1096,6 @@ export TPMJS_EXECUTOR_URL=https://executor.mycompany.com`}
|
|||
q: 'How are tools executed?',
|
||||
a: 'Tools are dynamically loaded from esm.sh and executed in a sandboxed Deno runtime on Railway. No local installation is required.',
|
||||
},
|
||||
{
|
||||
q: 'Can I run my own TPMJS registry?',
|
||||
a: 'Yes! Set the TPMJS_API_URL and TPMJS_EXECUTOR_URL environment variables to point to your own infrastructure.',
|
||||
},
|
||||
].map((item) => (
|
||||
<div key={item.q} className="p-4 border border-border rounded-lg bg-surface">
|
||||
<h4 className="font-semibold text-foreground mb-2">{item.q}</h4>
|
||||
|
|
|
|||
|
|
@ -113,36 +113,36 @@ export default function FAQPage(): React.ReactElement {
|
|||
</code>
|
||||
</FAQItem>
|
||||
|
||||
{/* Question 3: What are the metadata tiers? */}
|
||||
<FAQItem question="What are the metadata tiers (minimal, rich)?">
|
||||
{/* Question 3: How does schema extraction work? */}
|
||||
<FAQItem question="How does automatic schema extraction work?">
|
||||
<p>
|
||||
TPMJS supports three metadata tiers, each providing different levels of detail and
|
||||
affecting your tool's quality score:
|
||||
TPMJS automatically extracts your tool's input schema (parameters) by loading
|
||||
and analyzing your tool code in a sandboxed environment. This means you don't
|
||||
need to manually document parameters in package.json.
|
||||
</p>
|
||||
<ul className="space-y-3">
|
||||
<li>
|
||||
<strong className="text-foreground">Tier 1: Minimal (1x multiplier)</strong> -
|
||||
Basic metadata with category, frameworks, and simple tool descriptions. Quick to
|
||||
set up but lower visibility.
|
||||
<strong className="text-foreground">During sync</strong> - When your package is
|
||||
discovered or updated, TPMJS loads it via esm.sh and reads the inputSchema from
|
||||
your exported tool.
|
||||
</li>
|
||||
<li>
|
||||
<strong className="text-foreground">Tier 2: Basic (2x multiplier)</strong> - Adds
|
||||
parameter and return type information, helping AI agents understand how to use
|
||||
your tool.
|
||||
<strong className="text-foreground">Schema source badge</strong> - Tool pages show
|
||||
whether the schema was "Auto-extracted" or "Author-provided"
|
||||
(fallback).
|
||||
</li>
|
||||
<li>
|
||||
<strong className="text-foreground">Tier 3: Rich (4x multiplier)</strong> - Full
|
||||
documentation including AI agent guidance, use cases, limitations, examples, and
|
||||
environment variables. Gets the best visibility and quality score.
|
||||
<strong className="text-foreground">Manual re-extraction</strong> - Users can
|
||||
trigger re-extraction from the tool page if needed.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
Higher tiers get better quality scores and more visibility in search results. Learn
|
||||
more on our{' '}
|
||||
<Link href="/publish" className="text-primary hover:underline font-medium">
|
||||
publishing guide
|
||||
</Link>
|
||||
.
|
||||
This simplifies publishing - you only need to provide category, description, and
|
||||
exportName. See our{' '}
|
||||
<Link href="/spec" className="text-primary hover:underline font-medium">
|
||||
specification
|
||||
</Link>{' '}
|
||||
for details.
|
||||
</p>
|
||||
</FAQItem>
|
||||
|
||||
|
|
|
|||
|
|
@ -98,21 +98,15 @@ export default function HowItWorksPage(): React.ReactElement {
|
|||
"frameworks": ["vercel-ai"],
|
||||
"tools": [{
|
||||
"exportName": "analyzeSentiment",
|
||||
"description": "Analyze sentiment of text",
|
||||
"parameters": [{
|
||||
"name": "text",
|
||||
"type": "string",
|
||||
"description": "Text to analyze",
|
||||
"required": true
|
||||
}],
|
||||
"returns": {
|
||||
"type": "string",
|
||||
"description": "Sentiment score"
|
||||
}
|
||||
"description": "Analyze sentiment of text and return positive/negative/neutral"
|
||||
}]
|
||||
}
|
||||
}`}
|
||||
/>
|
||||
<p className="text-sm text-foreground-secondary mt-4">
|
||||
Parameters are automatically extracted from your tool code - no need to list them
|
||||
manually!
|
||||
</p>
|
||||
</div>
|
||||
|
||||
{/* Step 2 */}
|
||||
|
|
@ -232,11 +226,13 @@ const result = await streamText({
|
|||
</div>
|
||||
</div>
|
||||
|
||||
{/* 2. Validation */}
|
||||
{/* 2. Validation & Schema Extraction */}
|
||||
<div>
|
||||
<h3 className="text-2xl font-semibold mb-4 text-foreground">2. Validation</h3>
|
||||
<h3 className="text-2xl font-semibold mb-4 text-foreground">
|
||||
2. Validation & Schema Extraction
|
||||
</h3>
|
||||
<p className="text-lg text-foreground-secondary mb-4">
|
||||
Every discovered package is validated against the TPMJS schema:
|
||||
Every discovered package is validated and its schema is automatically extracted:
|
||||
</p>
|
||||
<ul className="space-y-2 text-foreground-secondary">
|
||||
<li className="flex items-start gap-2">
|
||||
|
|
@ -249,15 +245,18 @@ const result = await streamText({
|
|||
</li>
|
||||
<li className="flex items-start gap-2">
|
||||
<span className="text-success mt-1">✓</span>
|
||||
<span>Parameters follow type schema (string, number, boolean, etc.)</span>
|
||||
<span>
|
||||
<strong className="text-foreground">inputSchema auto-extracted</strong> from
|
||||
tool code via sandboxed executor
|
||||
</span>
|
||||
</li>
|
||||
<li className="flex items-start gap-2">
|
||||
<span className="text-success mt-1">✓</span>
|
||||
<span>Environment variables properly documented</span>
|
||||
<span>Parameters derived from JSON Schema for display</span>
|
||||
</li>
|
||||
<li className="flex items-start gap-2">
|
||||
<span className="text-success mt-1">✓</span>
|
||||
<span>Supports legacy single-tool and modern multi-tool formats</span>
|
||||
<span>Fallback to author-provided parameters if extraction fails</span>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -116,100 +116,76 @@ export default function PublishPage(): React.ReactElement {
|
|||
/>
|
||||
</section>
|
||||
|
||||
{/* Step 2: Metadata Tiers */}
|
||||
{/* Step 2: Metadata */}
|
||||
<section className="mb-16">
|
||||
<h2 className="text-3xl font-bold mb-6 text-foreground">Step 2: Add TPMJS Metadata</h2>
|
||||
<p className="text-lg text-foreground-secondary mb-6">
|
||||
There are three tiers of metadata. Higher tiers get better visibility and quality
|
||||
scores.
|
||||
Add a <code className="text-foreground bg-surface px-2 py-1 rounded">tpmjs</code>{' '}
|
||||
field to your package.json. TPMJS automatically extracts parameter schemas from your
|
||||
tool code, so you only need to provide basic metadata.
|
||||
</p>
|
||||
|
||||
{/* Tier 1: Minimal */}
|
||||
<div className="mb-8 p-6 border border-border rounded-lg bg-surface">
|
||||
<div className="flex items-center gap-3 mb-4">
|
||||
<span className="px-3 py-1 bg-foreground/10 rounded text-sm font-medium text-foreground">
|
||||
Tier 1: Minimal
|
||||
</span>
|
||||
<span className="text-foreground-secondary">Required fields only</span>
|
||||
{/* Auto-extraction callout */}
|
||||
<div className="mb-8 p-6 border-2 border-primary/30 rounded-lg bg-primary/5">
|
||||
<div className="flex items-start gap-4">
|
||||
<div className="text-3xl">✨</div>
|
||||
<div>
|
||||
<h3 className="text-xl font-bold text-foreground mb-2">
|
||||
Automatic Schema Extraction
|
||||
</h3>
|
||||
<p className="text-foreground-secondary">
|
||||
TPMJS automatically extracts your tool's input schema by analyzing your
|
||||
code. You don't need to manually document parameters, returns, or AI agent
|
||||
guidance in package.json - we extract it from your Zod schema automatically.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
<CodeBlock
|
||||
language="json"
|
||||
code={`{
|
||||
"tpmjs": {
|
||||
"category": "text-analysis",
|
||||
"frameworks": ["vercel-ai"],
|
||||
"tools": [
|
||||
{
|
||||
"exportName": "myTool",
|
||||
"description": "A concise description of what your tool does"
|
||||
}
|
||||
]
|
||||
}
|
||||
}`}
|
||||
/>
|
||||
<p className="mt-4 text-sm text-foreground-secondary">
|
||||
Quality Score: <strong className="text-foreground">1x base multiplier</strong>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
{/* Tier 2: Basic */}
|
||||
{/* Minimal Example */}
|
||||
<div className="mb-8 p-6 border border-border rounded-lg bg-surface">
|
||||
<div className="flex items-center gap-3 mb-4">
|
||||
<span className="px-3 py-1 bg-primary/20 rounded text-sm font-medium text-foreground">
|
||||
Tier 2: Basic
|
||||
Required Fields
|
||||
</span>
|
||||
<span className="text-foreground-secondary">Add parameter & return info</span>
|
||||
<span className="text-foreground-secondary">All you need to provide</span>
|
||||
</div>
|
||||
<CodeBlock
|
||||
language="json"
|
||||
code={`{
|
||||
"name": "@yourname/my-awesome-tool",
|
||||
"keywords": ["tpmjs-tool"],
|
||||
"tpmjs": {
|
||||
"category": "text-analysis",
|
||||
"frameworks": ["vercel-ai"],
|
||||
"tools": [
|
||||
{
|
||||
"exportName": "sentimentAnalysisTool",
|
||||
"description": "Analyzes sentiment in text",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "text",
|
||||
"type": "string",
|
||||
"description": "The text to analyze",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "language",
|
||||
"type": "string",
|
||||
"description": "Language code (e.g., 'en')",
|
||||
"required": false,
|
||||
"default": "en"
|
||||
}
|
||||
],
|
||||
"returns": {
|
||||
"type": "SentimentResult",
|
||||
"description": "Object with score and label"
|
||||
}
|
||||
"exportName": "myTool",
|
||||
"description": "A concise description of what your tool does (20-500 chars)"
|
||||
}
|
||||
]
|
||||
}
|
||||
}`}
|
||||
/>
|
||||
<p className="mt-4 text-sm text-foreground-secondary">
|
||||
Quality Score: <strong className="text-foreground">2x base multiplier</strong>
|
||||
That's it! Parameters are automatically extracted from your tool code.
|
||||
</p>
|
||||
</div>
|
||||
|
||||
{/* Tier 3: Rich */}
|
||||
{/* With Optional Fields */}
|
||||
<div className="mb-8 p-6 border border-border rounded-lg bg-surface">
|
||||
<div className="flex items-center gap-3 mb-4">
|
||||
<span className="px-3 py-1 bg-success/20 rounded text-sm font-medium text-foreground">
|
||||
Tier 3: Rich
|
||||
With Optional Fields
|
||||
</span>
|
||||
<span className="text-foreground-secondary">
|
||||
Add env vars and framework compatibility
|
||||
</span>
|
||||
<span className="text-foreground-secondary">Full documentation</span>
|
||||
</div>
|
||||
<CodeBlock
|
||||
language="json"
|
||||
code={`{
|
||||
"name": "@yourname/sentiment-tool",
|
||||
"keywords": ["tpmjs-tool"],
|
||||
"tpmjs": {
|
||||
"category": "text-analysis",
|
||||
"frameworks": ["vercel-ai", "langchain"],
|
||||
|
|
@ -223,24 +199,15 @@ export default function PublishPage(): React.ReactElement {
|
|||
"tools": [
|
||||
{
|
||||
"exportName": "sentimentAnalysisTool",
|
||||
"description": "Advanced sentiment analysis with emotion detection",
|
||||
"parameters": [...],
|
||||
"returns": {...},
|
||||
"aiAgent": {
|
||||
"useCase": "Use when users need to analyze sentiment or detect emotions",
|
||||
"limitations": "English and Spanish only. Max 10,000 characters",
|
||||
"examples": [
|
||||
"Analyze customer review sentiment",
|
||||
"Detect emotions in feedback"
|
||||
]
|
||||
}
|
||||
"description": "Advanced sentiment analysis with emotion detection"
|
||||
}
|
||||
]
|
||||
}
|
||||
}`}
|
||||
/>
|
||||
<p className="mt-4 text-sm text-foreground-secondary">
|
||||
Quality Score: <strong className="text-foreground">4x base multiplier</strong> 🚀
|
||||
Add <code className="text-foreground">env</code> for API keys and{' '}
|
||||
<code className="text-foreground">frameworks</code> for compatibility info.
|
||||
</p>
|
||||
</div>
|
||||
</section>
|
||||
|
|
@ -341,30 +308,16 @@ npm publish --access public
|
|||
"tools": [
|
||||
{
|
||||
"exportName": "createBlogPostTool",
|
||||
"description": "Creates structured blog posts with frontmatter and SEO metadata",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "title",
|
||||
"type": "string",
|
||||
"description": "The title of the blog post",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "content",
|
||||
"type": "string",
|
||||
"description": "The main content",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"returns": {
|
||||
"type": "BlogPost",
|
||||
"description": "Structured blog post with frontmatter"
|
||||
}
|
||||
"description": "Creates structured blog posts with frontmatter and SEO metadata"
|
||||
}
|
||||
]
|
||||
}
|
||||
}`}
|
||||
/>
|
||||
<p className="mt-4 text-sm text-foreground-secondary">
|
||||
Note: Parameters are automatically extracted from the tool code - no need to list them
|
||||
in package.json!
|
||||
</p>
|
||||
</section>
|
||||
|
||||
{/* Tips */}
|
||||
|
|
@ -378,9 +331,9 @@ npm publish --access public
|
|||
desc: 'Make your package name clear and searchable',
|
||||
},
|
||||
{
|
||||
icon: '📊',
|
||||
title: 'Complete metadata',
|
||||
desc: 'Rich tier tools get 4x better visibility',
|
||||
icon: '✨',
|
||||
title: 'Good Zod schemas',
|
||||
desc: 'Add descriptions to your Zod schema fields - they get auto-extracted',
|
||||
},
|
||||
{
|
||||
icon: '📚',
|
||||
|
|
@ -393,9 +346,9 @@ npm publish --access public
|
|||
desc: 'Regular updates boost download counts',
|
||||
},
|
||||
{
|
||||
icon: '🤖',
|
||||
title: 'AI-friendly descriptions',
|
||||
desc: 'Write aiAgent.useCase as guidance for AI agents',
|
||||
icon: '🔑',
|
||||
title: 'Document env vars',
|
||||
desc: 'List required API keys in the env field so users know what they need',
|
||||
},
|
||||
].map((tip) => (
|
||||
<div
|
||||
|
|
|
|||
|
|
@ -114,17 +114,54 @@ export default function SpecPage(): React.ReactElement {
|
|||
<p className="text-lg text-foreground-secondary mb-8">
|
||||
The TPMJS specification defines a{' '}
|
||||
<code className="text-foreground bg-surface px-2 py-1 rounded">tpmjs</code> field in
|
||||
package.json with three tiers of metadata. Higher tiers receive better visibility and
|
||||
quality scores.
|
||||
package.json. TPMJS automatically extracts parameter schemas from your tool code, so
|
||||
you only need to provide basic metadata.
|
||||
</p>
|
||||
|
||||
{/* Tier 1: Minimal */}
|
||||
{/* Auto-extraction callout */}
|
||||
<div className="mb-12 p-6 border-2 border-primary/30 rounded-lg bg-primary/5">
|
||||
<div className="flex items-start gap-4">
|
||||
<div className="text-3xl">✨</div>
|
||||
<div>
|
||||
<h3 className="text-xl font-bold text-foreground mb-2">
|
||||
Automatic Schema Extraction
|
||||
</h3>
|
||||
<p className="text-foreground-secondary mb-4">
|
||||
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.
|
||||
</p>
|
||||
<div className="grid md:grid-cols-3 gap-4 text-sm">
|
||||
<div className="p-3 bg-background rounded border border-border">
|
||||
<strong className="text-foreground">inputSchema</strong>
|
||||
<p className="text-foreground-secondary mt-1">
|
||||
Auto-extracted from your Zod schema
|
||||
</p>
|
||||
</div>
|
||||
<div className="p-3 bg-background rounded border border-border">
|
||||
<strong className="text-foreground">parameters</strong>
|
||||
<p className="text-foreground-secondary mt-1">
|
||||
Derived from inputSchema automatically
|
||||
</p>
|
||||
</div>
|
||||
<div className="p-3 bg-background rounded border border-border">
|
||||
<strong className="text-foreground">Tool page</strong>
|
||||
<p className="text-foreground-secondary mt-1">
|
||||
Shows extracted schema with source badge
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Required Fields */}
|
||||
<div className="mb-12">
|
||||
<div className="flex items-center gap-3 mb-4">
|
||||
<Badge variant="outline" size="lg">
|
||||
Tier 1: Minimal
|
||||
<Badge variant="default" size="lg">
|
||||
Required Fields
|
||||
</Badge>
|
||||
<span className="text-foreground-secondary">Required fields only</span>
|
||||
<span className="text-foreground-secondary">What you need to provide</span>
|
||||
</div>
|
||||
<Card>
|
||||
<CardContent className="pt-6">
|
||||
|
|
@ -147,23 +184,33 @@ export default function SpecPage(): React.ReactElement {
|
|||
|
||||
<div>
|
||||
<h4 className="text-lg font-semibold text-foreground mb-2">
|
||||
<code>description</code> <span className="text-red-500">*</span>
|
||||
<code>tools</code> <span className="text-red-500">*</span>
|
||||
</h4>
|
||||
<p className="text-sm text-foreground-secondary">
|
||||
Clear description of what the tool does. Must be 20-500 characters. This
|
||||
appears in search results and tool listings.
|
||||
<p className="text-sm text-foreground-secondary mb-3">
|
||||
Array of tools exported by your package. Each tool needs:
|
||||
</p>
|
||||
<ul className="list-disc list-inside space-y-1 text-sm text-foreground-secondary ml-4">
|
||||
<li>
|
||||
<code className="text-foreground">exportName</code> - The exported
|
||||
function name (required)
|
||||
</li>
|
||||
<li>
|
||||
<code className="text-foreground">description</code> - What the tool does,
|
||||
20-500 chars (required)
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="mt-6">
|
||||
<h5 className="text-sm font-semibold text-foreground mb-3">Example:</h5>
|
||||
<h5 className="text-sm font-semibold text-foreground mb-3">Minimal Example:</h5>
|
||||
<CodeBlock
|
||||
language="json"
|
||||
code={`{
|
||||
"name": "@yourname/my-tool",
|
||||
"keywords": ["tpmjs-tool"],
|
||||
"tpmjs": {
|
||||
"category": "text-analysis",
|
||||
"frameworks": ["vercel-ai"],
|
||||
"tools": [
|
||||
{
|
||||
"exportName": "sentimentAnalysisTool",
|
||||
|
|
@ -173,118 +220,23 @@ export default function SpecPage(): React.ReactElement {
|
|||
}
|
||||
}`}
|
||||
/>
|
||||
<p className="text-sm text-foreground-secondary mt-4">
|
||||
That's it! TPMJS will automatically extract the inputSchema from your
|
||||
tool when it syncs.
|
||||
</p>
|
||||
</div>
|
||||
</CardContent>
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
{/* Tier 2: Basic */}
|
||||
<div className="mb-12">
|
||||
<div className="flex items-center gap-3 mb-4">
|
||||
<Badge variant="default" size="lg">
|
||||
Tier 2: Basic
|
||||
</Badge>
|
||||
<span className="text-foreground-secondary">
|
||||
+ Parameter and return type documentation
|
||||
</span>
|
||||
</div>
|
||||
<Card>
|
||||
<CardContent className="pt-6">
|
||||
<div className="space-y-6">
|
||||
<div>
|
||||
<h4 className="text-lg font-semibold text-foreground mb-2">
|
||||
<code>parameters</code>
|
||||
</h4>
|
||||
<p className="text-sm text-foreground-secondary mb-3">
|
||||
Array of parameter objects describing function inputs. Each parameter has:
|
||||
</p>
|
||||
<ul className="list-disc list-inside space-y-1 text-sm text-foreground-secondary ml-4">
|
||||
<li>
|
||||
<code className="text-foreground">name</code> - Parameter name
|
||||
</li>
|
||||
<li>
|
||||
<code className="text-foreground">type</code> - TypeScript type
|
||||
</li>
|
||||
<li>
|
||||
<code className="text-foreground">description</code> - What it does
|
||||
</li>
|
||||
<li>
|
||||
<code className="text-foreground">required</code> - Boolean
|
||||
</li>
|
||||
<li>
|
||||
<code className="text-foreground">default</code> - Default value
|
||||
(optional)
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<h4 className="text-lg font-semibold text-foreground mb-2">
|
||||
<code>returns</code>
|
||||
</h4>
|
||||
<p className="text-sm text-foreground-secondary mb-3">
|
||||
Object describing the return value:
|
||||
</p>
|
||||
<ul className="list-disc list-inside space-y-1 text-sm text-foreground-secondary ml-4">
|
||||
<li>
|
||||
<code className="text-foreground">type</code> - Return type
|
||||
</li>
|
||||
<li>
|
||||
<code className="text-foreground">description</code> - What is returned
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="mt-6">
|
||||
<h5 className="text-sm font-semibold text-foreground mb-3">Example:</h5>
|
||||
<CodeBlock
|
||||
language="json"
|
||||
code={`{
|
||||
"tpmjs": {
|
||||
"category": "text-analysis",
|
||||
"frameworks": ["vercel-ai"],
|
||||
"tools": [
|
||||
{
|
||||
"exportName": "sentimentAnalysisTool",
|
||||
"description": "Analyzes sentiment in text",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "text",
|
||||
"type": "string",
|
||||
"description": "The text to analyze",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"name": "language",
|
||||
"type": "string",
|
||||
"description": "Language code (e.g., 'en', 'es')",
|
||||
"required": false,
|
||||
"default": "en"
|
||||
}
|
||||
],
|
||||
"returns": {
|
||||
"type": "SentimentResult",
|
||||
"description": "Object with score (-1 to 1) and label (positive/negative/neutral)"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}`}
|
||||
/>
|
||||
</div>
|
||||
</CardContent>
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
{/* Tier 3: Rich */}
|
||||
{/* Optional Fields */}
|
||||
<div className="mb-12">
|
||||
<div className="flex items-center gap-3 mb-4">
|
||||
<Badge variant="success" size="lg">
|
||||
Tier 3: Rich
|
||||
Optional Fields
|
||||
</Badge>
|
||||
<span className="text-foreground-secondary">
|
||||
+ Complete metadata for maximum visibility
|
||||
Additional metadata for better visibility
|
||||
</span>
|
||||
</div>
|
||||
<Card>
|
||||
|
|
@ -310,10 +262,6 @@ export default function SpecPage(): React.ReactElement {
|
|||
<code className="text-foreground">required</code> - Boolean (defaults to
|
||||
true)
|
||||
</li>
|
||||
<li>
|
||||
<code className="text-foreground">default</code> - Default value if not
|
||||
provided (optional)
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
|
|
@ -338,39 +286,17 @@ export default function SpecPage(): React.ReactElement {
|
|||
))}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<h4 className="text-lg font-semibold text-foreground mb-2">
|
||||
<code>aiAgent</code>
|
||||
</h4>
|
||||
<p className="text-sm text-foreground-secondary mb-2">
|
||||
AI agent integration guidance. Helps LLMs understand when and how to use
|
||||
your tool:
|
||||
</p>
|
||||
<ul className="list-disc list-inside space-y-1 text-sm text-foreground-secondary ml-4">
|
||||
<li>
|
||||
<code className="text-foreground">useCase</code> - When to use this tool
|
||||
(min 10 chars, required)
|
||||
</li>
|
||||
<li>
|
||||
<code className="text-foreground">limitations</code> - Known constraints
|
||||
(optional)
|
||||
</li>
|
||||
<li>
|
||||
<code className="text-foreground">examples</code> - Array of example use
|
||||
cases (optional)
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="mt-6">
|
||||
<h5 className="text-sm font-semibold text-foreground mb-3">
|
||||
Complete Example:
|
||||
Complete Example with Optional Fields:
|
||||
</h5>
|
||||
<CodeBlock
|
||||
language="json"
|
||||
code={`{
|
||||
"name": "@yourname/sentiment-tool",
|
||||
"keywords": ["tpmjs-tool"],
|
||||
"tpmjs": {
|
||||
"category": "text-analysis",
|
||||
"frameworks": ["vercel-ai", "langchain"],
|
||||
|
|
@ -384,17 +310,7 @@ export default function SpecPage(): React.ReactElement {
|
|||
"tools": [
|
||||
{
|
||||
"exportName": "sentimentAnalysisTool",
|
||||
"description": "Advanced sentiment analysis with emotion detection",
|
||||
"parameters": [...],
|
||||
"returns": {...},
|
||||
"aiAgent": {
|
||||
"useCase": "Use when users need to analyze sentiment or detect emotions in text",
|
||||
"limitations": "English and Spanish only. Max 10,000 characters per request.",
|
||||
"examples": [
|
||||
"Analyze customer review sentiment",
|
||||
"Detect emotions in user feedback"
|
||||
]
|
||||
}
|
||||
"description": "Advanced sentiment analysis with emotion detection"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -404,6 +320,106 @@ export default function SpecPage(): React.ReactElement {
|
|||
</CardContent>
|
||||
</Card>
|
||||
</div>
|
||||
|
||||
{/* Deprecated Fields */}
|
||||
<div className="mb-12">
|
||||
<div className="flex items-center gap-3 mb-4">
|
||||
<Badge variant="outline" size="lg">
|
||||
Deprecated
|
||||
</Badge>
|
||||
<span className="text-foreground-secondary">
|
||||
Now auto-extracted (kept for backward compatibility)
|
||||
</span>
|
||||
</div>
|
||||
<Card>
|
||||
<CardContent className="pt-6">
|
||||
<p className="text-foreground-secondary mb-4">
|
||||
The following fields are now automatically extracted from your tool code. You no
|
||||
longer need to specify them manually:
|
||||
</p>
|
||||
<ul className="space-y-3 text-sm text-foreground-secondary">
|
||||
<li className="flex items-start gap-2">
|
||||
<code className="text-foreground bg-surface px-2 py-1 rounded">
|
||||
parameters
|
||||
</code>
|
||||
<span>→ Auto-extracted from tool's Zod inputSchema</span>
|
||||
</li>
|
||||
<li className="flex items-start gap-2">
|
||||
<code className="text-foreground bg-surface px-2 py-1 rounded">returns</code>
|
||||
<span>→ Auto-extracted from tool definition</span>
|
||||
</li>
|
||||
<li className="flex items-start gap-2">
|
||||
<code className="text-foreground bg-surface px-2 py-1 rounded">aiAgent</code>
|
||||
<span>→ Auto-extracted from tool metadata</span>
|
||||
</li>
|
||||
</ul>
|
||||
<p className="text-foreground-secondary mt-4 text-sm">
|
||||
If auto-extraction fails, TPMJS will fall back to any manually provided values.
|
||||
</p>
|
||||
</CardContent>
|
||||
</Card>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
{/* Schema Extraction */}
|
||||
<section className="mb-16">
|
||||
<h2 className="text-3xl font-bold mb-6 text-foreground">Schema Extraction</h2>
|
||||
<p className="text-lg text-foreground-secondary mb-6">
|
||||
When TPMJS syncs your package, it automatically extracts your tool's inputSchema
|
||||
by loading and inspecting your tool in a sandboxed environment.
|
||||
</p>
|
||||
<div className="grid grid-cols-1 md:grid-cols-3 gap-6 mb-8">
|
||||
<Card>
|
||||
<CardHeader>
|
||||
<div className="text-3xl mb-2">🔄</div>
|
||||
<CardTitle>During Sync</CardTitle>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
<p className="text-sm text-foreground-secondary">
|
||||
Schema is extracted automatically when your package is discovered or updated
|
||||
</p>
|
||||
</CardContent>
|
||||
</Card>
|
||||
|
||||
<Card>
|
||||
<CardHeader>
|
||||
<div className="text-3xl mb-2">🏷️</div>
|
||||
<CardTitle>Source Badge</CardTitle>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
<p className="text-sm text-foreground-secondary">
|
||||
Tool pages show whether schema was "Auto-extracted" or
|
||||
"Author-provided"
|
||||
</p>
|
||||
</CardContent>
|
||||
</Card>
|
||||
|
||||
<Card>
|
||||
<CardHeader>
|
||||
<div className="text-3xl mb-2">🔁</div>
|
||||
<CardTitle>Manual Re-extract</CardTitle>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
<p className="text-sm text-foreground-secondary">
|
||||
Users can trigger re-extraction from the tool page if needed
|
||||
</p>
|
||||
</CardContent>
|
||||
</Card>
|
||||
</div>
|
||||
<Card>
|
||||
<CardContent className="pt-6">
|
||||
<h4 className="text-sm font-semibold text-foreground mb-3">How It Works:</h4>
|
||||
<ol className="space-y-2 text-sm text-foreground-secondary list-decimal list-inside">
|
||||
<li>Your tool is loaded in a Deno sandbox via esm.sh</li>
|
||||
<li>
|
||||
The <code className="text-foreground">inputSchema</code> property is read from
|
||||
your exported tool
|
||||
</li>
|
||||
<li>The JSON Schema is stored in our database</li>
|
||||
<li>Parameters are derived from the schema for display</li>
|
||||
</ol>
|
||||
</CardContent>
|
||||
</Card>
|
||||
</section>
|
||||
|
||||
{/* Field Reference Table */}
|
||||
|
|
@ -417,7 +433,6 @@ export default function SpecPage(): React.ReactElement {
|
|||
<tr className="border-b border-border">
|
||||
<th className="text-left py-3 px-4 text-foreground">Field</th>
|
||||
<th className="text-left py-3 px-4 text-foreground">Type</th>
|
||||
<th className="text-left py-3 px-4 text-foreground">Tier</th>
|
||||
<th className="text-left py-3 px-4 text-foreground">Required</th>
|
||||
<th className="text-left py-3 px-4 text-foreground">Description</th>
|
||||
</tr>
|
||||
|
|
@ -428,11 +443,6 @@ export default function SpecPage(): React.ReactElement {
|
|||
<code className="text-foreground">category</code>
|
||||
</td>
|
||||
<td className="py-3 px-4">string</td>
|
||||
<td className="py-3 px-4">
|
||||
<Badge variant="outline" size="sm">
|
||||
Minimal
|
||||
</Badge>
|
||||
</td>
|
||||
<td className="py-3 px-4">
|
||||
<span className="text-red-500">Yes</span>
|
||||
</td>
|
||||
|
|
@ -440,55 +450,21 @@ export default function SpecPage(): React.ReactElement {
|
|||
</tr>
|
||||
<tr className="border-b border-border">
|
||||
<td className="py-3 px-4">
|
||||
<code className="text-foreground">description</code>
|
||||
</td>
|
||||
<td className="py-3 px-4">string</td>
|
||||
<td className="py-3 px-4">
|
||||
<Badge variant="outline" size="sm">
|
||||
Minimal
|
||||
</Badge>
|
||||
</td>
|
||||
<td className="py-3 px-4">
|
||||
<span className="text-red-500">Yes</span>
|
||||
</td>
|
||||
<td className="py-3 px-4">Tool description (20-500 chars)</td>
|
||||
</tr>
|
||||
<tr className="border-b border-border">
|
||||
<td className="py-3 px-4">
|
||||
<code className="text-foreground">parameters</code>
|
||||
<code className="text-foreground">tools</code>
|
||||
</td>
|
||||
<td className="py-3 px-4">array</td>
|
||||
<td className="py-3 px-4">
|
||||
<Badge variant="default" size="sm">
|
||||
Basic
|
||||
</Badge>
|
||||
<span className="text-red-500">Yes</span>
|
||||
</td>
|
||||
<td className="py-3 px-4">No</td>
|
||||
<td className="py-3 px-4">Function parameter definitions</td>
|
||||
</tr>
|
||||
<tr className="border-b border-border">
|
||||
<td className="py-3 px-4">
|
||||
<code className="text-foreground">returns</code>
|
||||
Array of tool definitions (exportName + description)
|
||||
</td>
|
||||
<td className="py-3 px-4">object</td>
|
||||
<td className="py-3 px-4">
|
||||
<Badge variant="default" size="sm">
|
||||
Basic
|
||||
</Badge>
|
||||
</td>
|
||||
<td className="py-3 px-4">No</td>
|
||||
<td className="py-3 px-4">Return type definition</td>
|
||||
</tr>
|
||||
<tr className="border-b border-border">
|
||||
<td className="py-3 px-4">
|
||||
<code className="text-foreground">env</code>
|
||||
</td>
|
||||
<td className="py-3 px-4">array</td>
|
||||
<td className="py-3 px-4">
|
||||
<Badge variant="success" size="sm">
|
||||
Rich
|
||||
</Badge>
|
||||
</td>
|
||||
<td className="py-3 px-4">No</td>
|
||||
<td className="py-3 px-4">Required environment variables</td>
|
||||
</tr>
|
||||
|
|
@ -497,26 +473,50 @@ export default function SpecPage(): React.ReactElement {
|
|||
<code className="text-foreground">frameworks</code>
|
||||
</td>
|
||||
<td className="py-3 px-4">array</td>
|
||||
<td className="py-3 px-4">
|
||||
<Badge variant="success" size="sm">
|
||||
Rich
|
||||
</Badge>
|
||||
</td>
|
||||
<td className="py-3 px-4">No</td>
|
||||
<td className="py-3 px-4">Compatible AI frameworks</td>
|
||||
</tr>
|
||||
<tr className="border-b border-border">
|
||||
<tr className="border-b border-border bg-surface/50">
|
||||
<td className="py-3 px-4">
|
||||
<code className="text-foreground">aiAgent</code>
|
||||
<code className="text-foreground-tertiary">parameters</code>
|
||||
</td>
|
||||
<td className="py-3 px-4">object</td>
|
||||
<td className="py-3 px-4 text-foreground-tertiary">array</td>
|
||||
<td className="py-3 px-4">
|
||||
<Badge variant="success" size="sm">
|
||||
Rich
|
||||
<Badge variant="outline" size="sm">
|
||||
Deprecated
|
||||
</Badge>
|
||||
</td>
|
||||
<td className="py-3 px-4">No</td>
|
||||
<td className="py-3 px-4">AI agent integration guidance</td>
|
||||
<td className="py-3 px-4 text-foreground-tertiary">
|
||||
Auto-extracted from tool
|
||||
</td>
|
||||
</tr>
|
||||
<tr className="border-b border-border bg-surface/50">
|
||||
<td className="py-3 px-4">
|
||||
<code className="text-foreground-tertiary">returns</code>
|
||||
</td>
|
||||
<td className="py-3 px-4 text-foreground-tertiary">object</td>
|
||||
<td className="py-3 px-4">
|
||||
<Badge variant="outline" size="sm">
|
||||
Deprecated
|
||||
</Badge>
|
||||
</td>
|
||||
<td className="py-3 px-4 text-foreground-tertiary">
|
||||
Auto-extracted from tool
|
||||
</td>
|
||||
</tr>
|
||||
<tr className="border-b border-border bg-surface/50">
|
||||
<td className="py-3 px-4">
|
||||
<code className="text-foreground-tertiary">aiAgent</code>
|
||||
</td>
|
||||
<td className="py-3 px-4 text-foreground-tertiary">object</td>
|
||||
<td className="py-3 px-4">
|
||||
<Badge variant="outline" size="sm">
|
||||
Deprecated
|
||||
</Badge>
|
||||
</td>
|
||||
<td className="py-3 px-4 text-foreground-tertiary">
|
||||
Auto-extracted from tool
|
||||
</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue