diff --git a/TPMJS_FEATURES.md b/TPMJS_FEATURES.md new file mode 100644 index 0000000..1deeef4 --- /dev/null +++ b/TPMJS_FEATURES.md @@ -0,0 +1,698 @@ +# TPMJS Platform - Complete Feature Documentation + +A comprehensive overview of all TPMJS functionality for marketing, fundraising, and pet project ideation. + +--- + +## Table of Contents + +1. [Platform Overview](#platform-overview) +2. [Core Architecture](#core-architecture) +3. [Tool Registry & Discovery](#tool-registry--discovery) +4. [Tool Execution System](#tool-execution-system) +5. [MCP (Model Context Protocol) Implementation](#mcp-model-context-protocol-implementation) +6. [Collections System](#collections-system) +7. [Agent System](#agent-system) +8. [API Endpoints](#api-endpoints) +9. [SDK & Packages](#sdk--packages) +10. [Security & Privacy](#security--privacy) +11. [Infrastructure](#infrastructure) +12. [Use Cases](#use-cases) +13. [Competitive Advantages](#competitive-advantages) + +--- + +## Platform Overview + +**TPMJS (Tool Package Manager for JavaScript)** is an open platform for discovering, sharing, and executing AI tools via the Model Context Protocol (MCP). Think of it as "npm for AI tools" - a registry where developers can publish tools that AI assistants can use. + +### Key Value Propositions + +1. **Unified Tool Registry** - One place to discover and use AI tools +2. **Instant MCP Servers** - Any collection becomes an MCP-compatible server +3. **Secure Execution** - Sandboxed tool execution with rate limiting +4. **AI Agent Infrastructure** - Build multi-turn conversational agents with tool access +5. **Developer-Friendly** - Publish tools via npm, use via standard protocols + +--- + +## Core Architecture + +### Tech Stack + +| Layer | Technology | +|-------|------------| +| Frontend | Next.js 16 (App Router), React 19, Tailwind CSS | +| Backend | Next.js API Routes (Serverless) | +| Database | PostgreSQL (Neon) with Prisma ORM | +| Auth | NextAuth.js (GitHub OAuth) | +| Hosting | Vercel (Edge + Serverless) | +| Package Registry | npm (mirrored) | +| Build System | Turborepo + pnpm workspaces | + +### Monorepo Structure + +``` +tpmjs/ +├── apps/ +│ ├── web/ # Main Next.js application (tpmjs.com) +│ └── playground/ # Interactive tool testing environment +├── packages/ +│ ├── @tpmjs/types # Shared TypeScript types & Zod schemas +│ ├── @tpmjs/ui # React component library +│ ├── @tpmjs/utils # Utility functions +│ ├── @tpmjs/env # Environment variable validation +│ ├── @tpmjs/db # Prisma database client +│ ├── @tpmjs/mocks # MSW mock server for testing +│ └── @tpmjs/config # Shared configs (ESLint, Tailwind, TypeScript) +└── templates/ + └── vercel-executor/ # Template for deploying tool executors +``` + +--- + +## Tool Registry & Discovery + +### What is a TPMJS Tool? + +A TPMJS tool is an npm package with: +1. The `tpmjs` keyword in package.json +2. A `tpmjs` field defining the tool's MCP schema + +```json +{ + "name": "my-awesome-tool", + "keywords": ["tpmjs"], + "tpmjs": { + "name": "my-tool", + "description": "Does awesome things", + "inputSchema": { + "type": "object", + "properties": { + "query": { "type": "string" } + }, + "required": ["query"] + } + } +} +``` + +### Tool Tiers + +| Tier | Description | Features | +|------|-------------|----------| +| **Minimal** | Basic tool definition | Name, description, input schema only | +| **Rich** | Full-featured tool | Executor URL, examples, categories, tags | + +### Discovery Methods + +1. **npm Changes Feed Sync** (every 2 minutes) + - Monitors npm's real-time changes feed + - Catches new packages and updates instantly + - Processes ~100 changes per run + +2. **Keyword Search Sync** (every 15 minutes) + - Actively searches npm for `tpmjs` keyword + - Backfills any missed packages + - Processes up to 250 packages per run + +3. **Metrics Sync** (hourly) + - Updates download statistics + - Calculates quality scores + - Refreshes ranking data + +### Quality Scoring Algorithm + +``` +Quality Score = Tier Score + Downloads Score + Stars Score + +Where: +- Tier Score: rich = 0.6, minimal = 0.4 +- Downloads Score: min(0.3, log10(downloads + 1) / 10) +- Stars Score: min(0.1, log10(githubStars + 1) / 10) +``` + +### Tool Categories + +- AI/ML +- Development Tools +- Data Processing +- Web Scraping +- APIs & Integrations +- Utilities +- And more... + +### Current Registry Stats + +- **170+ Official Tools** in the ajax-collection +- **Growing Community Tools** published by developers +- **Real-time Sync** with npm registry + +--- + +## Tool Execution System + +### Execution Flow + +``` +User Request → TPMJS API → Executor Selection → Sandboxed Execution → Response +``` + +### Executor Types + +1. **HTTP Executor** - Calls external HTTP endpoints +2. **Serverless Executor** - Runs in Vercel Edge/Serverless +3. **Code Executor** - Executes arbitrary code in sandbox + +### Sandboxing Features + +- **Network Isolation** - Zero-trust or semi-trusted modes +- **Timeout Limits** - Configurable per-tool (1-900 seconds) +- **Resource Limits** - Memory and CPU constraints +- **Input Validation** - Zod schema validation + +### Executor Template + +The `templates/vercel-executor/` provides a ready-to-deploy executor: + +```typescript +// Example executor implementation +export async function POST(request: Request) { + const { tool, input } = await request.json(); + + // Validate input against schema + const validated = toolSchema.parse(input); + + // Execute tool logic + const result = await executeTool(tool, validated); + + return Response.json(result); +} +``` + +### Code Execution (via MCP Tool) + +The platform includes a powerful code execution tool: + +```javascript +// Execute code in 42+ languages +{ + "language": "python", + "code": "print('Hello, World!')", + "network_mode": "zerotrust", // or "semitrusted" + "ttl": 60 // timeout in seconds +} +``` + +Supported languages include: +- Python, JavaScript, TypeScript +- Go, Rust, C, C++ +- Ruby, PHP, Perl +- Java, Kotlin, Scala +- And 30+ more + +--- + +## MCP (Model Context Protocol) Implementation + +### What is MCP? + +MCP is an open protocol for AI assistants to interact with tools. TPMJS provides: +- **MCP Server Hosting** - Every collection is an MCP server +- **Multiple Transports** - HTTP and SSE support +- **Standard Compliance** - Full MCP specification support + +### Transport Options + +#### HTTP Transport +``` +POST /api/mcp/{username}/{collection-slug}/http +Content-Type: application/json + +{"jsonrpc": "2.0", "id": 1, "method": "tools/list"} +``` + +#### SSE Transport +``` +POST /api/mcp/{username}/{collection-slug}/sse +Content-Type: application/json + +{"jsonrpc": "2.0", "id": 1, "method": "initialize"} +``` + +### MCP Methods Supported + +| Method | Description | +|--------|-------------| +| `initialize` | Initialize MCP session | +| `tools/list` | List available tools | +| `tools/call` | Execute a tool | +| `resources/list` | List available resources | +| `resources/read` | Read a resource | +| `prompts/list` | List available prompts | +| `prompts/get` | Get a specific prompt | + +### Authentication + +- **API Key Auth** - Bearer token in Authorization header +- **Session Auth** - Cookie-based for web users +- **Scopes** - Granular permission control + - `mcp:access` - Access MCP endpoints + - `mcp:execute` - Execute tools + - `tools:read` - List tools + - `tools:execute` - Execute specific tools + - `collections:read` - Access collections + +### Integration Examples + +#### Claude Desktop +```json +{ + "mcpServers": { + "tpmjs": { + "command": "npx", + "args": ["-y", "@anthropic/mcp-remote", + "https://tpmjs.com/api/mcp/ajax/ajax-collection/sse"] + } + } +} +``` + +#### Cursor IDE +```json +{ + "mcpServers": { + "tpmjs": { + "url": "https://tpmjs.com/api/mcp/ajax/ajax-collection/sse" + } + } +} +``` + +--- + +## Collections System + +### What are Collections? + +Collections are curated groups of tools that form an MCP server. Users can: +- Create public or private collections +- Add tools from the registry +- Share collections as MCP endpoints + +### Collection Features + +- **Custom Naming** - Unique slug per user +- **Tool Curation** - Add/remove tools +- **Access Control** - Public or private +- **MCP Endpoint** - Automatic server generation + +### Collection API + +```typescript +// Create collection +POST /api/collections +{ "name": "My Tools", "slug": "my-tools", "isPublic": true } + +// Add tool to collection +POST /api/collections/{id}/tools +{ "toolId": "tool-123" } + +// Get collection's MCP endpoint +GET /api/mcp/{username}/{collection-slug}/http +``` + +--- + +## Agent System + +### What are TPMJS Agents? + +Agents are AI-powered conversational interfaces with access to TPMJS tools. They enable: +- Multi-turn conversations +- Tool execution within context +- Custom system prompts +- Provider flexibility (OpenAI, Anthropic, etc.) + +### Agent Configuration + +```typescript +interface Agent { + id: string; + uid: string; // Unique identifier + name: string; + description?: string; + provider: "OPENAI" | "ANTHROPIC" | "GOOGLE"; + modelId: string; // e.g., "gpt-4o-mini" + systemPrompt?: string; + isPublic: boolean; + tools: Tool[]; // Attached tools +} +``` + +### Agent Features + +1. **Multi-Turn Conversations** + - Persistent chat history + - Context-aware responses + - Tool execution in conversation + +2. **Provider Flexibility** + - OpenAI (GPT-4, GPT-4o-mini) + - Anthropic (Claude) + - Google (Gemini) + - Custom providers + +3. **Tool Integration** + - Attach any TPMJS tool + - Automatic tool calling + - Result injection into context + +4. **Public Chat Pages** + - Share agents via public URL + - Embeddable chat interfaces + - No auth required for public agents + +### Agent API + +```typescript +// Create agent +POST /api/agents +{ "name": "My Agent", "provider": "OPENAI", "modelId": "gpt-4o-mini" } + +// Chat with agent +POST /api/agents/{id}/chat +{ "messages": [{"role": "user", "content": "Hello!"}] } + +// Stream response +POST /api/agents/{id}/chat +{ "messages": [...], "stream": true } +``` + +--- + +## API Endpoints + +### Public Endpoints (No Auth) + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/health` | GET | Health check with build info | +| `/api/stats` | GET | Platform statistics | +| `/api/stats/health` | GET | Tool health metrics | +| `/api/tools` | GET | List public tools | +| `/api/tools/{id}` | GET | Get tool details | +| `/api/tools/search` | GET | Search tools | +| `/api/collections/public` | GET | List public collections | + +### Authenticated Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/user` | GET | Current user profile | +| `/api/user/settings` | PATCH | Update user settings | +| `/api/user/api-keys` | GET/POST | Manage API keys | +| `/api/agents` | CRUD | Agent management | +| `/api/collections` | CRUD | Collection management | + +### MCP Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/mcp/{user}/{collection}/http` | POST | HTTP transport | +| `/api/mcp/{user}/{collection}/sse` | POST | SSE transport | +| `/api/mcp/{user}/{collection}/http` | GET | Server info | + +### Sync Endpoints (Cron) + +| Endpoint | Schedule | Description | +|----------|----------|-------------| +| `/api/sync/changes` | */2 * * * * | npm changes feed | +| `/api/sync/keyword` | */15 * * * * | Keyword search | +| `/api/sync/metrics` | 0 * * * * | Metrics update | + +### Tool Execution + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/tools/{id}/execute` | POST | Execute a tool | +| `/api/execute/code` | POST | Execute code (sandbox) | + +--- + +## SDK & Packages + +### Published npm Packages + +| Package | Description | +|---------|-------------| +| `@tpmjs/types` | TypeScript types and Zod schemas | +| `@tpmjs/ui` | React component library | +| `@tpmjs/utils` | Utility functions | +| `@tpmjs/env` | Environment validation | + +### Type Definitions + +```typescript +// Tool types +interface TpmjsTool { + name: string; + description: string; + inputSchema: JSONSchema; + outputSchema?: JSONSchema; + executor?: string; + category?: string; + tags?: string[]; +} + +// MCP types +interface McpRequest { + jsonrpc: "2.0"; + id: string | number; + method: string; + params?: Record; +} + +interface McpResponse { + jsonrpc: "2.0"; + id: string | number; + result?: unknown; + error?: McpError; +} +``` + +### UI Components + +- Buttons, Cards, Badges +- Form inputs with validation +- Code editors with syntax highlighting +- Chat interfaces +- Tool cards and lists + +--- + +## Security & Privacy + +### Authentication Methods + +1. **GitHub OAuth** - Primary user auth +2. **API Keys** - Programmatic access +3. **Session Cookies** - Web auth + +### API Key Security + +- SHA-256 hashed storage +- Prefix-only display after creation +- Scoped permissions +- Optional expiration +- Revocation support + +### Rate Limiting + +- Per-user limits +- Per-IP limits +- Per-tool limits +- Customizable thresholds + +### Data Privacy + +- No tool input logging by default +- Optional usage analytics +- GDPR-compliant data handling +- User data export/deletion + +### Sandbox Security + +- Network isolation modes +- Resource limits +- No persistent storage +- Ephemeral execution + +--- + +## Infrastructure + +### Deployment Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Vercel │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ +│ │ Edge │ │ Serverless │ │ Serverless │ │ +│ │ Network │→ │ Functions │→ │ Executors │ │ +│ │ (CDN) │ │ (API) │ │ (Tool Runners) │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ Neon PostgreSQL │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ +│ │ Tools │ │ Users │ │ Collections │ │ +│ │ Registry │ │ & Auth │ │ & Agents │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Monitoring + +- **Health Checks** - Every 5 minutes via GitHub Actions +- **Vercel Analytics** - Performance monitoring +- **Sync Logging** - All sync operations logged +- **Error Tracking** - Automatic error collection + +### CI/CD Pipeline + +1. **Pre-commit** - Lint, format, type-check (Lefthook) +2. **CI** - Full test suite (GitHub Actions) +3. **Deploy** - Automatic on merge (Vercel) +4. **Health Check** - Post-deploy verification + +--- + +## Use Cases + +### For Developers + +1. **Publish AI Tools** + - Package as npm module + - Add `tpmjs` keyword + - Automatically synced to registry + +2. **Build Tool Collections** + - Curate tools for specific use cases + - Share as MCP endpoint + - Embed in applications + +3. **Create AI Agents** + - Attach tools to agents + - Custom system prompts + - Deploy public chat interfaces + +### For AI Applications + +1. **Integrate Tools** + - Connect via MCP protocol + - Use any TPMJS collection + - Standard JSON-RPC interface + +2. **Extend Capabilities** + - Web scraping, code execution + - API integrations + - Data processing + +3. **Build Workflows** + - Chain multiple tools + - Agent-based automation + - Custom orchestration + +### For Enterprises + +1. **Private Tool Registry** + - Internal tools only + - Access control + - Usage analytics + +2. **Secure Execution** + - Sandboxed environments + - Audit logging + - Compliance ready + +3. **Custom Agents** + - Brand-specific AI assistants + - Internal knowledge access + - Tool-enabled support + +--- + +## Competitive Advantages + +### vs. Building Custom MCP Servers + +| TPMJS | Custom MCP Server | +|-------|-------------------| +| Instant setup | Days/weeks of development | +| 170+ tools ready | Build each tool | +| Hosted infrastructure | Self-hosted required | +| Automatic scaling | Manual scaling | + +### vs. Other Tool Platforms + +| Feature | TPMJS | Competitors | +|---------|-------|-------------| +| Open Protocol (MCP) | ✅ | Often proprietary | +| npm Integration | ✅ | Custom registries | +| Self-hostable | ✅ | Usually SaaS-only | +| Code Execution | ✅ | Limited | +| Agent System | ✅ | Separate product | + +### Unique Features + +1. **npm-Native** - Tools are just npm packages +2. **MCP-First** - Built on open standard +3. **Hybrid Execution** - Local + cloud options +4. **Collection System** - Curated tool sets +5. **Agent Platform** - Full conversational AI + +--- + +## Appendix: Official Tools Collection + +The `ajax-collection` includes 170+ tools across categories: + +### Web & Data +- `firecrawl-aisdk` - Web crawling and extraction +- `tpmjs-tools-page-brief` - Page summarization +- `tpmjs-tools-search` - Web search + +### Development +- `tpmjs-unsandbox` - Code execution (42+ languages) +- `tpmjs-tools-toc-generate` - Markdown TOC generator +- `tpmjs-tools-changelog-entry` - Changelog generation + +### Content +- `tpmjs-createblogpost` - Blog post creation +- `tpmjs-tools-recipe-hash` - Recipe/workflow hashing +- `tpmjs-tools-workflow-variant-generate` - Workflow variations + +### And Many More... +- API integrations +- Data transformations +- File processing +- Image manipulation +- Text analysis + +--- + +## Summary + +TPMJS is a comprehensive platform for AI tool discovery, execution, and orchestration. Key takeaways: + +1. **Registry** - npm-native tool discovery with automatic syncing +2. **Execution** - Secure, sandboxed tool running +3. **MCP** - Standard protocol for AI integration +4. **Collections** - Curated tool sets as MCP servers +5. **Agents** - Conversational AI with tool access +6. **Infrastructure** - Production-ready, scalable, monitored + +The platform enables developers to publish tools, AI applications to consume them, and enterprises to build secure, tool-enabled AI experiences. diff --git a/apps/web/src/app/layout.tsx b/apps/web/src/app/layout.tsx index feaf064..f92a486 100644 --- a/apps/web/src/app/layout.tsx +++ b/apps/web/src/app/layout.tsx @@ -23,11 +23,11 @@ const spaceMono = Space_Mono({ export const metadata: Metadata = { metadataBase: new URL('https://tpmjs.com'), title: { - default: 'TPMJS - Tool Package Manager for AI Agents', + default: 'TPMJS - The NPM for AI Tools', template: '%s | TPMJS', }, description: - 'Discover and use npm packages as AI agent tools. No config files, automatic discovery, works with any framework.', + 'Discover and use npm packages as AI agent tools. Works with Claude, GPT, LangChain, and any MCP-compatible client.', icons: { icon: [ { url: '/favicon.svg', type: 'image/svg+xml' }, @@ -55,9 +55,9 @@ export const metadata: Metadata = { locale: 'en_US', url: 'https://tpmjs.com', siteName: 'TPMJS', - title: 'TPMJS - Tool Package Manager for AI Agents', + title: 'TPMJS - The NPM for AI Tools', description: - 'Discover and use npm packages as AI agent tools. No config files, automatic discovery, works with any framework.', + 'Discover and use npm packages as AI agent tools. Works with Claude, GPT, LangChain, and any MCP-compatible client.', images: [ { url: '/api/og/home', @@ -71,9 +71,9 @@ export const metadata: Metadata = { card: 'summary_large_image', site: '@tpmjs_registry', creator: '@tpmjs_registry', - title: 'TPMJS - Tool Package Manager for AI Agents', + title: 'TPMJS - The NPM for AI Tools', description: - 'Discover and use npm packages as AI agent tools. No config files, automatic discovery, works with any framework.', + 'Discover and use npm packages as AI agent tools. Works with Claude, GPT, LangChain, and any MCP-compatible client.', images: ['/api/og/home'], }, robots: { @@ -101,7 +101,7 @@ export default function RootLayout({ url: 'https://tpmjs.com', logo: 'https://tpmjs.com/logo.png', description: - 'Discover and use npm packages as AI agent tools. No config files, automatic discovery, works with any framework.', + 'The NPM for AI tools. Discover and use npm packages as AI agent tools. Works with Claude, GPT, LangChain, and any MCP-compatible client.', sameAs: ['https://github.com/tpmjs/tpmjs', 'https://x.com/tpmjs_registry'], }; @@ -111,7 +111,7 @@ export default function RootLayout({ name: 'TPMJS', url: 'https://tpmjs.com', description: - 'Discover and use npm packages as AI agent tools. No config files, automatic discovery, works with any framework.', + 'The NPM for AI tools. Discover and use npm packages as AI agent tools. Works with Claude, GPT, LangChain, and any MCP-compatible client.', potentialAction: { '@type': 'SearchAction', target: { diff --git a/apps/web/src/app/page.tsx b/apps/web/src/app/page.tsx index 60dfec9..e93d5c4 100644 --- a/apps/web/src/app/page.tsx +++ b/apps/web/src/app/page.tsx @@ -91,7 +91,7 @@ export default async function HomePage(): Promise { Featured Tools

- Top-rated tools from our registry. Sorted by quality score and community adoption. + Production-ready tools you can use today. Add to your AI agent in one line.

@@ -129,12 +129,18 @@ export default async function HomePage(): Promise {
+ {tool.qualityScore && Number(tool.qualityScore) > 0 ? ( + + ★ + {Number(tool.qualityScore).toFixed(2)} + + ) : ( + + )} - Quality:{' '} - {tool.qualityScore ? Number(tool.qualityScore).toFixed(2) : 'N/A'} - - - {tool.package.npmDownloadsLastMonth?.toLocaleString() || '0'} downloads/mo + {(tool.package.npmDownloadsLastMonth ?? 0) > 0 + ? `${tool.package.npmDownloadsLastMonth?.toLocaleString()} downloads/mo` + : 'New'}
@@ -164,6 +170,62 @@ export default async function HomePage(): Promise { + {/* Integration Section */} +
+ +
+

+ Works Everywhere +

+

+ Use TPMJS tools with any MCP-compatible AI client. One URL, instant access. +

+
+ +
+
+
Claude
+

Desktop, Projects, and API

+
+
+
Cursor
+

AI-powered code editor

+
+
+
Windsurf
+

Agentic IDE

+
+
+
Any MCP
+

Open protocol support

+
+
+ + {/* Code Example */} +
+
+
+ claude_desktop_config.json +
+ 
+                  {`{
+  "mcpServers": {
+    "tpmjs": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-remote",
+        "https://tpmjs.com/api/mcp/ajax/ajax-collection/sse"]
+    }
+  }
+}`}
+
+
+

+ Add this to your config and get instant access to 170+ tools. +

+
+ +
+ {/* Publish Your Tool Section */}
diff --git a/apps/web/src/components/home/HeroSection.tsx b/apps/web/src/components/home/HeroSection.tsx index f728dc1..a277d59 100644 --- a/apps/web/src/components/home/HeroSection.tsx +++ b/apps/web/src/components/home/HeroSection.tsx @@ -65,7 +65,7 @@ export function HeroSection({ stats }: HeroSectionProps): React.ReactElement { className="mb-8 font-bold leading-none tracking-tight text-foreground" style={{ fontSize: 'clamp(48px, 10vw, 96px)' }} > - TOOL REGISTRY FOR AI AGENTS + THE NPM FOR AI TOOLS {/* Live Metrics Strip */} @@ -83,7 +83,8 @@ export function HeroSection({ stats }: HeroSectionProps): React.ReactElement { {/* Subheading */}

- The open registry for AI tools. Browse, publish, and integrate tools into your agents. + Discover and use npm packages as AI agent tools. Works with Claude, GPT, LangChain, and + any MCP-compatible client.

{/* Brutalist Search Interface */} @@ -122,8 +123,8 @@ export function HeroSection({ stats }: HeroSectionProps): React.ReactElement { {/* Helper Text */}
- Try: “web-scraper”, “github-manager”, - “sql-query” + Try: “web scraper”, “discord”, “code + interpreter”