@mcptoolshop/site-theme 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# @mcptoolshop/site-theme
+
+Shared Astro theme for MCP Tool Shop org repo landing pages. Dark zinc palette, Tailwind CSS v4, config-driven content.
+
+## Quick Start
+
+### Scaffold a new site
+
+```bash
+npx @mcptoolshop/site-theme init
+cd site && npm install
+npm run dev
+```
+
+This creates a `site/` directory with Astro + Tailwind + theme wired up, plus a GitHub Pages workflow.
+
+### Edit your content
+
+All page content lives in `site/src/site-config.ts`. Edit the config object to customize your landing page:
+
+```typescript
+import type { SiteConfig } from '@mcptoolshop/site-theme';
+
+export const config: SiteConfig = {
+  title: '@mcptoolshop/my-tool',
+  description: 'What my tool does.',
+  logoBadge: 'MT',
+  brandName: 'my-tool',
+  repoUrl: 'https://github.com/mcp-tool-shop-org/my-tool',
+  npmUrl: 'https://www.npmjs.com/package/@mcptoolshop/my-tool',
+  footerText: 'MIT Licensed',
+
+  hero: { /* ... */ },
+  sections: [ /* ... */ ],
+};
+```
+
+## Components
+
+Import components individually from the package:
+
+```astro
+---
+import BaseLayout from '@mcptoolshop/site-theme/components/BaseLayout.astro';
+import Hero from '@mcptoolshop/site-theme/components/Hero.astro';
+import Section from '@mcptoolshop/site-theme/components/Section.astro';
+import FeatureGrid from '@mcptoolshop/site-theme/components/FeatureGrid.astro';
+import DataTable from '@mcptoolshop/site-theme/components/DataTable.astro';
+import CodeCardGrid from '@mcptoolshop/site-theme/components/CodeCardGrid.astro';
+import ApiList from '@mcptoolshop/site-theme/components/ApiList.astro';
+---
+```
+
+### BaseLayout
+
+Full page shell with header (logo, nav, GitHub/npm buttons) and footer.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | Page `<title>` |
+| `description` | `string` | Meta description |
+| `logoBadge` | `string` | 1-2 char logo badge (e.g. "RS") |
+| `brandName` | `string` | Name in header |
+| `nav` | `{ href, label }[]` | Anchor nav links |
+| `repoUrl` | `string` | GitHub repo URL |
+| `npmUrl?` | `string` | npm package URL |
+| `footerText` | `string` | Footer left text (HTML allowed) |
+
+### Hero
+
+Gradient hero section with status badge, headline, CTAs, and code preview cards.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `badge` | `string` | Status badge text |
+| `headline` | `string` | Main headline |
+| `headlineAccent` | `string` | Muted suffix |
+| `description` | `string` | Description (HTML allowed) |
+| `primaryCta` | `{ href, label }` | Primary button |
+| `secondaryCta` | `{ href, label }` | Secondary button |
+| `previews` | `{ label, code }[]` | Code preview cards |
+
+### Section
+
+Section wrapper with anchor id, heading, and optional subtitle.
+
+### FeatureGrid
+
+3-column grid of feature cards. Props: `features: { title, desc }[]`
+
+### DataTable
+
+Grid-based table. Props: `columns: string[]`, `rows: string[][]`
+
+### CodeCardGrid
+
+2-column grid of code block cards. Props: `cards: { title, code }[]`
+
+### ApiList
+
+Full-width API reference cards. Props: `apis: { signature, description }[]`
+
+## Section Types
+
+The `sections` array in your config supports these `kind` values:
+
+- `features` — 3-col feature card grid
+- `data-table` — bordered data table
+- `code-cards` — 2-col code example cards
+- `api` — stacked API reference cards
+
+Sections render in the order they appear in the array.
+
+## Tailwind Setup
+
+The theme uses Tailwind CSS v4. Your site's `global.css` needs the `@source` directive to scan theme components:
+
+```css
+@import "tailwindcss";
+@source "../../../node_modules/@mcptoolshop/site-theme";
+```
+
+The `init` CLI generates this automatically.
+
+## License
+
+MIT

package/cli/init.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, cpSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const templatesDir = join(__dirname, '..', 'templates');
+const cwd = process.cwd();
+
+// --- Helpers ---
+
+function die(msg) {
+  console.error(`\x1b[31mError:\x1b[0m ${msg}`);
+  process.exit(1);
+}
+
+function info(msg) {
+  console.log(`\x1b[36m>\x1b[0m ${msg}`);
+}
+
+function deriveBadge(name) {
+  // "registry-stats" → "RS", "mcpt" → "M", "tool-compass" → "TC"
+  return name
+    .split('-')
+    .map((w) => w[0]?.toUpperCase() ?? '')
+    .join('')
+    .slice(0, 2);
+}
+
+function unscopeName(name) {
+  // "@mcptoolshop/registry-stats" → "registry-stats"
+  return name.replace(/^@[^/]+\//, '');
+}
+
+function extractRepoName(repoUrl) {
+  // "https://github.com/mcp-tool-shop-org/registry-stats.git" → "registry-stats"
+  if (!repoUrl) return '';
+  return repoUrl.replace(/\.git$/, '').split('/').pop() || '';
+}
+
+function readTemplate(name) {
+  return readFileSync(join(templatesDir, name), 'utf-8');
+}
+
+function applyVars(content, vars) {
+  return content.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? '');
+}
+
+function writeFile(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, 'utf-8');
+}
+
+// --- Main ---
+
+function main() {
+  const siteDir = join(cwd, 'site');
+
+  if (existsSync(siteDir)) {
+    die('site/ directory already exists. Remove it first or run from a different repo.');
+  }
+
+  // Read repo's package.json
+  const pkgPath = join(cwd, 'package.json');
+  let pkg = {};
+  if (existsSync(pkgPath)) {
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    } catch {
+      // ignore parse errors
+    }
+  }
+
+  const packageName = pkg.name || 'my-package';
+  const brandName = unscopeName(packageName);
+  const description = pkg.description || 'A tool by mcp-tool-shop';
+  const repoUrl = (typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url)
+    ?.replace(/\.git$/, '')
+    ?.replace(/^git\+/, '') || `https://github.com/mcp-tool-shop-org/${brandName}`;
+  const npmUrl = packageName.startsWith('@')
+    ? `https://www.npmjs.com/package/${packageName}`
+    : `https://www.npmjs.com/package/${packageName}`;
+  const logoBadge = deriveBadge(brandName);
+  const basePath = `/${extractRepoName(repoUrl) || brandName}`;
+
+  const vars = {
+    PACKAGE_NAME: packageName,
+    BRAND_NAME: brandName,
+    DESCRIPTION: description,
+    REPO_URL: repoUrl,
+    NPM_URL: npmUrl,
+    LOGO_BADGE: logoBadge,
+    BASE_PATH: basePath,
+  };
+
+  info(`Package: ${packageName}`);
+  info(`Brand: ${brandName} (${logoBadge})`);
+  info(`Base path: ${basePath}`);
+  info('');
+
+  // Create site/ files
+  const files = [
+    ['astro.config.mjs', 'astro.config.mjs.tpl'],
+    ['package.json', 'package.json.tpl'],
+    ['tsconfig.json', 'tsconfig.json.tpl'],
+    ['src/styles/global.css', 'global.css.tpl'],
+    ['src/pages/index.astro', 'index.astro.tpl'],
+    ['src/site-config.ts', 'site-config.ts.tpl'],
+  ];
+
+  for (const [dest, tpl] of files) {
+    const content = applyVars(readTemplate(tpl), vars);
+    writeFile(join(siteDir, dest), content);
+    info(`Created site/${dest}`);
+  }
+
+  // Create .github/workflows/pages.yml
+  const workflowDir = join(cwd, '.github', 'workflows');
+  const workflowDest = join(workflowDir, 'pages.yml');
+  if (!existsSync(workflowDest)) {
+    const content = applyVars(readTemplate('pages.yml.tpl'), vars);
+    writeFile(workflowDest, content);
+    info('Created .github/workflows/pages.yml');
+  } else {
+    info('Skipped .github/workflows/pages.yml (already exists)');
+  }
+
+  console.log('');
+  console.log('\x1b[32mDone!\x1b[0m Site scaffold created.');
+  console.log('');
+  console.log('Next steps:');
+  console.log(`  cd site && npm install`);
+  console.log(`  Edit src/site-config.ts with your content`);
+  console.log(`  npm run dev`);
+  console.log('');
+}
+
+main();

package/components/ApiList.astro

@@ -0,0 +1,12 @@
+---
+const { apis } = Astro.props;
+---
+
+<div class="mt-8 grid gap-6">
+  {apis.map((a: { signature: string; description: string }) => (
+    <div class="rounded-2xl border border-zinc-900 bg-zinc-950 p-6">
+      <h3 class="text-lg font-semibold"><code set:html={a.signature} /></h3>
+      <p class="mt-2 text-sm text-zinc-400" set:html={a.description} />
+    </div>
+  ))}
+</div>

package/components/BaseLayout.astro

@@ -0,0 +1,80 @@
+---
+const {
+  title,
+  description,
+  logoBadge,
+  brandName,
+  nav = [],
+  repoUrl,
+  npmUrl,
+  footerText,
+} = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content={description} />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>{title}</title>
+  </head>
+
+  <body class="min-h-screen bg-zinc-950 text-zinc-50 antialiased">
+    <div class="mx-auto max-w-6xl px-4">
+      <header class="flex items-center justify-between py-6">
+        <a href="/" class="flex items-center gap-2 font-semibold tracking-tight">
+          <span class="inline-flex h-8 w-8 items-center justify-center rounded-xl bg-zinc-800">
+            {logoBadge}
+          </span>
+          <span>{brandName}</span>
+        </a>
+
+        <nav class="hidden items-center gap-6 text-sm text-zinc-300 md:flex">
+          {nav.map((item: { href: string; label: string }) => (
+            <a href={item.href} class="hover:text-zinc-50">{item.label}</a>
+          ))}
+        </nav>
+
+        <div class="flex items-center gap-3">
+          {npmUrl && (
+            <a
+              class="hidden rounded-xl border border-zinc-800 px-4 py-2 text-sm text-zinc-200 hover:bg-zinc-900 md:inline-flex"
+              href={npmUrl}
+              target="_blank"
+              rel="noreferrer"
+            >
+              npm
+            </a>
+          )}
+          <a
+            class="inline-flex rounded-xl bg-zinc-50 px-4 py-2 text-sm font-medium text-zinc-950 hover:bg-zinc-200"
+            href={repoUrl}
+            target="_blank"
+            rel="noreferrer"
+          >
+            GitHub
+          </a>
+        </div>
+      </header>
+
+      <main class="pb-24">
+        <slot />
+      </main>
+
+      <footer class="border-t border-zinc-900 py-10 text-sm text-zinc-400">
+        <div class="flex flex-col justify-between gap-4 md:flex-row">
+          <p set:html={footerText} />
+          <div class="flex gap-4">
+            {npmUrl && (
+              <a class="hover:text-zinc-200" href={npmUrl} target="_blank" rel="noreferrer">npm</a>
+            )}
+            <a class="hover:text-zinc-200" href={repoUrl} target="_blank" rel="noreferrer">GitHub</a>
+            <a class="hover:text-zinc-200" href="https://opensource.org/license/mit/" target="_blank" rel="noreferrer">License</a>
+          </div>
+        </div>
+      </footer>
+    </div>
+  </body>
+</html>

package/components/CodeCardGrid.astro

@@ -0,0 +1,12 @@
+---
+const { cards } = Astro.props;
+---
+
+<div class="mt-6 grid gap-6 md:grid-cols-2">
+  {cards.map((c: { title: string; code: string }) => (
+    <div class="rounded-2xl border border-zinc-900 bg-zinc-950 p-6">
+      <h3 class="text-lg font-semibold">{c.title}</h3>
+      <pre class="mt-4 overflow-x-auto rounded-xl bg-zinc-900 p-4 text-sm text-zinc-200"><code set:html={c.code} /></pre>
+    </div>
+  ))}
+</div>

package/components/DataTable.astro

@@ -0,0 +1,18 @@
+---
+const { columns, rows } = Astro.props;
+const colCount = columns.length;
+---
+
+<div class="mt-8 overflow-hidden rounded-2xl border border-zinc-900">
+  <div class={`grid gap-0 bg-zinc-950 text-xs text-zinc-400`} style={`grid-template-columns: repeat(${colCount}, minmax(0, 1fr))`}>
+    {columns.map((col: string) => (
+      <div class="border-b border-zinc-900 p-4">{col}</div>
+    ))}
+
+    {rows.map((row: string[]) => (
+      row.map((cell: string, i: number) => (
+        <div class={`border-b border-zinc-900 p-4${i === 0 ? ' font-medium text-zinc-200' : ''}`}>{cell}</div>
+      ))
+    ))}
+  </div>
+</div>

package/components/FeatureGrid.astro

@@ -0,0 +1,12 @@
+---
+const { features } = Astro.props;
+---
+
+<div class="mt-8 grid gap-6 md:grid-cols-3">
+  {features.map((f: { title: string; desc: string }) => (
+    <div class="rounded-2xl border border-zinc-900 bg-zinc-950 p-6">
+      <h3 class="text-lg font-semibold">{f.title}</h3>
+      <p class="mt-2 text-sm text-zinc-400">{f.desc}</p>
+    </div>
+  ))}
+</div>

package/components/Hero.astro

@@ -0,0 +1,55 @@
+---
+const {
+  badge,
+  headline,
+  headlineAccent,
+  description,
+  primaryCta,
+  secondaryCta,
+  previews = [],
+} = Astro.props;
+---
+
+<section class="relative overflow-hidden rounded-3xl border border-zinc-800 bg-gradient-to-b from-zinc-900/60 to-zinc-950 px-6 py-16 md:px-12">
+  <div class="absolute inset-0 opacity-40 [background:radial-gradient(900px_circle_at_20%_20%,rgba(255,255,255,0.10),transparent_60%),radial-gradient(700px_circle_at_80%_30%,rgba(255,255,255,0.06),transparent_60%)]"></div>
+
+  <div class="relative">
+    <div class="inline-flex items-center gap-2 rounded-full border border-zinc-800 bg-zinc-950/60 px-3 py-1 text-xs text-zinc-300">
+      <span class="h-2 w-2 rounded-full bg-emerald-400"></span>
+      <span set:html={badge} />
+    </div>
+
+    <h1 class="mt-6 text-4xl font-semibold tracking-tight md:text-6xl">
+      {headline}
+      <span class="text-zinc-300"> {headlineAccent}</span>
+    </h1>
+
+    <p class="mt-4 max-w-2xl text-lg text-zinc-300" set:html={description} />
+
+    <div class="mt-8 flex flex-col gap-3 sm:flex-row">
+      <a
+        href={primaryCta.href}
+        class="inline-flex items-center justify-center rounded-xl bg-zinc-50 px-5 py-3 text-sm font-medium text-zinc-950 hover:bg-zinc-200"
+      >
+        {primaryCta.label}
+      </a>
+      <a
+        href={secondaryCta.href}
+        class="inline-flex items-center justify-center rounded-xl border border-zinc-800 px-5 py-3 text-sm text-zinc-200 hover:bg-zinc-900"
+      >
+        {secondaryCta.label}
+      </a>
+    </div>
+
+    {previews.length > 0 && (
+      <div class="mt-10 grid gap-4 md:grid-cols-3">
+        {previews.map((p: { label: string; code: string }) => (
+          <div class="rounded-2xl border border-zinc-800 bg-zinc-950/60 p-5">
+            <p class="text-xs text-zinc-400">{p.label}</p>
+            <p class="mt-2 text-sm text-zinc-200"><code>{p.code}</code></p>
+          </div>
+        ))}
+      </div>
+    )}
+  </div>
+</section>

package/components/Section.astro

@@ -0,0 +1,11 @@
+---
+const { id, title, subtitle } = Astro.props;
+---
+
+<section id={id} class="mt-20">
+  <h2 class="text-3xl font-semibold tracking-tight">{title}</h2>
+  {subtitle && (
+    <p class="mt-2 max-w-2xl text-zinc-400">{subtitle}</p>
+  )}
+  <slot />
+</section>

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mcptoolshop/site-theme",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shared Astro theme for MCP Tool Shop org repo landing pages",
+  "keywords": ["astro-component", "withastro", "theme", "mcp"],
+  "author": "mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcp-tool-shop-org/site-theme.git"
+  },
+  "homepage": "https://github.com/mcp-tool-shop-org/site-theme",
+  "exports": {
+    ".": "./types/config.ts",
+    "./components/BaseLayout.astro": "./components/BaseLayout.astro",
+    "./components/Hero.astro": "./components/Hero.astro",
+    "./components/Section.astro": "./components/Section.astro",
+    "./components/FeatureGrid.astro": "./components/FeatureGrid.astro",
+    "./components/DataTable.astro": "./components/DataTable.astro",
+    "./components/CodeCardGrid.astro": "./components/CodeCardGrid.astro",
+    "./components/ApiList.astro": "./components/ApiList.astro"
+  },
+  "files": [
+    "components",
+    "styles",
+    "types",
+    "templates",
+    "cli",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "site-theme": "./cli/init.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "peerDependencies": {
+    "astro": ">=5.0.0",
+    "tailwindcss": ">=4.0.0",
+    "@tailwindcss/vite": ">=4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/styles/theme.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/templates/astro.config.mjs.tpl

@@ -0,0 +1,13 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+
+import tailwindcss from '@tailwindcss/vite';
+
+// https://astro.build/config
+export default defineConfig({
+  site: 'https://mcp-tool-shop-org.github.io',
+  base: '{{BASE_PATH}}',
+  vite: {
+    plugins: [tailwindcss()]
+  }
+});

package/templates/global.css.tpl

@@ -0,0 +1,2 @@
+@import "tailwindcss";
+@source "../../../node_modules/@mcptoolshop/site-theme";

package/templates/index.astro.tpl

@@ -0,0 +1,32 @@
+---
+import BaseLayout from '@mcptoolshop/site-theme/components/BaseLayout.astro';
+import Hero from '@mcptoolshop/site-theme/components/Hero.astro';
+import Section from '@mcptoolshop/site-theme/components/Section.astro';
+import FeatureGrid from '@mcptoolshop/site-theme/components/FeatureGrid.astro';
+import DataTable from '@mcptoolshop/site-theme/components/DataTable.astro';
+import CodeCardGrid from '@mcptoolshop/site-theme/components/CodeCardGrid.astro';
+import ApiList from '@mcptoolshop/site-theme/components/ApiList.astro';
+import { config } from '../site-config';
+---
+
+<BaseLayout
+  title={config.title}
+  description={config.description}
+  logoBadge={config.logoBadge}
+  brandName={config.brandName}
+  repoUrl={config.repoUrl}
+  npmUrl={config.npmUrl}
+  footerText={config.footerText}
+  nav={config.sections.map(s => ({ href: `#${s.id}`, label: s.title }))}
+>
+  <Hero {...config.hero} />
+
+  {config.sections.map((s) => (
+    <Section id={s.id} title={s.title} subtitle={s.subtitle}>
+      {s.kind === 'features' && <FeatureGrid features={s.features} />}
+      {s.kind === 'data-table' && <DataTable columns={s.columns} rows={s.rows} />}
+      {s.kind === 'code-cards' && <CodeCardGrid cards={s.cards} />}
+      {s.kind === 'api' && <ApiList apis={s.apis} />}
+    </Section>
+  ))}
+</BaseLayout>

package/templates/package.json.tpl

@@ -0,0 +1,17 @@
+{
+  "name": "site",
+  "type": "module",
+  "private": true,
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "@mcptoolshop/site-theme": "^0.1.0",
+    "@tailwindcss/vite": "^4.2.0",
+    "astro": "^5.17.0",
+    "tailwindcss": "^4.2.0"
+  }
+}

package/templates/pages.yml.tpl

@@ -0,0 +1,50 @@
+name: Deploy site to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install site dependencies
+        working-directory: site
+        run: npm ci
+
+      - name: Build site
+        working-directory: site
+        run: npm run build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

package/templates/site-config.ts.tpl

@@ -0,0 +1,48 @@
+import type { SiteConfig } from '@mcptoolshop/site-theme';
+
+export const config: SiteConfig = {
+  title: '{{PACKAGE_NAME}}',
+  description: '{{DESCRIPTION}}',
+  logoBadge: '{{LOGO_BADGE}}',
+  brandName: '{{BRAND_NAME}}',
+  repoUrl: '{{REPO_URL}}',
+  npmUrl: '{{NPM_URL}}',
+  footerText: 'MIT Licensed',
+
+  hero: {
+    badge: 'Open source',
+    headline: '{{BRAND_NAME}}',
+    headlineAccent: 'by mcp-tool-shop.',
+    description: '{{DESCRIPTION}}',
+    primaryCta: { href: '#usage', label: 'Get started' },
+    secondaryCta: { href: '#features', label: 'Learn more' },
+    previews: [
+      { label: 'Install', code: 'npm install {{PACKAGE_NAME}}' },
+      { label: 'Import', code: "import { ... } from '{{PACKAGE_NAME}}'" },
+      { label: 'Use', code: '// your code here' },
+    ],
+  },
+
+  sections: [
+    {
+      kind: 'features',
+      id: 'features',
+      title: 'Features',
+      subtitle: 'What makes {{BRAND_NAME}} useful.',
+      features: [
+        { title: 'Feature one', desc: 'Describe the first feature.' },
+        { title: 'Feature two', desc: 'Describe the second feature.' },
+        { title: 'Feature three', desc: 'Describe the third feature.' },
+      ],
+    },
+    {
+      kind: 'code-cards',
+      id: 'usage',
+      title: 'Usage',
+      cards: [
+        { title: 'Install', code: 'npm install {{PACKAGE_NAME}}' },
+        { title: 'Basic usage', code: "import { ... } from '{{PACKAGE_NAME}}';\n\n// your code here" },
+      ],
+    },
+  ],
+};

package/templates/tsconfig.json.tpl

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

package/types/config.ts

@@ -0,0 +1,89 @@
+export interface SiteConfig {
+  /** Page <title>, e.g. "@mcptoolshop/registry-stats" */
+  title: string;
+  /** Meta description */
+  description: string;
+  /** 1-2 char logo badge, e.g. "RS" */
+  logoBadge: string;
+  /** Brand name in header, e.g. "registry-stats" */
+  brandName: string;
+  /** GitHub repo URL */
+  repoUrl: string;
+  /** npm package URL (omit to hide npm header button) */
+  npmUrl?: string;
+  /** Footer left-side text, e.g. "MIT Licensed" */
+  footerText: string;
+
+  /** Hero section */
+  hero: HeroDef;
+
+  /** Ordered page sections (rendered top-to-bottom) */
+  sections: SectionDef[];
+}
+
+export interface HeroDef {
+  /** Status badge text */
+  badge: string;
+  /** Main headline */
+  headline: string;
+  /** Muted/accent suffix of headline */
+  headlineAccent: string;
+  /** Description paragraph (HTML allowed, rendered via set:html) */
+  description: string;
+  /** Primary CTA button */
+  primaryCta: CtaDef;
+  /** Secondary CTA button */
+  secondaryCta: CtaDef;
+  /** Code preview cards (typically 3) */
+  previews: PreviewDef[];
+}
+
+export interface CtaDef {
+  href: string;
+  label: string;
+}
+
+export interface PreviewDef {
+  label: string;
+  code: string;
+}
+
+export interface NavItem {
+  href: string;
+  label: string;
+}
+
+// --- Section variants ---
+
+export type SectionDef =
+  | FeatureSectionDef
+  | DataTableSectionDef
+  | CodeCardSectionDef
+  | ApiSectionDef;
+
+interface BaseSectionDef {
+  id: string;
+  title: string;
+  subtitle?: string;
+}
+
+export interface FeatureSectionDef extends BaseSectionDef {
+  kind: 'features';
+  features: { title: string; desc: string }[];
+}
+
+export interface DataTableSectionDef extends BaseSectionDef {
+  kind: 'data-table';
+  columns: string[];
+  rows: string[][];
+}
+
+export interface CodeCardSectionDef extends BaseSectionDef {
+  kind: 'code-cards';
+  cards: { title: string; code: string }[];
+}
+
+export interface ApiSectionDef extends BaseSectionDef {
+  kind: 'api';
+  apis: { signature: string; description: string }[];
+}