smithery-homepage

What this skill does

# 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:
   ```bash
   mkdir -p ~/.smithery
   cd ~/.smithery && npx shadcn@latest init --preset b1FSjVe3E --template start --name homepage
   ```
2. Install additional dependencies:
   ```bash
   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:

```typescript
// 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:

```typescript
// 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 server functions — the API key never reaches the browser.

### Pattern: Shared MCP helper

Create a shared `src/lib/mcp.ts` that handles MCP connections for any server:

```typescript
// src/lib/mcp.ts
import { createConnection } from "@smithery/api/mcp"
import { Client } from "@modelcontextprotocol/sdk/client/index.js"

const NAMESPACE = process.env.SMITHERY_NAMESPACE ?? ""

export async function callMcpTool(
  connectionId: string,
  toolName: string,
  args: Record<string, unknown>,
): Promise<unknown> {
  const { transport } = await createConnection({
    namespace: NAMESPACE,
    connectionId,
  })

  const client = new Client({ name: "homepage", version: "1.0.0" })
  await client.connect(transport)

  try {
    const result = await client.callTool({ name: toolName, arguments: args })
    const content = result.content
    if (!Array.isArray(content)) return null
    const textBlock = content.find(
      (c): c is { type: "text"; text: string } => c.type === "text",
    )
    return textBlock?.text ? JSON.parse(textBlock.text) : null
  } finally {
    await client.close()
  }
}
```

### Pattern: Creating a tool caller module

**CRITICAL: Always use cached tool schemas for type safety.** The Smithery CLI caches Zod schemas for tool inputs and outputs at `~/.smithery/<connection>__<tool_name>.ts` after each successful tool call. These schemas contain the **real** input and output types — never hand-write or guess tool response types. **Never use `as` type casting on tool results.** Always parse results through the cached `outputSchema` to get proper types at runtime.

#### Step 1: Ensure the schema exists

Before writing a tool caller module, check if the cached schema file exists at `~/.smithery/<connection>__<tool_name>.ts`. If it does NOT exist, you MUST run the tool first to generate it:

```bash
smithery mcp call <connection> <tool_name> [--args '{}']
```

This creates the schema file with accurate `inputSchema`, `Input`, `outputSchema`, and `Output` types inferred from the real tool response. **You must always run the tool to generate the schema before writing code that depends on it — do not guess or hallucinate tool response shapes.**

#### Step 2: Copy the schema into the homepage project

Copy the cached schema file into the homepage's `src/lib/schemas/` directory so it's part of the project and available to the TypeScript compiler:

```bash
mkdir -p ~/.smithery/homepage/src/lib/schemas
cp ~/.smithery/<connection>__<tool_name>.ts ~/.smithery/homepage/src/lib/schemas/
```

Also ensure `zod` is installed in the homepage project (`npm install zod` if needed).

#### Step 3: Import sc