@igstack/app-catalog-frontend-core 1.0.0-alpha-20260913172344 → 1.0.0

package/src/modules/appCatalog/ui/pages/McpPage.tsx

@@ -0,0 +1,275 @@
+import { Check, Copy, TriangleAlert } from 'lucide-react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { Button } from '~/ui/button'
+import { Spinner } from '~/ui/spinner'
+import type { McpTool } from '../../utils/fetchMcpTools'
+import { MCP_ENDPOINT_PATH, fetchMcpTools } from '../../utils/fetchMcpTools'
+
+/**
+ * MCP docs page: how to point an AI agent at this catalog.
+ *
+ * Every snippet is built from `window.location.origin`, so production, a
+ * preview host and localhost each show a config that actually works — nothing
+ * is hardcoded.
+ *
+ * The tool reference is fetched from the live registry (`tools/list`) rather
+ * than written out by hand, so it cannot rot when the server's tools change.
+ */
+export function McpPage() {
+  const origin = typeof window === 'undefined' ? '' : window.location.origin
+  const endpoint = `${origin}${MCP_ENDPOINT_PATH}`
+  const serverName = 'app-catalog'
+
+  const [tools, setTools] = useState<McpTool[] | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [reloadKey, setReloadKey] = useState(0)
+  const headingRef = useRef<HTMLHeadingElement>(null)
+
+  // New view: land keyboard and screen-reader users in the content rather than
+  // leaving focus on whatever nav element was clicked.
+  useEffect(() => {
+    headingRef.current?.focus()
+  }, [])
+
+  useEffect(() => {
+    const controller = new AbortController()
+    setTools(null)
+    setError(null)
+    fetchMcpTools(origin, controller.signal)
+      .then(setTools)
+      .catch((err: unknown) => {
+        if (controller.signal.aborted) return
+        setError(
+          err instanceof Error
+            ? err.message
+            : 'Could not reach the MCP endpoint.',
+        )
+      })
+    return () => controller.abort()
+  }, [origin, reloadKey])
+
+  const mcpJson = JSON.stringify(
+    {
+      mcpServers: {
+        [serverName]: { type: 'http', url: endpoint },
+      },
+    },
+    null,
+    2,
+  )
+  const cliCommand = `claude mcp add --transport http ${serverName} ${endpoint}`
+
+  return (
+    <div className="flex flex-col flex-1 min-h-0 overflow-y-auto">
+      <div className="flex flex-col gap-8 max-w-3xl pb-8">
+        <section className="flex flex-col gap-2">
+          <h1
+            ref={headingRef}
+            tabIndex={-1}
+            className="text-xl font-semibold outline-none"
+          >
+            MCP server
+          </h1>
+          <p className="text-sm text-muted-foreground">
+            This catalog exposes a{' '}
+            <a
+              href="https://modelcontextprotocol.io"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="text-primary hover:underline"
+            >
+              Model Context Protocol
+            </a>{' '}
+            server, so an AI agent can search the catalog and read an entry the
+            same way you can — what exists, who owns it, and how to request
+            access. Point your agent at the endpoint below and it gains those
+            tools; no key or account is needed.
+          </p>
+          <p className="text-sm text-muted-foreground">
+            It speaks MCP over Streamable HTTP (JSON-RPC over{' '}
+            <code className="text-xs">POST</code>), and it is read-only.
+          </p>
+        </section>
+
+        <Snippet
+          title="Endpoint"
+          description="The URL an MCP client connects to."
+          value={endpoint}
+        />
+
+        <Snippet
+          title="Add it with the CLI"
+          description="One command, if your agent ships a CLI that manages MCP servers."
+          value={cliCommand}
+        />
+
+        <Snippet
+          title="Or add it to .mcp.json"
+          description="Commit this in a project so everyone working on it gets the same tools."
+          value={mcpJson}
+          language="json"
+        />
+
+        <section
+          className="flex flex-col gap-3"
+          aria-busy={tools === null && error === null}
+        >
+          <div className="flex flex-col gap-1">
+            <h2 className="text-base font-semibold">Tools</h2>
+            <p className="text-xs text-muted-foreground">
+              Read live from the server, so this list is always what your agent
+              will actually see.
+            </p>
+          </div>
+
+          {error !== null ? (
+            <div
+              role="alert"
+              className="flex flex-col items-start gap-3 rounded-md border border-destructive/40 bg-destructive/5 p-4"
+            >
+              <p className="flex items-start gap-2 text-sm">
+                <TriangleAlert className="size-4 shrink-0 mt-0.5 text-destructive" />
+                <span>
+                  Could not read the tool list. {error} The setup instructions
+                  above are still correct.
+                </span>
+              </p>
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => setReloadKey((k) => k + 1)}
+              >
+                Try again
+              </Button>
+            </div>
+          ) : tools === null ? (
+            <p className="flex items-center gap-2 text-sm text-muted-foreground">
+              <Spinner className="size-4" />
+              Reading the tool list…
+            </p>
+          ) : tools.length === 0 ? (
+            <p className="text-sm text-muted-foreground">
+              The server reported no tools.
+            </p>
+          ) : (
+            <ul className="flex flex-col gap-4 list-none p-0 m-0">
+              {tools.map((tool) => (
+                <li
+                  key={tool.name}
+                  className="rounded-md border p-4 flex flex-col gap-2"
+                >
+                  <code className="text-sm font-semibold">{tool.name}</code>
+                  {tool.description && (
+                    <p className="text-sm text-muted-foreground">
+                      {tool.description}
+                    </p>
+                  )}
+                  {tool.parameters.length === 0 ? (
+                    <p className="text-xs text-muted-foreground">
+                      No parameters.
+                    </p>
+                  ) : (
+                    <dl className="flex flex-col gap-2 m-0">
+                      {tool.parameters.map((param) => (
+                        <div key={param.name} className="flex flex-col gap-0.5">
+                          <dt className="text-xs">
+                            <code className="font-medium">{param.name}</code>
+                            {param.type && (
+                              <span className="text-muted-foreground">
+                                {' '}
+                                {param.type}
+                              </span>
+                            )}
+                            <span className="text-muted-foreground">
+                              {' '}
+                              — {param.required ? 'required' : 'optional'}
+                            </span>
+                          </dt>
+                          {param.description && (
+                            <dd className="text-xs text-muted-foreground m-0">
+                              {param.description}
+                            </dd>
+                          )}
+                          {param.enumValues && (
+                            <dd className="text-xs text-muted-foreground m-0">
+                              One of: {param.enumValues.join(', ')}
+                            </dd>
+                          )}
+                        </div>
+                      ))}
+                    </dl>
+                  )}
+                </li>
+              ))}
+            </ul>
+          )}
+        </section>
+      </div>
+    </div>
+  )
+}
+
+function Snippet({
+  title,
+  description,
+  value,
+  language,
+}: {
+  title: string
+  description: string
+  value: string
+  language?: string
+}) {
+  return (
+    <section className="flex flex-col gap-2">
+      <h2 className="text-base font-semibold">{title}</h2>
+      <p className="text-xs text-muted-foreground">{description}</p>
+      <div className="relative">
+        <pre
+          className="overflow-x-auto rounded-md border bg-muted/40 p-3 pr-12 text-xs"
+          data-language={language}
+        >
+          <code>{value}</code>
+        </pre>
+        <CopyButton value={value} label={title} />
+      </div>
+    </section>
+  )
+}
+
+function CopyButton({ value, label }: { value: string; label: string }) {
+  const [copied, setCopied] = useState(false)
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(
+    () => () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current)
+    },
+    [],
+  )
+
+  const copy = useCallback(() => {
+    void navigator.clipboard.writeText(value)
+    setCopied(true)
+    if (timeoutRef.current) clearTimeout(timeoutRef.current)
+    timeoutRef.current = setTimeout(() => setCopied(false), 2000)
+  }, [value])
+
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="icon"
+      onClick={copy}
+      aria-label={copied ? `${label} copied` : `Copy ${label}`}
+      title={copied ? 'Copied' : 'Copy'}
+      className="absolute right-1.5 top-1.5"
+    >
+      {copied ? (
+        <Check className="size-4 text-primary" />
+      ) : (
+        <Copy className="size-4" />
+      )}
+    </Button>
+  )
+}

package/src/modules/appCatalog/utils/fetchMcpTools.ts

@@ -0,0 +1,140 @@
+/**
+ * Minimal MCP client for the docs page: one `tools/list` call over Streamable
+ * HTTP. Deliberately raw `fetch` rather than the MCP SDK — the page needs one
+ * unauthenticated read and nothing else.
+ *
+ * The endpoint is stateless (a fresh server per request), so `tools/list`
+ * stands alone with no `initialize` handshake. It may answer with either JSON
+ * or a single SSE event, so both are parsed.
+ */
+
+export interface McpToolParameter {
+  name: string
+  type?: string
+  required: boolean
+  description?: string
+  enumValues?: string[]
+}
+
+export interface McpTool {
+  name: string
+  title?: string
+  description?: string
+  parameters: McpToolParameter[]
+}
+
+/** Path the MCP server is mounted at, relative to the site origin. */
+export const MCP_ENDPOINT_PATH = '/api/mcp'
+
+interface JsonSchemaProperty {
+  type?: string | string[]
+  description?: string
+  enum?: unknown[]
+  items?: { type?: string | string[]; enum?: unknown[] }
+}
+
+function describeType(prop: JsonSchemaProperty): string | undefined {
+  const base = Array.isArray(prop.type) ? prop.type.join(' | ') : prop.type
+  if (base === 'array') {
+    const itemType = Array.isArray(prop.items?.type)
+      ? prop.items.type.join(' | ')
+      : prop.items?.type
+    return itemType ? `${itemType}[]` : 'array'
+  }
+  return base
+}
+
+function enumValues(prop: JsonSchemaProperty): string[] | undefined {
+  const values = prop.enum ?? prop.items?.enum
+  return values?.length ? values.map(String) : undefined
+}
+
+/** Pull the single JSON-RPC payload out of a JSON or SSE response body. */
+function parseBody(contentType: string, body: string): unknown {
+  if (!contentType.includes('text/event-stream')) {
+    return JSON.parse(body)
+  }
+  const dataLines = body
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith('data:'))
+    .map((line) => line.slice('data:'.length).trim())
+  if (dataLines.length === 0) {
+    throw new Error('The server returned an empty event stream.')
+  }
+  return JSON.parse(dataLines.join(''))
+}
+
+/**
+ * Fetch the live tool registry so this page cannot go stale when the tools
+ * change.
+ *
+ * @param origin - Site origin, e.g. `window.location.origin`
+ * @param signal - Optional abort signal
+ */
+export async function fetchMcpTools(
+  origin: string,
+  signal?: AbortSignal,
+): Promise<McpTool[]> {
+  const response = await fetch(`${origin}${MCP_ENDPOINT_PATH}`, {
+    method: 'POST',
+    signal,
+    headers: {
+      'content-type': 'application/json',
+      // The Streamable HTTP transport requires the client to accept both.
+      accept: 'application/json, text/event-stream',
+    },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/list',
+      params: {},
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(
+      `The MCP endpoint answered ${response.status} ${response.statusText}.`,
+    )
+  }
+
+  const payload = parseBody(
+    response.headers.get('content-type') ?? '',
+    await response.text(),
+  ) as {
+    error?: { message?: string }
+    result?: {
+      tools?: {
+        name: string
+        title?: string
+        description?: string
+        inputSchema?: {
+          properties?: Record<string, JsonSchemaProperty>
+          required?: string[]
+        }
+      }[]
+    }
+  }
+
+  if (payload.error) {
+    throw new Error(
+      payload.error.message ?? 'The MCP endpoint returned an error.',
+    )
+  }
+
+  return (payload.result?.tools ?? []).map((tool) => {
+    const properties = tool.inputSchema?.properties ?? {}
+    const required = new Set(tool.inputSchema?.required ?? [])
+    return {
+      name: tool.name,
+      title: tool.title,
+      description: tool.description,
+      parameters: Object.entries(properties).map(([name, prop]) => ({
+        name,
+        type: describeType(prop),
+        required: required.has(name),
+        description: prop.description,
+        enumValues: enumValues(prop),
+      })),
+    }
+  })
+}

package/src/modules/appCatalog/utils/highlightText.ts

@@ -0,0 +1,51 @@
+/**
+ * Render-side helper for the search UI. The ranking engine itself lives in
+ * `@igstack/app-catalog-shared-core` so the UI and the MCP server rank
+ * identically and cannot drift.
+ */
+
+/**
+ * Highlight matching text in a string
+ * @param text - Text to highlight
+ * @param query - Search query
+ * @returns Array of text segments with highlight flags
+ */
+export function highlightText(
+  text: string,
+  query: string,
+): { text: string; highlight: boolean }[] {
+  if (!query.trim()) {
+    return [{ text, highlight: false }]
+  }
+
+  const normalizedQuery = query.trim().toLowerCase()
+  const lowerText = text.toLowerCase()
+  const index = lowerText.indexOf(normalizedQuery)
+
+  if (index === -1) {
+    return [{ text, highlight: false }]
+  }
+
+  const segments: { text: string; highlight: boolean }[] = []
+
+  // Text before match
+  if (index > 0) {
+    segments.push({ text: text.slice(0, index), highlight: false })
+  }
+
+  // Matched text
+  segments.push({
+    text: text.slice(index, index + normalizedQuery.length),
+    highlight: true,
+  })
+
+  // Text after match
+  if (index + normalizedQuery.length < text.length) {
+    segments.push({
+      text: text.slice(index + normalizedQuery.length),
+      highlight: false,
+    })
+  }
+
+  return segments
+}

package/src/routeTree.gen.ts

@@ -13,6 +13,7 @@ import { Route as LayoutRouteImport } from './routes/_layout'
 import { Route as LayoutIndexRouteImport } from './routes/_layout/index'
 import { Route as AuthCallbackRouteImport } from './routes/auth.callback'
 import { Route as LayoutServiceDesksRouteImport } from './routes/_layout/service-desks'
+import { Route as LayoutMcpRouteImport } from './routes/_layout/mcp'
 import { Route as LayoutLoginRouteImport } from './routes/_layout/login'
 import { Route as LayoutAppSlugRouteImport } from './routes/_layout/app.$slug'
 import { Route as LayoutCatalogAppsIndexRouteImport } from './routes/_layout/catalog.apps.index'
@@ -37,6 +38,11 @@ const LayoutServiceDesksRoute = LayoutServiceDesksRouteImport.update({
   path: '/service-desks',
   getParentRoute: () => LayoutRoute,
 } as any)
+const LayoutMcpRoute = LayoutMcpRouteImport.update({
+  id: '/mcp',
+  path: '/mcp',
+  getParentRoute: () => LayoutRoute,
+} as any)
 const LayoutLoginRoute = LayoutLoginRouteImport.update({
   id: '/login',
   path: '/login',
@@ -61,6 +67,7 @@ const LayoutAppSlugSubSubSlugRoute = LayoutAppSlugSubSubSlugRouteImport.update({
 export interface FileRoutesByFullPath {
   '/': typeof LayoutIndexRoute
   '/login': typeof LayoutLoginRoute
+  '/mcp': typeof LayoutMcpRoute
   '/service-desks': typeof LayoutServiceDesksRoute
   '/auth/callback': typeof AuthCallbackRoute
   '/app/$slug': typeof LayoutAppSlugRoute
@@ -69,6 +76,7 @@ export interface FileRoutesByFullPath {
 }
 export interface FileRoutesByTo {
   '/login': typeof LayoutLoginRoute
+  '/mcp': typeof LayoutMcpRoute
   '/service-desks': typeof LayoutServiceDesksRoute
   '/auth/callback': typeof AuthCallbackRoute
   '/': typeof LayoutIndexRoute
@@ -80,6 +88,7 @@ export interface FileRoutesById {
   __root__: typeof rootRouteImport
   '/_layout': typeof LayoutRouteWithChildren
   '/_layout/login': typeof LayoutLoginRoute
+  '/_layout/mcp': typeof LayoutMcpRoute
   '/_layout/service-desks': typeof LayoutServiceDesksRoute
   '/auth/callback': typeof AuthCallbackRoute
   '/_layout/': typeof LayoutIndexRoute
@@ -92,6 +101,7 @@ export interface FileRouteTypes {
   fullPaths:
     | '/'
     | '/login'
+    | '/mcp'
     | '/service-desks'
     | '/auth/callback'
     | '/app/$slug'
@@ -100,6 +110,7 @@ export interface FileRouteTypes {
   fileRoutesByTo: FileRoutesByTo
   to:
     | '/login'
+    | '/mcp'
     | '/service-desks'
     | '/auth/callback'
     | '/'
@@ -110,6 +121,7 @@ export interface FileRouteTypes {
     | '__root__'
     | '/_layout'
     | '/_layout/login'
+    | '/_layout/mcp'
     | '/_layout/service-desks'
     | '/auth/callback'
     | '/_layout/'
@@ -153,6 +165,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LayoutServiceDesksRouteImport
       parentRoute: typeof LayoutRoute
     }
+    '/_layout/mcp': {
+      id: '/_layout/mcp'
+      path: '/mcp'
+      fullPath: '/mcp'
+      preLoaderRoute: typeof LayoutMcpRouteImport
+      parentRoute: typeof LayoutRoute
+    }
     '/_layout/login': {
       id: '/_layout/login'
       path: '/login'
@@ -186,6 +205,7 @@ declare module '@tanstack/react-router' {
 
 interface LayoutRouteChildren {
   LayoutLoginRoute: typeof LayoutLoginRoute
+  LayoutMcpRoute: typeof LayoutMcpRoute
   LayoutServiceDesksRoute: typeof LayoutServiceDesksRoute
   LayoutIndexRoute: typeof LayoutIndexRoute
   LayoutAppSlugRoute: typeof LayoutAppSlugRoute
@@ -195,6 +215,7 @@ interface LayoutRouteChildren {
 
 const LayoutRouteChildren: LayoutRouteChildren = {
   LayoutLoginRoute: LayoutLoginRoute,
+  LayoutMcpRoute: LayoutMcpRoute,
   LayoutServiceDesksRoute: LayoutServiceDesksRoute,
   LayoutIndexRoute: LayoutIndexRoute,
   LayoutAppSlugRoute: LayoutAppSlugRoute,

package/src/routes/_layout/mcp.tsx

@@ -0,0 +1,22 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { appCatalogRouteLoader } from '~/modules/appCatalog/routeLoader'
+import { AppCatalogLayout } from '~/modules/appCatalog/ui/layout/AppCatalogLayout'
+import { McpPage } from '~/modules/appCatalog/ui/pages/McpPage'
+
+export const Route = createFileRoute('/_layout/mcp')({
+  component: RouteComponent,
+  async loader() {
+    const appCatalogLoader = await appCatalogRouteLoader()
+    return { appCatalogLoader }
+  },
+})
+
+function RouteComponent() {
+  const { queryClient, trpcClient } = Route.useRouteContext()
+
+  return (
+    <AppCatalogLayout queryClient={queryClient} trpcClient={trpcClient}>
+      <McpPage />
+    </AppCatalogLayout>
+  )
+}

package/dist/esm/__tests__/modules/appCatalog/utils/searchApps.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/esm/modules/appCatalog/utils/searchApps.d.ts

@@ -1,49 +0,0 @@
-import { Resource } from '@igstack/app-catalog-backend-core';
-export interface SearchMatch {
-    /** Field where the match occurred */
-    field: 'displayName' | 'abbreviation' | 'nicknames' | 'slug' | 'tags' | 'teams' | 'description' | 'subResource';
-    /** Type of match */
-    type: 'exact' | 'prefix' | 'contains';
-}
-export interface SearchResult {
-    app: Resource;
-    match: SearchMatch;
-}
-/**
- * Search and sort resources by relevance with highlighting support.
- * Only root resources (no parentSlug) are scored and returned.
- * Child resources (with parentSlug) contribute to their parent's score.
- *
- * Priority order:
- * 0. Exact match in abbreviation
- * 1. Exact match in displayName
- * 2. Exact match in nickname
- * 3. Prefix match in abbreviation
- * 4. Prefix match in displayName
- * 5. Prefix match in nickname
- * 6. Exact match in tags
- * 7. Prefix match in tags
- * 8. Contains match in abbreviation
- * 9. Contains match in displayName
- * 10. Contains match in nickname
- * 11. Contains match in tags
- * 12. Teams
- * 13. Description
- *
- * @param resources - Array of all resources (root + children)
- * @param searchQuery - Search query string
- * @returns Filtered and sorted array of root resources
- */
-export declare function searchResources(resources: Resource[], searchQuery: string): Resource[];
-/**
- * Highlight matching text in a string
- * @param text - Text to highlight
- * @param query - Search query
- * @returns Array of text segments with highlight flags
- */
-export declare function highlightText(text: string, query: string): {
-    text: string;
-    highlight: boolean;
-}[];
-/** @deprecated Use searchResources instead */
-export declare const searchApps: typeof searchResources;