From 0e5815e4ce44a07f82df0ac7934b565ad46b566e Mon Sep 17 00:00:00 2001 From: Ajax Davis Date: Fri, 30 Jan 2026 23:41:03 +1000 Subject: [PATCH] docs(sdk): add MCP server, REST API, and agent building documentation - Add MCP Server Integration section with Claude Desktop, Cursor, VS Code config examples - Add REST API Reference documenting /api/tools, /api/tools/search, /api/tools/execute endpoints - Add "Building an Agent Like Omega" section with complete implementation examples - Include SSE streaming patterns for real-time tool execution UI - Update .gitignore to exclude .env*.local files --- .gitignore | 1 + apps/web/src/app/sdk/page.tsx | 554 +++++++++++++++++++++++++++++++++- 2 files changed, 551 insertions(+), 4 deletions(-) diff --git a/.gitignore b/.gitignore index 2d7c8f1..c32553e 100644 --- a/.gitignore +++ b/.gitignore @@ -72,3 +72,4 @@ storybook-static !.changeset/README.md .vercel packages/tool-ideas/data/tools-export.json +.env*.local diff --git a/apps/web/src/app/sdk/page.tsx b/apps/web/src/app/sdk/page.tsx index de649bf..392ecdd 100644 --- a/apps/web/src/app/sdk/page.tsx +++ b/apps/web/src/app/sdk/page.tsx @@ -199,7 +199,12 @@ Use registrySearch to find tools, then registryExecute to run them.\`, rel="noopener noreferrer" className="inline-flex items-center gap-2 px-3 py-1.5 text-sm font-medium bg-red-500/10 text-red-500 rounded-md hover:bg-red-500/20 transition-colors" > - + npm @@ -325,7 +330,12 @@ Use registrySearch to find tools, then registryExecute to run them.\`, rel="noopener noreferrer" className="inline-flex items-center gap-2 px-3 py-1.5 text-sm font-medium bg-red-500/10 text-red-500 rounded-md hover:bg-red-500/20 transition-colors" > - + npm @@ -698,6 +708,542 @@ const tools = await tpmjs.loadCollection('my-company/internal-tools');`} + {/* MCP Server Integration */} +
+

+ MCP Server Integration +

+

+ TPMJS supports the{' '} + + Model Context Protocol (MCP) + + , allowing you to use your tool collections directly in Claude Desktop, Cursor, VS + Code, and other MCP-compatible clients. +

+ +
+ {/* Create a Collection */} +
+
+ + 1 + +

Create a Collection

+
+

+ Sign in to{' '} + + tpmjs.com + {' '} + and create a collection of tools. Add the tools you want your agent to have access + to, and configure any required API keys. +

+
+ + {/* Get Your MCP URL */} +
+
+ + 2 + +

Get Your MCP URL

+
+

+ Your collection has a unique MCP endpoint URL: +

+ +

+ Replace {'{username}'} with your username + and {'{collection-slug}'} with your + collection's slug. +

+
+ + {/* Configure Your Client */} +
+
+ + 3 + +

Configure Your Client

+
+ +
+
+

Claude Desktop

+

+ Add to your claude_desktop_config.json: +

+ +
+ +
+

Cursor / VS Code

+

+ Add to your .cursor/mcp.json or VS Code MCP settings: +

+ +
+
+
+ + {/* Get an API Key */} +
+
+ + 4 + +

Get an API Key

+
+

+ Generate an API key from your{' '} + + account settings + + . API keys authenticate your MCP requests and enable access to your private + collections. +

+
+
+ + + {/* REST API Reference */} +
+

+ REST API Reference +

+

+ For advanced integrations, you can use the TPMJS REST API directly. All endpoints are + available at https://tpmjs.com/api. +

+ +
+ {/* List Tools */} +
+
+ + GET + +

/api/tools

+
+

+ List all tools with filtering, sorting, and pagination. +

+ +

Query Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
qstringSearch query (package name, description)
categorystringFilter by category
officialbooleanFilter by official status
limitnumberResults per page (1-1000, default 20)
offsetnumberPagination offset (default 0)
+
+ +

Example

+ +
+ + {/* Search Tools */} +
+
+ + GET + +

+ /api/tools/search +

+
+

+ Semantic search using BM25 algorithm. Better for natural language queries. +

+ +

Query Parameters

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
qstringSearch query (natural language)
categorystringFilter by category
limitnumberMax results (1-100, default 10)
+
+ +

Example

+ + +

Response

+ +
+ + {/* Execute Tool */} +
+
+ + POST + +

+ /api/tools/execute/{'{package}'}/{'{tool}'} +

+
+

+ Execute a tool in the secure sandbox. Returns the tool output. +

+ +

Request Body

+ + +

Example

+ + +

Response

+ +
+
+
+ + {/* Building an Agent Like Omega */} +
+

+ Building an Agent Like Omega +

+

+ + Omega + {' '} + is our flagship AI agent that demonstrates dynamic tool discovery at scale. + Here's how to build something similar. +

+ +
+ {/* Architecture Overview */} +
+

+ Architecture Overview +

+

+ Omega uses a two-tier tool discovery pattern: +

+
    +
  1. + Automatic discovery — Every message triggers a BM25 search to + find relevant tools +
    2. +
  2. + Agent-driven search — The agent can explicitly search for more + tools using registrySearchTool +
    3. +
+
+ + {/* Complete Implementation */} +
+

+ Complete Implementation +

+ = { + FIRECRAWL_API_KEY: process.env.FIRECRAWL_API_KEY!, + EXA_API_KEY: process.env.EXA_API_KEY!, + OPENAI_API_KEY: process.env.OPENAI_API_KEY!, +}; + +// Wrapped execute tool with pre-configured keys +const registryExecute = tool({ + description: registryExecuteTool.description, + parameters: registryExecuteTool.parameters, + execute: async ({ toolId, params }) => { + return registryExecuteTool.execute({ toolId, params, env: API_KEYS }); + }, +}); + +// System prompt for Omega-like behavior +const SYSTEM_PROMPT = \`You are an AI assistant with access to thousands of tools via the TPMJS registry. + +## Available Tools +- registrySearch: Search the registry to find tools for any task +- registryExecute: Execute any tool by its toolId + +## Workflow +1. When given a task, first search for relevant tools +2. Review the results - each tool has: toolId, name, description, requiredEnvVars +3. Execute tools with appropriate parameters +4. Synthesize results into a helpful response + +## Best Practices +- Search first when unsure what tools exist +- Execute tools to get real results (not just descriptions) +- Handle errors gracefully - suggest alternatives if a tool fails +- Be efficient - don't search repeatedly for the same thing\`; + +// Auto-discover tools based on user message +async function discoverTools(message: string) { + const response = await fetch( + \`https://tpmjs.com/api/tools/search?q=\${encodeURIComponent(message)}&limit=10\` + ); + const data = await response.json(); + return data.results?.tools || []; +} + +// Main agent function +async function runAgent(userMessage: string) { + // Step 1: Auto-discover relevant tools + const discoveredTools = await discoverTools(userMessage); + console.log(\`Found \${discoveredTools.length} relevant tools\`); + + // Step 2: Create dynamic tool context for the prompt + const toolContext = discoveredTools.length > 0 + ? \`\\n\\n## Pre-discovered Tools\\nBased on your request, these tools may be helpful:\\n\${ + discoveredTools.map((t: { toolId: string; description: string }) => + \`- \${t.toolId}: \${t.description}\` + ).join('\\n') + }\` + : ''; + + // Step 3: Run the agent with tool access + const result = await streamText({ + model: openai('gpt-4.1'), + tools: { + registrySearch: registrySearchTool, + registryExecute, + }, + maxSteps: 10, + system: SYSTEM_PROMPT + toolContext, + prompt: userMessage, + }); + + // Step 4: Stream the response + for await (const chunk of result.textStream) { + process.stdout.write(chunk); + } + + return result; +} + +// Usage +await runAgent('Scrape https://example.com and summarize the content');`} + /> +
+ + {/* Streaming with SSE */} +
+

+ Streaming with Server-Sent Events +

+

+ For real-time UI updates, stream tool execution status via SSE: +

+ { + if (stepType === 'tool-result') { + controller.enqueue(encoder.encode( + \`event: tool.completed\\ndata: \${JSON.stringify({ toolCalls, toolResults })}\\n\\n\` + )); + } + }, + }); + + // Stream text chunks + for await (const chunk of result.textStream) { + controller.enqueue(encoder.encode( + \`event: message.delta\\ndata: \${JSON.stringify({ content: chunk })}\\n\\n\` + )); + } + + controller.enqueue(encoder.encode(\`event: done\\ndata: {}\\n\\n\`)); + controller.close(); + }, + }); + + return new Response(stream, { + headers: { + 'Content-Type': 'text/event-stream', + 'Cache-Control': 'no-cache', + Connection: 'keep-alive', + }, + }); +}`} + /> +
+
+
+ {/* CTA */}

@@ -725,7 +1271,7 @@ const tools = await tpmjs.loadCollection('my-company/internal-tools');`} rel="noopener noreferrer" className="inline-flex items-center gap-2 px-3 py-1.5 font-medium bg-red-500/10 text-red-500 rounded-md hover:bg-red-500/20 transition-colors" > - + @tpmjs/registry-search @@ -736,7 +1282,7 @@ const tools = await tpmjs.loadCollection('my-company/internal-tools');`} rel="noopener noreferrer" className="inline-flex items-center gap-2 px-3 py-1.5 font-medium bg-red-500/10 text-red-500 rounded-md hover:bg-red-500/20 transition-colors" > - + @tpmjs/registry-execute