@bojanrajkovic/mcp-paprika 2.0.0-beta.0 → 2.0.0-beta.2

package/dist/auth/consent-page.d.ts

@@ -41,9 +41,15 @@ export declare function renderDeniedPage(): RenderedPage;
 export declare function renderExpiredPage(): RenderedPage;
 /**
  * Security headers for every consent-flow response. The CSP pins inline styles
- * to `nonce`, denies all other resource loads, restricts form submission to
- * our own origin, and forbids framing; `X-Frame-Options` backs frame-ancestors
- * for older browsers; `Cache-Control` keeps the page (and its ticket) out of
- * shared caches.
+ * to `nonce`, denies all other resource loads, restricts form submission, and
+ * forbids framing; `X-Frame-Options` backs frame-ancestors for older browsers;
+ * `Cache-Control` keeps the page (and its ticket) out of shared caches.
+ *
+ * `form-action` is enforced across redirects: the Allow form posts same-origin to
+ * `/oauth/consent`, which 302-redirects to the upstream IdP authorize endpoint,
+ * so `'self'` alone blocks the approve navigation. Callers rendering the consent
+ * *form* must pass `formActionOrigin` (the IdP authorize-endpoint origin) so that
+ * redirect is allowed; terminal pages (denied/expired) carry no form and omit it,
+ * keeping `form-action 'self'`.
  */
-export declare function consentSecurityHeaders(nonce: string): Record<string, string>;
+export declare function consentSecurityHeaders(nonce: string, formActionOrigin?: string): Record<string, string>;

package/dist/auth/consent-page.js

@@ -34,12 +34,19 @@ function escapeHtml(value) {
 function generateNonce() {
     return randomBytes(16).toString("base64");
 }
+/**
+ * The authorization server's display name in the consent brandbar and page
+ * titles. This is the OAuth-surface identity (distinct from the host-facing
+ * connector card name in `src/utils/branding.ts`); a connecting user reads it as
+ * "the Paprika MCP Connector wants to connect."
+ */
+const DISPLAY_NAME = "Paprika MCP Connector";
 const STYLES = `
   :root {
     --paper: oklch(0.985 0.006 75); --card: oklch(0.995 0.004 75);
     --ink: oklch(0.26 0.012 70); --muted: oklch(0.53 0.012 70); --faint: oklch(0.66 0.010 70);
     --line: oklch(0.90 0.008 70); --line-2: oklch(0.83 0.010 70);
-    --clay: oklch(0.55 0.12 45); --clay-ink: oklch(0.99 0.01 75); --dest-bg: oklch(0.965 0.012 70);
+    --clay: oklch(0.543 0.174 30); --clay-ink: oklch(0.99 0.01 75); --dest-bg: oklch(0.965 0.012 70); /* --clay = #C0392B, the connector icon color */
     --mono: ui-monospace, "SF Mono", Menlo, monospace;
     --sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
   }
@@ -69,14 +76,14 @@ const STYLES = `
   .grants .lbl { font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.06em;
     color: var(--faint); margin-bottom: 4px; }
   .grants p { margin: 0; font-size: 0.9rem; color: var(--muted); }
-  .denyline { font-size: 0.82rem; color: var(--muted); padding: 14px 22px 0; }
+  .denyline { font-size: 0.82rem; color: var(--muted); padding: 14px 0 0; }
   .denyline b { color: var(--ink); }
-  .actions { display: flex; gap: 10px; padding: 14px 22px 20px; }
+  .actions { display: flex; gap: 10px; padding: 14px 0 20px; }
   .btn { flex: 1; text-align: center; padding: 11px 14px; border-radius: 9px; font: inherit;
     font-size: 0.92rem; font-weight: 600; border: 1px solid transparent; cursor: pointer; }
   .btn-ghost { background: transparent; color: var(--ink); border-color: var(--line-2); }
   .btn-fill { background: var(--clay); color: var(--clay-ink); }
-  .foot { padding: 0 22px 18px; font-size: 0.78rem; color: var(--faint); }
+  .foot { padding: 0 0 18px; font-size: 0.78rem; color: var(--faint); }
   .terminal { padding: 28px 24px; text-align: center; }
   .terminal h1 { font-size: 1.2rem; font-weight: 650; margin: 0 0 8px; }
   .terminal p { margin: 0; color: var(--muted); font-size: 0.9rem; }
@@ -108,7 +115,7 @@ export function renderConsentPage(params) {
     const safeTicket = escapeHtml(params.ticket);
     const initial = escapeHtml(name.charAt(0).toUpperCase() || "?");
     const body = `<main class="screen">
-  <div class="brandbar"><span class="dot"></span> mcp-paprika</div>
+  <div class="brandbar"><span class="dot"></span> ${DISPLAY_NAME}</div>
   <form class="body" method="post" action="/oauth/consent">
     <input type="hidden" name="ticket" value="${safeTicket}">
     <div class="head">
@@ -134,45 +141,52 @@ export function renderConsentPage(params) {
     <div class="foot">You&#39;ll sign in after allowing. Only you can complete this.</div>
   </form>
 </main>`;
-    return { html: shell(nonce, "Authorize access — mcp-paprika", body), nonce };
+    return { html: shell(nonce, `Authorize access — ${DISPLAY_NAME}`, body), nonce };
 }
 /** Terminal page shown on Deny. Stays on our origin; never redirects to the redirect_uri. */
 export function renderDeniedPage() {
     const nonce = generateNonce();
     const body = `<main class="screen">
-  <div class="brandbar"><span class="dot"></span> mcp-paprika</div>
+  <div class="brandbar"><span class="dot"></span> ${DISPLAY_NAME}</div>
   <div class="terminal">
     <h1>Access denied</h1>
     <p>No connection was authorized. You can close this tab.</p>
   </div>
 </main>`;
-    return { html: shell(nonce, "Access denied — mcp-paprika", body), nonce };
+    return { html: shell(nonce, `Access denied — ${DISPLAY_NAME}`, body), nonce };
 }
 /** Terminal page shown when a consent ticket is unknown or expired. */
 export function renderExpiredPage() {
     const nonce = generateNonce();
     const body = `<main class="screen">
-  <div class="brandbar"><span class="dot"></span> mcp-paprika</div>
+  <div class="brandbar"><span class="dot"></span> ${DISPLAY_NAME}</div>
   <div class="terminal">
     <h1>Request expired</h1>
     <p>This authorization request is no longer valid. Start the connection again from your app.</p>
   </div>
 </main>`;
-    return { html: shell(nonce, "Request expired — mcp-paprika", body), nonce };
+    return { html: shell(nonce, `Request expired — ${DISPLAY_NAME}`, body), nonce };
 }
 /**
  * Security headers for every consent-flow response. The CSP pins inline styles
- * to `nonce`, denies all other resource loads, restricts form submission to
- * our own origin, and forbids framing; `X-Frame-Options` backs frame-ancestors
- * for older browsers; `Cache-Control` keeps the page (and its ticket) out of
- * shared caches.
+ * to `nonce`, denies all other resource loads, restricts form submission, and
+ * forbids framing; `X-Frame-Options` backs frame-ancestors for older browsers;
+ * `Cache-Control` keeps the page (and its ticket) out of shared caches.
+ *
+ * `form-action` is enforced across redirects: the Allow form posts same-origin to
+ * `/oauth/consent`, which 302-redirects to the upstream IdP authorize endpoint,
+ * so `'self'` alone blocks the approve navigation. Callers rendering the consent
+ * *form* must pass `formActionOrigin` (the IdP authorize-endpoint origin) so that
+ * redirect is allowed; terminal pages (denied/expired) carry no form and omit it,
+ * keeping `form-action 'self'`.
  */
-export function consentSecurityHeaders(nonce) {
+export function consentSecurityHeaders(nonce, formActionOrigin) {
+    const formAction = formActionOrigin ? `form-action 'self' ${formActionOrigin}` : "form-action 'self'";
     return {
         "Content-Security-Policy": [
             "default-src 'none'",
             `style-src 'nonce-${nonce}'`,
-            "form-action 'self'",
+            formAction,
             "base-uri 'none'",
             "frame-ancestors 'none'",
         ].join("; "),

package/dist/auth/provider.js

@@ -83,7 +83,11 @@ export class MintingOAuthServerProvider {
             ...clientNameProp,
             redirectHost: new URL(params.redirectUri).origin,
         });
-        c.res = c.html(html, 200, consentSecurityHeaders(nonce));
+        // The Allow form posts to /oauth/consent, which 302s to the upstream IdP.
+        // form-action is enforced across that redirect, so the IdP origin must be
+        // allowed or the browser blocks the approve navigation (consuming the ticket).
+        const idpOrigin = new URL(this._discovery.authorization_endpoint).origin;
+        c.res = c.html(html, 200, consentSecurityHeaders(nonce, idpOrigin));
     }
     /** Narrow deps bundle for the shared `redirectUpstream` helper. */
     _upstreamRedirectDeps() {

package/dist/tools/aisles.js

@@ -3,6 +3,7 @@ import { textResult } from "./helpers.js";
 export function registerAislesTool(server, ctx) {
     const log = ctx.log.child({ component: "list_aisles" });
     server.registerTool("list_aisles", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "List all known aisles, sorted by order then name. " +
             "Includes the aisle UID needed for pantry and grocery item writes.",
         inputSchema: {},

package/dist/tools/categories.js

@@ -3,6 +3,7 @@ import { textResult } from "./helpers.js";
 export function registerCategoryTools(server, ctx) {
     const log = ctx.log.child({ component: "list_categories" });
     server.registerTool("list_categories", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "List all recipe categories with the number of recipes in each. Categories are sorted alphabetically.",
         inputSchema: {},
     }, async (_args) => {

package/dist/tools/category-writes.js

@@ -11,6 +11,7 @@ function categorySummary(ctx, category) {
 export function registerCreateCategoryTool(server, ctx) {
     const log = ctx.log.child({ component: "create_category" });
     server.registerTool("create_category", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Create a new recipe category. Optionally nest it under an existing category by passing that " +
             "category's UID as `parentUid` to build a hierarchy (e.g. Thai → Curries). Use `list_categories` " +
             "to find parent UIDs. To put recipes in the new category, follow up with `update_recipe`.",
@@ -45,6 +46,7 @@ export function registerCreateCategoryTool(server, ctx) {
 export function registerUpdateCategoryTool(server, ctx) {
     const log = ctx.log.child({ component: "update_category" });
     server.registerTool("update_category", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Rename and/or re-parent an existing category. Pass `name` to rename, `parentUid` to move it under " +
             "another category, or `null` for `parentUid` to make it top-level. Re-parenting builds the hierarchy " +
             "that `list_categories` renders.",
@@ -99,6 +101,7 @@ export function registerUpdateCategoryTool(server, ctx) {
 export function registerDeleteCategoryTool(server, ctx) {
     const log = ctx.log.child({ component: "delete_category" });
     server.registerTool("delete_category", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Delete a category. Refuses if the category still has child categories or is assigned to any recipe — " +
             "reassign or delete those first (move recipes with `update_recipe`, re-parent children with " +
             "`update_category`). This keeps the hierarchy and recipe links consistent.",

package/dist/tools/create.js

@@ -6,6 +6,7 @@ import { coldStartGuard, commitRecipe, recipeToMarkdown, resolveCategoryRefs, te
 export function registerCreateTool(server, ctx) {
     const log = ctx.log.child({ component: "create_recipe" });
     server.registerTool("create_recipe", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Create a new recipe in the Paprika account. If you built this recipe from a web page, " +
             "follow up with `upload_recipe_photo` and the page's main/hero (og:image) image URL to attach its photo.",
         inputSchema: {

package/dist/tools/delete.js

@@ -4,6 +4,7 @@ import { coldStartGuard, commitRecipe, textResult } from "./helpers.js";
 export function registerDeleteTool(server, ctx) {
     const log = ctx.log.child({ component: "trash_recipe" });
     server.registerTool("trash_recipe", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
         description: "Soft-delete a recipe by UID, moving it to the Paprika trash. " +
             "This operation is reversible — trashed recipes can be recovered in the Paprika app. " +
             "Requires an exact UID; fuzzy title matching is not supported to prevent accidental deletion.",

package/dist/tools/discover.js

@@ -3,6 +3,7 @@ import { coldStartGuard, recipeMetadataLines, textResult } from "./helpers.js";
 export function registerDiscoverTool(server, ctx, vectorStore) {
     const log = ctx.log.child({ component: "discover_recipes" });
     server.registerTool("discover_recipes", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "Discover recipes using semantic search. Finds recipes matching a natural language description of what you're looking for.",
         inputSchema: {
             query: z.string().describe("Natural language description of what you're looking for"),

package/dist/tools/empty-trash.js

@@ -5,6 +5,7 @@ import { coldStartGuard, commitRecipeHardDelete, reconcileLocalRecipe, reconcile
 export function registerEmptyTrashTool(server, ctx) {
     const log = ctx.log.child({ component: "purge_recipe" });
     server.registerTool("purge_recipe", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
         description: "Permanently delete a recipe that is already in the Paprika trash. " +
             "This is IRREVERSIBLE — once emptied from the trash the recipe cannot be recovered. " +
             "The recipe must first be moved to the trash with trash_recipe (a reversible soft-delete); " +

package/dist/tools/grocery-clear.js

@@ -5,6 +5,7 @@ import { textResult } from "./helpers.js";
 export function registerClearPurchasedTool(server, ctx) {
     const log = ctx.log.child({ component: "clear_purchased_grocery_items" });
     server.registerTool("clear_purchased_grocery_items", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Clear all purchased items from a grocery list.",
         inputSchema: {
             listUid: GroceryListUidSchema.describe("Grocery list UID to clear purchased items from"),
@@ -37,6 +38,7 @@ export function registerClearPurchasedTool(server, ctx) {
 export function registerClearAllTool(server, ctx) {
     const log = ctx.log.child({ component: "clear_grocery_list" });
     server.registerTool("clear_grocery_list", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Clear all items from a grocery list.",
         inputSchema: {
             listUid: GroceryListUidSchema.describe("Grocery list UID to clear all items from"),

package/dist/tools/grocery-item-purchase.js

@@ -11,6 +11,7 @@ export const markGroceryItemPurchasedInputSchema = z
 export function registerMarkGroceryItemPurchasedTool(server, ctx) {
     const log = ctx.log.child({ component: "mark_grocery_item_purchased" });
     server.registerTool("mark_grocery_item_purchased", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         description: "Mark a grocery item as purchased (checked off) by UID.",
         inputSchema: markGroceryItemPurchasedInputSchema,
     }, async (args) => {

package/dist/tools/grocery-item.js

@@ -17,6 +17,7 @@ const itemInputSchema = z.object({
 export function registerAddGroceryItemsTool(server, ctx) {
     const log = ctx.log.child({ component: "add_grocery_items" });
     server.registerTool("add_grocery_items", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Add one or more items to a grocery list. Check read_grocery_list first to avoid duplicate ingredients — no server-side duplicate guard.",
         inputSchema: {
             listUid: GroceryListUidSchema.describe("UID of the grocery list to add items to"),
@@ -150,6 +151,7 @@ export const updateGroceryItemInputSchema = z
 export function registerUpdateGroceryItemTool(server, ctx) {
     const log = ctx.log.child({ component: "update_grocery_item" });
     server.registerTool("update_grocery_item", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Update a grocery item's quantity, aisle, or notes by UID. Only provided fields are changed; " +
             "omitted fields retain their current values. To check an item off, use mark_grocery_item_purchased.",
         inputSchema: updateGroceryItemInputSchema,
@@ -188,6 +190,7 @@ export function registerUpdateGroceryItemTool(server, ctx) {
 export function registerDeleteGroceryItemTool(server, ctx) {
     const log = ctx.log.child({ component: "delete_grocery_item" });
     server.registerTool("delete_grocery_item", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Delete a grocery item by UID.",
         inputSchema: {
             uid: GroceryItemUidSchema.describe("Grocery item UID to delete"),

package/dist/tools/grocery-list.js

@@ -6,6 +6,7 @@ import { formatLookupOutcome, resolveLookup, textResult, uidOrTextLookupSchema }
 export function registerListGroceryListsTool(server, ctx) {
     const log = ctx.log.child({ component: "list_grocery_lists" });
     server.registerTool("list_grocery_lists", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "List all grocery lists sorted alphabetically by name, with UID and item count per list.",
         inputSchema: {},
     }, async () => {
@@ -28,6 +29,7 @@ export function registerListGroceryListsTool(server, ctx) {
 export function registerReadGroceryListTool(server, ctx) {
     const log = ctx.log.child({ component: "read_grocery_list" });
     server.registerTool("read_grocery_list", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "Get a grocery list by UID or name. Name lookup is tiered (exact → starts-with → contains) " +
             "and case-insensitive, with a disambiguation list when multiple lists match the same tier. " +
             'Pass exactly one shape: {"uid": "..."} or {"name": "..."}.',
@@ -58,6 +60,7 @@ export function registerReadGroceryListTool(server, ctx) {
 export function registerCreateGroceryListTool(server, ctx) {
     const log = ctx.log.child({ component: "create_grocery_list" });
     server.registerTool("create_grocery_list", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Create a new grocery list with the given name. Rejects duplicate names (case-insensitive exact match); " +
             "if a duplicate is found, the response includes the existing UID.",
         inputSchema: {
@@ -99,6 +102,7 @@ export function registerCreateGroceryListTool(server, ctx) {
 export function registerRenameGroceryListTool(server, ctx) {
     const log = ctx.log.child({ component: "rename_grocery_list" });
     server.registerTool("rename_grocery_list", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         description: "Rename a grocery list. Rejects if the new name conflicts with a different existing list.",
         inputSchema: {
             uid: GroceryListUidSchema.describe("Grocery list UID to rename"),
@@ -140,6 +144,7 @@ export function registerRenameGroceryListTool(server, ctx) {
 export function registerDeleteGroceryListTool(server, ctx) {
     const log = ctx.log.child({ component: "delete_grocery_list" });
     server.registerTool("delete_grocery_list", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Delete a grocery list by UID.",
         inputSchema: {
             uid: GroceryListUidSchema.describe("Grocery list UID to delete"),

package/dist/tools/grocery-move.js

@@ -8,6 +8,7 @@ import { commitPantryItemsBatch } from "./pantry-helpers.js";
 export function registerMoveToPantryTool(server, ctx) {
     const log = ctx.log.child({ component: "move_grocery_items_to_pantry" });
     server.registerTool("move_grocery_items_to_pantry", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
         description: "Move one or more grocery items to the pantry. Creates pantry items (with today's purchase date), then deletes the grocery items.",
         inputSchema: {
             uids: z.array(GroceryItemUidSchema).min(1).describe("Grocery item UIDs to move to pantry"),

package/dist/tools/list.js

@@ -3,6 +3,7 @@ import { coldStartGuard, textResult } from "./helpers.js";
 export function registerListTool(server, ctx) {
     const log = ctx.log.child({ component: "list_recipes" });
     server.registerTool("list_recipes", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "List all recipes with pagination. Returns recipe summaries sorted alphabetically. Use offset/limit to paginate through the full library. Response includes total recipe count.",
         inputSchema: {
             offset: z.number().int().nonnegative().optional().default(0).describe("Number of recipes to skip (default: 0)"),

package/dist/tools/meal-add-menu.js

@@ -56,6 +56,7 @@ function renderPlannerAdds(menuName, startDay, items) {
 export function registerAddMenuToPlannerTool(server, ctx) {
     const log = ctx.log.child({ component: "schedule_menu" });
     server.registerTool("schedule_menu", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Instantiate a saved menu's recipes as meal-planner entries. Look the menu up by UID or name " +
             "(tiered fuzzy match), then materialize each of its items into a meal dated start_date + (day − 1) " +
             "days, posting them all in one batch. This is a one-way COPY, not a link: the planner meals carry no " +

package/dist/tools/meal-history-search.js

@@ -30,6 +30,7 @@ export const searchMealHistoryInputSchema = z
 export function registerSearchMealHistoryTool(server, ctx) {
     const log = ctx.log.child({ component: "search_meal_history" });
     server.registerTool("search_meal_history", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: 'Search PAST meals (recall/browse), by a specific recipe, a recipe category ("class"), a meal type, ' +
             'and/or a date window — any combination, ANDed. Answers "when did we last have tacos", "how often do ' +
             'we eat Italian", "show the dinners we had in March", or "what have we eaten lately". With no filters ' +

package/dist/tools/meal-log-cooked.js

@@ -21,6 +21,7 @@ export const logCookedMealInputSchema = z
 export function registerLogCookedMealTool(server, ctx) {
     const log = ctx.log.child({ component: "log_cooked_meal" });
     server.registerTool("log_cooked_meal", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Log a meal you cooked: records the given recipe on the planner, defaulting to today and the Dinner " +
             "meal type — a quick way to keep your cooking history current. Pass `date` to log a different day or " +
             "`type` for a non-dinner meal. To log a freeform (non-recipe) meal or to plan ahead in bulk, use plan_meals.",

package/dist/tools/meal-plan-read.js

@@ -16,6 +16,7 @@ export const readMealPlanInputSchema = z
 export function registerReadMealPlanTool(server, ctx) {
     const log = ctx.log.child({ component: "read_meal_plan" });
     server.registerTool("read_meal_plan", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "Read the upcoming meal plan: meals scheduled from today forward, grouped by day in ascending date " +
             'order (today first). Defaults to the next 7 days; pass `days` to widen the window. For past meals or recall ("when did we last have X"), use search_meal_history.',
         inputSchema: readMealPlanInputSchema,

package/dist/tools/meal-reschedule.js

@@ -24,6 +24,7 @@ export const rescheduleMealInputSchema = z
 export function registerRescheduleMealTool(server, ctx) {
     const log = ctx.log.child({ component: "reschedule_meal" });
     server.registerTool("reschedule_meal", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         description: "Reschedule a planned meal to a different date by UID, optionally also changing its meal type. " +
             "Moving the date re-sequences the meal to the end of the destination day's order. To change a " +
             "meal's recipe link, freeform name, or scale instead, use update_meal.",

package/dist/tools/meal-types.js

@@ -35,6 +35,7 @@ function mealTypeLine(mt) {
 export function registerMealTypesTool(server, ctx) {
     const log = ctx.log.child({ component: "list_meal_types" });
     server.registerTool("list_meal_types", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "List all meal types — the built-in Breakfast/Lunch/Dinner/Snacks plus any custom " +
             "types — sorted by order then name. Each entry shows whether it is built-in or custom, " +
             "its calendar-export schedule (all-day or a clock time), and its UID. Reference a type " +

package/dist/tools/meal-writes.js

@@ -55,6 +55,7 @@ export const addMealsInputSchema = z.object({
 export function registerAddMealsTool(server, ctx) {
     const log = ctx.log.child({ component: "plan_meals" });
     server.registerTool("plan_meals", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Add one or more meals to the meal planner. Each item is EITHER recipe-linked (supply " +
             "recipe_uid; display name auto-resolves from the recipe) OR freeform (supply name; no " +
             "recipe). The two shapes are mutually exclusive — Paprika.app's UI dispatches display " +
@@ -226,6 +227,7 @@ export const updateMealInputSchema = z.object({
 export function registerUpdateMealTool(server, ctx) {
     const log = ctx.log.child({ component: "update_meal" });
     server.registerTool("update_meal", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Update an existing meal by UID. The `update` payload is a discriminated union: pick exactly one " +
             "of {recipe_uid?, ...other} | {name, ...other} | {recipe_uid: null, name?, ...other}. Recipe link " +
             "and display name are structurally exclusive: name auto-resolves from the recipe for linked meals, " +
@@ -368,6 +370,7 @@ const deleteMealInputSchema = z.object({
 export function registerDeleteMealTool(server, ctx) {
     const log = ctx.log.child({ component: "delete_meal" });
     server.registerTool("delete_meal", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Soft-delete a meal from the planner by UID. Idempotent: a second delete on the same UID " +
             "returns a friendly 'already deleted' message without re-POSTing. Requires an exact UID.",
         inputSchema: deleteMealInputSchema.shape,

package/dist/tools/menu-item-move.js

@@ -20,6 +20,7 @@ export const moveMenuItemInputSchema = z
 export function registerMoveMenuItemTool(server, ctx) {
     const log = ctx.log.child({ component: "move_menu_item" });
     server.registerTool("move_menu_item", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         description: "Move a menu item to a different day within its menu, by UID. A day beyond the menu's current span " +
             "auto-extends the menu so the item stays visible, and the item is re-sequenced to the end of the " +
             "menu's order. To change a menu item's meal type or recipe link instead, use update_menu_item.",

package/dist/tools/menu-item-write.js

@@ -47,6 +47,7 @@ export const addMenuItemsInputSchema = z.object({
 export function registerAddMenuItemsTool(server, ctx) {
     const log = ctx.log.child({ component: "add_menu_items" });
     server.registerTool("add_menu_items", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Add one or more menuitems to a menu (saved meal plan). Look the menu up by UID or name (tiered " +
             "fuzzy match). Each item is EITHER recipe-linked (supply recipe_uid; display name auto-resolves " +
             "from the recipe) OR freeform (supply name; no recipe) — the two are mutually exclusive, matching " +
@@ -205,6 +206,7 @@ export const updateMenuItemInputSchema = z
 export function registerUpdateMenuItemTool(server, ctx) {
     const log = ctx.log.child({ component: "update_menu_item" });
     server.registerTool("update_menu_item", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Update an existing menuitem's meal type or recipe link by UID. Provide at least one of type or " +
             "recipe_uid; omitted fields keep their current values. Changing recipe_uid re-resolves the display " +
             "name from the new recipe. To move an item to a different day, use move_menu_item. The menu link " +
@@ -283,6 +285,7 @@ export const deleteMenuItemInputSchema = z.object({
 export function registerDeleteMenuItemTool(server, ctx) {
     const log = ctx.log.child({ component: "delete_menu_item" });
     server.registerTool("delete_menu_item", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Soft-delete a menuitem (a planned recipe) from a menu by UID. Idempotent: a second delete on the " +
             "same UID returns a friendly 'already deleted' message without re-POSTing. Requires an exact UID.",
         inputSchema: deleteMenuItemInputSchema.shape,

package/dist/tools/menu-read.js

@@ -4,6 +4,7 @@ import { menuStartGuard, menuToMarkdown } from "./menu-helpers.js";
 export function registerListMenusTool(server, ctx) {
     const log = ctx.log.child({ component: "list_menus" });
     server.registerTool("list_menus", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "List all menus (saved meal plans) in Paprika order, with item count and day span per menu. " +
             "Use read_menu to see a menu's full day-by-day breakdown.",
         inputSchema: {},
@@ -26,6 +27,7 @@ export function registerListMenusTool(server, ctx) {
 export function registerReadMenuTool(server, ctx) {
     const log = ctx.log.child({ component: "read_menu" });
     server.registerTool("read_menu", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "Get a menu by UID or name, rendered day by day with each day's planned recipes. " +
             "Name lookup is tiered (exact → starts-with → contains) and case-insensitive, with a " +
             "disambiguation list when multiple menus match the same tier. Each recipe line carries " +

package/dist/tools/menu-write.js

@@ -6,6 +6,7 @@ import { commitMenu, commitMenuItemsBatch, menuStartGuard, menuToMarkdown } from
 export function registerCreateMenuTool(server, ctx) {
     const log = ctx.log.child({ component: "create_menu" });
     server.registerTool("create_menu", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Create a new menu (saved meal plan) with the given name. Rejects duplicate names " +
             "(case-insensitive exact match); if a duplicate is found, the response includes the existing UID. " +
             "Optionally set the day span (default 1) and free-text notes.",
@@ -57,6 +58,7 @@ export function registerCreateMenuTool(server, ctx) {
 export function registerUpdateMenuTool(server, ctx) {
     const log = ctx.log.child({ component: "update_menu" });
     server.registerTool("update_menu", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Update a menu's name, day span, and/or notes. Look it up by UID or name (tiered fuzzy match, " +
             "case-insensitive). Provide at least one of name, days, or notes. Renaming to a name already used " +
             "by a different menu is rejected (the existing UID is surfaced). Shrinking days below the highest " +
@@ -154,6 +156,7 @@ export function registerUpdateMenuTool(server, ctx) {
 export function registerDeleteMenuTool(server, ctx) {
     const log = ctx.log.child({ component: "delete_menu" });
     server.registerTool("delete_menu", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
         description: "Delete a menu and all of its planned recipes (menuitems). Look it up by UID or name (tiered fuzzy " +
             "match, case-insensitive). The menuitems are tombstoned first, then the menu itself. " +
             'Pass exactly one lookup shape: {"uid": "..."} or {"name": "..."}.',

package/dist/tools/pantry-batch-add.js

@@ -20,6 +20,7 @@ const itemInputSchema = z.object({
 export function registerAddPantryItemsTool(server, ctx) {
     const log = ctx.log.child({ component: "add_pantry_items" });
     server.registerTool("add_pantry_items", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Add one or more items to the pantry. Skips items that duplicate an existing ingredient (case-insensitive) " +
             "and reports them with the existing UID and a suggestion to use update_pantry_item. " +
             "All date fields are validated up-front; a single unparseable date rejects the entire batch.",

package/dist/tools/pantry-delete.js

@@ -5,6 +5,7 @@ import { commitPantryItem, pantryStartGuard } from "./pantry-helpers.js";
 export function registerDeletePantryItemTool(server, ctx) {
     const log = ctx.log.child({ component: "delete_pantry_item" });
     server.registerTool("delete_pantry_item", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Soft-delete a pantry item by UID. Idempotent: a second delete on the same UID " +
             "returns a friendly 'already deleted' message without re-saving. Requires an exact UID.",
         inputSchema: {

package/dist/tools/pantry-get.js

@@ -4,6 +4,7 @@ import { pantryItemToMarkdown, pantryStartGuard } from "./pantry-helpers.js";
 export function registerGetPantryItemTool(server, ctx) {
     const log = ctx.log.child({ component: "read_pantry_item" });
     server.registerTool("read_pantry_item", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "Get a pantry item by UID or ingredient name. Ingredient lookup is fuzzy " +
             "(exact → starts-with → contains) and case-insensitive, with a disambiguation list " +
             "when multiple items match the same tier. " +

package/dist/tools/pantry-list.js

@@ -3,6 +3,7 @@ import { pantryStartGuard } from "./pantry-helpers.js";
 export function registerListPantryTool(server, ctx) {
     const log = ctx.log.child({ component: "list_pantry_items" });
     server.registerTool("list_pantry_items", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "List all pantry items sorted alphabetically by ingredient name. Returns the ingredient, quantity, and aisle for each item. Use read_pantry_item with the UID for full details.",
         inputSchema: {},
     }, async () => {

package/dist/tools/pantry-stock.js

@@ -16,6 +16,7 @@ export const restockPantryItemInputSchema = z
 export function registerMarkPantryItemOutOfStockTool(server, ctx) {
     const log = ctx.log.child({ component: "mark_pantry_item_out_of_stock" });
     server.registerTool("mark_pantry_item_out_of_stock", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         description: "Mark a pantry item as out of stock by UID (e.g. you've run out of it).",
         inputSchema: markPantryItemOutOfStockInputSchema,
     }, async (args) => {
@@ -43,6 +44,7 @@ export function registerMarkPantryItemOutOfStockTool(server, ctx) {
 export function registerRestockPantryItemTool(server, ctx) {
     const log = ctx.log.child({ component: "restock_pantry_item" });
     server.registerTool("restock_pantry_item", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         description: "Mark a pantry item as back in stock by UID (e.g. you've restocked it).",
         inputSchema: restockPantryItemInputSchema,
     }, async (args) => {

package/dist/tools/pantry-update.js

@@ -28,6 +28,7 @@ export const updatePantryItemInputSchema = z
 export function registerUpdatePantryItemTool(server, ctx) {
     const log = ctx.log.child({ component: "update_pantry_item" });
     server.registerTool("update_pantry_item", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Update a pantry item's ingredient, quantity, aisle, or dates by UID. Only provided fields are " +
             "changed; omitted fields retain their existing values. Setting expirationDate also updates " +
             "hasExpiration accordingly. To change stock status, use mark_pantry_item_out_of_stock / restock_pantry_item.",

package/dist/tools/photo-generate.js

@@ -41,6 +41,7 @@ export const generatePhotoInputSchema = z.object({
 export function registerGeneratePhotoTool(server, ctx, photographyClient) {
     const log = ctx.log.child({ component: "generate_recipe_photo" });
     server.registerTool("generate_recipe_photo", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Generate a styled food photo for a recipe with an AI image model and (by default) attach it to the " +
             "recipe. The prompt is built from the recipe's name, description, and categories — so well-described, " +
             "categorized recipes produce the best results; pass `style` to guide plating or describe an obscure dish. " +

package/dist/tools/photo-writes.js

@@ -99,6 +99,7 @@ async function resolveSourceBytes(source, ctx, recipeUid) {
 export function registerUploadPhotoTool(server, ctx) {
     const log = ctx.log.child({ component: "upload_recipe_photo" });
     server.registerTool("upload_recipe_photo", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
         description: "Attach a photo to a recipe from exactly one `source`: a `url` (PREFERRED for web images — the server " +
             "downloads it), a `generation_token` (to save an image you previewed with generate_recipe_photo, attach:false — " +
             "no need to regenerate), or, for programmatic callers, inline `image_base64`. If you built the recipe " +
@@ -160,6 +161,7 @@ export function registerUploadPhotoTool(server, ctx) {
 export function registerDeletePhotoTool(server, ctx) {
     const log = ctx.log.child({ component: "delete_recipe_photo" });
     server.registerTool("delete_recipe_photo", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Delete a photo from a recipe by UID. Idempotent: a second delete on the same UID returns a friendly " +
             "'already deleted' message without re-POSTing. Requires an exact photo UID.",
         inputSchema: deletePhotoInputSchema.shape,

package/dist/tools/read.js

@@ -3,6 +3,7 @@ import { coldStartGuard, formatLookupOutcome, recipeToMarkdown, resolveLookup, u
 export function registerReadTool(server, ctx) {
     const log = ctx.log.child({ component: "read_recipe" });
     server.registerTool("read_recipe", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "Read a recipe by UID or title. Title lookup is fuzzy (exact → starts-with → contains) " +
             "and returns a disambiguation list when multiple recipes match the same tier. " +
             'Pass exactly one shape: {"uid": "..."} or {"title": "..."}.',

package/dist/tools/recipe-categorize.js

@@ -24,6 +24,7 @@ export const categorizeRecipeInputSchema = z
 export function registerCategorizeRecipeTool(server, ctx) {
     const log = ctx.log.child({ component: "categorize_recipe" });
     server.registerTool("categorize_recipe", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Add, replace, or remove a recipe's categories by UID. Pass category names or UIDs and a mode: " +
             "add (union with current — the default), replace (set exactly these), or remove (drop these). " +
             "Unknown category names are skipped with a warning. To edit other recipe fields, use update_recipe.",

package/dist/tools/recipe-favorite.js

@@ -15,6 +15,7 @@ export const unfavoriteRecipeInputSchema = z
 export function registerFavoriteRecipeTool(server, ctx) {
     const log = ctx.log.child({ component: "favorite_recipe" });
     server.registerTool("favorite_recipe", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         description: "Mark a recipe as a favorite by UID (adds it to the Favorites list).",
         inputSchema: favoriteRecipeInputSchema,
     }, async (args) => {
@@ -43,6 +44,7 @@ export function registerFavoriteRecipeTool(server, ctx) {
 export function registerUnfavoriteRecipeTool(server, ctx) {
     const log = ctx.log.child({ component: "unfavorite_recipe" });
     server.registerTool("unfavorite_recipe", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         description: "Remove a recipe from the Favorites list by UID.",
         inputSchema: unfavoriteRecipeInputSchema,
     }, async (args) => {

package/dist/tools/recipe-rating.js

@@ -11,6 +11,7 @@ export const rateRecipeInputSchema = z
 export function registerRateRecipeTool(server, ctx) {
     const log = ctx.log.child({ component: "rate_recipe" });
     server.registerTool("rate_recipe", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         description: "Rate a recipe 0–5 stars by UID. Sets the recipe's star rating; pass 0 to clear it.",
         inputSchema: rateRecipeInputSchema,
     }, async (args) => {

package/dist/tools/recipe-restore.js

@@ -11,6 +11,7 @@ export const restoreRecipeInputSchema = z
 export function registerRestoreRecipeTool(server, ctx) {
     const log = ctx.log.child({ component: "restore_recipe" });
     server.registerTool("restore_recipe", {
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
         description: "Restore a trashed recipe by UID, moving it out of the trash back into the active library. " +
             "The inverse of trash_recipe; use purge_recipe to permanently delete a trashed recipe instead.",
         inputSchema: restoreRecipeInputSchema,

package/dist/tools/search.js

@@ -31,6 +31,7 @@ export const searchRecipesInputSchema = z
 export function registerSearchTool(server, ctx) {
     const log = ctx.log.child({ component: "search_recipes" });
     server.registerTool("search_recipes", {
+        annotations: { readOnlyHint: true, idempotentHint: true },
         description: "Search and filter recipes. Use any combination of: free-text query (matches name, " +
             "ingredients, description), an ingredient list with all/any match mode, and/or max " +
             "prep/cook/total time constraints. At least one criterion is required. Results are " +

package/dist/tools/update.js

@@ -29,6 +29,7 @@ export const updateRecipeInputSchema = z
 export function registerUpdateTool(server, ctx) {
     const log = ctx.log.child({ component: "update_recipe" });
     server.registerTool("update_recipe", {
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
         description: "Update a recipe's content fields by UID (name, ingredients, directions, description, notes, " +
             "servings, prep/cook/total time, source, difficulty, nutritional info). Only provided fields " +
             "change; omitted fields keep their values. This tool does NOT edit rating, categories, favorite " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bojanrajkovic/mcp-paprika",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0-beta.2",
   "description": "MCP server for Paprika recipe manager",
   "license": "MIT",
   "repository": {