merge: sync release/v2 into assistant authoring
Preserve release/v2's concise public documentation while compacting the expanded skill trigger and routing text so the serialized lazy resource remains below 12,000 bytes.
This commit is contained in:
commit
288bbcff98
60 files changed
+3482
-4485
No files matched your search
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: codebase-context
|
||||
description: Navigate Homarr's monorepo architecture and reuse shared packages. Use when locating code, choosing a package boundary, understanding runtime services, tRPC, databases, widgets, integrations, cron jobs, Custom Widgets, Workshop, or checking @homarr/common before creating a utility.
|
||||
---
|
||||
|
||||
# Homarr Codebase Context
|
||||
|
||||
Orient from the current checkout before editing. Treat package manifests, exports, and source as authoritative when they differ from this snapshot.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Confirm the branch and inspect the nearest `package.json`, existing sibling modules, and package exports.
|
||||
2. Search `@homarr/common` before creating a general-purpose helper. Read [references/common.md](references/common.md) for every public entrypoint and export.
|
||||
3. Read [references/architecture.md](references/architecture.md) when the task crosses packages, runtimes, routing, data, widgets, integrations, cron jobs, Custom Widgets, or Workshop.
|
||||
4. Keep the change in the deepest package that owns the behavior. Reuse public entrypoints rather than deep-importing implementation files.
|
||||
5. Re-run targeted searches before documenting counts, consumers, or dependency edges; these change faster than the architectural seams.
|
||||
|
||||
## Current toolchain
|
||||
|
||||
- Use Node `24.18.0` from `mise.toml` and pnpm `11.15.1` from `package.json`.
|
||||
- Use pnpm workspaces with Turborepo. Workspace packages use the `@homarr/` scope and catalog-managed dependencies.
|
||||
- Use Next.js App Router, TypeScript, tRPC, Drizzle, Mantine v9, Tabler icons, Jotai, TanStack Query, next-intl, Vitest, and Playwright.
|
||||
- Use oxlint and oxfmt. Mantine is the application UI system; Tailwind is limited to the docs app.
|
||||
- `pnpm dev` starts only `@homarr/nextjs`. Start a standalone runtime explicitly when the task needs it.
|
||||
|
||||
## High-value seams
|
||||
|
||||
- Server/RSC tRPC: `@homarr/api/server`
|
||||
- Client tRPC hooks: `@homarr/api/client`
|
||||
- Main router: `packages/api/src/root.ts`
|
||||
- MCP eager router: `packages/api/src/mcp.ts`
|
||||
- Database schemas: `packages/db/schema/{sqlite,mysql,postgresql}.ts`
|
||||
- Widget registry: `packages/widgets/src/registry.ts`
|
||||
- Widget loading manifest: `packages/widgets/src/manifest.ts`
|
||||
- Integration definitions: `packages/definitions/src/integration.ts`
|
||||
- Integration factory: `packages/integrations/src/base/creator.ts`
|
||||
- Cron jobs: `packages/cron-jobs/src/jobs/`
|
||||
- App routes: `apps/nextjs/src/app/[locale]/`
|
||||
|
||||
When a code change affects users, invoke `documentation-sync`. When exposing tRPC through MCP, invoke `mcp-integration`.
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Homarr Codebase Context"
|
||||
short_description: "Navigate Homarr architecture and shared APIs"
|
||||
default_prompt: "Use $codebase-context to locate the right Homarr package and reuse existing shared APIs."
|
||||
@@ -0,0 +1,110 @@
|
||||
# Homarr architecture
|
||||
|
||||
## Contents
|
||||
|
||||
- [Applications and runtimes](#applications-and-runtimes)
|
||||
- [Package map](#package-map)
|
||||
- [Dependency direction](#dependency-direction)
|
||||
- [Core patterns](#core-patterns)
|
||||
- [Commands and conventions](#commands-and-conventions)
|
||||
|
||||
## Applications and runtimes
|
||||
|
||||
| Path | Role |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `apps/nextjs` | Main Next.js application and HTTP APIs on port 3000 |
|
||||
| `apps/docs` | Docusaurus documentation site on port 3003 |
|
||||
| `apps/tasks` | Cron-job initialization and scheduling runtime; it does not expose the old port-3002 API |
|
||||
| `apps/websocket` | tRPC WebSocket subscriptions on port 3001 |
|
||||
| `apps/workshop` | Go/PocketBase Workshop service and provider integration |
|
||||
|
||||
`pnpm dev` runs only `@homarr/nextjs`. Use `pnpm --filter @homarr/tasks dev`, `pnpm --filter @homarr/websocket dev`, or `pnpm dev:docs` when a task needs those runtimes.
|
||||
|
||||
In production, `apps/nextjs/src/instrumentation-node.ts` starts the tasks and WebSocket runtimes inside the Node process. Nginx listens on port 7575, proxies `/websockets` to port 3001, and sends other traffic to port 3000. Redis can run internally or externally.
|
||||
|
||||
## Package map
|
||||
|
||||
### Foundation and domain
|
||||
|
||||
- `core`: environment validation, database and Redis factories, logging, infrastructure.
|
||||
- `definitions`: domain enums, integration definitions, widget kinds, permissions.
|
||||
- `common`: shared utilities with environment-specific entrypoints. Search it before adding helpers.
|
||||
- `validation`: shared Zod schemas.
|
||||
- `server-settings`: typed server-setting keys and access.
|
||||
|
||||
### Data, identity, and transport
|
||||
|
||||
- `db`: Drizzle schemas, queries, migrations, and three database drivers.
|
||||
- `auth`: Auth.js/NextAuth configuration, sessions, providers, and API keys.
|
||||
- `api`: tRPC routers, contexts, MCP metadata extraction, OpenAPI, and client/server entrypoints.
|
||||
- `redis`: Redis clients, pub/sub channels, and caches.
|
||||
- `cron-jobs-core`, `cron-jobs`, `cron-job-status`: scheduling primitives, job implementations, and status transport.
|
||||
|
||||
### Backends and external systems
|
||||
|
||||
- `integrations`: typed clients for external applications.
|
||||
- `request-handler`: shared server request flows.
|
||||
- `docker`, `ping`, `image-proxy`, `icons`, `analytics`: bounded infrastructure capabilities.
|
||||
- `custom-widgets`: Custom JSX v2 schema, validation, runtime, and security contracts.
|
||||
- `workshop`: TypeScript Workshop client, backend contracts, and schemas used by Homarr.
|
||||
|
||||
### UI and composed features
|
||||
|
||||
- `ui`: shared Mantine components, theme, and hooks. Search here before creating a primitive.
|
||||
- `form`, `forms-collection`: Zod-backed form setup and reusable forms.
|
||||
- `modals`, `modals-collection`: modal primitives and feature modals.
|
||||
- `boards`: board state, edit mode, and cache coordination.
|
||||
- `settings`, `spotlight`, `notifications`, `onboarding`: cross-feature UI flows.
|
||||
- `widgets`: widget definitions, dynamic component loaders, and shared widget UI.
|
||||
- `translation`: next-intl configuration and locale catalogs.
|
||||
- `cli`: Node operations CLI. `tools/homarr-dev` is the separate Go developer CLI.
|
||||
|
||||
## Dependency direction
|
||||
|
||||
Prefer these directions; verify the exact dependency in package manifests before changing a boundary.
|
||||
|
||||
1. Put infrastructure in `core` and stable domain names in `definitions`.
|
||||
2. Put reusable, dependency-light helpers in `common`; use its public environment-specific entrypoints.
|
||||
3. Build persistence in `db`, identity in `auth`, transport in `redis`, and external clients in `integrations`.
|
||||
4. Compose server behavior in `api`, `cron-jobs`, and request-handler packages.
|
||||
5. Build primitives in `ui`, `form`, and `modals`; compose product surfaces in widgets and collection packages.
|
||||
6. Keep app entrypoints in `apps/*` thin. Avoid moving reusable behavior into `apps/nextjs` when a package already owns it.
|
||||
|
||||
## Core patterns
|
||||
|
||||
### tRPC and MCP
|
||||
|
||||
`packages/api/src/root.ts` lazily composes the application router. Server components use `@homarr/api/server`; client components use `@homarr/api/client`. MCP extraction requires the eager router in `packages/api/src/mcp.ts`, so MCP-enabled subrouters must be imported and registered there directly. Use the `mcp-integration` skill for exposure and security rules.
|
||||
|
||||
### Databases
|
||||
|
||||
Drizzle schemas live in parallel files under `packages/db/schema/`. `DB_DRIVER` selects `better-sqlite3`, `mysql2`, or `node-postgres`; migrations live in matching directories under `packages/db/migrations/`. Apply schema behavior consistently across all supported drivers unless the task is explicitly driver-specific.
|
||||
|
||||
### Widgets
|
||||
|
||||
`packages/widgets/src/registry.ts` owns the explicit widget-module and component-loader registries. `packages/widgets/src/manifest.ts` caches those loaders and exposes definitions, components, and combined resources. Widget modules use `createWidgetDefinition` and typed option builders. Data commonly comes from tRPC queries or Redis-backed cron results. Use existing shared widget components before creating local variants.
|
||||
|
||||
### Integrations
|
||||
|
||||
`packages/definitions/src/integration.ts` owns `integrationDefs` and `IntegrationKind`. `packages/integrations/src/base/creator.ts` owns `createIntegrationAsync`; concrete integrations implement the shared base contract. Keep credentials and permission checks on server-owned paths.
|
||||
|
||||
### Cron jobs
|
||||
|
||||
Jobs live in `packages/cron-jobs/src/jobs/` and use `createCronJob`. `apps/tasks` initializes and starts the job group. Job results and status can flow through Redis and tRPC; the retired port-3002 management-API model is no longer part of the architecture.
|
||||
|
||||
### Routing and localization
|
||||
|
||||
User routes live below `apps/nextjs/src/app/[locale]/`; the locale segment does not add a URL prefix. Route groups organize home and board surfaces. Administrative routes live under `manage`, Custom Widget configuration has a token route, and Workshop has a management surface.
|
||||
|
||||
### Custom Widgets and Workshop
|
||||
|
||||
`packages/custom-widgets` owns the Custom JSX v2 contract. `packages/workshop` is the Homarr-side client/contract package; `apps/workshop` is the separate Go/PocketBase service. Use the `homarr-custom-widget` skill for authoring and security constraints.
|
||||
|
||||
## Commands and conventions
|
||||
|
||||
- Read current scripts from the root or package `package.json`; avoid caching commands that do not exist.
|
||||
- Use `pnpm dev` for Next.js, `pnpm dev:docs` for docs, and `pnpm dev:cli -- <args>` for the Go developer CLI.
|
||||
- Use `pnpm docker:dev:up` for the Redis development dependency.
|
||||
- Use package-filtered typechecks or focused tests for the touched behavior.
|
||||
- Use `~/*` only inside the Next.js app. Use public `@homarr/*` entrypoints across package boundaries.
|
||||
- Keep Mantine application styles separate from the Tailwind-based docs app.
|
||||
@@ -0,0 +1,86 @@
|
||||
# `@homarr/common` public API
|
||||
|
||||
## Contents
|
||||
|
||||
- [Reuse workflow](#reuse-workflow)
|
||||
- [Entrypoints](#entrypoints)
|
||||
- [Root exports](#root-exports)
|
||||
- [Types exports](#types-exports)
|
||||
- [Server exports](#server-exports)
|
||||
- [Client and environment exports](#client-and-environment-exports)
|
||||
|
||||
## Reuse workflow
|
||||
|
||||
Before writing a utility, search both the public name and the behavior:
|
||||
|
||||
```bash
|
||||
rg -n "export (const|function|class|type|interface)|export \*" packages/common
|
||||
rg -n "@homarr/common" apps packages
|
||||
```
|
||||
|
||||
Import only from an exported package entrypoint. Do not deep-import `@homarr/common/src/*`. Check `packages/common/package.json` and the source again when adding or renaming an export; this inventory describes the current repository tree.
|
||||
|
||||
## Entrypoints
|
||||
|
||||
| Import | Source | Environment |
|
||||
| ----------------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
|
||||
| `@homarr/common` | `index.ts` -> `src/index.ts` | Shared root; includes React hooks and some Next/Mantine-aware helpers |
|
||||
| `@homarr/common/types` | `src/types.ts` | Type-only utilities |
|
||||
| `@homarr/common/server` | `src/server.ts` | Node/server-only security, encryption, request, error, and bounded-response helpers |
|
||||
| `@homarr/common/client` | `src/client.ts` | Client-facing Next server action export |
|
||||
| `@homarr/common/env` | `env.ts` | Validated package environment |
|
||||
|
||||
## Root exports
|
||||
|
||||
| Area | Public exports | Purpose |
|
||||
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
|
||||
| Objects | `objectKeys`, `objectEntries`, `hashObjectBase64` | Typed key/entry iteration and stable query-key hashing |
|
||||
| Strings | `capitalize`, `isNullOrWhitespace`, `bestMatch`, `normalizeImageName`, `getImageMatchRank` | Text normalization and matching |
|
||||
| Cookies | `parseCookies`, `setClientCookie` | Cookie parsing and browser cookie serialization |
|
||||
| Arrays | `splitToNChunks`, `splitToChunksWithNItems` | Split by number of groups or maximum group size |
|
||||
| Dates | `formatDuration`, `toValidDate`, `isDateWithin` | Duration formatting, safe date coercion, relative-window checks |
|
||||
| Timing | `Stopwatch` | Elapsed-time measurement and formatting |
|
||||
| React hooks | `useTimeAgo`, `useIntegrationConnected` | Relative time and integration freshness state |
|
||||
| URLs | `removeTrailingSlash`, `extractBaseUrlFromHeaders`, `getPortFromUrl`, `isAbsoluteUrl`, `SAFE_NEW_TAB_REL`, `getSafeApplicationUrl`, `getSafeAppHref` | URL normalization, safe navigation, ports, and new-tab policy |
|
||||
| Numbers and bytes | `formatNumber`, `randomInt`, `formatBytes`, `formatBytesPair`, `formatByteRate`, `metricToImperial`, `imperialToMetric` | Compact numbers, byte displays, rates, and unit conversion |
|
||||
| Legacy bytes | `humanFileSize` | Deprecated; use the `formatBytes*` helpers in new code |
|
||||
| Byte types | `ByteUnitSystem`, `FormatBytesOptions` | Options for byte formatting |
|
||||
| Errors | `extractErrorMessage`, `FlattenError` | Unknown-error messages and flattenable domain errors |
|
||||
| Theme | `getMantineColor` | Resolve a Mantine color and shade |
|
||||
| Functions | `isFunction` | Unknown-value function guard |
|
||||
| Grid | `GridAlgorithmItem`, `generateResponsiveGridFor` | Responsive nested-section grid placement |
|
||||
| IDs | `createId` | CUID2 ID creation |
|
||||
|
||||
The root deliberately does not re-export `types`, `server`, `client`, or `env`; use their named entrypoints.
|
||||
|
||||
## Types exports
|
||||
|
||||
`@homarr/common/types` exports:
|
||||
|
||||
- `MaybePromise<T>`
|
||||
- `AtLeastOneOf<T>`
|
||||
- `Modify<T, R>`
|
||||
- `RemoveReadonly<T>`
|
||||
- `MaybeArray<T>`
|
||||
- `Inverse<T>`
|
||||
- `inferSearchParamsFromSchema<TSchema>`
|
||||
|
||||
## Server exports
|
||||
|
||||
`@homarr/common/server` exports:
|
||||
|
||||
- Security: `generateSecureRandomToken`.
|
||||
- Encryption: `encryptSecret`, `decryptSecret`, `decryptSecretWithKey`, `createKeyedFingerprint`, `verifyKeyedFingerprint`.
|
||||
- Requests: `userAgent`, `DeviceType`, `ipAddressFromHeaders`.
|
||||
- Bounded bodies: `readBoundedJsonResponseAsync`.
|
||||
- Parse errors: `ParseError`, `ParseErrorHandler`, `ZodParseErrorHandler`, `JsonParseErrorHandler`.
|
||||
- HTTP handlers: `HttpErrorHandler`, `FetchHttpErrorHandler`, `matchErrorCode`, `OFetchHttpErrorHandler`, `AxiosHttpErrorHandler`, `TsdavHttpErrorHandler`, `OctokitHttpErrorHandler`.
|
||||
- HTTP errors: `RequestError`, `ResponseError`, `requestErrorMap`.
|
||||
- HTTP error types: `AnyRequestError`, `AnyRequestErrorInput`, `RequestErrorInput`, `RequestErrorType`, `RequestErrorReason`, `AnyRequestErrorReason`, `RequestErrorCode`.
|
||||
|
||||
`NodeFetchHttpErrorHandler` exists as an implementation file but is not exported by the public server entrypoint. Add an intentional public export before using it across packages.
|
||||
|
||||
## Client and environment exports
|
||||
|
||||
- `@homarr/common/client` exports `revalidatePathActionAsync`, a Next server action for page revalidation.
|
||||
- `@homarr/common/env` exports `env` with validated `NODE_ENV`, `SECRET_ENCRYPTION_KEY`, and `NO_EXTERNAL_CONNECTION` values.
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: documentation-sync
|
||||
description: Keep Homarr's Docusaurus documentation aligned with user-facing code. Use when adding or changing integrations, widgets, APIs, environment variables, CLI commands, authentication, permissions, cron jobs, settings, or UI behavior that users must understand.
|
||||
---
|
||||
|
||||
# Documentation Sync
|
||||
|
||||
Update `apps/docs/` in the same change as user-facing behavior. Inspect adjacent pages and the docs types before copying a pattern; the source and docs evolve together.
|
||||
|
||||
## Map the change
|
||||
|
||||
| Code change | Documentation target |
|
||||
| ----------------------------------- | -------------------------------------------------------------------- |
|
||||
| New integration | `apps/docs/docs/integrations/<slug>/index.mdx` and `index.ts` |
|
||||
| New widget | `apps/docs/docs/widgets/<slug>/index.mdx` and `index.ts` |
|
||||
| Changed public or management API | `apps/docs/docs/management/api/index.mdx` |
|
||||
| New or changed environment variable | Relevant page under `apps/docs/docs/advanced/` or installation docs |
|
||||
| New or changed CLI command | `apps/docs/docs/advanced/command-line/` |
|
||||
| Authentication/provider change | Relevant SSO or authentication page under `apps/docs/docs/advanced/` |
|
||||
| UI or workflow change | Relevant getting-started, management, widget, or integration page |
|
||||
| Cron-job behavior | `apps/docs/docs/management/tasks.mdx` |
|
||||
| Permission behavior | `apps/docs/docs/management/users.mdx` and the affected feature page |
|
||||
| Custom Widget or Workshop behavior | Relevant Custom Widget, Assistant, or Workshop documentation |
|
||||
|
||||
If no existing row fits, search by the user-visible term and update the page where a user would look for the behavior:
|
||||
|
||||
```bash
|
||||
rg -n "<term>" apps/docs/docs apps/docs/src
|
||||
```
|
||||
|
||||
## Follow existing typed patterns
|
||||
|
||||
For an integration:
|
||||
|
||||
- Add or update `apps/docs/docs/integrations/<slug>/index.ts` with the local `IntegrationDefinition` pattern.
|
||||
- Add or update `index.mdx` with the established `IntegrationHeader`, `IntegrationCapabilites`, and `IntegrationSecrets` components as applicable.
|
||||
- Reuse metadata from `@homarr/definitions` when the docs app already exposes it.
|
||||
|
||||
For a widget:
|
||||
|
||||
- Add or update `apps/docs/docs/widgets/<slug>/index.ts` with the local `WidgetDefinition` pattern.
|
||||
- Add or update `index.mdx` with the established `WidgetHeader`, `WidgetConfig`, and `AddingWidget` components as applicable.
|
||||
- Document options, required integrations, permissions, empty states, and changed behavior that affect setup or use.
|
||||
|
||||
## Completion criteria
|
||||
|
||||
1. Describe the shipped behavior, not an implementation plan.
|
||||
2. Keep names, defaults, paths, screenshots, links, and prerequisites consistent with code.
|
||||
3. Update every affected page and remove superseded guidance.
|
||||
4. Run the narrowest useful docs validation. Use `pnpm turbo build --filter=@homarr/docs` when links, MDX, generated definitions, or navigation can fail; otherwise run the docs package formatter on touched files.
|
||||
5. Treat broken links and anchors as failures; Docusaurus checks them strictly.
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Homarr Documentation Sync"
|
||||
short_description: "Keep user-facing docs aligned with code"
|
||||
default_prompt: "Use $documentation-sync to map this Homarr code change to the required documentation updates."
|
||||
@@ -1,11 +1,11 @@
|
||||
---
|
||||
name: homarr-custom-widget
|
||||
description: Author safe Homarr Custom JSX v2 widgets from API documentation.
|
||||
description: Author, validate, preview, test, install, or configure API-backed Homarr Custom JSX v2 widgets.
|
||||
---
|
||||
|
||||
# Homarr Custom Widget
|
||||
|
||||
Author one widget or a coordinated set of widgets. Start with the compact release-matched entrypoint; load only needed references, components, shared props, or examples. Run lifecycle tools alone; independent context reads may run together. For a set, research once and finish each widget's validation, evidence, and persistence before the next.
|
||||
Author one widget or a coordinated set of widgets. Load only needed release-matched context. Run lifecycle tools alone; independent reads may run together. For a set, research once and finish each widget's validation, evidence, and persistence before the next.
|
||||
|
||||
1. Read primary API documentation. Use web search when documentation is not supplied or may have changed.
|
||||
2. Create credential-free definitions with keyed `sources`, `requests`, optional `options`, and safe JSX `template`.
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Homarr Custom Widget"
|
||||
short_description: "Build and deploy safe Custom JSX widgets"
|
||||
default_prompt: "Use $homarr-custom-widget to author, validate, preview, and configure a safe Custom JSX v2 widget."
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
name: mcp-integration
|
||||
description: Expose Homarr tRPC procedures safely through MCP. Use when adding or changing tRPC procedures under packages/api, adding MCP metadata, registering an eager MCP router, shaping tool inputs and descriptions, or reviewing MCP authorization, sensitive data, and destructive actions.
|
||||
---
|
||||
|
||||
# MCP Integration
|
||||
|
||||
Expose a procedure only when an AI client should call it. Preserve the procedure's existing authorization and add MCP-specific safeguards for sensitive or destructive behavior.
|
||||
|
||||
## Assess exposure
|
||||
|
||||
Prefer:
|
||||
|
||||
- Data queries: list, search, get, health, stats, and summaries.
|
||||
- User-requested actions with explicit permission checks and bounded inputs.
|
||||
- Serializable results that do not reveal credentials or internal-only state.
|
||||
|
||||
Skip subscriptions, session/onboarding internals, file streams, blobs, credential values, and procedures whose authorization or audit behavior is unclear. Ask for a security review when a mutation is destructive, tenant boundaries are ambiguous, or returned data is sensitive.
|
||||
|
||||
## Add metadata
|
||||
|
||||
Place `.meta()` before `.input()` and `.query()` or `.mutation()`:
|
||||
|
||||
```typescript
|
||||
getAll: protectedProcedure
|
||||
.meta({
|
||||
mcp: {
|
||||
enabled: true,
|
||||
description: "List resources the current user can access, including stable IDs used by resource_get",
|
||||
},
|
||||
})
|
||||
.input(z.object({ limit: z.number().int().min(1).max(100).default(50) }))
|
||||
.query(async ({ ctx, input }) => {
|
||||
// Preserve normal procedure authorization.
|
||||
});
|
||||
```
|
||||
|
||||
No-input procedures can omit `.input()`; the MCP extractor accepts an empty object for them.
|
||||
|
||||
For mutations, state the effect and required permission in the description:
|
||||
|
||||
```typescript
|
||||
remove: permissionRequiredProcedure
|
||||
.meta({
|
||||
mcp: {
|
||||
enabled: true,
|
||||
description: "Delete one resource by ID. Requires full access; get the ID from resource_all",
|
||||
},
|
||||
})
|
||||
.input(z.object({ id: z.string() }))
|
||||
.mutation(async ({ ctx, input }) => {
|
||||
// Perform the permission-scoped action.
|
||||
});
|
||||
```
|
||||
|
||||
## Write discoverable descriptions
|
||||
|
||||
Include every item that applies:
|
||||
|
||||
- What the tool returns or changes.
|
||||
- Supported integrations or services.
|
||||
- Required IDs and the tool that returns them.
|
||||
- Permission requirements and the meaning of permission fields.
|
||||
- Important bounds, confirmation semantics, or irreversible effects.
|
||||
|
||||
Use precise domain language. A description such as `Get calendar events` is insufficient because it omits supported services, required IDs, and result scope.
|
||||
|
||||
## Shape inputs for clients
|
||||
|
||||
- Use a top-level `z.object({...})` for parameterized tools.
|
||||
- Bound strings, arrays, numeric ranges, pagination, and payload sizes.
|
||||
- Use defaults where a safe, unsurprising value exists.
|
||||
- Prefer explicit fields over a top-level union or discriminated union.
|
||||
- Keep identifiers stable and describe how to obtain them.
|
||||
- Keep secrets out of inputs unless the procedure is explicitly a credential-configuration flow with server-owned encryption and non-return guarantees.
|
||||
|
||||
## Register the eager router
|
||||
|
||||
The application router in `packages/api/src/root.ts` is lazy. MCP tool extraction is synchronous, so add an eager import and registration in `packages/api/src/mcp.ts`:
|
||||
|
||||
```typescript
|
||||
import { resourceRouter } from "./router/resource";
|
||||
|
||||
export const mcpRouter = createTRPCRouter({
|
||||
resource: resourceRouter,
|
||||
});
|
||||
```
|
||||
|
||||
Register the smallest router that owns the enabled procedures. If a parent router uses `lazy()`, import the needed subrouter directly. Metadata on a procedure is not enough; a procedure absent from `mcpRouter` is not exposed.
|
||||
|
||||
## Validate the tool surface
|
||||
|
||||
1. Confirm the procedure still enforces its ordinary auth and permission boundary.
|
||||
2. Confirm `packages/api/src/mcp.ts` eagerly includes the procedure.
|
||||
3. Confirm the generated tool name, description, and JSON schema are unambiguous.
|
||||
4. Run the focused API MCP spec when the tool list or extraction changes: `pnpm test packages/api/src/test/mcp.spec.ts`.
|
||||
5. Run the focused route spec when protocol or transport behavior changes: `pnpm test apps/nextjs/src/app/api/mcp/[transport]/route.spec.ts`.
|
||||
6. If manually probing `/api/mcp/<transport>`, use a scoped API key and avoid printing credentials or secret-bearing results.
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "Homarr MCP Integration"
|
||||
short_description: "Expose tRPC procedures safely through MCP"
|
||||
default_prompt: "Use $mcp-integration to expose this Homarr tRPC procedure as a safe, discoverable MCP tool."
|
||||
Reference in new issue
Block a user