engineering/tpmjs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2.3k

feat: improve homepage marketing and add integrations section

Browse source 
- Update headline to "THE NPM FOR AI TOOLS" for clearer positioning
- Add new integrations section showing Claude, Cursor, Windsurf support
- Include config code example for easy onboarding
- Fix search placeholder to use real tool names
- Improve featured tools display (hide N/A scores, show "New" for 0 downloads)
- Update site metadata and structured data with new tagline
- Add comprehensive TPMJS features documentation
This commit is contained in:
Ajax Davis 2026-01-14 06:43:15 +10:00
parent d64983163c
commit faf4b622c7
4 changed files with 779 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

698
TPMJS_FEATURES.md Normal file
View file

@ -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<string, unknown>;
}
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.