多模板Astro网站主题工具包

English | 日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

@mcptoolshop/site-theme

Multi-template Astro toolkit for landing pages, docs, product sites, portfolios, and SaaS dashboards —
plus front-door, the verifier for a repo's AI-native README / AGENTS.md / llms.txt.
Dark palette · Tailwind CSS v4 · GitHub Pages ready.

Templates · Quick Start · Front Door · Design Tokens · Components · Deploy · License

Templates

Pick a template, scaffold, build. Every template ships CI-tested and GitHub Pages-ready.

npx @mcptoolshop/site-theme list-templates            # see all options
npx @mcptoolshop/site-theme list-templates --json      # machine-readable output
npx @mcptoolshop/site-theme init --template app        # scaffold a template
npx @mcptoolshop/site-theme init --template app --dry-run   # preview files
npx @mcptoolshop/site-theme init --out ../other-repo   # scaffold into another directory

Quick Start

Scaffold a new site

npx @mcptoolshop/site-theme init
cd site && npm install
npm run dev

This creates a site/ directory with Astro 7 + Tailwind + theme wired up, plus a GitHub Pages workflow. The CSS import, @source path, and base path are all pre-configured — no manual setup needed. Existing consumers on Astro 5 or 6 keep working (peerDependencies.astro is >=5).

Edit your content

All page content lives in site/src/site-config.ts. Edit the config object to customize your landing page:

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',
  packageUrl: 'https://www.npmjs.com/package/@mcptoolshop/my-tool',
  footerText: 'MIT Licensed',

  hero: { /* ... */ },
  sections: [ /* ... */ ],
};

Front Door

site-theme renders a repo's human front door; front-door verifies its agent/machine front door — the README, AGENTS.md, and llms.txt that humans, agents, and tooling read first. It is verify-first: it doesn't write prose for you, it proves your prose is true and minimal.

npx @mcptoolshop/site-theme front-door verify                  # audit; exits 1 if the gate fails
npx @mcptoolshop/site-theme front-door verify --run-doctests   # also compile/run fenced JS examples
npx @mcptoolshop/site-theme front-door init                    # scaffold a minimal, verify-clean front door
npx @mcptoolshop/site-theme front-door standard                # print the front-door spine
npx @mcptoolshop/site-theme front-door eval                    # the verifier's self-eval receipt
npx @mcptoolshop/site-theme front-door mcp                     # start the MCP server (agents call verify)

It routes each documented claim to the evidence that can back it — dead paths / scripts / links, AGENTS.md↔README duplication, status-badge distrust, example imports vs real exports (and, with --run-doctests, that the examples actually compile and run), provenance claims vs real attestation, and bloat (length / readability / directive budget for AGENTS.md). Findings are risk-ordered into four buckets: Verified / Contradicted / Missing / Unverifiable.

Use it programmatically (shipcheck consumes this):

import { verify } from '@mcptoolshop/site-theme/front-door';

const scorecard = verify({ root: process.cwd() });
if (!scorecard.gate.pass) process.exit(1);

Or let an agent call it: front-door mcp starts a zero-dependency MCP server (stdio) exposing front_door_verify — the agent receives the same structured scorecard.

See the Front Door reference for the full channel list and the standard.

Design Tokens

The theme ships semantic design tokens via styles/theme.css. Components reference these tokens instead of hardcoded colors, so you can reskin the entire theme by overriding a few values.

Default tokens

Customizing

Override any token in your site's global.css by adding a @theme block after the imports:

@import "tailwindcss";
@import "@mcptoolshop/site-theme/styles/theme.css";
@source "../../node_modules/@mcptoolshop/site-theme";

/* Override tokens */
@theme {
  --color-accent: #60a5fa;          /* blue status dot   */
  --color-surface: #0a0a1a;         /* navy background   */
  --color-action: #60a5fa;          /* blue buttons      */
  --color-action-hover: #3b82f6;
}

Tokens generate standard Tailwind v4 utilities (bg-surface, text-heading, border-edge, etc.) so you can also use them in your own components.

Components

Import components individually from the package:

---
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 DocLayout from '@mcptoolshop/site-theme/components/DocLayout.astro';
import Sidebar from '@mcptoolshop/site-theme/components/Sidebar.astro';
import TableOfContents from '@mcptoolshop/site-theme/components/TableOfContents.astro';
import ContentSection from '@mcptoolshop/site-theme/components/ContentSection.astro';
import SocialProof from '@mcptoolshop/site-theme/components/SocialProof.astro';
import PricingGrid from '@mcptoolshop/site-theme/components/PricingGrid.astro';
import TestimonialGrid from '@mcptoolshop/site-theme/components/TestimonialGrid.astro';
import CtaBanner from '@mcptoolshop/site-theme/components/CtaBanner.astro';
import PortfolioGrid from '@mcptoolshop/site-theme/components/PortfolioGrid.astro';
import FilterBar from '@mcptoolshop/site-theme/components/FilterBar.astro';
---

The theme ships 17 Astro components across five categories: layout shells, content sections, marketing blocks, portfolio, and documentation.

BaseLayout

Full page shell with sticky header (logo badge, nav links, GitHub / package buttons) and footer. Named slot head is the extension point for extra <head> tags (OG image, JSON-LD, preconnect).

<BaseLayout {title} {description} {logoBadge} {brandName} {repoUrl} packageUrl={config.packageUrl} {footerText}>
  <Fragment slot="head">
    <meta property="og:image" content={ogImage} />
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:image" content={ogImage} />
  </Fragment>
  <!-- page body -->
</BaseLayout>

Hero

Gradient hero with status badge, headline, CTAs, and optional code preview cards.

Section

Section wrapper with anchor id, heading, and optional subtitle.

FeatureGrid

3-column responsive card grid. Props: features: { title, desc }[]

DataTable

Grid-based bordered table. Props: columns: string[], rows: string[][]

CodeCardGrid

2-column grid of dark code block cards. Props: cards: { title, code }[]

ApiList

Full-width stacked API reference cards. Props: apis: { signature, description }[]

FilterBar

Client-side search + tag filtering bar for portfolio grids. Props: tags: string[], searchable?: boolean, searchPlaceholder?: string

PortfolioGrid

Configurable card grid with status badges, category grouping, and image/badge fallbacks. Props: items: PortfolioItem[], columns?: 2 | 3 | 4, groupByCategory?: boolean

DocLayout

Two-column layout with collapsible sidebar and main content area. Used by the docs template. Props: sidebar: SidebarGroup[], currentPath: string

Sidebar

Grouped navigation list with active-link highlighting. Props: groups: SidebarGroup[], currentPath?: string

TableOfContents

On-page heading navigation. Props: headings?: { text, id, depth }[]

ContentSection

Anchor-linked content block that renders HTML via set:html. Props: id: string, title: string, content: string

SocialProof

Stats bar with headline and value/label pairs. Props: headline?: string, stats?: { value, label }[]

PricingGrid

Responsive pricing tier cards with highlighted "Popular" tier. Props: tiers?: PricingTier[]

TestimonialGrid

Two-column quote cards with avatar fallback initials. Props: testimonials?: { quote, author, role, avatarUrl? }[]

CtaBanner

Full-width gradient call-to-action banner. Props: headline: string, description?: string, cta: { href, label }

Section Types

The sections array in your config supports these kind values:

Sections render in the order they appear in the array.

Deploy

The init CLI creates .github/workflows/pages.yml automatically. To go live:

1. Push your repo to GitHub
2. Go to your repo → Settings → Pages
3. Under Build and deployment, set Source to GitHub Actions
4. Push any change to site/ to trigger the first build

Your site will be live at https://<org>.github.io/<repo>/.

Security & Data Scope

HTML Props (set:html)

Several component props render raw HTML via Astro's set:html directive. If your data source is untrusted (user-generated content, external APIs), sanitize the HTML before passing it using a library like DOMPurify or sanitize-html.

See SECURITY.md for vulnerability reporting.

Scorecard

Full audit: SHIP_GATE.md · SCORECARD.md

License

MIT

Built by MCP Tool Shop