@heyseo/mcp-server 0.1.2 → 0.2.0

package/dist/tools/workflows.js

@@ -0,0 +1,162 @@
+/**
+ * SEO Audit Workflow Tools
+ * Composite workflow tools for high-level site analysis
+ */
+import { z } from 'zod';
+import { formatResponse, formatErrorResponse } from '../utils/response-formatter.js';
+// Schema for site audit workflow
+export const siteAuditSchema = z.object({
+    siteId: z.string().describe('The ID of the site to audit'),
+    days: z
+        .number()
+        .min(7)
+        .max(90)
+        .optional()
+        .default(28)
+        .describe('Number of days to analyze'),
+});
+/**
+ * Execute site audit workflow
+ * Performs comprehensive SEO audit including GSC, GA4, and opportunities analysis
+ */
+export async function executeSiteAudit(client, input) {
+    try {
+        // Calculate date range
+        const endDate = new Date().toISOString().split('T')[0];
+        const startDate = new Date(Date.now() - input.days * 24 * 60 * 60 * 1000)
+            .toISOString()
+            .split('T')[0];
+        // Fetch all data in parallel
+        const [site, overview, topKeywords, topPages, opportunities] = await Promise.all([
+            client.getSite(input.siteId),
+            client.getSiteOverview(input.siteId, { startDate, endDate }),
+            client.getTopKeywords(input.siteId, { startDate, endDate, limit: 10 }),
+            client.getTopPages(input.siteId, { startDate, endDate, limit: 10 }),
+            client.getOpportunities(input.siteId),
+        ]);
+        // Extract and format GSC metrics
+        const gscRow = overview.gsc.rows[0];
+        const gscMetrics = {
+            clicks: gscRow?.clicks || 0,
+            impressions: gscRow?.impressions || 0,
+            ctr: gscRow ? `${(gscRow.ctr * 100).toFixed(2)}%` : '0%',
+            avgPosition: gscRow?.position.toFixed(1) || 'N/A',
+        };
+        // Extract and format GA4 metrics
+        const ga4Row = overview.ga4[0];
+        const ga4Metrics = {
+            sessions: ga4Row?.metrics?.sessions || 0,
+            activeUsers: ga4Row?.metrics?.activeUsers || 0,
+            bounceRate: ga4Row?.metrics?.bounceRate
+                ? `${(ga4Row.metrics.bounceRate * 100).toFixed(1)}%`
+                : '0%',
+            engagementRate: ga4Row?.metrics?.engagementRate
+                ? `${(ga4Row.metrics.engagementRate * 100).toFixed(1)}%`
+                : '0%',
+        };
+        // Format top keywords
+        const topKeywordsList = topKeywords.rows.slice(0, 10).map((row, index) => ({
+            rank: index + 1,
+            keyword: row.keys[0] || 'N/A',
+            clicks: row.clicks || 0,
+            position: row.position.toFixed(1),
+        }));
+        // Format top pages
+        const topPagesList = topPages.rows.slice(0, 10).map((row, index) => ({
+            rank: index + 1,
+            page: row.keys[0] || 'N/A',
+            clicks: row.clicks || 0,
+            position: row.position.toFixed(1),
+        }));
+        // Count opportunities by type and find high-priority items
+        const opportunitiesByType = {
+            keyword: 0,
+            page: 0,
+            technical: 0,
+            content: 0,
+        };
+        const highPriorityOpportunities = [];
+        for (const opp of opportunities) {
+            const type = opp.type;
+            if (type in opportunitiesByType) {
+                opportunitiesByType[type]++;
+            }
+            if (opp.priority === 'high' && highPriorityOpportunities.length < 5) {
+                highPriorityOpportunities.push({
+                    type: opp.type,
+                    title: opp.title,
+                    priority: opp.priority,
+                });
+            }
+        }
+        // Build audit report
+        const auditReport = {
+            siteInfo: {
+                name: site.name || 'N/A',
+                url: site.url || 'N/A',
+                gscConnected: site.gscConnected,
+                ga4Connected: site.ga4Connected,
+            },
+            period: {
+                startDate,
+                endDate,
+                days: input.days,
+            },
+            metrics: {
+                gsc: gscMetrics,
+                ga4: ga4Metrics,
+            },
+            topKeywords: topKeywordsList,
+            topPages: topPagesList,
+            opportunities: {
+                total: opportunities.length,
+                byType: opportunitiesByType,
+                topPriority: highPriorityOpportunities,
+            },
+        };
+        return formatResponse(true, auditReport, {
+            summary: `Site audit for ${site.name || site.url} completed`,
+            period: { startDate, endDate },
+        });
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        return formatErrorResponse(errorMessage, 'siteAudit');
+    }
+}
+/**
+ * Workflow tool definitions for MCP
+ */
+export const workflowTools = [
+    {
+        name: 'heyseo_site_audit',
+        description: `Perform comprehensive SEO audit for a site.
+
+Analyzes GSC performance data, GA4 user engagement metrics, top keywords and pages, and SEO opportunities.
+Returns a complete site health assessment with actionable insights.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                siteId: {
+                    type: 'string',
+                    description: 'The ID of the site to audit',
+                },
+                days: {
+                    type: 'number',
+                    minimum: 7,
+                    maximum: 90,
+                    default: 28,
+                    description: 'Number of days to analyze',
+                },
+            },
+            required: ['siteId'],
+        },
+        hints: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    },
+];
+//# sourceMappingURL=workflows.js.map

package/dist/tools/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../src/tools/workflows.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAErF,iCAAiC;AACjC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAC1D,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,EAAE;SACV,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,2BAA2B,CAAC;CACzC,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAuB,EACvB,KAAqB;IAErB,IAAI,CAAC;QACH,uBAAuB;QACvB,MAAM,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;aACtE,WAAW,EAAE;aACb,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAEjB,6BAA6B;QAC7B,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC/E,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC;YAC5B,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;YAC5D,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;YACtE,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;YACnE,MAAM,CAAC,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC;SACtC,CAAC,CAAC;QAEH,iCAAiC;QACjC,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpC,MAAM,UAAU,GAAG;YACjB,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;YAC3B,WAAW,EAAE,MAAM,EAAE,WAAW,IAAI,CAAC;YACrC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI;YACxD,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK;SAClD,CAAC;QAEF,iCAAiC;QACjC,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC/B,MAAM,UAAU,GAAG;YACjB,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,IAAI,CAAC;YACxC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,IAAI,CAAC;YAC9C,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU;gBACrC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;gBACpD,CAAC,CAAC,IAAI;YACR,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;gBAC7C,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,cAAc,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;gBACxD,CAAC,CAAC,IAAI;SACT,CAAC;QAEF,sBAAsB;QACtB,MAAM,eAAe,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YACzE,IAAI,EAAE,KAAK,GAAG,CAAC;YACf,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK;YAC7B,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC;YACvB,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;SAClC,CAAC,CAAC,CAAC;QAEJ,mBAAmB;QACnB,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YACnE,IAAI,EAAE,KAAK,GAAG,CAAC;YACf,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK;YAC1B,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,CAAC;YACvB,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;SAClC,CAAC,CAAC,CAAC;QAEJ,2DAA2D;QAC3D,MAAM,mBAAmB,GAA2B;YAClD,OAAO,EAAE,CAAC;YACV,IAAI,EAAE,CAAC;YACP,SAAS,EAAE,CAAC;YACZ,OAAO,EAAE,CAAC;SACX,CAAC;QACF,MAAM,yBAAyB,GAAG,EAAE,CAAC;QAErC,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAwC,CAAC;YAC1D,IAAI,IAAI,IAAI,mBAAmB,EAAE,CAAC;gBAChC,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,CAAC;YACD,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,yBAAyB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpE,yBAAyB,CAAC,IAAI,CAAC;oBAC7B,IAAI,EAAE,GAAG,CAAC,IAAI;oBACd,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;iBACvB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,qBAAqB;QACrB,MAAM,WAAW,GAAG;YAClB,QAAQ,EAAE;gBACR,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,KAAK;gBACxB,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,KAAK;gBACtB,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,YAAY,EAAE,IAAI,CAAC,YAAY;aAChC;YACD,MAAM,EAAE;gBACN,SAAS;gBACT,OAAO;gBACP,IAAI,EAAE,KAAK,CAAC,IAAI;aACjB;YACD,OAAO,EAAE;gBACP,GAAG,EAAE,UAAU;gBACf,GAAG,EAAE,UAAU;aAChB;YACD,WAAW,EAAE,eAAe;YAC5B,QAAQ,EAAE,YAAY;YACtB,aAAa,EAAE;gBACb,KAAK,EAAE,aAAa,CAAC,MAAM;gBAC3B,MAAM,EAAE,mBAAmB;gBAC3B,WAAW,EAAE,yBAAyB;aACvC;SACF,CAAC;QAEF,OAAO,cAAc,CAAC,IAAI,EAAE,WAAW,EAAE;YACvC,OAAO,EAAE,kBAAkB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,YAAY;YAC5D,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;SAC/B,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QAC9E,OAAO,mBAAmB,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B;QACE,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE;;;oEAGmD;QAChE,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,6BAA6B;iBAC3C;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,OAAO,EAAE,CAAC;oBACV,OAAO,EAAE,EAAE;oBACX,OAAO,EAAE,EAAE;oBACX,WAAW,EAAE,2BAA2B;iBACzC;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACrB;QACD,KAAK,EAAE;YACL,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,IAAI;YACpB,aAAa,EAAE,IAAI;SACpB;KACF;CACF,CAAC"}

package/dist/utils/api-client.d.ts

@@ -55,6 +55,22 @@ export declare class HeySeoApiClient {
      * Delete a Kanban task
      */
     deleteTask(taskId: string): Promise<void>;
+    /**
+     * Bulk create multiple tasks
+     */
+    bulkCreateTasks(siteId: string, tasks: Array<{
+        title: string;
+        description?: string;
+        priority?: 'low' | 'medium' | 'high';
+        category?: 'technical' | 'content' | 'links' | 'ux';
+    }>): Promise<KanbanTask[]>;
+    /**
+     * Bulk update multiple tasks
+     */
+    bulkUpdateTasks(taskIds: string[], updates: {
+        status?: 'todo' | 'in_progress' | 'done';
+        priority?: 'low' | 'medium' | 'high';
+    }): Promise<KanbanTask[]>;
     /**
      * Get top keywords for a site
      */

package/dist/utils/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/utils/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/utils/api-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EACV,cAAc,EACd,cAAc,EACd,cAAc,EACd,MAAM,EACN,eAAe,EACf,cAAc,EACd,UAAU,EAEX,MAAM,aAAa,CAAC;AAErB,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,EAAE,YAAY;YAIlB,OAAO;IAuBrB;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAQvC;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAUlD;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAqB/D;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAyBzD;;OAEG;IACG,gBAAgB,CACpB,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,QAAQ,GAAG,SAAoB,GACxC,OAAO,CAAC,eAAe,CAAC;IAc3B;;OAEG;IACG,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAClD,OAAO,CAAC,cAAc,EAAE,CAAC;IAW5B;;OAEG;IACG,UAAU,CACd,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GACvD,OAAO,CAAC,UAAU,CAAC;IActB;;OAEG;IACG,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,MAAM,CAAC;QACzC,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;QACrC,QAAQ,CAAC,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC;KAChD,GACL,OAAO,CAAC,UAAU,EAAE,CAAC;IAgBxB;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAUlD;;OAEG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC,CAAC,GAC/F,OAAO,CAAC,UAAU,CAAC;IActB;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/C;;OAEG;IACG,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;QACrC,QAAQ,CAAC,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,IAAI,CAAC;KACrD,CAAC,GACD,OAAO,CAAC,UAAU,EAAE,CAAC;IAsBxB;;OAEG;IACG,eAAe,CACnB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE;QACP,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,MAAM,CAAC;QACzC,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;KACtC,GACA,OAAO,CAAC,UAAU,EAAE,CAAC;IAiBxB;;OAEG;IACG,cAAc,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GACL,OAAO,CAAC,cAAc,CAAC;IAgB1B;;OAEG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KACX,GACL,OAAO,CAAC,cAAc,CAAC;IAgB1B;;OAEG;IACG,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KACb,GACL,OAAO,CAAC;QACT,GAAG,EAAE,cAAc,CAAC;QACpB,GAAG,EAAE,MAAM,EAAE,CAAC;KACf,CAAC;CA+BH;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,eAAe,CAWnF"}

package/dist/utils/api-client.js

@@ -176,6 +176,43 @@ export class HeySeoApiClient {
             throw new Error(response.error || 'Failed to delete task');
         }
     }
+    /**
+     * Bulk create multiple tasks
+     */
+    async bulkCreateTasks(siteId, tasks) {
+        const response = await this.request('/api/mcp/tasks/bulk', {
+            method: 'POST',
+            body: JSON.stringify({
+                siteId,
+                tasks: tasks.map((task) => ({
+                    ...task,
+                    status: 'todo',
+                    priority: task.priority || 'medium',
+                    category: task.category || 'technical',
+                })),
+            }),
+        });
+        if (!response.success || !response.data) {
+            throw new Error(response.error || 'Failed to bulk create tasks');
+        }
+        return response.data;
+    }
+    /**
+     * Bulk update multiple tasks
+     */
+    async bulkUpdateTasks(taskIds, updates) {
+        const response = await this.request('/api/mcp/tasks/bulk', {
+            method: 'PATCH',
+            body: JSON.stringify({
+                taskIds,
+                updates,
+            }),
+        });
+        if (!response.success || !response.data) {
+            throw new Error(response.error || 'Failed to bulk update tasks');
+        }
+        return response.data;
+    }
     /**
      * Get top keywords for a site
      */
@@ -245,7 +282,7 @@ export class HeySeoApiClient {
  */
 export function createApiClient(config = {}) {
     const apiKey = config.apiKey || process.env.HEYSEO_API_KEY;
-    const baseUrl = config.baseUrl || process.env.HEYSEO_API_URL || 'https://heyseo.app';
+    const baseUrl = config.baseUrl || process.env.HEYSEO_API_URL || 'https://www.heyseo.app';
     if (!apiKey) {
         throw new Error('HeySeo API key is required. Set HEYSEO_API_KEY environment variable or pass apiKey in config.');
     }

package/dist/utils/api-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/utils/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/utils/api-client.ts"],"names":[],"mappings":"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"}

package/dist/utils/response-formatter.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Response Formatter Utility
+ * Provides standardized response formatting functions for MCP tool responses
+ */
+/**
+ * Standardized response format for all MCP tool responses
+ */
+export interface FormattedResponse {
+    success: boolean;
+    summary?: string;
+    data: unknown;
+    meta?: {
+        period?: {
+            startDate?: string;
+            endDate?: string;
+        };
+        totalResults?: number;
+        rowCount?: number;
+        [key: string]: unknown;
+    };
+    error?: string;
+}
+/**
+ * Options for formatting responses
+ */
+export interface FormatResponseOptions {
+    summary?: string;
+    period?: {
+        startDate?: string;
+        endDate?: string;
+    };
+    totalResults?: number;
+    rowCount?: number;
+}
+/**
+ * Format a successful response into standardized JSON format
+ *
+ * @param success - Whether the operation was successful
+ * @param data - The response data
+ * @param options - Optional formatting options
+ * @returns JSON string of FormattedResponse
+ */
+export declare function formatResponse(success: boolean, data: unknown, options?: FormatResponseOptions): string;
+/**
+ * Format an error response into standardized JSON format
+ *
+ * @param message - The error message
+ * @param context - Optional context information
+ * @returns JSON string of FormattedResponse with success=false
+ */
+export declare function formatErrorResponse(message: string, context?: string): string;
+/**
+ * Get actionable suggestions based on error message
+ * Helps LLM agents self-correct
+ *
+ * @param errorMessage - The error message to analyze
+ * @returns Actionable suggestion string
+ */
+export declare function getSuggestion(errorMessage: string): string;
+/**
+ * Truncate text to a maximum length and add ellipsis with details
+ *
+ * @param text - The text to truncate
+ * @param maxLength - Maximum length before truncation (default: 25000)
+ * @returns Truncated text with ellipsis message if over limit
+ */
+export declare function truncateText(text: string, maxLength?: number): string;
+//# sourceMappingURL=response-formatter.d.ts.map

package/dist/utils/response-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-formatter.d.ts","sourceRoot":"","sources":["../../src/utils/response-formatter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE;YACP,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,CAAC;QACF,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE;QACP,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAgCR;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAyB7E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAyD1D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAc,GAAG,MAAM,CAO5E"}

package/dist/utils/response-formatter.js

@@ -0,0 +1,128 @@
+/**
+ * Response Formatter Utility
+ * Provides standardized response formatting functions for MCP tool responses
+ */
+/**
+ * Format a successful response into standardized JSON format
+ *
+ * @param success - Whether the operation was successful
+ * @param data - The response data
+ * @param options - Optional formatting options
+ * @returns JSON string of FormattedResponse
+ */
+export function formatResponse(success, data, options = {}) {
+    const response = {
+        success,
+        data,
+    };
+    // Add summary if provided
+    if (options.summary !== undefined) {
+        response.summary = options.summary;
+    }
+    // Build meta object if any meta options are provided
+    const metaEntries = [];
+    if (options.period !== undefined) {
+        metaEntries.push(['period', options.period]);
+    }
+    if (options.totalResults !== undefined) {
+        metaEntries.push(['totalResults', options.totalResults]);
+    }
+    if (options.rowCount !== undefined) {
+        metaEntries.push(['rowCount', options.rowCount]);
+    }
+    // Only add meta if there are entries
+    if (metaEntries.length > 0) {
+        response.meta = Object.fromEntries(metaEntries);
+    }
+    return JSON.stringify(response, null, 2);
+}
+/**
+ * Format an error response into standardized JSON format
+ *
+ * @param message - The error message
+ * @param context - Optional context information
+ * @returns JSON string of FormattedResponse with success=false
+ */
+export function formatErrorResponse(message, context) {
+    const suggestion = getSuggestion(message);
+    const response = {
+        success: false,
+        data: null,
+        error: message,
+    };
+    // Add context and suggestion in meta if provided or available
+    const metaEntries = [];
+    if (context !== undefined) {
+        metaEntries.push(['context', context]);
+    }
+    if (suggestion) {
+        metaEntries.push(['suggestion', suggestion]);
+    }
+    if (metaEntries.length > 0) {
+        response.meta = Object.fromEntries(metaEntries);
+    }
+    return JSON.stringify(response, null, 2);
+}
+/**
+ * Get actionable suggestions based on error message
+ * Helps LLM agents self-correct
+ *
+ * @param errorMessage - The error message to analyze
+ * @returns Actionable suggestion string
+ */
+export function getSuggestion(errorMessage) {
+    const lowerError = errorMessage.toLowerCase();
+    // Rate limit errors
+    if (lowerError.includes('rate limit') || lowerError.includes('429')) {
+        return 'Consider batching requests or implementing exponential backoff. Try again after the rate limit window resets. Check the error details for reset time.';
+    }
+    // API key errors
+    if (lowerError.includes('api key') ||
+        lowerError.includes('unauthorized') ||
+        lowerError.includes('401') ||
+        lowerError.includes('authentication')) {
+        return 'Verify that your API key is valid and has not expired. Check that the API key is properly set in the environment or configuration. Ensure you have the required permissions.';
+    }
+    // Site/resource not found errors
+    if (lowerError.includes('site') ||
+        lowerError.includes('not found') ||
+        lowerError.includes('404') ||
+        lowerError.includes('does not exist')) {
+        return 'Verify that the site ID is correct and that the site is connected to your account. Check that you have access to this site. Try listing all available sites to confirm the ID.';
+    }
+    // Date range errors
+    if (lowerError.includes('date') ||
+        lowerError.includes('start') ||
+        lowerError.includes('end')) {
+        return 'Check that start date is before end date. Ensure dates are in valid format (YYYY-MM-DD). Verify that the date range contains data for the requested period.';
+    }
+    // Invalid parameter errors
+    if (lowerError.includes('parameter') ||
+        lowerError.includes('invalid') ||
+        lowerError.includes('required')) {
+        return 'Review the required parameters and ensure they are provided correctly. Check the tool documentation for valid parameter values and formats. Ensure all mandatory parameters are included.';
+    }
+    // Server errors
+    if (lowerError.includes('server') ||
+        lowerError.includes('500') ||
+        lowerError.includes('503')) {
+        return 'The server is temporarily unavailable. Try again in a few moments. If the problem persists, check the service status page.';
+    }
+    // Generic fallback
+    return 'Please check the error details above. Review the tool documentation and verify your parameters are correct. Try again or contact support if the issue persists.';
+}
+/**
+ * Truncate text to a maximum length and add ellipsis with details
+ *
+ * @param text - The text to truncate
+ * @param maxLength - Maximum length before truncation (default: 25000)
+ * @returns Truncated text with ellipsis message if over limit
+ */
+export function truncateText(text, maxLength = 25000) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    const omittedChars = text.length - maxLength;
+    return text.slice(0, maxLength) + `\n\n... (truncated, ${omittedChars} characters omitted)`;
+}
+//# sourceMappingURL=response-formatter.js.map

package/dist/utils/response-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-formatter.js","sourceRoot":"","sources":["../../src/utils/response-formatter.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyseo/mcp-server",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "HeySeo MCP Server - Connect LLMs to your SEO data",
   "type": "module",
   "main": "dist/index.js",