tpmjs/TPMJS_FEATURES.md

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
2. Core Architecture
3. Tool Registry & Discovery
4. Tool Execution System
5. MCP (Model Context Protocol) Implementation
6. Collections System
7. Agent System
8. API Endpoints
9. SDK & Packages
10. Security & Privacy
11. Infrastructure
12. Use Cases
13. 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

{
  "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:

// 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:

// 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

{
  "mcpServers": {
    "tpmjs": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-remote",
        "https://tpmjs.com/api/mcp/ajax/ajax-collection/sse"]
    }
  }
}

Cursor IDE

{
  "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

// 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

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

// 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

// 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.