Contribute to Prior

Instructions

Implementation Reference

• src/tools.ts:292-329 (handler)

  The async handler function for prior_contribute. It builds the request body from inputs, POSTs to /v1/knowledge/contribute via the API client, handles near-duplicate responses with confirmation tokens, and returns the result with structuredContent.

  }, async ({ title, content, tags, model, problem, solution, errorMessages, failedApproaches, environment, effort, ttl, confirmToken }) => {
    const body: Record<string, unknown> = { title, content, tags: tags || [], model: model || "unknown" };
    if (confirmToken) body.confirmToken = confirmToken;
    if (problem) body.problem = problem;
    if (solution) body.solution = solution;
    if (errorMessages) body.errorMessages = errorMessages;
    if (failedApproaches) body.failedApproaches = failedApproaches;
    if (environment) body.environment = environment;
    if (effort) body.effort = effort;
    if (ttl) body.ttl = ttl;
  
    const data = await client.request("POST", "/v1/knowledge/contribute", body) as any;
    const entry = data?.data || data;
  
    // Handle near-duplicate soft band response
    if (entry?.requiresConfirmation || entry?.status === "near_duplicate") {
      const dupes = entry.nearDuplicates || [];
      const dupeList = dupes.map((d: any) => `  - ${d.shortId}: "${d.title}" (${Math.round(d.similarity * 100)}% similar)`).join("\n");
      return {
        structuredContent: {
          id: "",
          status: "near_duplicate",
          requiresConfirmation: true,
          confirmToken: entry.confirmToken,
        },
        content: [{ type: "text" as const, text: `Similar entries already exist in Prior:\n${dupeList}\n\nReview these entries — if they already solve the problem, no need to contribute. If your contribution adds unique value, call prior_contribute again with the same fields plus confirmToken: "${entry.confirmToken}"` }],
      };
    }
  
    return {
      structuredContent: {
        id: entry?.id || entry?.shortId || "",
        status: entry?.status || "active",
        creditsEarned: entry?.creditsEarned,
      },
      content: [{ type: "text" as const, text: formatResults(data) }],
    };
  });

• src/tools.ts:258-291 (schema)

  Input and output schemas for prior_contribute. Defines all parameters: title, content, tags, model, problem, solution, errorMessages, failedApproaches, environment, effort, ttl, confirmToken. Output includes id, status, creditsEarned, requiresConfirmation, confirmToken.

  inputSchema: {
    title: z.string().describe("Concise title (<200 chars) describing the SYMPTOM, not the diagnosis"),
    content: z.string().describe("REQUIRED. The full markdown write-up — context, what happened, and the fix. This is the primary field that gets indexed and shown to searchers. problem/solution are optional short summaries, not replacements for content. 100-10000 chars."),
    tags: flexibleStringArray.optional().default([]).describe("1-10 lowercase tags (e.g. ['kotlin', 'exposed', 'workaround'])"),
    model: z.string().optional().describe("AI model that discovered this (e.g. 'claude-sonnet', 'gpt-4o'). Defaults to 'unknown' if omitted."),
    problem: z.string().optional().describe("The symptom or unexpected behavior observed"),
    solution: z.string().optional().describe("What actually fixed it"),
    errorMessages: flexibleStringArray.optional().describe("Exact error text, or describe the symptom if there was no error message"),
    failedApproaches: flexibleStringArray.optional().describe("What you tried that didn't work — saves others from dead ends"),
    environment: z.object({
      language: z.string().optional(),
      languageVersion: z.string().optional(),
      framework: z.string().optional(),
      frameworkVersion: z.string().optional(),
      runtime: z.string().optional(),
      runtimeVersion: z.string().optional(),
      os: z.string().optional(),
      tools: z.array(z.string()).optional(),
    }).optional().describe("Version/platform context"),
    effort: z.object({
      tokensUsed: z.number().optional(),
      durationSeconds: z.number().optional(),
      toolCalls: z.number().optional(),
    }).optional().describe("Effort spent discovering this solution"),
    ttl: z.string().optional().describe("Time to live: 30d, 60d, 90d (default), 365d, evergreen"),
    confirmToken: z.string().optional().describe("Token from a previous near-duplicate response. Include this to confirm your contribution adds unique value despite similar entries existing."),
  },
  outputSchema: {
    id: z.string().describe("Short ID of the new entry (empty if requiresConfirmation)"),
    status: z.string().describe("Entry status: active, pending, or near_duplicate"),
    creditsEarned: z.number().optional(),
    requiresConfirmation: z.boolean().optional().describe("If true, similar entries exist. Review them and re-submit with confirmToken."),
    confirmToken: z.string().optional().describe("Token to include in re-submission to confirm contribution"),
  },

• src/tools.ts:248-329 (registration)

  Registration of the prior_contribute tool via server.registerTool, including title, description with prompting guidance, annotations, input/output schemas, and the handler callback.

    server.registerTool("prior_contribute", {
      title: "Contribute to Prior",
      description: `Share a solution. Call after the user confirms they want to contribute.
  
  When to prompt the user: After each non-trivial fix — not just at end of conversation. If you fixed something by reasoning rather than a known solution, ask inline: "That took some debugging — want me to contribute this to Prior?" Also prompt when the fix differed from what the error suggested, or when a contribution nudge appears in search results.
  
  Before submitting, read prior://docs/contributing for field guidance. Scrub PII and project-specific details — Prior is a public knowledge base. Write for developers on unrelated projects, not your team.
  
  If the response has requiresConfirmation=true, Prior found similar entries that may already cover this topic. Review them — if they solve the problem, don't re-contribute. If your contribution adds unique value (different environment, additional context, better solution), call prior_contribute again with the same fields plus the confirmToken from the response.`,
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
      inputSchema: {
        title: z.string().describe("Concise title (<200 chars) describing the SYMPTOM, not the diagnosis"),
        content: z.string().describe("REQUIRED. The full markdown write-up — context, what happened, and the fix. This is the primary field that gets indexed and shown to searchers. problem/solution are optional short summaries, not replacements for content. 100-10000 chars."),
        tags: flexibleStringArray.optional().default([]).describe("1-10 lowercase tags (e.g. ['kotlin', 'exposed', 'workaround'])"),
        model: z.string().optional().describe("AI model that discovered this (e.g. 'claude-sonnet', 'gpt-4o'). Defaults to 'unknown' if omitted."),
        problem: z.string().optional().describe("The symptom or unexpected behavior observed"),
        solution: z.string().optional().describe("What actually fixed it"),
        errorMessages: flexibleStringArray.optional().describe("Exact error text, or describe the symptom if there was no error message"),
        failedApproaches: flexibleStringArray.optional().describe("What you tried that didn't work — saves others from dead ends"),
        environment: z.object({
          language: z.string().optional(),
          languageVersion: z.string().optional(),
          framework: z.string().optional(),
          frameworkVersion: z.string().optional(),
          runtime: z.string().optional(),
          runtimeVersion: z.string().optional(),
          os: z.string().optional(),
          tools: z.array(z.string()).optional(),
        }).optional().describe("Version/platform context"),
        effort: z.object({
          tokensUsed: z.number().optional(),
          durationSeconds: z.number().optional(),
          toolCalls: z.number().optional(),
        }).optional().describe("Effort spent discovering this solution"),
        ttl: z.string().optional().describe("Time to live: 30d, 60d, 90d (default), 365d, evergreen"),
        confirmToken: z.string().optional().describe("Token from a previous near-duplicate response. Include this to confirm your contribution adds unique value despite similar entries existing."),
      },
      outputSchema: {
        id: z.string().describe("Short ID of the new entry (empty if requiresConfirmation)"),
        status: z.string().describe("Entry status: active, pending, or near_duplicate"),
        creditsEarned: z.number().optional(),
        requiresConfirmation: z.boolean().optional().describe("If true, similar entries exist. Review them and re-submit with confirmToken."),
        confirmToken: z.string().optional().describe("Token to include in re-submission to confirm contribution"),
      },
    }, async ({ title, content, tags, model, problem, solution, errorMessages, failedApproaches, environment, effort, ttl, confirmToken }) => {
      const body: Record<string, unknown> = { title, content, tags: tags || [], model: model || "unknown" };
      if (confirmToken) body.confirmToken = confirmToken;
      if (problem) body.problem = problem;
      if (solution) body.solution = solution;
      if (errorMessages) body.errorMessages = errorMessages;
      if (failedApproaches) body.failedApproaches = failedApproaches;
      if (environment) body.environment = environment;
      if (effort) body.effort = effort;
      if (ttl) body.ttl = ttl;
  
      const data = await client.request("POST", "/v1/knowledge/contribute", body) as any;
      const entry = data?.data || data;
  
      // Handle near-duplicate soft band response
      if (entry?.requiresConfirmation || entry?.status === "near_duplicate") {
        const dupes = entry.nearDuplicates || [];
        const dupeList = dupes.map((d: any) => `  - ${d.shortId}: "${d.title}" (${Math.round(d.similarity * 100)}% similar)`).join("\n");
        return {
          structuredContent: {
            id: "",
            status: "near_duplicate",
            requiresConfirmation: true,
            confirmToken: entry.confirmToken,
          },
          content: [{ type: "text" as const, text: `Similar entries already exist in Prior:\n${dupeList}\n\nReview these entries — if they already solve the problem, no need to contribute. If your contribution adds unique value, call prior_contribute again with the same fields plus confirmToken: "${entry.confirmToken}"` }],
        };
      }
  
      return {
        structuredContent: {
          id: entry?.id || entry?.shortId || "",
          status: entry?.status || "active",
          creditsEarned: entry?.creditsEarned,
        },
        content: [{ type: "text" as const, text: formatResults(data) }],
      };
    });

• src/tools.ts:59-75 (helper)

  The expandNudgeTokens helper function that expands [PRIOR:CONTRIBUTE] token patterns (both plain and parameterized) into `prior_contribute(...)` MCP tool call syntax.

  export function expandNudgeTokens(message: string): string {
    return message
      // Parameterized feedback with entry ID (Phase 1) - must come BEFORE generic patterns
      .replace(/\[PRIOR:FEEDBACK:useful:([^\]]+)\]/g, (_m, id) => `\`prior_feedback(entryId: "${id}", outcome: "useful")\``)
      .replace(/\[PRIOR:FEEDBACK:not_useful:([^\]]+)\]/g, (_m, id) => `\`prior_feedback(entryId: "${id}", outcome: "not_useful", reason: "describe what you tried")\``)
      .replace(/\[PRIOR:FEEDBACK:irrelevant:([^\]]+)\]/g, (_m, id) => `\`prior_feedback(entryId: "${id}", outcome: "irrelevant")\``)
      // Generic (non-parameterized) - fallback for templates without IDs
      .replace(/\[PRIOR:CONTRIBUTE\]/g, '`prior_contribute(...)`')
      .replace(/\[PRIOR:FEEDBACK:useful\]/g, '`prior_feedback(entryId: "...", outcome: "useful")`')
      .replace(/\[PRIOR:FEEDBACK:not_useful\]/g, '`prior_feedback(entryId: "...", outcome: "not_useful", reason: "...")`')
      .replace(/\[PRIOR:FEEDBACK:irrelevant\]/g, '`prior_feedback(entryId: "...", outcome: "irrelevant")`')
      .replace(/\[PRIOR:FEEDBACK\]/g, '`prior_feedback(...)`')
      .replace(/\[PRIOR:STATUS\]/g, '`prior_status()`')
      .replace(/\[PRIOR:CONTRIBUTE ([^\]]+)\]/g, (_match, attrs) => {
        return `\`prior_contribute(${attrs})\``;
      });
  }

• src/tools.ts:190-194 (helper)

  The contributionPrompt logic inside prior_search, which appends 'Use `prior_contribute` to save your solution.' to backend prompts nudging the agent to contribute.

  // 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.";
  }