Skip to content

Open-source status page, incident response and uptime monitoring

chore: more dashboard mcp stuff (#2709)

Maximilian Kaske3a6efd1f9172
diff --git a/.env.docker.example b/.env.docker.example
index b7c721a0c..3b34a96d8 100644
--- a/.env.docker.example
+++ b/.env.docker.example
@@ -173,8 +173,8 @@ DASHBOARD_URL=http://localhost:3002
# OPENSTATUS_KEY, pointing at this stack's private-location service on port 8081.
# Docs knowledge base for the AI assistant / MCP server (optional)
-# The search_docs and get_doc_page tools query this site's /api/search and
-# /api/markdown endpoints. Defaults to the public openstatus.dev docs.
+# The search_docs/get_doc_page and search_content/get_content_page tools query
+# this site's /api/search and /api/markdown endpoints. Defaults to the public openstatus.dev docs.
# OPENSTATUS_WEB_BASE_URL=https://www.openstatus.dev
# AI chat provider (optional). Configure ONE option to enable the assistant.
diff --git a/apps/dashboard/src/app/(dashboard)/agents/mcp/page.tsx b/apps/dashboard/src/app/(dashboard)/agents/mcp/page.tsx
index fc58bea7e..ded7745be 100644
--- a/apps/dashboard/src/app/(dashboard)/agents/mcp/page.tsx
+++ b/apps/dashboard/src/app/(dashboard)/agents/mcp/page.tsx
@@ -225,6 +225,15 @@ const tools = [
"get_audit_log",
],
},
+ {
+ group: "Content",
+ items: [
+ "search_docs",
+ "get_doc_page",
+ "search_content",
+ "get_content_page",
+ ],
+ },
];
export default function Page() {
@@ -235,8 +244,8 @@ export default function Page() {
<SectionTitle>MCP Server</SectionTitle>
<SectionDescription>
Connect Claude, ChatGPT, Cursor or any Model Context Protocol client
- to read and manage your status pages, reports and maintenances from
- a conversation.{" "}
+ to read and manage your status pages, reports and maintenances, and
+ search public openstatus.dev content, from a conversation.{" "}
<Link href="https://www.openstatus.dev/docs/reference/mcp-server">
Read more
</Link>
@@ -336,7 +345,8 @@ export default function Page() {
<SectionDescription>
Read tools are available on every credential. Mutation tools require
read &amp; write access. Audit log tools require the audit-log
- feature on your plan.
+ feature on your plan. Content tools search public openstatus.dev
+ pages and carry no workspace data.
</SectionDescription>
</SectionHeader>
<ul className="flex flex-col gap-2">
diff --git a/apps/dashboard/src/components/chat/chat-suggestions.tsx b/apps/dashboard/src/components/chat/chat-suggestions.tsx
index 58713f9f6..ee88f1826 100644
--- a/apps/dashboard/src/components/chat/chat-suggestions.tsx
+++ b/apps/dashboard/src/components/chat/chat-suggestions.tsx
@@ -1,6 +1,7 @@
import { ModelContextProtocolIcon } from "@openstatus/icons/brand";
import { Badge } from "@openstatus/ui/components/ui/badge";
import { Button } from "@openstatus/ui/components/ui/button";
+import { useQuery } from "@tanstack/react-query";
import NextLink from "next/link";
import { Note, NoteButton } from "@/components/common/note";
@@ -11,6 +12,7 @@ import {
SectionHeader,
SectionTitle,
} from "@/components/content/section";
+import { useTRPC } from "@/lib/trpc/client";
const SUGGESTIONS = [
"List all my monitors",
@@ -24,6 +26,13 @@ type Props = {
};
export function ChatSuggestions({ onSelect }: Props) {
+ const trpc = useTRPC();
+ const { data: workspace } = useQuery(trpc.workspace.get.queryOptions());
+ const suggestions =
+ workspace?.plan === "free"
+ ? [...SUGGESTIONS, "Which pricing plan fits best to me?"]
+ : SUGGESTIONS;
+
return (
<SectionGroup className="mx-auto max-w-3xl">
<Section className="flex w-full flex-col items-center">
@@ -41,7 +50,7 @@ export function ChatSuggestions({ onSelect }: Props) {
</SectionDescription>
</SectionHeader>
<div className="flex flex-wrap items-center justify-center gap-2">
- {SUGGESTIONS.map((s) => (
+ {suggestions.map((s) => (
<Button
key={s}
variant="outline"
diff --git a/apps/dashboard/src/components/chat/tool-renderers/index.tsx b/apps/dashboard/src/components/chat/tool-renderers/index.tsx
index 5c584622b..bd843473e 100644
--- a/apps/dashboard/src/components/chat/tool-renderers/index.tsx
+++ b/apps/dashboard/src/components/chat/tool-renderers/index.tsx
@@ -30,6 +30,7 @@ import { listStatusPagesTable } from "./list-status-pages";
import { listStatusReportsTable } from "./list-status-reports";
import { resolveStatusReportChanges } from "./resolve-status-report";
import { ResultTable } from "./result-table";
+import { searchContentTable } from "./search-content";
import { searchDocsTable } from "./search-docs";
import { updateStatusReportChanges } from "./update-status-report";
@@ -213,6 +214,16 @@ export const toolRenderers: ToolRendererRegistry = {
summary: (o) =>
o.error ? o.error : `read ${o.url}${o.truncated ? " (truncated)" : ""}`,
},
+ search_content: {
+ renderResult: ({ output }) => (
+ <ResultTable {...searchContentTable(output)} />
+ ),
+ summary: (o) => (o.error ? o.error : itemsCountSummary(o.results)),
+ },
+ get_content_page: {
+ summary: (o) =>
+ o.error ? o.error : `read ${o.url}${o.truncated ? " (truncated)" : ""}`,
+ },
};
function itemsCountSummary(items: unknown[] | undefined): string | undefined {
diff --git a/apps/dashboard/src/components/chat/tool-renderers/search-content.tsx b/apps/dashboard/src/components/chat/tool-renderers/search-content.tsx
new file mode 100644
index 000000000..8d06ba696
--- /dev/null
+++ b/apps/dashboard/src/components/chat/tool-renderers/search-content.tsx
@@ -0,0 +1,34 @@
+import type { AgentToolOutput } from "@openstatus/services/agent-tools";
+
+import { TableCellLink } from "@/components/data-table/table-cell-link";
+import { TableCellText } from "@/components/data-table/table-cell-text";
+
+import type { ResultTableData } from "./result-table";
+
+type Output = AgentToolOutput<"search_content">;
+
+export function searchContentTable(
+ output: Output,
+): ResultTableData<"title" | "type" | "snippet"> {
+ const results = output?.results ?? [];
+ return {
+ empty: output?.error ?? "No results.",
+ columns: [
+ { key: "title", header: "Title" },
+ { key: "type", header: "Type" },
+ { key: "snippet", header: "Snippet" },
+ ],
+ rows: results.map((r) => ({
+ id: r.path,
+ cells: {
+ title: <TableCellLink href={r.url} value={r.title} />,
+ type: (
+ <TableCellText value={r.type} className="text-muted-foreground" />
+ ),
+ snippet: (
+ <TableCellText value={r.snippet} className="text-muted-foreground" />
+ ),
+ },
+ })),
+ };
+}
diff --git a/apps/dashboard/src/components/nav/nav-banner-checklist.tsx b/apps/dashboard/src/components/nav/nav-banner-checklist.tsx
index b08269f55..ed83f991b 100644
--- a/apps/dashboard/src/components/nav/nav-banner-checklist.tsx
+++ b/apps/dashboard/src/components/nav/nav-banner-checklist.tsx
@@ -69,8 +69,8 @@ export function NavBannerChecklist({
if (items.every((i) => i.checked)) return null;
return (
- <SidebarGroup className="bg-background rounded-lg border group-data-[collapsible=icon]:hidden">
- <SidebarGroupLabel className="flex items-center justify-between pr-1">
+ <SidebarGroup className="bg-background rounded-lg border px-2 py-1.5 group-data-[collapsible=icon]:hidden">
+ <SidebarGroupLabel className="flex h-7 items-center justify-between pr-0 pl-0">
<span>
Getting Started ({items.filter((i) => i.checked).length}/
{items.length})
@@ -90,25 +90,19 @@ export function NavBannerChecklist({
>
{item.checked ? (
<>
- <Success className="text-success shrink-0" size={12} />
+ <Success className="text-success size-3 shrink-0" />
<span>{item.title}</span>
</>
) : (
<>
- <Pending
- className="text-muted-foreground/50 shrink-0"
- size={12}
- />
+ <Pending className="text-muted-foreground/50 size-3 shrink-0" />
<Link href={item.href}>{item.title}</Link>
</>
)}
</SidebarMenuItem>
))}
<SidebarMenuItem className="flex items-center gap-2 text-sm">
- <ArrowUpRight
- className="text-muted-foreground/50 shrink-0"
- size={12}
- />
+ <ArrowUpRight className="text-muted-foreground/50 size-3 shrink-0" />
<a
href="https://www.openstatus.dev/docs"
target="_blank"
diff --git a/apps/dashboard/src/components/nav/nav-banner-upgrade.tsx b/apps/dashboard/src/components/nav/nav-banner-upgrade.tsx
index 6142e3e92..51331cd02 100644
--- a/apps/dashboard/src/components/nav/nav-banner-upgrade.tsx
+++ b/apps/dashboard/src/components/nav/nav-banner-upgrade.tsx
@@ -1,6 +1,8 @@
"use client";
-import { Launch, Close } from "@openstatus/icons";
+import { allPlans } from "@openstatus/db/src/schema/plan/config";
+import { Clock, Close, Globe, Notification, Team } from "@openstatus/icons";
+import { SlackIcon } from "@openstatus/icons/brand";
import {
SidebarGroup,
SidebarGroupLabel,
@@ -16,6 +18,19 @@ import { useTRPC } from "@/lib/trpc/client";
import { UpgradeDialog } from "../dialogs/upgrade";
+const plan = allPlans.starter;
+
+const features = [
+ {
+ icon: Clock,
+ title: `1 min checks, ${plan.limits.monitors} monitors`,
+ },
+ { icon: Globe, title: "Custom domain & subscribers" },
+ { icon: Team, title: "Unlimited team members" },
+ { icon: SlackIcon, title: "Slack integration" },
+ { icon: Notification, title: "PagerDuty, Opsgenie & SMS" },
+];
+
export function NavBannerUpgrade({ handleClose }: { handleClose: () => void }) {
const trpc = useTRPC();
const { data: workspace } = useQuery(trpc.workspace.get.queryOptions());
@@ -24,9 +39,9 @@ export function NavBannerUpgrade({ handleClose }: { handleClose: () => void }) {
if (!workspace) return null;
return (
- <SidebarGroup className="bg-background rounded-lg border group-data-[collapsible=icon]:hidden">
- <SidebarGroupLabel className="flex items-center justify-between pr-1">
- <span>OpenStatus Pro</span>
+ <SidebarGroup className="bg-background rounded-lg border px-2 py-1.5 group-data-[collapsible=icon]:hidden">
+ <SidebarGroupLabel className="flex h-7 items-center justify-between pr-0 pl-0">
+ <span>Upgrade to {plan.title}</span>
<SidebarMenuAction
onClick={handleClose}
className="relative top-0 right-0"
@@ -35,13 +50,16 @@ export function NavBannerUpgrade({ handleClose }: { handleClose: () => void }) {
</SidebarMenuAction>
</SidebarGroupLabel>
<SidebarMenu>
- <SidebarMenuItem className="flex items-center gap-2 text-sm">
- <Launch className="text-info shrink-0" size={12} />
- <span>
- Unlock custom domains, teams, 1 min. checks, subscriptions and more.
- </span>
- </SidebarMenuItem>
- <SidebarMenuItem>
+ {features.map((feature) => (
+ <SidebarMenuItem
+ key={feature.title}
+ className="flex items-center gap-2 text-sm"
+ >
+ <feature.icon className="text-muted-foreground size-3 shrink-0" />
+ <span>{feature.title}</span>
+ </SidebarMenuItem>
+ ))}
+ <SidebarMenuItem className="pt-1">
<SidebarMenuButton
className="justify-center border"
data-active="true"
diff --git a/apps/server/src/routes/mcp/handler.test.ts b/apps/server/src/routes/mcp/handler.test.ts
index 949d0c3fa..872cb32c3 100644
--- a/apps/server/src/routes/mcp/handler.test.ts
+++ b/apps/server/src/routes/mcp/handler.test.ts
@@ -123,6 +123,8 @@ describe("MCP transport", () => {
"create_maintenance",
"create_status_report",
"get_audit_log",
+ "get_content_page",
+ "get_doc_page",
"get_monitor",
"get_monitor_status",
"get_monitor_summary",
@@ -137,6 +139,8 @@ describe("MCP transport", () => {
"list_status_pages",
"list_status_reports",
"resolve_status_report",
+ "search_content",
+ "search_docs",
"update_status_report",
]);
});
diff --git a/apps/server/src/routes/mcp/server.ts b/apps/server/src/routes/mcp/server.ts
index 309591776..280059698 100644
--- a/apps/server/src/routes/mcp/server.ts
+++ b/apps/server/src/routes/mcp/server.ts
@@ -4,6 +4,7 @@ import type { ServiceContext } from "@openstatus/services";
import packageJson from "../../../package.json" with { type: "json" };
import { registerPublicResources } from "./resources";
import { registerAuditTools } from "./tools/audit";
+import { registerContentTools } from "./tools/content";
import { registerMaintenanceTools } from "./tools/maintenance";
import { registerMonitorTools } from "./tools/monitor";
import { registerNotificationTools } from "./tools/notification";
@@ -35,5 +36,6 @@ export function createMcpServer(ctx: ServiceContext): McpServer {
registerNotificationTools(server, ctx);
registerPrivateLocationTools(server, ctx);
registerAuditTools(server, ctx);
+ registerContentTools(server, ctx);
return server;
}
diff --git a/apps/server/src/routes/mcp/tools/content.ts b/apps/server/src/routes/mcp/tools/content.ts
new file mode 100644
index 000000000..7b898e104
--- /dev/null
+++ b/apps/server/src/routes/mcp/tools/content.ts
@@ -0,0 +1,26 @@
+import type {
+ McpServer,
+ RegisteredTool,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServiceContext } from "@openstatus/services";
+import {
+ getContentPageTool,
+ getDocPageTool,
+ searchContentTool,
+ searchDocsTool,
+} from "@openstatus/services/agent-tools";
+
+import { registerRegistryTools } from "./registry-adapter";
+
+/** Public openstatus.dev content — no workspace data, so any credential sees these. */
+export function registerContentTools(
+ server: McpServer,
+ ctx: ServiceContext,
+): Map<string, RegisteredTool> {
+ return registerRegistryTools(server, ctx, [
+ searchDocsTool,
+ getDocPageTool,
+ searchContentTool,
+ getContentPageTool,
+ ]);
+}
diff --git a/apps/web/public/.well-known/agent-skills/openstatus-mcp/SKILL.md b/apps/web/public/.well-known/agent-skills/openstatus-mcp/SKILL.md
index 41eeddba1..f5ab5138f 100644
--- a/apps/web/public/.well-known/agent-skills/openstatus-mcp/SKILL.md
+++ b/apps/web/public/.well-known/agent-skills/openstatus-mcp/SKILL.md
@@ -1,11 +1,11 @@
---
name: openstatus-mcp
-description: Use the openstatus MCP server to read monitors, notification channels, private locations and audit logs, and to read and update status pages, status reports, and maintenance windows from any Model Context Protocol client (Claude, ChatGPT, Cursor, Codex, opencode, etc.). Use when an AI assistant needs to check a monitor's health, post an incident, append an update, resolve a report, or schedule maintenance for an openstatus workspace.
+description: Use the openstatus MCP server to read monitors, notification channels, private locations and audit logs, to read and update status pages, status reports, and maintenance windows, and to search the openstatus docs, pricing, and other public content from any Model Context Protocol client (Claude, ChatGPT, Cursor, Codex, opencode, etc.). Use when an AI assistant needs to check a monitor's health, post an incident, append an update, resolve a report, or schedule maintenance for an openstatus workspace.
---
# openstatus MCP server
-The openstatus MCP server is a remote, streamable-HTTP endpoint at `https://api.openstatus.dev/mcp`. It exposes 19 tools (17 on plans without the `audit-log` feature) scoped to a single workspace.
+The openstatus MCP server is a remote, streamable-HTTP endpoint at `https://api.openstatus.dev/mcp`. It exposes 23 tools (21 on plans without the `audit-log` feature): 19 scoped to a single workspace plus 4 that search and read public openstatus.dev content.
## Connect
@@ -88,6 +88,15 @@ Both credentials carry a scope. **Read-only** credentials only see `list_*` and
- `list_audit_logs` — audit-log entries, last 14 days, optional `entityType` + `entityId` filter. Requires the `audit-log` plan feature.
- `get_audit_log` — before/after snapshots and `changedFields` for one entry. Requires the `audit-log` plan feature.
+### Content (read-only, public)
+
+Public openstatus.dev pages — no workspace data, available on any credential and any scope.
+
+- `search_docs` — search documentation, guides, or changelog (`type`, default `docs`). Returns a `path` for `get_doc_page`.
+- `get_doc_page` — full markdown of one docs, guide, or changelog page by `path`.
+- `search_content` — search every public page: product/pricing, blog, comparisons, use cases, customer stories, tooling, plus docs/guides/changelog (`type`, default `all`). Returns a `path` for `get_content_page`.
+- `get_content_page` — full markdown of any public page by `path` (e.g. `pricing`, `blog/…`, `compare/…`). Use it for "which plan fits" or "how does openstatus compare to X" questions.
+
### Resources
The server also exposes three read-only resources on any credential: `openapi-specification`, `mcp-server-reference`, and `site-index` (`llms.txt`).
diff --git a/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx b/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx
index bef43ba75..833b75a35 100644
--- a/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx
+++ b/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx
@@ -44,7 +44,7 @@ We know the naming is bad. The prefixed image (`openstatus-private-location`) is
Self-hosting openstatus currently has these constraints:
- It only works with private locations. You have to deploy our probes to the cloud provider of your choice.
-- The AI assistant's docs knowledge base (the `search_docs` and `get_doc_page` tools) queries the public `https://www.openstatus.dev` docs by default. Set `OPENSTATUS_WEB_BASE_URL` if you mirror the marketing site and want the assistant to read your own copy.
+- The AI assistant's docs knowledge base (the `search_docs`/`get_doc_page` and `search_content`/`get_content_page` tools) queries the public `https://www.openstatus.dev` site by default. Set `OPENSTATUS_WEB_BASE_URL` if you mirror the marketing site and want the assistant to read your own copy.
- **IP Restriction is not secure outside Vercel.** The IP restriction feature for status pages relies on the `X-Forwarded-For` header, which [Vercel overwrites with the verified client IP](https://vercel.com/docs/headers/request-headers#x-forwarded-for). When self-hosting behind a different reverse proxy, clients can spoof this header to bypass IP restrictions. If you self-host and use IP restriction, ensure your reverse proxy strips and rewrites `X-Forwarded-For` with the real client IP before forwarding to openstatus.
## Step-by-step guide
diff --git a/apps/web/src/content/pages/docs/reference/mcp-server.mdx b/apps/web/src/content/pages/docs/reference/mcp-server.mdx
index faf8ea119..1a1fc3795 100644
--- a/apps/web/src/content/pages/docs/reference/mcp-server.mdx
+++ b/apps/web/src/content/pages/docs/reference/mcp-server.mdx
@@ -62,7 +62,7 @@ For AI agents that should only observe state — health summaries, paging on-cal
## Tools
-The server exposes 19 tools (17 on plans without the `audit-log` feature), grouped by resource and scoped to the workspace tied to your credential. Mutations write to the audit log with `actor_type = "mcp"` (see [Audit log](#audit-log)).
+The server exposes 23 tools (21 on plans without the `audit-log` feature), grouped by resource: 19 scoped to the workspace tied to your credential, plus 4 public content tools that read openstatus.dev pages on any credential and any scope (see [Content](#content)). Mutations write to the audit log with `actor_type = "mcp"` (see [Audit log](#audit-log)).
### Pages
@@ -120,6 +120,17 @@ Registered only when the workspace plan includes the `audit-log` feature — oth
| `list_audit_logs` | read | List audit-log entries (mutating actions) newest-first, bounded to the last 14 days. Optional `entityType` + `entityId` filter. |
| `get_audit_log` | read | Full before/after snapshots and `changedFields` for a single audit-log entry. |
+### Content
+
+Public openstatus.dev content — no workspace data, available on any credential and any scope.
+
+| Tool | Type | Purpose |
+|--------------------|------|---------|
+| `search_docs` | read | Search the documentation, guides, or changelog (`type`, default `docs`). Returns title, snippet, url, and a `path` for `get_doc_page`. |
+| `get_doc_page` | read | Full markdown of one docs, guide, or changelog page by `path`. |
+| `search_content` | read | Search every public page — product/pricing, blog, comparisons, use cases, customer stories, tooling, plus docs/guides/changelog. `type` defaults to `all`. Returns title, type, snippet, url, and a `path` for `get_content_page`. |
+| `get_content_page` | read | Full markdown of any public page by `path` (e.g. `pricing`, `blog/…`, `compare/…`). |
+
The MCP client gates every tool call behind your approval — the server does not gate again. Each tool also carries [MCP annotations](https://modelcontextprotocol.io/specification/server/tools#tool-annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so well-behaved clients can decide whether to confirm, cache, or surface differently.
### Resources
diff --git a/apps/web/src/content/pages/product/tooling/mcp-server.mdx b/apps/web/src/content/pages/product/tooling/mcp-server.mdx
index e6a3d7cbc..d62ccd31c 100644
--- a/apps/web/src/content/pages/product/tooling/mcp-server.mdx
+++ b/apps/web/src/content/pages/product/tooling/mcp-server.mdx
@@ -27,7 +27,7 @@ Add the URL as a custom connector in Claude, ChatGPT, or Cursor, or run `claude
## What you can do
-The server exposes **19 tools** scoped to your workspace, grouped by entity:
+The server exposes **23 tools**, grouped by entity:
- **Status pages** — `list_status_pages` · `list_page_components`
- **Status reports** — `list_status_reports` · `create_status_report` · `add_status_report_update` · `update_status_report` · `resolve_status_report`
@@ -37,6 +37,7 @@ The server exposes **19 tools** scoped to your workspace, grouped by entity:
- **Notifications** — `list_notifications`
- **Private locations** — `list_private_locations`
- **Audit log** *(workspaces on the audit-log plan only)* — `list_audit_logs` · `get_audit_log`
+- **Content** *(public openstatus.dev pages)* — `search_docs` · `get_doc_page` · `search_content` · `get_content_page`
The four **publishing** tools (`create_status_report`, `add_status_report_update`, `resolve_status_report`, `create_maintenance`) require `notify: true | false` — the assistant must explicitly choose whether to notify subscribers, so an LLM cannot quietly fan out an alert. `update_status_report` is metadata-only and cannot notify.
diff --git a/apps/web/src/content/utils/resolve.ts b/apps/web/src/content/utils/resolve.ts
index d7a4ab50b..33f1600fa 100644
--- a/apps/web/src/content/utils/resolve.ts
+++ b/apps/web/src/content/utils/resolve.ts
@@ -8,6 +8,7 @@ import {
getGuides,
getHomePage,
getProductPages,
+ getToolingPages,
getToolsPages,
getUnrelatedPages,
getUseCasePages,
@@ -85,6 +86,8 @@ function resolveMdxContent(pathname: string): MDXData | null {
return getGuides().find((p) => p.slug === slug) ?? null;
case "play":
return getToolsPages().find((p) => p.slug === slug) ?? null;
+ case "tooling":
+ return getToolingPages().find((p) => p.slug === slug) ?? null;
case "use-case":
return getUseCasePages().find((p) => p.slug === slug) ?? null;
default:
diff --git a/packages/services/src/agent-tools/__tests__/content.test.ts b/packages/services/src/agent-tools/__tests__/content.test.ts
new file mode 100644
index 000000000..c2704eccb
--- /dev/null
+++ b/packages/services/src/agent-tools/__tests__/content.test.ts
@@ -0,0 +1,203 @@
+import { expect } from "@std/expect";
+import { afterEach, describe, test } from "@std/testing/bdd";
+import { assertSpyCalls, spy } from "@std/testing/mock";
+
+import type { ServiceContext } from "../../context";
+import { getContentPageTool, searchContentTool } from "../content";
+
+// Both tools ignore ctx — public content, workspace-independent.
+const ctx = {} as ServiceContext;
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+ globalThis.fetch = originalFetch;
+});
+
+function mockFetch(response: Response) {
+ const fn = spy(async () => response);
+ globalThis.fetch = fn as unknown as typeof fetch;
+ return fn;
+}
+
+function searchFixture(i: number, type = "product") {
+ return {
+ metadata: {
+ title: `Result ${i}`,
+ description: `Description ${i}`,
+ publishedAt: "2018-10-20T01:46:40.000Z",
+ author: "openstatus",
+ },
+ type,
+ content: `...snippet for result ${i}...`,
+ slug: `page-${i}`,
+ href: `/page-${i}?q=pricing#some-heading`,
+ filePath: `/var/task/apps/web/src/content/pages/product/page-${i}.mdx`,
+ };
+}
+
+describe("search_content", () => {
+ test("defaults to the `all` corpus", async () => {
+ const fn = mockFetch(Response.json([]));
+ await searchContentTool.run({
+ ctx,
+ input: searchContentTool.inputSchema.parse({ query: "pricing" }),
+ });
+ assertSpyCalls(fn, 1);
+ const url = String((fn.calls[0] as { args: unknown[] }).args[0]);
+ expect(url).toContain("/api/search?p=all&q=pricing");
+ });
+
+ test("passes a narrowed type through", async () => {
+ const fn = mockFetch(Response.json([]));
+ await searchContentTool.run({
+ ctx,
+ input: { query: "pricing", type: "compare" },
+ });
+ const url = String((fn.calls[0] as { args: unknown[] }).args[0]);
+ expect(url).toContain("/api/search?p=compare&q=pricing");
+ });
+
+ test("maps live response shape incl. type, strips query/hash/filePath", async () => {
+ mockFetch(Response.json([searchFixture(1), searchFixture(2, "blog")]));
+ const result = await searchContentTool.run({
+ ctx,
+ input: { query: "pricing", type: "all" },
+ });
+ const parsed = searchContentTool.outputSchema.safeParse(result);
+ expect(parsed.success, parsed.error?.message).toBe(true);
+ expect(result.results).toHaveLength(2);
+ const first = result.results[0];
+ expect(first.title).toBe("Result 1");
+ expect(first.type).toBe("product");
+ expect(first.path).toBe("page-1");
+ expect(first.url).toBe(
+ "https://www.openstatus.dev/page-1?q=pricing#some-heading",
+ );
+ expect(result.results[1].type).toBe("blog");
+ expect(JSON.stringify(result)).not.toContain("filePath");
+ });
+
+ test("drops the homepage — get_content_page has no path for it", async () => {
+ mockFetch(
+ Response.json([
+ { ...searchFixture(0), href: "/" },
+ { ...searchFixture(1), href: "/?ref=search" },
+ searchFixture(2),
+ ]),
+ );
+ const result = await searchContentTool.run({
+ ctx,
+ input: { query: "what is openstatus", type: "all" },
+ });
+ expect(result.results.map((r) => r.path)).toEqual(["page-2"]);
+ });
+
+ test("returns error shape on non-OK response without throwing", async () => {
+ mockFetch(new Response("oops", { status: 500 }));
+ const result = await searchContentTool.run({
+ ctx,
+ input: { query: "pricing", type: "all" },
+ });
+ expect(result.results).toEqual([]);
+ expect(result.error).toBe("search unavailable (HTTP 500)");
+ expect(searchContentTool.outputSchema.safeParse(result).success).toBe(true);
+ });
+
+ test("returns error shape when fetch throws", async () => {
+ globalThis.fetch = (async () => {
+ throw new Error("ECONNREFUSED");
+ }) as unknown as typeof fetch;
+ const result = await searchContentTool.run({
+ ctx,
+ input: { query: "pricing", type: "all" },
+ });
+ expect(result.results).toEqual([]);
+ expect(result.error).toBe("search unavailable (network error)");
+ });
+
+ test("caps results at 8", async () => {
+ mockFetch(
+ Response.json(Array.from({ length: 12 }, (_, i) => searchFixture(i))),
+ );
+ const result = await searchContentTool.run({
+ ctx,
+ input: { query: "pricing", type: "all" },
+ });
+ expect(result.results).toHaveLength(8);
+ });
+});
+
+describe("get_content_page", () => {
+ test("fetches any site page, not only docs", async () => {
+ const fn = mockFetch(new Response("# Pricing\n\nPlans."));
+ const result = await getContentPageTool.run({
+ ctx,
+ input: { path: "/pricing" },
+ });
+ const parsed = getContentPageTool.outputSchema.safeParse(result);
+ expect(parsed.success, parsed.error?.message).toBe(true);
+ expect(result.markdown).toBe("# Pricing\n\nPlans.");
+ expect(result.truncated).toBe(false);
+ expect(result.url).toBe("https://www.openstatus.dev/pricing");
+ const url = String((fn.calls[0] as { args: unknown[] }).args[0]);
+ expect(url).toBe("https://www.openstatus.dev/api/markdown/pricing");
+ });
+
+ test("truncates long pages with a marker", async () => {
+ mockFetch(new Response("x".repeat(30_000)));
+ const result = await getContentPageTool.run({
+ ctx,
+ input: { path: "blog/some-post" },
+ });
+ expect(result.truncated).toBe(true);
+ expect(result.markdown.length).toBeLessThan(24_200);
+ expect(
+ result.markdown.endsWith(
+ "[truncated — content continues at https://www.openstatus.dev/blog/some-post]",
+ ),
+ ).toBe(true);
+ });
+
+ test("returns error shape on 404", async () => {
+ mockFetch(new Response("Not Found", { status: 404 }));
+ const result = await getContentPageTool.run({
+ ctx,
+ input: { path: "compare/does-not-exist" },
+ });
+ expect(result.markdown).toBe("");
+ expect(result.error).toBe("page not found (HTTP 404)");
+ });
+
+ test("reports non-404 failures as unavailable, not missing", async () => {
+ mockFetch(new Response("oops", { status: 500 }));
+ const result = await getContentPageTool.run({
+ ctx,
+ input: { path: "pricing" },
+ });
+ expect(result.markdown).toBe("");
+ expect(result.error).toBe("page unavailable (HTTP 500)");
+ });
+
+ test("rejects traversal, absolute urls and odd characters without fetching", async () => {
+ const fn = mockFetch(new Response("should not be called"));
+ for (const path of [
+ "../etc",
+ "docs/../../etc",
+ "https://evil.example/x",
+ "//evil.example/x",
+ "pricing?x=1",
+ "api/markdown/pricing#frag",
+ ]) {
+ const result = await getContentPageTool.run({ ctx, input: { path } });
+ expect(result.markdown).toBe("");
+ expect(result.error).toBe(
+ "path must be a site-relative page path like docs/concept/monitor",
+ );
+ expect(getContentPageTool.outputSchema.safeParse(result).success).toBe(
+ true,
+ );
+ }
+ assertSpyCalls(fn, 0);
+ });
+});
diff --git a/packages/services/src/agent-tools/__tests__/docs.test.ts b/packages/services/src/agent-tools/__tests__/docs.test.ts
index 63f50d313..1537e16d5 100644
--- a/packages/services/src/agent-tools/__tests__/docs.test.ts
+++ b/packages/services/src/agent-tools/__tests__/docs.test.ts
@@ -130,6 +130,16 @@ describe("get_doc_page", () => {
expect(result.error).toBe("page not found (HTTP 404)");
});
+ test("reports non-404 failures as unavailable, not missing", async () => {
+ mockFetch(new Response("oops", { status: 500 }));
+ const result = await getDocPageTool.run({
+ ctx,
+ input: { path: "docs/concept/monitor" },
+ });
+ expect(result.markdown).toBe("");
+ expect(result.error).toBe("page unavailable (HTTP 500)");
+ });
+
test("returns error shape when fetch throws", async () => {
globalThis.fetch = (async () => {
throw new Error("ECONNREFUSED");
diff --git a/packages/services/src/agent-tools/content.ts b/packages/services/src/agent-tools/content.ts
new file mode 100644
index 000000000..2020d72bd
--- /dev/null
+++ b/packages/services/src/agent-tools/content.ts
@@ -0,0 +1,196 @@
+import { z } from "zod";
+
+import type { AgentTool } from "./types";
+
+// Public marketing-site content API; override for local/self-hosted setups.
+const WEB_BASE_URL =
+ process.env.OPENSTATUS_WEB_BASE_URL ?? "https://www.openstatus.dev";
+
+const MAX_RESULTS = 8;
+const FETCH_TIMEOUT_MS = 10_000;
+// ≈6k tokens — the free tier runs Haiku; a clipped page beats a blown context.
+const MAX_MARKDOWN_CHARS = 24_000;
+
+// Mirrors `PAGE_TYPES` in apps/web/src/content/utils — the corpora /api/search accepts.
+const CONTENT_TYPES = [
+ "all",
+ "docs",
+ "guides",
+ "changelog",
+ "blog",
+ "product",
+ "compare",
+ "use-case",
+ "customers",
+ "tooling",
+ "tools",
+ "unrelated",
+] as const;
+
+// Site-relative slug path only (`docs/concept/monitor`, `pricing`) — blocks
+// traversal and absolute URLs; /api/markdown decides whether the page exists.
+const SAFE_PATH = /^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/;
+
+const SearchContentInput = z
+ .object({
+ query: z.string().min(1),
+ type: z.enum(CONTENT_TYPES).default("all"),
+ })
+ .strict();
+
+const SearchContentOutput = z.object({
+ results: z.array(
+ z.object({
+ title: z.string(),
+ description: z.string().optional(),
+ type: z.string(),
+ snippet: z.string(),
+ url: z.string(),
+ path: z.string(),
+ }),
+ ),
+ error: z.string().optional(),
+});
+
+export const searchContentTool: AgentTool<
+ z.infer<typeof SearchContentInput>,
+ z.infer<typeof SearchContentOutput>
+> = {
+ name: "search_content",
+ description:
+ "Search every public openstatus.dev page — marketing/product pages (pricing, features), blog, comparisons, use cases, customer stories, tooling, plus docs/guides/changelog. Broader than search_docs; prefer search_docs for pure how-to questions. Narrow with `type`. Returns scored results with title, type, snippet, url, and a path usable with get_content_page.",
+ scope: "read",
+ destructive: false,
+ inputSchema: SearchContentInput,
+ outputSchema: SearchContentOutput,
+ // A content lookup failure should degrade the answer, not abort the chat turn.
+ async run({ input }) {
+ try {
+ // Adapters parse through the schema, but direct callers may skip the default.
+ const { query, type = "all" } = input;
+ const res = await fetch(
+ `${WEB_BASE_URL}/api/search?p=${type}&q=${encodeURIComponent(query)}`,
+ { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) },
+ );
+ if (!res.ok) {
+ return {
+ results: [],
+ error: `search unavailable (HTTP ${res.status})`,
+ };
+ }
+ const body = (await res.json()) as unknown;
+ if (!Array.isArray(body)) {
+ return {
+ results: [],
+ error: "search unavailable (unexpected response)",
+ };
+ }
+ // Pick fields defensively — the web app's response shape can drift.
+ const results = body
+ .flatMap((el) => {
+ const item = el as {
+ metadata?: { title?: unknown; description?: unknown };
+ type?: unknown;
+ content?: unknown;
+ href?: unknown;
+ };
+ const title = item.metadata?.title;
+ const href = item.href;
+ if (typeof title !== "string" || typeof href !== "string") return [];
+ // Homepage (href "/") has no slug path get_content_page can fetch.
+ const path = href.split(/[?#]/)[0].replace(/^\//, "");
+ if (!path) return [];
+ return [
+ {
+ title,
+ description:
+ typeof item.metadata?.description === "string"
+ ? item.metadata.description
+ : undefined,
+ type: typeof item.type === "string" ? item.type : "page",
+ snippet: typeof item.content === "string" ? item.content : "",
+ url: `${WEB_BASE_URL}${href}`,
+ path,
+ },
+ ];
+ })
+ .slice(0, MAX_RESULTS);
+ return { results };
+ } catch {
+ return { results: [], error: "search unavailable (network error)" };
+ }
+ },
+};
+
+const GetContentPageInput = z.object({ path: z.string().min(1) }).strict();
+
+const GetContentPageOutput = z.object({
+ url: z.string(),
+ markdown: z.string(),
+ truncated: z.boolean(),
+ error: z.string().optional(),
+});
+
+export const getContentPageTool: AgentTool<
+ z.infer<typeof GetContentPageInput>,
+ z.infer<typeof GetContentPageOutput>
+> = {
+ name: "get_content_page",
+ description:
+ "Fetch the full markdown content of any public openstatus.dev page by path (as returned by search_content), e.g. pricing, blog/…, compare/…, use-case/…. Superset of get_doc_page.",
+ scope: "read",
+ destructive: false,
+ inputSchema: GetContentPageInput,
+ outputSchema: GetContentPageOutput,
+ async run({ input }) {
+ // Loop instead of /\/+$/ — CodeQL flags that regex as polynomial on
+ // untrusted input.
+ let path = input.path;
+ while (path.startsWith("/")) path = path.slice(1);
+ while (path.endsWith("/")) path = path.slice(0, -1);
+ const url = `${WEB_BASE_URL}/${path}`;
+ if (!SAFE_PATH.test(path)) {
+ return {
+ url,
+ markdown: "",
+ truncated: false,
+ error:
+ "path must be a site-relative page path like docs/concept/monitor",
+ };
+ }
+ try {
+ // No Accept: text/markdown header — the site middleware rewrites any
+ // request carrying it to /api/markdown/<path>, doubling the prefix → 404.
+ const res = await fetch(`${WEB_BASE_URL}/api/markdown/${path}`, {
+ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+ });
+ if (!res.ok) {
+ return {
+ url,
+ markdown: "",
+ truncated: false,
+ error:
+ res.status === 404
+ ? `page not found (HTTP ${res.status})`
+ : `page unavailable (HTTP ${res.status})`,
+ };
+ }
+ const text = await res.text();
+ if (text.length <= MAX_MARKDOWN_CHARS) {
+ return { url, markdown: text, truncated: false };
+ }
+ return {
+ url,
+ markdown: `${text.slice(0, MAX_MARKDOWN_CHARS)}\n\n[truncated — content continues at ${url}]`,
+ truncated: true,
+ };
+ } catch {
+ return {
+ url,
+ markdown: "",
+ truncated: false,
+ error: "page unavailable (network error)",
+ };
+ }
+ },
+};
diff --git a/packages/services/src/agent-tools/docs.ts b/packages/services/src/agent-tools/docs.ts
index b88941428..a280d8390 100644
--- a/packages/services/src/agent-tools/docs.ts
+++ b/packages/services/src/agent-tools/docs.ts
@@ -143,7 +143,10 @@ export const getDocPageTool: AgentTool<
url,
markdown: "",
truncated: false,
- error: `page not found (HTTP ${res.status})`,
+ error:
+ res.status === 404
+ ? `page not found (HTTP ${res.status})`
+ : `page unavailable (HTTP ${res.status})`,
};
}
const text = await res.text();
diff --git a/packages/services/src/agent-tools/index.ts b/packages/services/src/agent-tools/index.ts
index 72ebc266f..28edff493 100644
--- a/packages/services/src/agent-tools/index.ts
+++ b/packages/services/src/agent-tools/index.ts
@@ -1,6 +1,7 @@
import type { z } from "zod";
import { getAuditLogTool, listAuditLogsTool } from "./audit";
+import { getContentPageTool, searchContentTool } from "./content";
import { getDocPageTool, searchDocsTool } from "./docs";
import { createMaintenanceTool, listMaintenancesTool } from "./maintenance";
import {
@@ -25,6 +26,7 @@ import {
import type { AnyAgentTool } from "./types";
export { getAuditLogTool, listAuditLogsTool } from "./audit";
+export { getContentPageTool, searchContentTool } from "./content";
export { getDocPageTool, searchDocsTool } from "./docs";
export { createMaintenanceTool, listMaintenancesTool } from "./maintenance";
export {
@@ -94,6 +96,8 @@ export const agentTools = {
get_audit_log: getAuditLogTool,
search_docs: searchDocsTool,
get_doc_page: getDocPageTool,
+ search_content: searchContentTool,
+ get_content_page: getContentPageTool,
} satisfies Record<string, AnyAgentTool>;
// Multi-flag confirmation UX should be a modal, not 2^N buttons. Fail
diff --git a/packages/services/src/agent-tools/prompt.ts b/packages/services/src/agent-tools/prompt.ts
index 49dbeb237..8c996015c 100644
--- a/packages/services/src/agent-tools/prompt.ts
+++ b/packages/services/src/agent-tools/prompt.ts
@@ -31,10 +31,10 @@ export function buildAgentSystemPrompt(opts: AgentSystemPromptOptions): string {
opts.surface === "dashboard"
? `\n\nAfter a tool returns, the dashboard already renders a structured view of the result:
- Write tools (create_*, update_*, resolve_*, add_*) render a diff card with every input/output field (id, status, message, dates, notify outcome).
-- List tools (list_status_pages, list_page_components, list_status_reports, list_maintenances, list_monitors, list_notifications, list_response_logs, list_audit_logs, search_docs) render a table with one row per result.
+- List tools (list_status_pages, list_page_components, list_status_reports, list_maintenances, list_monitors, list_notifications, list_response_logs, list_audit_logs, search_docs, search_content) render a table with one row per result.
- Detail tools (get_monitor, get_monitor_status, get_monitor_summary, get_response_log, get_audit_log) render a structured detail card.
DO NOT restate that data in your reply — no markdown tables, no bullet recaps of the rows, no field-by-field summaries. A one-line acknowledgement ("You have 4 status reports — 3 active." / "Monitor 12 is healthy in 5/7 regions; failing in gru, fra." / "Incident resolved.") plus an optional next step is enough.
-Exception: after get_doc_page, DO synthesize an answer from the page content — the answer is the point; just don't paste the whole page.`
+Exception: after get_doc_page or get_content_page, DO synthesize an answer from the page content — the answer is the point; just don't paste the whole page.`
: "";
const preamble = opts.preamble ? `${opts.preamble}\n\n` : "";
@@ -77,8 +77,9 @@ Docs knowledge base:
- For questions about how openstatus itself works (features, configuration, CLI, API, plans), call search_docs BEFORE answering — never answer product questions from memory.
- Reformulate the question into keyword queries. If the first search misses, retry once with different terms or type: "guides". "When did X ship?" → type: "changelog".
- For the best 1-2 hits, call get_doc_page and ground your answer in that content. ALWAYS cite the page URL(s) in your reply as markdown links.
+- For questions beyond the docs — pricing and which plan fits, feature comparisons with other tools, use cases, customer stories, blog posts — call search_content (type: "all", or narrow to "product", "compare", "use-case", "customers", "blog") and read the best hits with get_content_page. Plan/pricing questions → search_content + get_content_page on "pricing".
- If nothing relevant is found, say so plainly instead of guessing.
-- Do NOT use search_docs for workspace data questions — the list/get tools are the source of truth there.
+- Do NOT use search_docs or search_content for workspace data questions — the list/get tools are the source of truth there.
Lifecycle:
- Status reports flow: create_status_report once → add_status_report_update repeatedly → resolve_status_report.