Developer Documentation
Documentation &
System Architecture
Everything you need to configure Search Console sync, calculate headroom,
and connect coding agents to our 17-tool MCP protocol server.
Google Search Console OAuth & Setup
Impiseo connects directly to your verified Google Search Console account via official Google OAuth with strict read-only access. Zero DNS modifications, zero write permissions.
Domain vs URL-Prefix Properties
We support both sc-domain:example.com (DNS verified, covering all subdomains and protocols) and https://example.com/ (URL-prefix). Domain properties give unified visibility across marketing, docs, and application subdomains.
Read-Only Scope Guarantee
We request strictly https://www.googleapis.com/auth/webmasters.readonly. Impiseo cannot modify your DNS records, alter sitemaps, or mutate your verified Google account in any way.
24–48h Google Sync Window
For newly verified sites, Google's API takes 24 to 48 hours to compile query metrics. While Google processes initial search logs, Impiseo's live HTML scraper and 17-tool MCP server work immediately.
OAuth 2.0 Scope Configuration
const GSC_SCOPES = [
"https://www.googleapis.com/auth/webmasters.readonly",
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/userinfo.profile",
];CTR Headroom & Opportunities Engine
Traditional SEO tools report average position. Impiseo models your actual traffic headroom by calculating the delta between your current clicks and empirical top 3 CTR distribution curves.
Empirical CTR Curve Benchmarks
Based on millions of verified search queries: Position #1 averages ~28.5% CTR, Position #2 averages ~15.7%, and Position #3 averages ~11.2%.
Headroom Formulation
For queries ranking between positions #4 and #20 with >25 impressions: Headroom = (Impressions × Target Top-3 CTR) − Actual Clicks. This calculates your exact untapped organic click volume.
Revenue Impact Modeling
Map your average customer LTV or conversion rate per landing page in $, €, £, or ₹. Impiseo computes the real dollar unlock for moving each query into the top 3.
CTR Headroom Calculation (TypeScript)
export function calculateHeadroom(impressions: number, clicks: number, position: number): number {
if (position < 3.5 || impressions < 25) return 0;
// Position #3 conservative target CTR baseline: 11.2%
const targetCtr = 0.112;
const projectedClicks = Math.round(impressions * targetCtr);
return Math.max(0, projectedClicks - clicks);
}Keyword Cannibalization Detector
Detect when multiple URLs from your domain are competing for identical queries and splitting ranking authority, depressing click-through rates and confusing search engines.
Multi-URL Impression Split Detection
Flags any query where two or more distinct URLs receive at least 10% of total impressions over a rolling 28-day window.
Automated Remediation Guidance
Prescribes actionable technical solutions: 301 redirect consolidation, rel=canonical tag alignment, or internal anchor text disambiguation.
Cannibalization Detection Filter
// Evaluates query-to-page impression distribution
const isCannibalized = pages.length >= 2 &&
pages.filter(p => (p.impressions / totalQueryImpressions) >= 0.10).length >= 2;Model Context Protocol (MCP) Server
Impiseo runs a production Model Context Protocol server exposing 17 specialized tools over HTTP/SSE. AI coding assistants in Cursor, Claude Desktop, and Windsurf can inspect and audit your search performance programmatically.
17 Production MCP Tools
Includes get_overview, get_queries, get_pages, get_query_opportunities, detect_cannibalization, run_page_audit, get_crawl_status, get_recommendations, and get_page_html.
Hashed Personal API Keys
Create and revoke API keys with 1-click clipboard copy from /dashboard/api-keys. All keys are SHA-256 hashed before storage in MongoDB.
In-Browser Test Sandbox
Test any tool call with custom arguments and view live JSON-RPC outputs directly in the dashboard at /dashboard/mcp-test.
Cursor Configuration (~/.cursor/mcp.json)
{
"mcpServers": {
"impiseo": {
"url": "https://mcp.impiclabs.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Autonomous Technical Crawler & Lighthouse
Inspect live production HTML in real time. Verify title tags, meta descriptions, canonical links, OpenGraph headers, schema JSON-LD, and Core Web Vitals.
Live On-Page HTML Scraper
Inspects live HTML for missing meta tags, duplicate h1 headings, missing image alt attributes, non-canonical targets, and robot indexability directives.
Google Lighthouse Performance Pass
Measures Core Web Vitals: Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), and Interaction to Next Paint (INP) with 0–100 category scoring.
AI Code Fix Modal
Click 'Fix with AI' on any crawl recommendation to generate copy-paste ready Next.js Metadata objects and JSON-LD schema patches.