PromptingBox MCP Server

Instructions

Implementation Reference

• src/index.ts:192-229 (handler)

  The main handler function for search_prompts tool. It registers the tool with MCP server, defines input parameters using zod schema (query, tag, folder, favorites), calls client.searchPrompts() API, formats the results as a bulleted list with prompt titles, IDs, favorite indicators, and folder names, and returns the response with account info suffix.

  server.tool(
    'search_prompts',
    'Search prompts in PromptingBox by title, content, tag, folder, or favorites. Returns matching prompts.',
    {
      query: z.string().optional().describe('Search text to match against title and content'),
      tag: z.string().optional().describe('Filter by tag name'),
      folder: z.string().optional().describe('Filter by folder name'),
      favorites: z.boolean().optional().describe('Set to true to only show favorited prompts'),
    },
    async ({ query, tag, folder, favorites }) => {
      try {
        const [results, suffix] = await Promise.all([
          client.searchPrompts({ search: query, tag, folder, favorites }),
          getResponseSuffix(),
        ]);
  
        if (results.length === 0) {
          return {
            content: [{ type: 'text' as const, text: `No prompts found matching your search.\n\n${suffix}` }],
          };
        }
  
        const lines = results.map((p) =>
          `- ${p.isFavorite ? '⭐ ' : ''}${p.title} (id: \`${p.id}\`)${p.folderName ? ` — 📁 ${p.folderName}` : ''}`
        );
  
        return {
          content: [{
            type: 'text' as const,
            text: `Found ${results.length} prompt${results.length === 1 ? '' : 's'}:\n\n${lines.join('\n')}\n\n${suffix}`,
          }],
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        return errorResult(`Failed to search prompts: ${message}`);
      }
    }
  );

• src/index.ts:195-200 (schema)

  Input validation schema for search_prompts using zod. Defines optional parameters: query (search text for title/content), tag (filter by tag name), folder (filter by folder name), and favorites (boolean filter for favorited prompts only).

  {
    query: z.string().optional().describe('Search text to match against title and content'),
    tag: z.string().optional().describe('Filter by tag name'),
    folder: z.string().optional().describe('Filter by folder name'),
    favorites: z.boolean().optional().describe('Set to true to only show favorited prompts'),
  },

• src/api-client.ts:172-180 (helper)

  The API client method that makes the actual HTTP request to search prompts. Constructs URLSearchParams from the provided search parameters (search, tag, folder, favorites) and makes a GET request to /api/mcp/prompt endpoint. Returns an array of PromptListItem objects.

  async searchPrompts(params: SearchPromptsParams): Promise<PromptListItem[]> {
    const qs = new URLSearchParams();
    if (params.search) qs.set('search', params.search);
    if (params.tag) qs.set('tag', params.tag);
    if (params.folder) qs.set('folder', params.folder);
    if (params.favorites) qs.set('favorites', 'true');
    const query = qs.toString();
    return this.request<PromptListItem[]>(`/api/mcp/prompt${query ? `?${query}` : ''}`);
  }

• src/api-client.ts:99-104 (schema)

  TypeScript interface defining the shape of search_prompts parameters: optional search string, optional tag string, optional folder string, and optional favorites boolean. This type is used by the searchPrompts API client method.

  export interface SearchPromptsParams {
    search?: string;
    tag?: string;
    folder?: string;
    favorites?: boolean;
  }

• src/api-client.ts:41-47 (schema)

  TypeScript interface defining the PromptListItem structure returned by searchPrompts: id, title, folderId, folderName, and optional isFavorite boolean. This is the output type for the search_prompts tool results.

  export interface PromptListItem {
    id: string;
    title: string;
    folderId: string | null;
    folderName: string | null;
    isFavorite?: boolean;
  }