smithery-ai/cli/smithery-homepage

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 ``

1. Install additional dependencies:

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

1. Initialize git: git init && git add -A && git commit -m "feat: initial commit"
2. 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 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:

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

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:

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 schemas and parse tool results

For each MCP server, create a helper in src/lib/ that imports the shared MCP helper AND the cached schemas. Import outputSchema (the Zod schema) to parse results, and type Input for compile-time argument checking:

// src/lib/linear.ts
import { createServerFn } from "@tanstack/react-start"
import { queryOptions } from "@tanstack/react-query"
import { callMcpTool } from "./mcp"
import type { Input as ListIssuesInput } from "./schemas/linear__list_issues"
import { outputSchema as listIssuesOutputSchema } from "./schemas/linear__list_issues"
// Server functions (called by React Query from the client)
export const fetchIssues = createServerFn({ method: "GET" }).handler(
  async () => {
    const raw = await callMcpTool("linear", "list_issues", {
      assignee: "me",
      includeArchived: false,
    } satisfies ListIssuesInput)
    const data = listIssuesOutputSchema.parse(raw)
    return data.issues.filter(
      (i) => i.statusType !== "canceled" && i.statusType !== "completed"
    )
  },
)
// Query options factory — use this in routes and components
export const issuesQueryOptions = () =>
  queryOptions({
    queryKey: ["linear", "issues"],
    queryFn: () => fetchIssues(),
    staleTime: 1000 * 60 * 2, // 2 minutes
  })

Key points:

• Use satisfies Input on the args object to catch invalid tool inputs at compile time
• Always parse results with `outputSchema.parse(raw)` — this validates the data at runtime AND gives you the correct TypeScript type. Never use as casting on tool results.
• Never hand-write tool response types — always derive them from the cached schema
• If a schema file seems stale, re-run the tool (smithery mcp call ...) to regenerate it

Server functions with input parameters

IMPORTANT: .validator() does NOT exist in TanStack Start. For server functions that accept input:

• For GET server functions, type the handler's { data } parameter directly:

``typescript export const fetchItem = createServerFn({ method: "GET" }).handler( async ({ data }: { data: { id: string } }) => { return callMcpTool("service", "get_item", { item_id: data.id }) }, ) // Call: fetchItem({ data: { id: "123" } }) ``

• For POST mutations, use .inputValidator() (not .validator()):

``typescript export const createItem = createServerFn({ method: "POST" }) .inputValidator((data: { title: string }) => data) .handler(async ({ data }) => { return callMcpTool("service", "create_item", { title: data.title }) }) ``

Pattern: Using React Query in routes

Use queryOptions + useQuery for data fetching. Prefetch in the route loader for instant navigation, then read via React Query in the component. Always destructure isLoading, error, and refetch alongside data to handle all states.

// src/routes/issues.tsx
import { createFileRoute } from "@tanstack/react-router"
import { useQuery } from "@tanstack/react-query"
import { issuesQueryOptions } from "@/lib/linear"
export const Route = createFileRoute("/issues")({
  loader: ({ context: { queryClient } }) =>
    // Use void to fire-and-forget — don't block navigation on data
    void queryClient.ensureQueryData(issuesQueryOptions()),
  component: IssuesPage,
})
function IssuesPage() {
  const { data: issues, isLoading, error, refetch } = useQuery(issuesQueryOptions())
  // Handle all three states: loading, error, success
  return (/* render issues */)
}

CRITICAL: Loading & Error Handling

Every component that uses `useQuery` MUST handle loading and error states. Never render only the success case.

Standard loading/error pattern

Use isLoading and error from useQuery, plus a skeleton loader and an error component with retry:

function DataSection() {
  const { data, isLoading, error, refetch } = useQuery(dataQueryOptions())