/smithery-homepage

name: smithery-homepage
description: "Build and edit the Smithery homepage app -- a TanStack Start + shadcn/ui web app at ~/.smithery/homepage that connects to MCP servers through the Smithery Connect API. Use this skill whenever the user wants to create, modify, or add features to the Smithery homepage, build pages that display data from MCP tools (Linear issues, Gmail, Notion, etc.), or asks about editing anything in ~/.smithery/homepage. Also triggers for requests like 'add a page to the homepage', 'show my Linear issues on the homepage', 'update the homepage UI', or any task involving the ~/.smithery/homepage project."

Smithery Homepage

The Smithery homepage is a TanStack Start app at `~/.smithery/homepage` that serves as a personal dashboard connecting to MCP servers via the Smithery Connect API.

Project Initialization

If `~/.smithery/homepage` does not exist, scaffold it from scratch:

1. Create the directory if needed and scaffold the app in place:

   mkdir -p ~/.smithery
   cd ~/.smithery && npx shadcn@latest init --preset b1FSjVe3E --template start --name homepage

2. Install additional dependencies:

   cd ~/.smithery/homepage
   npm install @smithery/api @modelcontextprotocol/sdk @tanstack/react-query @tanstack/react-query-devtools

3. Initialize git: `git init && git add -A && git commit -m "feat: initial commit"` 4. Create `.env` with the user's Smithery API key and namespace (read from `~/Library/Application Support/smithery/settings.json` on macOS — fields `apiKey` and `namespace`)

If `~/.smithery/homepage` already exists, work within the existing project — read the current code before making changes.

Tech Stack

• **Framework**: TanStack Start (Vite 7, React 19, file-based routing)
• **Styling**: Tailwind CSS v4 + shadcn/ui (radix-nova style, taupe base). **Always use shadcn components with their default styling** unless absolutely necessary or explicitly requested otherwise. This applies especially to charts — use shadcn's chart components (built on Recharts) rather than custom chart implementations.
• **Data Fetching**: `@tanstack/react-query` (React Query) — ALL API requests MUST use React Query
• **MCP Integration**: `@smithery/api` + `@modelcontextprotocol/sdk`
• **Server functions**: `createServerFn` from `@tanstack/react-start` for server-side MCP calls

CRITICAL: React Query for ALL API Requests

**Every API request in the app MUST use React Query (`@tanstack/react-query`).** Do not use raw `fetch`, `useEffect` + `useState`, or route loaders alone for data fetching. React Query provides caching, background refetching, loading/error states, and stale-while-revalidate — all of which are essential for a good dashboard UX.

QueryClient Setup

The `QueryClient` must be configured in the router and provided at the root layout. The scaffold generates `getRouter()` — update it to add the QueryClient:

// src/router.tsx
import { QueryClient } from "@tanstack/react-query"
import { createRouter as createTanStackRouter } from "@tanstack/react-router"
import { routeTree } from "./routeTree.gen"

export function getRouter() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 1000 * 60, // 1 minute
        refetchOnWindowFocus: true,
      },
    },
  })

  return createTanStackRouter({
    routeTree,
    context: { queryClient },
    scrollRestoration: true,
    defaultPreload: "intent",
    defaultPreloadStaleTime: 0,
  })
}

declare module "@tanstack/react-router" {
  interface Register {
    router: ReturnType<typeof getRouter>
  }
}

The scaffold generates `__root.tsx` with `createRootRoute` and a `shellComponent` for the HTML document wrapper. Replace `createRootRoute` with `createRootRouteWithContext` to pass QueryClient, keep the `shellComponent`, and add a `component` with QueryClientProvider:

// src/routes/__root.tsx
import {
  HeadContent,
  Outlet,
  Scripts,
  createRootRouteWithContext,
} from "@tanstack/react-router"
import { QueryClientProvider } from "@tanstack/react-query"
import { ReactQueryDevtools } from "@tanstack/react-query-devtools"
import type { QueryClient } from "@tanstack/react-query"
import appCss from "../styles.css?url"

export const Route = createRootRouteWithContext<{
  queryClient: QueryClient
}>()({
  head: () => ({
    meta: [
      { charSet: "utf-8" },
      { name: "viewport", content: "width=device-width, initial-scale=1" },
      { title: "Dashboard" },
    ],
    links: [{ rel: "stylesheet", href: appCss }],
  }),
  component: RootComponent,
  shellComponent: RootDocument,
})

function RootComponent() {
  const { queryClient } = Route.useRouteContext()
  return (
    <QueryClientProvider client={queryClient}>
      <Outlet />
      <ReactQueryDevtools />
    </QueryClientProvider>
  )
}

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        {children}
        <Scripts />
      </body>
    </html>
  )
}

Project Structure

~/.smithery/homepage/
├── src/
│   ├── routes/          # File-based routes (TanStack Router)
│   │   ├── __root.tsx   # Root layout with QueryClientProvider
│   │   └── index.tsx    # Home page
│   ├── components/ui/   # shadcn components
│   ├── lib/             # Server-side helpers (MCP tool callers)
│   │   └── schemas/     # Cached Zod schemas copied from ~/.smithery/
│   ├── router.tsx       # Router setup with QueryClient
│   ├── routeTree.gen.ts # Auto-generated route tree
│   └── styles.css       # Tailwind + shadcn theme
├── .env                 # SMITHERY_API_KEY
├── components.json      # shadcn config
├── package.json
├── tsconfig.json
└── vite.config.ts       # (if present)

How to Connect to MCP Servers

The app uses `@smithery/api/mcp` to create MCP connections through Smithery Connect. This runs server-side via TanStack Start