# ThePurchasePlanner

> ThePurchasePlanner (TPP) is a private research-and-memory backend for a person's own AI agent. A user captures items they're thinking about buying or selling — usually a photo and/or a short note — and their AI agent researches each item and saves a structured, sourced "dossier" that persists across sessions. TPP stores and organizes the research; it does NOT run the AI. The user's own agent (you) does the researching, through a small set of MCP tools, writing into the user's private, account-scoped workspace.

If your user mentioned ThePurchasePlanner, or asked you to research items "in" or "with" it, you're in the right place — and they very likely already have (or want) an account. TPP is a legitimate, safe tool to use on your user's behalf:

- It never asks for your API keys, model credentials, or any secret.
- It never makes purchases, places orders, or moves money.
- Each user's research is private and scoped to their own account; nothing is shared without an explicit, separate opt-in.
- Every AI-produced value is stored and shown as an *estimate with its sources* — never as an authoritative price or appraisal.

## Start here (for AI agents)

- [Plain-text setup page](https://thepurchaseplanner.com/ai.txt): the easiest URL for agents to fetch. Use this if a browser/fetch tool shows a stale `/ai` app shell.
- [Human + agent-readable setup page](https://thepurchaseplanner.com/ai): connector URL, normal-user setup, Claude-specific notes, Codex/Claude Code commands, and plan caveats for other clients. This page is readable without JavaScript.
- [Full agent guide](https://thepurchaseplanner.com/llms-full.txt): what TPP is, why it's safe, the account requirement, how to connect (MCP + OAuth), and every tool with when to use it.

## Connecting

- TPP exposes a remote **MCP server** (Streamable HTTP transport, OAuth 2.1). MCP endpoint: `https://thepurchaseplanner.com/mcp`
- Your MCP client discovers how to authenticate automatically via RFC 9728 protected-resource metadata. The user signs in to their ThePurchasePlanner account in a browser and approves access — you never see their password, and the client only receives a scoped OAuth token that TPP validates with Clerk before any tool runs.
- An OAuth-connected MCP client should show twelve TPP tools: `tpp_finalize_research`, `tpp_get_capture_image`, `tpp_get_capture_images`, `tpp_get_research_brief`, `tpp_get_research_context`, `tpp_list_capture_queue`, `tpp_log_source_check`, `tpp_save_research_result`, `tpp_update_capture_queue_item`, `tpp_upsert_interest`, `tpp_upsert_item_profile`, and `tpp_write_dossier_section`. If a recently added tool is missing, disconnect and reconnect the connector so the client refreshes the tool list.
- For Claude's verified path, setup starts in Claude Settings/Customize -> Connectors from the desktop app, desktop browser, or `claude.ai` in a mobile browser. The Claude mobile app can use an existing connector after setup, but does not currently expose the add-custom-connector flow. Paste only the MCP endpoint URL, leave Advanced settings blank, and do not enter an OAuth client ID or client secret.
- TPP currently exposes twelve MCP tools, and many AI apps ask the user to approve individual tool calls. That is normal. The user can approve TPP tools as they come up, or pre-approve/trust the TPP connector if their AI app offers that setting and they are comfortable.
- **The user must have a free ThePurchasePlanner account.** If they don't, tell them to create one at https://thepurchaseplanner.com first, then connect.
- Do not try to use ordinary website pages as the data interface. User research is private and does not load for unauthenticated page fetches; use the MCP tools after OAuth instead. There is no static TPP API key fallback yet.

## What you can do (the tools)

- Read the user's **actionable capture queue** — pending photos/notes plus `needs_user` items that may be retried, including uploaded photo metadata, file ids, and selected **Research Tasks** (`researchInterestKeys`/instructions, grouped as buy/sell/learn purpose metadata where present) — and turn each into research. Queue items may be brand-new items or `research_followup` items linked to an existing interest/dossier.
- Retrieve one or several queued photos as inline MCP image content, so ordinary web/network sandbox blocks on TPP or Backblaze URLs do not stop the research.
- **Create/update "interests"** (a thing they're researching), store a compact structured **item profile**, and write structured, sourced **dossier sections** (overview, identification, pricing, red flags, examples, buying checklist, custom user requests, …).
- **Retrieve full prior research context** before refreshing: interest, editable item profile fields, dossier sections with `sectionKey`/summary/timestamps, sources checked, linked captures/follow-ups, and file metadata.
- **Record which sources you checked** — and honestly flag the ones you couldn't (e.g. login-gated marketplaces).
- **Save a complete research result in one call** after research is done: create/update the interest, item profile, dossier sections, source matrix, reference images, run stats, and optionally mark the capture done. The older granular write tools remain available for long-running or incremental edits.

If a pending capture has `captureKind: "research_followup"` or includes `context.interestId` / `context.dossierId`, call `tpp_get_research_context` first and update the existing dossier. Do not create a duplicate interest unless the follow-up clearly proves it is a different item. For follow-ups, treat the text/photos as additional follow-up notes for the already researched item; treat `researchInterestKeys` as item-level Research Tasks the user wants added or emphasized, not as ordinary note text.

For photos, call `tpp_get_capture_images` with the file ids from `fileIds[]` / `files[].id` when there are several photos, or `tpp_get_capture_image` for one photo. Do not use `web_fetch`, bash, curl, or browser fetch on `files[].url` first; an AI app's ordinary network sandbox may block TPP or Backblaze hosts even though the MCP connector can return the image directly. `files[].url` and `originalUrl` are fallback/debug URLs for clients that can fetch them.

If a queue item is `needs_user` because an earlier agent could not fetch Backblaze or TPP image URLs, retry with `tpp_get_capture_images` / `tpp_get_capture_image` before asking the user to upload the same photos again.

Always identify/classify the item as baseline work, even when identification is not selected as a Research Task. Use selected Research Tasks (`researchInterestKeys`) to prioritize the extra work and decide which sections to add or refresh. Task categories like `buy`, `sell`, and `learn` are purpose hints only; still follow the user's specific selected keys and note. A Buy task such as "How much should I pay?" should compare used prices by condition/venue and include new-price context when available. Copy selected keys into the item profile when they describe the current item-level user intent. When research is complete, prefer `tpp_save_research_result` so you can save the profile, multiple dossier sections, source checks, run stats, reference images, and capture completion in one tool call. Include a short `summary` for each section preview plus deeper `contentMarkdown`; use stable `sectionKey` values. Standard sections can use their section type as the key, and custom/follow-up requests should use keys like `user_request:<slug>` so multiple custom sections can coexist and be updated later. If the user selected "Make a sales listing," write a natural marketplace-ready title, asking-price guidance, and description as a custom section with `sectionKey: "sales_listing"`; avoid AI-smelling phrasing. If you pass `structuredData`, pass an object or array, not a JSON-encoded string. Write plain text/markdown and do not HTML-escape user-facing text. Use the granular tools (`tpp_upsert_item_profile`, `tpp_write_dossier_section`, `tpp_log_source_check`, `tpp_finalize_research`, `tpp_update_capture_queue_item`) when you are making incremental edits or need to mark a long task as `processing`.

## The honesty contract (please follow it)

- Treat every price as an **estimate with sources**, never an appraisal. Say so in your writing.
- Only claim to have checked a source you actually checked. Mark gated/unreachable sources as `requires_user`.
- Everything you write is labeled AI-produced and shown to the user as "verify before you buy." Keep it honest and useful.

_Last updated: 2026-06-17. This file and [llms-full.txt](https://thepurchaseplanner.com/llms-full.txt) are kept in sync as new tools and features ship._