@sentry/junior-notion 0.8.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # @sentry/junior-notion
 
-`@sentry/junior-notion` adds read-only Notion search workflows for pages and data sources to Junior via a shared internal Notion integration.
+`@sentry/junior-notion` adds read-only Notion search workflows for pages and data sources to Junior through Notion's hosted MCP server.
 
 Install it alongside `@sentry/junior`:
 
@@ -8,21 +8,6 @@ Install it alongside `@sentry/junior`:
 pnpm add @sentry/junior @sentry/junior-notion
 ```
 
-Create an internal Notion integration by following Notion's Authorization guide:
-
-- https://developers.notion.com/guides/get-started/authorization
-
-In the Notion integration settings:
-
-- choose the workspace where the integration will live
-- enable the `Read content` capability
-- copy the integration secret from the `Configuration` tab
-- share any pages or data sources Junior should read via `•••` -> `Add connections`
-
-Set that value in your host environment:
-
-- `NOTION_TOKEN`
-
 Then register the plugin package in `withJunior(...)`:
 
 ```js
@@ -33,24 +18,23 @@ export default withJunior({
 });
 ```
 
-There is no `/notion auth` flow for this plugin. Once the token is configured and pages or data sources are shared with the integration, users can run `/notion <query>` directly.
+This package does not use `NOTION_TOKEN` or a shared workspace integration. Each user connects their own Notion account the first time Junior calls a Notion MCP tool. Junior sends the OAuth link privately and resumes the thread automatically after the user authorizes.
 
-## Search limitations
+Junior intentionally keeps this package read-only by exposing only Notion's `notion-search` and `notion-fetch` MCP tools. The plugin does not expose create, update, move, or other write-capable Notion tools.
 
-This plugin currently uses Notion's public `v1` API for search and content retrieval.
+## Search limitations
 
-- `v1/search` is title-biased and does not match the richer `Best matches` behavior users see in notion.so.
-- Results can differ from the UI even when the user can see a page in the Notion app.
-- The most common cause of missing results is that the target page or data source is not directly shared with the integration.
-- Newly shared content can also lag behind search indexing.
+This package uses Notion MCP search and fetch rather than the older REST helper flow.
 
-We also tested Notion's private `api/v3/search` endpoint with the same integration token. It accepted the token at the HTTP layer, but it did not return useful results for the same sample queries, so this plugin does not depend on `api/v3`.
+- Search is still title-biased, so prompts work best when users search for the actual page or data source title.
+- Results can differ from the Notion UI even when the user can see a page in the app.
+- Search across connected sources like Slack, Google Drive, and Jira requires a Notion AI plan. Without Notion AI, search is limited to the user's Notion workspace.
+- Missing results are usually a permissions problem on the user's Notion account or a weak query phrase.
 
-For local debugging, the package exposes one Notion helper script through two subcommands that load the workspace env first:
+## Auth model
 
-```bash
-pnpm notion:search -- --query "company holidays"
-pnpm notion:fetch -- --id "<notion-id>" --object page
-```
+- Notion MCP requires user-based OAuth and does not support bearer token authentication.
+- This package is not suitable for fully headless or unattended automation.
+- Users can disconnect from Junior App Home with `Unlink`, or by asking Junior to disconnect Notion.
 
 Full setup guide: https://junior.sentry.dev/extend/notion-plugin/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-notion",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/plugin.yaml

@@ -1,13 +1,9 @@
 name: notion
 description: Notion page search and summarization
 
-capabilities:
-  - api
-
-credentials:
-  type: oauth-bearer
-  api-domains:
-    - api.notion.com
-  api-headers:
-    Notion-Version: "2025-09-03"
-  auth-token-env: NOTION_TOKEN
+mcp:
+  transport: http
+  url: https://mcp.notion.com/mcp
+  allowed-tools:
+    - notion-search
+    - notion-fetch

package/skills/notion/SKILL.md

@@ -1,48 +1,51 @@
 ---
 name: notion
 description: Search Notion pages and data sources and summarize the best match. Use when users ask to look up docs, specs, notes, meeting notes, project context, roadmaps, trackers, or internal references stored in Notion.
-requires-capabilities: notion.api
-allowed-tools: bash
 ---
 
 # Notion Operations
 
-Use this skill for `/notion` workflows in the harness.
+Use this skill for Notion search and summarization workflows in the harness.
 
 ## Workflow
 
-1. Classify the request:
+1. Treat the request as a read-only query.
 
-- `auth`: explain that this plugin uses a shared internal Notion integration, so there is no per-user auth flow. Tell the user the workspace admin must configure `NOTION_TOKEN` and share the relevant pages or data sources with the integration.
-- `disconnect`: explain that there is no per-user Notion connection to remove because the plugin uses a shared internal integration.
-- otherwise treat the request as a read-only query.
+2. Keep tool work mostly silent:
 
-2. Enable credentials:
+- Send at most one short acknowledgment before Notion tool work.
+- Keep intermediate search/fetch reasoning internal.
+- Do not narrate each step with "let me...", "I found...", or partial findings while tools are still running.
+- Reply with the real answer once you have enough evidence, or explain the actual blocker if you cannot finish.
 
-- Before any Notion API call, run `jr-rpc issue-credential notion.api`.
-- If credential issuance fails, explain that Notion is not configured on the host and the admin must set `NOTION_TOKEN`.
+3. Search with MCP:
 
-3. Search with the checked-in helper:
-
-- Do not improvise `curl` requests or inline `node` snippets for Notion.
+- `loadSkill` returns `available_tools` for this skill, including the exact `tool_name` values and argument schemas for the Notion tools exposed in this turn.
+- Use `useTool` with those exact `tool_name` values.
+- Use `searchTools` only if you need to rediscover or filter the active Notion tools later in the turn.
 - Decide the actual search phrases first. Notion search is title-biased, so search for the likely page or data source title, not the user's full sentence.
 - Use 1-3 short explicit search phrases.
 - Good: `deployment pipeline`, `launch tracker`, `incident review`
 - Bad: `how do we handle deployment pipelines for mobile releases`
-- Run search with the loaded `skill_dir` path:
-  `node <skill_dir>/scripts/notion-cli.mjs search --query "<best phrase>" --query "<fallback phrase>"`
-- If the first phrase misses, rerun with 1-2 alternate title-style phrases.
-- Search returns ranked page/data-source candidates only. Pick the best candidate, then fetch content with:
-  `node <skill_dir>/scripts/notion-cli.mjs fetch --id "<result id>" --object "page"`
-  or
-  `node <skill_dir>/scripts/notion-cli.mjs fetch --id "<result id>" --object "data_source"`
-- Use the fetch output to summarize page markdown, or summarize the data source schema and returned rows.
+- For list/report/calendar requests, search for the canonical container first:
+  - page title: `holidays`, `company holidays`
+  - data source title: `people calendar`
+- Prefer one refinement round at most. If the first search already found a plausible canonical page or data source, fetch it before searching again.
+
+4. Fetch efficiently:
+
+- Search returns ranked page and data-source candidates only. Pick the best candidate, then fetch content with the disclosed Notion fetch tool via `useTool` using the returned URL or ID.
+- If a fetched page clearly points at an inline data source or database, fetch that data source next and work from it.
+- If the fetched data source already contains the rows and fields needed to answer, stop there and answer from that result.
+- Do not serially fetch many individual row pages when the container page or data source already exposes the needed fields.
+- Fetch individual rows only when a small number of important fields are still missing or ambiguous after fetching the canonical page or data source.
+- Once you have enough evidence to answer, stop fetching and respond.
 
 ## Guardrails
 
 - Read-only only.
-- Do not print credential values.
-- The runtime injects `Authorization` and `Notion-Version`; the helper handles request-specific headers.
+- Junior intentionally exposes only Notion search and fetch tools for this skill. Do not ask for writes, comments, or page moves.
 - Search results may be pages or data sources. Do not treat data sources as unsupported.
-- If search returns no accessible matches, say that no accessible pages or data sources matched and note the content may not be shared with the integration yet.
+- For scoped requests like "US holidays" or "2026 holidays", apply the user's scope when reading the fetched content and state any assumption you made if the source mixes multiple geos or years.
+- If search returns no accessible matches, say that no accessible pages or data sources matched and note that the content may be outside the user's Notion permissions or poorly matched by title.
 - If content retrieval fails for the top result, return the best matching Notion URL and explain that the result could not be fetched for summarization.

package/skills/notion/scripts/notion-cli.mjs

@@ -1,557 +0,0 @@
-#!/usr/bin/env node
-
-import { pathToFileURL } from "node:url";
-
-/**
- * Unified Notion helper for LLM-facing search and fetch operations.
- *
- * `search` preserves the public v1 Search API's native ordering as closely as possible and
- * returns broad candidate results for the raw query without forcing a winner.
- *
- * `fetch` loads normalized content for a specific page or data source chosen from search
- * results so the model can summarize a stable payload.
- */
-
-const DEFAULT_API_BASE_URL = "https://api.notion.com/v1";
-// Keep this pinned in sync with packages/junior-notion/plugin.yaml.
-const DEFAULT_NOTION_VERSION = "2025-09-03";
-const DEFAULT_PAGE_SIZE = 100;
-const DEFAULT_ROW_LIMIT = 10;
-const DEFAULT_TIMEOUT_MS = 15_000;
-const DEFAULT_RETRY_LIMIT = 2;
-
-function parseArgs(argv) {
-  const parsed = {};
-  for (let index = 0; index < argv.length; index += 1) {
-    const token = argv[index];
-    if (!token.startsWith("--")) {
-      continue;
-    }
-    const [rawKey, inlineValue] = token.slice(2).split("=", 2);
-    if (inlineValue !== undefined) {
-      if (parsed[rawKey] === undefined) {
-        parsed[rawKey] = inlineValue;
-      } else if (Array.isArray(parsed[rawKey])) {
-        parsed[rawKey].push(inlineValue);
-      } else {
-        parsed[rawKey] = [parsed[rawKey], inlineValue];
-      }
-      continue;
-    }
-    const next = argv[index + 1];
-    if (!next || next.startsWith("--")) {
-      parsed[rawKey] = "true";
-      continue;
-    }
-    if (parsed[rawKey] === undefined) {
-      parsed[rawKey] = next;
-    } else if (Array.isArray(parsed[rawKey])) {
-      parsed[rawKey].push(next);
-    } else {
-      parsed[rawKey] = [parsed[rawKey], next];
-    }
-    index += 1;
-  }
-  return parsed;
-}
-
-function normalizeWhitespace(value) {
-  return String(value ?? "")
-    .replace(/\s+/g, " ")
-    .trim();
-}
-
-function toStringArray(value) {
-  if (Array.isArray(value)) {
-    return value.map((item) => normalizeWhitespace(item)).filter(Boolean);
-  }
-  const normalized = normalizeWhitespace(value);
-  return normalized ? [normalized] : [];
-}
-
-function buildSearchQueries(queries) {
-  const normalizedQueries = [];
-  const seenQueries = new Set();
-  for (const value of toStringArray(queries)) {
-    if (seenQueries.has(value)) {
-      continue;
-    }
-    seenQueries.add(value);
-    normalizedQueries.push(value);
-  }
-  return normalizedQueries;
-}
-
-function extractPlainText(value) {
-  if (typeof value === "string") {
-    return value;
-  }
-  if (!Array.isArray(value)) {
-    return "";
-  }
-  return value
-    .map((item) => {
-      if (typeof item?.plain_text === "string") {
-        return item.plain_text;
-      }
-      if (typeof item?.text?.content === "string") {
-        return item.text.content;
-      }
-      return "";
-    })
-    .join("")
-    .trim();
-}
-
-function extractTitleFromProperties(properties) {
-  if (!properties || typeof properties !== "object") {
-    return "";
-  }
-  for (const property of Object.values(properties)) {
-    if (property?.type === "title") {
-      return extractPlainText(property.title);
-    }
-  }
-  return "";
-}
-
-function extractResultTitle(result) {
-  if (!result || typeof result !== "object") {
-    return "";
-  }
-  if (Array.isArray(result.title)) {
-    return extractPlainText(result.title);
-  }
-  if (typeof result.title === "string") {
-    return result.title.trim();
-  }
-  if (result.properties) {
-    return extractTitleFromProperties(result.properties);
-  }
-  return "";
-}
-
-function simplifySearchResult(result) {
-  return {
-    id: String(result?.id ?? ""),
-    object: String(result?.object ?? ""),
-    title: extractResultTitle(result),
-    url: String(result?.url ?? ""),
-    last_edited_time: result?.last_edited_time ?? null,
-  };
-}
-
-function buildHeaders(extraHeaders) {
-  const headers = {
-    Accept: "application/json",
-    "Notion-Version": process.env.NOTION_VERSION || DEFAULT_NOTION_VERSION,
-    ...extraHeaders,
-  };
-  const token = normalizeWhitespace(process.env.NOTION_TOKEN);
-  // In sandboxed runs the broker can set a placeholder value here and inject the
-  // real Authorization header later, so skip the placeholder rather than sending it.
-  if (token && token !== "host_managed_credential") {
-    headers.Authorization = `Bearer ${token}`;
-  }
-  return headers;
-}
-
-function getApiBaseUrl() {
-  return normalizeWhitespace(process.env.NOTION_API_BASE_URL) || DEFAULT_API_BASE_URL;
-}
-
-function isRetryableStatus(status) {
-  return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
-}
-
-function parseRetryAfterMs(value) {
-  const seconds = Number.parseFloat(String(value ?? ""));
-  if (!Number.isFinite(seconds) || seconds < 0) {
-    return 0;
-  }
-  return Math.ceil(seconds * 1000);
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-async function notionRequest(pathname, init = {}, options = {}) {
-  const retryLimit = options.retryLimit ?? DEFAULT_RETRY_LIMIT;
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const method = init.method ?? "GET";
-  const headers = buildHeaders(init.headers ?? {});
-  const url = `${getApiBaseUrl()}${pathname}`;
-
-  for (let attempt = 0; attempt <= retryLimit; attempt += 1) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-      const response = await fetch(url, {
-        ...init,
-        method,
-        headers,
-        signal: controller.signal,
-      });
-      if (!response.ok) {
-        const bodyText = await response.text();
-        if (attempt < retryLimit && isRetryableStatus(response.status)) {
-          const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
-          await sleep(retryAfterMs || 250 * (attempt + 1));
-          continue;
-        }
-        throw new Error(
-          `Notion API ${method} ${pathname} failed with ${response.status}: ${bodyText || response.statusText}`,
-        );
-      }
-      const contentType = response.headers.get("content-type") || "";
-      if (contentType.includes("application/json")) {
-        return await response.json();
-      }
-      return await response.text();
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-
-  throw new Error(`Notion API ${method} ${pathname} failed after retries`);
-}
-
-async function searchOnce(query, pageSize, object) {
-  const body = {
-    query,
-    page_size: pageSize,
-  };
-  if (object) {
-    body.filter = {
-      property: "object",
-      value: object,
-    };
-  }
-  return await notionRequest("/search", {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify(body),
-  });
-}
-
-async function searchNotion({ queries = [], pageSize = DEFAULT_PAGE_SIZE, object = "" } = {}) {
-  const searchQueries = buildSearchQueries(queries);
-  const attempts = [];
-  const candidateMap = new Map();
-
-  for (const variant of searchQueries) {
-    const response = await searchOnce(variant, pageSize, object || undefined);
-    const results = Array.isArray(response?.results) ? response.results : [];
-    attempts.push({
-      query: variant,
-      object: object || "page_or_data_source",
-      result_count: results.length,
-      has_more: Boolean(response?.has_more),
-      next_cursor: response?.next_cursor ?? null,
-    });
-
-    for (const result of results) {
-      if (!result?.id || candidateMap.has(result.id)) {
-        continue;
-      }
-      candidateMap.set(result.id, {
-        ...simplifySearchResult(result),
-        query: variant,
-      });
-    }
-  }
-
-  return {
-    ok: true,
-    query_variants: searchQueries,
-    attempts,
-    result_count: candidateMap.size,
-    results: [...candidateMap.values()].map((candidate) => ({
-      id: candidate.id,
-      object: candidate.object,
-      title: candidate.title,
-      url: candidate.url,
-      last_edited_time: candidate.last_edited_time,
-      query: candidate.query,
-    })),
-  };
-}
-
-function simplifyFormulaValue(formula) {
-  if (!formula || typeof formula !== "object") {
-    return null;
-  }
-
-  switch (formula.type) {
-    case "string":
-      return formula.string ?? null;
-    case "number":
-      return formula.number ?? null;
-    case "boolean":
-      return formula.boolean ?? null;
-    case "date":
-      return formula.date
-        ? {
-            start: formula.date.start ?? null,
-            end: formula.date.end ?? null,
-          }
-        : null;
-    case "page":
-      return formula.page?.id ?? null;
-    case "person":
-      return formula.person?.name || formula.person?.id || null;
-    case "list":
-      return Array.isArray(formula.list)
-        ? formula.list.map((item) => simplifyFormulaValue(item)).filter((item) => item !== null)
-        : [];
-    default:
-      return null;
-  }
-}
-
-function simplifyPropertyValue(property) {
-  if (!property || typeof property !== "object") {
-    return null;
-  }
-  switch (property.type) {
-    case "title":
-      return extractPlainText(property.title);
-    case "rich_text":
-      return extractPlainText(property.rich_text);
-    case "status":
-      return property.status?.name ?? null;
-    case "select":
-      return property.select?.name ?? null;
-    case "multi_select":
-      return Array.isArray(property.multi_select)
-        ? property.multi_select.map((item) => item?.name).filter(Boolean)
-        : [];
-    case "number":
-      return property.number ?? null;
-    case "checkbox":
-      return property.checkbox ?? null;
-    case "url":
-      return property.url ?? null;
-    case "email":
-      return property.email ?? null;
-    case "phone_number":
-      return property.phone_number ?? null;
-    case "date":
-      return property.date
-        ? {
-            start: property.date.start ?? null,
-            end: property.date.end ?? null,
-          }
-        : null;
-    case "people":
-      return Array.isArray(property.people)
-        ? property.people.map((item) => item?.name || item?.id).filter(Boolean)
-        : [];
-    case "relation":
-      return Array.isArray(property.relation)
-        ? property.relation.map((item) => item?.id).filter(Boolean)
-        : [];
-    case "formula":
-      return simplifyFormulaValue(property.formula);
-    case "created_time":
-      return property.created_time ?? null;
-    case "last_edited_time":
-      return property.last_edited_time ?? null;
-    case "unique_id":
-      if (!property.unique_id) {
-        return null;
-      }
-      if (property.unique_id.prefix) {
-        return `${property.unique_id.prefix}-${property.unique_id.number ?? ""}`;
-      }
-      return property.unique_id.number ?? null;
-    default:
-      return null;
-  }
-}
-
-function simplifyPageRecord(page) {
-  const properties = {};
-  if (page?.properties && typeof page.properties === "object") {
-    for (const [key, value] of Object.entries(page.properties)) {
-      properties[key] = simplifyPropertyValue(value);
-    }
-  }
-
-  return {
-    id: String(page?.id ?? ""),
-    object: String(page?.object ?? "page"),
-    title: extractResultTitle(page),
-    url: String(page?.url ?? ""),
-    last_edited_time: page?.last_edited_time ?? null,
-    properties,
-  };
-}
-
-function simplifyDataSourceSchema(dataSource) {
-  const properties = dataSource?.properties;
-  if (!properties || typeof properties !== "object") {
-    return [];
-  }
-  return Object.entries(properties).map(([name, value]) => ({
-    name,
-    type: String(value?.type ?? "unknown"),
-  }));
-}
-
-async function fetchPageMetadata(pageId) {
-  const page = await notionRequest(`/pages/${pageId}`);
-  return simplifySearchResult(page);
-}
-
-async function fetchPageMarkdown(pageId) {
-  const response = await notionRequest(`/pages/${pageId}/markdown`);
-  if (typeof response === "string") {
-    return response;
-  }
-  if (typeof response?.markdown === "string") {
-    return response.markdown;
-  }
-  if (Array.isArray(response?.results)) {
-    return response.results
-      .map((item) => (typeof item === "string" ? item : item?.markdown ?? ""))
-      .filter(Boolean)
-      .join("\n");
-  }
-  return JSON.stringify(response, null, 2);
-}
-
-async function fetchDataSourceContent(dataSourceId, rowLimit) {
-  const dataSource = await notionRequest(`/data_sources/${dataSourceId}`);
-  const target = {
-    id: String(dataSource?.id ?? dataSourceId),
-    object: "data_source",
-    title: extractResultTitle(dataSource),
-    url: String(dataSource?.url ?? ""),
-    last_edited_time: dataSource?.last_edited_time ?? null,
-  };
-
-  try {
-    const rowsResponse = await notionRequest(`/data_sources/${dataSourceId}/query`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ page_size: rowLimit }),
-    });
-
-    return {
-      target,
-      content: {
-        type: "data_source",
-        schema: simplifyDataSourceSchema(dataSource),
-        rows: Array.isArray(rowsResponse?.results)
-          ? rowsResponse.results.map((row) => simplifyPageRecord(row))
-          : [],
-      },
-    };
-  } catch (error) {
-    return {
-      target,
-      content: null,
-      content_error: error instanceof Error ? error.message : String(error),
-    };
-  }
-}
-
-export async function fetchContent({ id, object, rowLimit = DEFAULT_ROW_LIMIT } = {}) {
-  if (!id) {
-    throw new Error("notion fetch requires --id");
-  }
-  if (object !== "page" && object !== "data_source") {
-    throw new Error("notion fetch requires --object page|data_source");
-  }
-
-  if (object === "page") {
-    let target = {
-      id,
-      object: "page",
-      title: "",
-      url: "",
-      last_edited_time: null,
-    };
-    try {
-      target = await fetchPageMetadata(id);
-      const markdown = await fetchPageMarkdown(id);
-      return {
-        ok: true,
-        target,
-        content: {
-          type: "page",
-          markdown,
-        },
-      };
-    } catch (error) {
-      return {
-        ok: true,
-        target,
-        content: null,
-        content_error: error instanceof Error ? error.message : String(error),
-      };
-    }
-  }
-
-  try {
-    return {
-      ok: true,
-      ...(await fetchDataSourceContent(id, rowLimit)),
-    };
-  } catch (error) {
-    return {
-      ok: true,
-      target: {
-        id,
-        object: "data_source",
-        title: "",
-        url: "",
-        last_edited_time: null,
-      },
-      content: null,
-      content_error: error instanceof Error ? error.message : String(error),
-    };
-  }
-}
-
-async function main() {
-  const [command, ...rest] = process.argv.slice(2);
-  if (command !== "search" && command !== "fetch") {
-    throw new Error("notion-cli requires a subcommand: search | fetch");
-  }
-
-  const args = parseArgs(rest[0] === "--" ? rest.slice(1) : rest);
-  let result;
-  if (command === "search") {
-    const queries = toStringArray(args.query);
-    if (queries.length === 0) {
-      throw new Error("notion search requires at least one --query");
-    }
-    result = await searchNotion({
-      queries,
-      pageSize: args["page-size"] ? Number.parseInt(args["page-size"], 10) : DEFAULT_PAGE_SIZE,
-      object: normalizeWhitespace(args.object),
-    });
-  } else {
-    result = await fetchContent({
-      id: normalizeWhitespace(args.id),
-      object: normalizeWhitespace(args.object),
-      rowLimit: args["row-limit"] ? Number.parseInt(args["row-limit"], 10) : DEFAULT_ROW_LIMIT,
-    });
-  }
-
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-}
-
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  main().catch((error) => {
-    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-    process.exitCode = 1;
-  });
-}