Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat(mcp): expose update_opportunity_status tool for workflow transitions (#110)

Gökhan Geyikc79b015b2acd
diff --git a/web/src/app/api/mcp/content-opportunities/[id]/status/route.ts b/web/src/app/api/mcp/content-opportunities/[id]/status/route.ts
new file mode 100644
index 000000000..2fbb8b5ce
--- /dev/null
+++ b/web/src/app/api/mcp/content-opportunities/[id]/status/route.ts
@@ -0,0 +1,60 @@
+import { NextResponse } from 'next/server';
+import { authenticateMcpRequest } from '@/lib/mcp-auth';
+import {
+ CONTENT_OPPORTUNITY_STATUSES,
+ updateOpportunityStatusFor,
+ type ContentOpportunityStatus,
+} from '@/lib/mcp/data';
+
+/**
+ * PATCH /api/mcp/content-opportunities/[id]/status
+ *
+ * Parallel REST surface for the `update_opportunity_status` MCP tool —
+ * same data-layer function, same ownership guarantee, same enum validation.
+ * Body: `{ "status": "in_progress" }` (one of new | sent | in_progress | done | dismissed).
+ */
+export async function PATCH(req: Request, { params }: { params: Promise<{ id: string }> }) {
+ const auth = await authenticateMcpRequest(req);
+ if (auth instanceof NextResponse) return auth;
+
+ const resolvedParams = await params;
+ const opportunityId = resolvedParams.id;
+ if (!opportunityId) {
+ return NextResponse.json({ error: 'id is required' }, { status: 400 });
+ }
+
+ let body: { status?: unknown };
+ try {
+ body = (await req.json()) as { status?: unknown };
+ } catch {
+ return NextResponse.json({ error: 'Invalid JSON body' }, { status: 400 });
+ }
+
+ const status = body.status;
+ if (
+ typeof status !== 'string' ||
+ !(CONTENT_OPPORTUNITY_STATUSES as readonly string[]).includes(status)
+ ) {
+ return NextResponse.json(
+ {
+ error: `status is required and must be one of: ${CONTENT_OPPORTUNITY_STATUSES.join(', ')}`,
+ },
+ { status: 400 },
+ );
+ }
+
+ try {
+ const updated = await updateOpportunityStatusFor(
+ auth,
+ opportunityId,
+ status as ContentOpportunityStatus,
+ );
+ if (!updated) {
+ return NextResponse.json({ error: 'Content opportunity not found' }, { status: 404 });
+ }
+ return NextResponse.json(updated);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : 'Failed';
+ return NextResponse.json({ error: message }, { status: 500 });
+ }
+}
diff --git a/web/src/lib/mcp/data.ts b/web/src/lib/mcp/data.ts
index 71cd1cc6c..1535c41a4 100644
--- a/web/src/lib/mcp/data.ts
+++ b/web/src/lib/mcp/data.ts
@@ -554,3 +554,64 @@ export async function getContentOpportunityFor(
updated_at: r.updated_at ?? '',
};
}
+
+export const CONTENT_OPPORTUNITY_STATUSES = [
+ 'new',
+ 'sent',
+ 'in_progress',
+ 'done',
+ 'dismissed',
+] as const;
+
+export type ContentOpportunityStatus = (typeof CONTENT_OPPORTUNITY_STATUSES)[number];
+
+export interface UpdatedOpportunityStatus {
+ id: string;
+ status: ContentOpportunityStatus;
+ updated_at: string;
+}
+
+/**
+ * Move a content opportunity between workflow states (`new` → `sent` →
+ * `in_progress` → `done`, or `dismissed`). Closes the loop for MCP-driven
+ * content workflows — without this, the user analyses an opportunity in
+ * Claude and still has to click through the dashboard to mark progress.
+ *
+ * Ownership-check-first: the update only runs after we've verified the
+ * opportunity's brand belongs to the caller's org. Wrong-org or missing
+ * id returns null (→ 404) with no DB write.
+ */
+export async function updateOpportunityStatusFor(
+ auth: McpAuthContext,
+ opportunityId: string,
+ status: ContentOpportunityStatus,
+): Promise<UpdatedOpportunityStatus | null> {
+ if (!auth.organizationId) return null;
+
+ // Ownership check via the same brands!inner join used by the read tools.
+ // A wrong-org id misses here and we return null *before* any update.
+ const { data: ownership } = await supabaseAdmin
+ .from('content_opportunities')
+ .select('id, brands!inner(organization_id)')
+ .eq('id', opportunityId)
+ .eq('brands.organization_id', auth.organizationId)
+ .maybeSingle();
+ if (!ownership) return null;
+
+ const updatedAt = new Date().toISOString();
+
+ const { data, error } = await supabaseAdmin
+ .from('content_opportunities')
+ .update({ status, updated_at: updatedAt })
+ .eq('id', opportunityId)
+ .select('id, status, updated_at')
+ .single();
+
+ if (error) throw new Error(error.message);
+
+ return {
+ id: data.id,
+ status: data.status as ContentOpportunityStatus,
+ updated_at: data.updated_at ?? updatedAt,
+ };
+}
diff --git a/web/src/lib/mcp/server.ts b/web/src/lib/mcp/server.ts
index 5f41c82b5..7c1b794cb 100644
--- a/web/src/lib/mcp/server.ts
+++ b/web/src/lib/mcp/server.ts
@@ -3,6 +3,7 @@ import { z } from 'zod';
import type { McpAuthContext } from '@/lib/mcp-auth';
import {
+ CONTENT_OPPORTUNITY_STATUSES,
generateBriefFor,
getContentOpportunityFor,
getVisibilitySummaryFor,
@@ -10,6 +11,7 @@ import {
listContentOpportunitiesFor,
listPromptsFor,
listTopicsFor,
+ updateOpportunityStatusFor,
} from './data';
/**
@@ -250,5 +252,34 @@ export function createMcpServer(auth: McpAuthContext): McpServer {
},
);
+ server.registerTool(
+ 'update_opportunity_status',
+ {
+ description:
+ 'Move a content opportunity between workflow states. Valid statuses are: "new" (just generated), "sent" (delivered to a CMS / writer via webhook), "in_progress" (someone is actively writing), "done" (published), "dismissed" (intentionally skipped). Use this to close the loop on the content backlog from inside an MCP conversation — e.g. "mark that opportunity as in_progress" once the user starts writing, or "dismiss this one, we already cover it." This is a write — only fire on explicit user intent for a specific opportunity, never as part of an exploratory query.',
+ inputSchema: {
+ opportunity_id: z
+ .string()
+ .uuid()
+ .describe('Content opportunity UUID, from list_content_opportunities.'),
+ status: z
+ .enum(CONTENT_OPPORTUNITY_STATUSES)
+ .describe('New workflow state. One of: new, sent, in_progress, done, dismissed.'),
+ },
+ },
+ async (args) => {
+ const updated = await updateOpportunityStatusFor(auth, args.opportunity_id, args.status);
+ if (!updated) {
+ return {
+ content: [{ type: 'text', text: 'Content opportunity not found' }],
+ isError: true,
+ };
+ }
+ return {
+ content: [{ type: 'text', text: JSON.stringify(updated, null, 2) }],
+ };
+ },
+ );
+
return server;
}