@gmbranker/seo Engine Core

GMB Ranker SEO Engine

Framework-agnostic SEO infrastructure for JavaScript applications. The engine turns site configuration and route data into consistent metadata, JSON-LD, robots.txt, llms.txt, sitemap entries, redirects, content analysis, audits, and approval-safe SEO change proposals.

It is designed for applications that own their source code. Runtime output is generated by your application; the engine does not require WordPress, a CMS, Prisma, Redis, or a hosted GMB Ranker account.

Packages

Install only the packages needed by your application:

npm install @gmbranker/seo-engine-core
# Next.js
npm install @gmbranker/seo-engine-adapters-next
# Optional CI auditing
npm install --save-dev @gmbranker/seo-engine-cli

The adapters depend on the matching core release. Keep the core and adapter versions aligned when pinning versions.

Quick start: core

import {
  buildGlobalSchemaJsonLd,
  generateLlmsTxt,
  generateRobots,
  resolveMetadata,
} from "@gmbranker/seo-engine-core";

const config = {
  siteName: "Example Inc",
  separator: "|",
  title: "%title% %sep% %sitename%",
};

const metadata = resolveMetadata(
  { title: "About us", description: "Learn about Example Inc." },
  { title: "About us", url: "https://example.com/about" },
  config,
);

const robots = generateRobots({
  sitemapUrl: "https://example.com/sitemap.xml",
  disallow: ["/admin", "/account"],
});

const organization = buildGlobalSchemaJsonLd(
  { schema: { name: "Example Inc", schemaType: "Organization" } },
  "https://example.com",
);

const llms = generateLlmsTxt(
  { llms: { enabled: true, summary: "Example Inc website" } },
  "https://example.com",
);

Quick start: Next.js App Router

// app/[slug]/page.tsx
import { createNextMetadata } from "@gmbranker/seo-engine-adapters-next";

export const metadata = createNextMetadata({
  seo: {
    title: "About us",
    description: "Learn about Example Inc.",
    canonical: "https://example.com/about",
    ogImage: "https://example.com/images/about.jpg",
  },
  context: {
    title: "About us",
    url: "https://example.com/about",
  },
  config: { siteName: "Example Inc", separator: "|" },
});

Route factories keep generated files small and let your application provide its own persistence:

// app/robots.txt/route.ts
import { createRobotsRoute } from "@gmbranker/seo-engine-adapters-next";

export const GET = createRobotsRoute({
  baseUrl: process.env.NEXT_PUBLIC_SITE_URL!,
  getContent: async () => null,
});

The Next adapter also provides createLlmsRoute, createSitemapHandler, and createNextMetadata/toNextMetadata. See the adapter README for complete route examples.

What the core provides

• Metadata templates: title, description, canonical, robots, Open Graph, Twitter/X, locale, and alternate-language URLs.
• Structured data: JSON-LD normalization, serialization, validation, breadcrumbs, Organization/LocalBusiness schema, and custom schema values.
• Discovery files: robots.txt policies, AI crawler presets, llms.txt, and sitemap contracts.
• Content analysis: keyword parsing and density, readability, title and description limits, headings, links, images, and deterministic SEO scores.
• Technical helpers: redirect matching and graph inspection, URL normalization, link counting, internal-link proposals, and broken-link classification.
• Decision contracts: capability discovery, privacy-safe site manifests, validated metadata/social/schema/redirect/link/robots changes, audit reports, and change history interfaces.
• Storage interfaces: application-owned adapters for settings, metadata, redirects, robots content, sitemaps, and change history.

Decision engine and MCP boundary

The package does not directly mutate a customer website. It provides typed evidence and change contracts that a host, CMS adapter, MCP server, or CI pipeline can inspect, approve, execute, and verify.

import {
  createSeoSiteManifest,
  validateSeoChange,
} from "@gmbranker/seo-engine-core";

const manifest = createSeoSiteManifest({
  siteId: "example-production",
  baseUrl: "https://example.com",
  framework: "next",
  environment: "production",
  packageVersion: "0.2.6",
  capabilities: ["metadata", "schema", "redirects"],
  executionModes: ["runtime", "pull-request"],
});

const proposal = validateSeoChange({
  type: "UPDATE_PAGE_METADATA",
  route: "/about",
  changes: { title: "About Example Inc | Official Site" },
  audit: { source: "mcp", reason: "Improve branded search snippet" },
});

Treat MCP or AI output as a proposal. The host application remains responsible for authentication, authorization, approval, rate limits, secrets, persistence, rollback, and deployment.

Capability status

SEO_ENGINE_CAPABILITIES is the public capability registry shared by the engine, adapters, CLI, and MCP integrations. Each capability has a status:

• stable: implemented and covered by the package contract;
• beta: usable but still evolving;
• planned: product roadmap or host integration, not a runtime promise.

Do not advertise a planned capability as implemented. CMS connectors, Google Search Console/Analytics/Business Profile providers, and MCP transport are host integrations rather than hidden dependencies of the core package.

Storage

The core is deliberately persistence-free. Implement the interfaces in STORAGE.md using your database, filesystem, CMS, or service. Never put credentials or provider tokens in the SEO manifest or public JSON-LD.

CLI audit

npx seo-engine audit --url https://example.com
npx seo-engine audit --url https://example.com --rules title,description,canonical,schema
npx seo-engine audit --url https://example.com --rules social,hreflang,robots-ai,llms,viewport

The CLI reports pass, warning, and fail findings. Warnings do not fail the audit; missing titles and descriptions do. Use it in CI after your site is deployed or against a preview URL.

Development

npm install
npm run build
npm test
npm run check:publish

check:publish builds and tests every workspace and performs a dry-run pack for each publishable package. Releases are published by the GitHub Actions workflow from version tags with npm provenance. Never commit an npm token or a credential-bearing .npmrc.

Documentation

• Core package guide
• Next.js adapter guide
• Nuxt adapter guide
• Astro adapter guide
• CLI guide
• Storage contracts
• Contribution guide
• Versioning policy

License

MIT — see LICENSE.