TPMJS

TPMJS Architecture

A complete overview of the TPMJS platform - from tool discovery to sandboxed execution, collections, agents, and custom executors.

Platform Overview

The complete TPMJS stack - tool registry, execution infrastructure, and user-facing products.

USER PRODUCTS
tpmjs.com
Dashboard
Tool Browser
Collection Editor
Agent Builder
Playground
SDK Packages
@tpmjs/registry-search
@tpmjs/registry-execute
@tpmjs/types
@tpmjs/ui
MCP Protocol
Claude Desktop
Cursor
Claude Code
Any MCP Client
API LAYER (Next.js 16)
/api/tools
/api/tools/search
/api/tools/execute
/api/collections
/api/agents
/api/mcp/*
/api/sync/*
/api/health
INFRASTRUCTURE
Database
PostgreSQL (Neon)
Prisma ORM
Execution
Vercel Sandbox
Custom Executors
External
npm Registry
esm.sh CDN

Tool Execution Pipeline

How a tool call flows from SDK/MCP through the executor sandbox.

1. REQUEST
SDK:registryExecute()
MCP:tools/call
Agent:tool_call
2. RESOLVE
Lookup tool by ID
Resolve executor config
Build import URL
3. EXECUTE
npm install pkg
tool.execute(params)
Return result
4. RESPONSE
output: any
executionTimeMs
success: boolean

Executor System

Sandboxed runtime environments for safe tool execution. Support for default and custom executors.

Default
Vercel Sandbox
Sandbox VM
Node.js 22
2 vCPUs
2 min timeout
Isolated FS
✓Network isolated
✓Per-request env injection
✓Automatic npm install
✓Cold start optimized
Custom
User-Deployed
User Infrastructure
Vercel
Railway
AWS Lambda
Self-hosted
★Custom dependencies pre-installed
★Your own API keys built-in
★Custom security policies
★One-click deploy templates
Executor API Contract
POST /execute-tool
packageName: string
name: string
params: object
env?: object
Response
success: boolean
output?: any
error?: string
executionTimeMs: number

Collections & Agents

Higher-level abstractions built on top of the tool registry.

Collection

Curated bundles of tools exposed via MCP protocol or API.

Structure
name"Web Scraping Tools"
tools[]CollectionTool[]
executorConfig?ExecutorConfig
visibilitypublic | private
/api/mcp/{user}/{slug}/http
/api/collections/{id}
Tool-level env overrides
Agent

AI-powered assistants with multi-turn conversations and tool access.

Structure
name"Research Assistant"
systemPromptstring
collections[]Collection[]
modelgpt-4o | claude-3.5...
/agents/{id}/chat
Streaming: SSE tool_call events
Persistent conversations
Executor Config Hierarchy
System Default
Vercel Sandbox
↓
Collection Config
executorConfig
↓
Agent Override
agent.executorConfig

Agent config overrides Collection config, which overrides System default.

Tool Discovery & Sync

How tools are discovered from npm and kept in sync with the registry.

npm Registry
keyword: "tpmjs"
tpmjs field
package.json
Sync Jobs
Changes Feed (2min)
Keyword Search (15min)
Metrics Sync (1hr)
Processing
Validate tpmjs field
Extract inputSchema
Calculate quality score
Database
Tool (metadata)
Package (npm info)
inputSchema (JSON)

Tool Data Model

Core entities and their relationships in the TPMJS database.

Package
npmPackageName PK
npmVersion
npmDownloadsLastMonth
repositoryUrl
author
Tool
id PK
name
description
inputSchema JSON
category
qualityScore
healthStatus
packageId FK
CollectionTool
collectionId FK
toolId FK
displayName
envOverrides JSON
position
Package 1:N Tool
Collection N:M Tool
Agent N:M Collection
User 1:N Agent

Learn More

Documentation
Full SDK and API reference
Custom Executors
Deploy your own execution environment
Agent Docs
Build AI assistants with tools