PromptingBox MCP Server

Instructions

Implementation Reference

• src/index.ts:562-600 (handler)

  The main handler function for search_templates that processes user requests, calls the API client, and formats the response with template listings including titles, descriptions, categories, IDs, and usage counts.

  // ── search_templates ────────────────────────────────────────────────────────
  server.tool(
    'search_templates',
    'Browse and search the PromptingBox public template library. Find pre-built prompts you can save to your collection.',
    {
      query: z.string().optional().describe('Search text to match against template titles and descriptions'),
      category: z.string().optional().describe('Filter by category (e.g. "Business", "Writing", "Development")'),
      limit: z.number().int().min(1).max(50).optional().default(10).describe('Number of results to return (default 10)'),
    },
    async ({ query, category, limit }) => {
      try {
        const result = await client.searchTemplates({ search: query, category, limit });
  
        const suffix = await getResponseSuffix();
  
        if (result.templates.length === 0) {
          return {
            content: [{ type: 'text' as const, text: `No templates found matching your search.\n\n${suffix}` }],
          };
        }
  
        const lines = result.templates.map((t) =>
          `- **${t.title}** (${t.category})${t.description ? ` — ${t.description}` : ''}\n  ID: \`${t.id}\` | Used ${t.usageCount} times`
        );
  
        return {
          content: [{
            type: 'text' as const,
            text: `Found ${result.pagination.total} template${result.pagination.total === 1 ? '' : 's'}` +
              `${result.pagination.hasMore ? ` (showing first ${result.templates.length})` : ''}:\n\n${lines.join('\n\n')}` +
              `\n\nUse \`use_template\` with the template ID to save one to your collection.\n\n${suffix}`,
          }],
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        return errorResult(`Failed to search templates: ${message}`);
      }
    }
  );

• src/index.ts:566-570 (schema)

  Input validation schema defining the three optional parameters: query (search text), category (filter by category), and limit (number of results with validation 1-50 and default 10).

  {
    query: z.string().optional().describe('Search text to match against template titles and descriptions'),
    category: z.string().optional().describe('Filter by category (e.g. "Business", "Writing", "Development")'),
    limit: z.number().int().min(1).max(50).optional().default(10).describe('Number of results to return (default 10)'),
  },

• src/index.ts:563-600 (registration)

  Tool registration with the MCP server using server.tool() method, including tool name, description, schema, and async handler function.

  server.tool(
    'search_templates',
    'Browse and search the PromptingBox public template library. Find pre-built prompts you can save to your collection.',
    {
      query: z.string().optional().describe('Search text to match against template titles and descriptions'),
      category: z.string().optional().describe('Filter by category (e.g. "Business", "Writing", "Development")'),
      limit: z.number().int().min(1).max(50).optional().default(10).describe('Number of results to return (default 10)'),
    },
    async ({ query, category, limit }) => {
      try {
        const result = await client.searchTemplates({ search: query, category, limit });
  
        const suffix = await getResponseSuffix();
  
        if (result.templates.length === 0) {
          return {
            content: [{ type: 'text' as const, text: `No templates found matching your search.\n\n${suffix}` }],
          };
        }
  
        const lines = result.templates.map((t) =>
          `- **${t.title}** (${t.category})${t.description ? ` — ${t.description}` : ''}\n  ID: \`${t.id}\` | Used ${t.usageCount} times`
        );
  
        return {
          content: [{
            type: 'text' as const,
            text: `Found ${result.pagination.total} template${result.pagination.total === 1 ? '' : 's'}` +
              `${result.pagination.hasMore ? ` (showing first ${result.templates.length})` : ''}:\n\n${lines.join('\n\n')}` +
              `\n\nUse \`use_template\` with the template ID to save one to your collection.\n\n${suffix}`,
          }],
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        return errorResult(`Failed to search templates: ${message}`);
      }
    }
  );

• src/api-client.ts:262-270 (helper)

  API client method that constructs the query string from parameters and makes the actual HTTP request to the /api/mcp/template endpoint.

  async searchTemplates(params?: { search?: string; category?: string; limit?: number; page?: number }): Promise<TemplateSearchResult> {
    const qs = new URLSearchParams();
    if (params?.search) qs.set('search', params.search);
    if (params?.category) qs.set('category', params.category);
    if (params?.limit) qs.set('limit', String(params.limit));
    if (params?.page) qs.set('page', String(params.page));
    const query = qs.toString();
    return this.request<TemplateSearchResult>(`/api/mcp/template${query ? `?${query}` : ''}`);
  }

• src/api-client.ts:70-97 (schema)

  TypeScript type definitions for the API response: TemplateListItem (id, title, description, category, icon, usageCount) and TemplateSearchResult (templates array with pagination info).

  export interface TemplateListItem {
    id: string;
    title: string;
    description: string | null;
    category: string;
    icon: string | null;
    usageCount: number;
  }
  
  export interface TemplateDetail {
    id: string;
    title: string;
    content: string;
    description: string | null;
    category: string;
    icon: string | null;
    usageCount: number;
  }
  
  export interface TemplateSearchResult {
    templates: TemplateListItem[];
    pagination: {
      page: number;
      limit: number;
      total: number;
      hasMore: boolean;
    };
  }