Search Prior Knowledge Base

Instructions

Implementation Reference

• src/tools.ts:81-81 (registration)

  Registration of the 'prior_search' tool via server.registerTool with title and description.

  server.registerTool("prior_search", {

• src/tools.ts:91-111 (schema)

  Input/output schema definitions for prior_search tool using Zod.

  inputSchema: {
    query: z.string().describe("Specific technical query — paste exact error strings for best results"),
    maxResults: z.number().optional().describe("Max results (default 3, max 10)"),
    maxTokens: z.number().optional().describe("Max tokens per result (default 2000, max 5000)"),
    minQuality: z.number().optional().describe("Min quality score filter (0.0-1.0)"),
    context: z.object({
      tools: z.array(z.string()).optional(),
      runtime: z.string().optional().describe("Runtime environment (e.g. node, python, openclaw, claude-code)"),
      os: z.string().optional(),
      shell: z.string().optional(),
      taskType: z.string().optional(),
    }).optional().describe("Optional context for better relevance. Include runtime if known."),
    requiredTags: z.array(z.string()).optional().describe("Only return entries that have ALL of these tags"),
    excludeTags: z.array(z.string()).optional().describe("Exclude entries that have ANY of these tags"),
    preferredTags: z.array(z.string()).optional().describe("Boost entries with these tags (soft signal, does not exclude non-matches)"),
    previousSearchFeedback: z.object({
      searchId: z.string().optional().describe("searchId from the previous search response"),
      entryId: z.string().describe("Entry ID from the previous search result"),
      outcome: z.enum(["useful", "irrelevant", "not_useful"]).describe("useful = it worked, irrelevant = wrong topic, not_useful = tried but failed (will be redirected to prior_feedback for details)"),
    }).optional().describe("Rate a result from your last search — piggyback feedback costs nothing and refunds your previous search credit"),
  },

• src/tools.ts:144-244 (handler)

  The main handler function that executes the prior_search tool logic.

  }, async ({ query, maxResults, maxTokens, minQuality, context, requiredTags, excludeTags, preferredTags, previousSearchFeedback }) => {
    const body: Record<string, unknown> = { query };
    // Build context — use provided values, fall back to detected runtime
    const ctx = context || {};
    if (!ctx.runtime) ctx.runtime = detectHost();
    body.context = ctx;
  
    if (maxResults) body.maxResults = maxResults;
    if (maxTokens) body.maxTokens = maxTokens;
    if (minQuality !== undefined) body.minQuality = minQuality;
    if (requiredTags?.length) body.requiredTags = requiredTags;
    if (excludeTags?.length) body.excludeTags = excludeTags;
    if (preferredTags?.length) body.preferredTags = preferredTags;
    if (previousSearchFeedback) body.previousSearchFeedback = previousSearchFeedback;
  
    const data = await client.request("POST", "/v1/knowledge/search", body) as any;
    const rawResults = data?.results || data?.data?.results || [];
    const searchId = data?.searchId || data?.data?.searchId;
  
    const structuredResults = rawResults.map((r: any) => ({
      id: r.id || "",
      title: r.title || "",
      content: r.content || "",
      tags: r.tags,
      qualityScore: r.qualityScore,
      relevanceScore: r.relevanceScore,
      errorMessages: r.errorMessages,
      failedApproaches: r.failedApproaches,
      feedbackActions: {
        useful: { entryId: r.id, outcome: "useful" },
        not_useful: { entryId: r.id, outcome: "not_useful", reason: "" },
        irrelevant: { entryId: r.id, outcome: "irrelevant" },
      },
    }));
  
    let text = formatResults(data);
  
    // Surface piggyback feedback result
    const rawData = data?.data || data;
    const pbf = rawData?.piggybackFeedback as { applied?: boolean; creditsRefunded?: number; message?: string } | undefined;
    if (pbf?.message) {
      const prefix = pbf.applied ? "✅ Feedback applied" : "ℹ️ Feedback";
      const creditNote = pbf.creditsRefunded ? ` (+${pbf.creditsRefunded} credit refunded)` : "";
      text = `${prefix}: ${pbf.message}${creditNote}\n\n${text}`;
    }
  
    // Surface backend contribution prompt, enhanced with MCP tool name
    let contributionPrompt = rawData?.contributionPrompt as string | undefined;
    if (contributionPrompt) {
      contributionPrompt += " Use `prior_contribute` to save your solution.";
    }
    const agentHint = rawData?.agentHint as string | undefined;
    const doNotTry = rawData?.doNotTry as string[] | undefined;
  
    // Process nudge from backend (feedback/contribution reminders)
    const rawNudge = rawData?.nudge as { kind?: string; template?: string; message?: string; context?: any } | undefined;
    let nudge: { kind: string; template: string; message: string; context: any; previousResults?: any[] } | undefined;
    if (rawNudge?.message) {
      // Expand client-side tokens to MCP tool syntax
      const expandedMessage = expandNudgeTokens(rawNudge.message);
  
      // Build feedbackActions for previous search results
      const previousResults = rawNudge.context?.previousResults?.map((r: any) => ({
        id: r.id,
        title: r.title,
        feedbackActions: {
          useful: { entryId: r.id, outcome: "useful" },
          not_useful: { entryId: r.id, outcome: "not_useful", reason: "" },
          irrelevant: { entryId: r.id, outcome: "irrelevant" },
        },
      }));
  
      nudge = {
        kind: rawNudge.kind || "",
        template: rawNudge.template || "",
        message: expandedMessage,
        context: rawNudge.context,
        ...(previousResults?.length ? { previousResults } : {}),
      };
      text += `\n\n💡 ${expandedMessage}`;
      if (previousResults?.length) {
        text += `\n  Previous results:`;
        for (const r of previousResults) {
          text += `\n    - "${r.title}" → prior_feedback(entryId: "${r.id}", outcome: "useful")`;
        }
      }
    }
  
    return {
      structuredContent: {
        results: structuredResults || [],
        searchId,
        creditsUsed: data?.creditsUsed || data?.data?.creditsUsed || 1,
        contributionPrompt: contributionPrompt || undefined,
        agentHint: agentHint || undefined,
        doNotTry: doNotTry || undefined,
        nudge: nudge || undefined,
      },
      content: [{ type: "text" as const, text }],
    };
  });

• src/utils.ts:6-12 (helper)

  Helper used by prior_search handler: detects the runtime environment (cursor, vscode, windsurf, openclaw, unknown) for context.

  export function detectHost(): string {
    if (process.env.CURSOR_TRACE_ID || process.env.CURSOR_SESSION) return "cursor";
    if (process.env.VSCODE_PID || process.env.VSCODE_CWD) return "vscode";
    if (process.env.WINDSURF_SESSION) return "windsurf";
    if (process.env.OPENCLAW_SESSION) return "openclaw";
    return "unknown";
  }

• src/utils.ts:14-36 (helper)

  Helper used by prior_search handler: formats API response data to a readable string, including feedback nudge.

  export function formatResults(data: unknown): string {
    const json = JSON.stringify(data, null, 2);
    // Append feedback nudge for search results
    // Backend wraps in {ok, data: {results: [...]}, error} — unwrap first
    const d = data as Record<string, unknown>;
    const inner = (d?.data as Record<string, unknown>) || d;
    const results = inner?.results;
    if (results && Array.isArray(results) && results.length > 0) {
      const topResult = results[0] as Record<string, unknown>;
      const topId = topResult?.id;
      // Check if the first result has an 'id' property with a meaningful value
      // Exclude null, undefined, and empty string
      if (topResult && 'id' in topResult && topId !== null && topId !== undefined && topId !== '') {
        const ids = (results as Array<Record<string, unknown>>).map(r => r?.id || '').join(", ");
        return json + `\n\n---\nYou already paid 1 credit for this search. Get it back — call prior_feedback with ONE of:\n` +
          `  worked: prior_feedback(entryId="${topId}", outcome="useful")\n` +
          `  didn't work: prior_feedback(entryId="${topId}", outcome="not_useful", reason="describe why")\n` +
          `  wrong result: prior_feedback(entryId="${topId}", outcome="irrelevant")\n` +
          `All result IDs: ${ids}`;
      }
    }
    return json;
  }