@mcp-rune/create 0.11.0

package/templates/advanced/__only_if_useFetchClient__/src/api/fetch-client.ts

@@ -0,0 +1,111 @@
+/**
+ * FetchApiClient — starter scaffolded by `rune new --api-client fetch`.
+ *
+ * Implements the framework's `ApiClient` interface using native `fetch` (Node 18+).
+ * Returns `Promise<Record<string, unknown>>` from each verb. Adapt the
+ * convention hook and error parsing for your backend's wire format.
+ */
+
+import type { BaseConvention } from '@mcp-rune/mcp-rune/api-conventions'
+import type { ApiClient } from '@mcp-rune/mcp-rune/core'
+
+interface FetchApiClientOptions {
+  baseUrl: string
+  accessToken?: string
+  convention?: BaseConvention
+  fetchImpl?: typeof fetch
+}
+
+interface HttpError extends Error {
+  status?: number
+  body?: unknown
+}
+
+export class FetchApiClient implements ApiClient {
+  baseUrl: string
+  private accessToken?: string
+  private convention?: BaseConvention
+  private _fetch: typeof fetch
+
+  constructor({ baseUrl, accessToken, convention, fetchImpl = globalThis.fetch }: FetchApiClientOptions) {
+    this.baseUrl = baseUrl
+    this.accessToken = accessToken
+    this.convention = convention
+    this._fetch = fetchImpl
+  }
+
+  async get(url: string, params?: Record<string, unknown>): Promise<Record<string, unknown>> {
+    return this._request('GET', url, { params })
+  }
+
+  async post(url: string, data?: Record<string, unknown>): Promise<Record<string, unknown>> {
+    return this._request('POST', url, { body: data })
+  }
+
+  async put(url: string, data?: Record<string, unknown>): Promise<Record<string, unknown>> {
+    return this._request('PUT', url, { body: data })
+  }
+
+  async patch(url: string, data?: Record<string, unknown>): Promise<Record<string, unknown>> {
+    return this._request('PATCH', url, { body: data })
+  }
+
+  async delete(url: string): Promise<Record<string, unknown>> {
+    return this._request('DELETE', url)
+  }
+
+  private async _request(
+    method: string,
+    url: string,
+    { params, body }: { params?: Record<string, unknown>; body?: unknown } = {}
+  ): Promise<Record<string, unknown>> {
+    const target = new URL(this._resolveUrl(url))
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null) continue
+        target.searchParams.set(k, String(v))
+      }
+    }
+
+    const headers: Record<string, string> = { Accept: 'application/json' }
+    if (this.accessToken) headers.Authorization = `Bearer ${this.accessToken}`
+
+    const init: RequestInit = { method, headers }
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json'
+      init.body = JSON.stringify(body)
+    }
+
+    const response = await this._fetch(target, init)
+    const text = await response.text()
+    const payload = text ? safeJson(text) : {}
+
+    if (!response.ok) {
+      const messages = this.convention?.parseErrorResponse?.({
+        status: response.status,
+        data: payload
+      }) ?? [text || `HTTP ${response.status}`]
+      const err: HttpError = new Error(messages.join('; '))
+      err.status = response.status
+      err.body = payload
+      throw err
+    }
+
+    return payload as Record<string, unknown>
+  }
+
+  private _resolveUrl(url: string): string {
+    if (/^https?:\/\//i.test(url)) return url
+    const base = this.baseUrl?.replace(/\/$/, '') ?? ''
+    const path = url.startsWith('/') ? url : `/${url}`
+    return `${base}${path}`
+  }
+}
+
+function safeJson(text: string): Record<string, unknown> {
+  try {
+    return JSON.parse(text) as Record<string, unknown>
+  } catch {
+    return { raw: text }
+  }
+}

package/templates/advanced/__only_if_useFlatRestConvention__/src/conventions/flat-rest-convention.ts

@@ -0,0 +1,85 @@
+/**
+ * Flat REST convention — starter scaffolded by `rune new --api-convention rest-flat`.
+ *
+ * Targets plain REST APIs that accept and return resources without a JSON:API
+ * `data: { attributes: ... }` envelope. Customize for your backend's exact
+ * shape (pagination, association style, error envelope).
+ */
+
+import type {
+  FieldDefinition,
+  NormalizedListResponse
+} from '@mcp-rune/mcp-rune/api-conventions'
+import { BaseConvention } from '@mcp-rune/mcp-rune/api-conventions'
+import type { BelongsToAssociation, HasManyAssociation } from '@mcp-rune/mcp-rune/models'
+
+export class FlatRestConvention extends BaseConvention {
+  override get name(): string {
+    return 'rest-flat'
+  }
+
+  override resolveAssociationFields(
+    relName: string,
+    relConfig: BelongsToAssociation | HasManyAssociation,
+    overrides: Record<string, Partial<FieldDefinition>> = {}
+  ): Record<string, FieldDefinition> {
+    const isMany = 'many' in relConfig && Boolean(relConfig.many)
+    const fieldName = isMany ? `${singularize(relName)}_ids` : `${relName}_id`
+    const field: FieldDefinition = {
+      name: fieldName,
+      type: isMany ? 'array' : 'integer',
+      required: Boolean(relConfig.required),
+      description: relConfig.description ?? `Association to ${relConfig.target_model}`,
+      ...overrides[fieldName]
+    }
+    if (isMany) field.items = { type: 'integer' }
+    return { [fieldName]: field }
+  }
+
+  override normalizeListResponse(
+    response: Record<string, unknown> | unknown[],
+    { page, perPage }: { page: number; perPage: number }
+  ): NormalizedListResponse {
+    const records = pickRecords(response)
+    const total = pickTotal(response, records.length)
+    return {
+      records,
+      pagination: {
+        page,
+        per_page: perPage,
+        total,
+        total_pages: Math.max(1, Math.ceil(total / perPage))
+      }
+    }
+  }
+
+  override cleanResponse(data: unknown): unknown {
+    return data
+  }
+}
+
+function singularize(name: string): string {
+  if (name.endsWith('ies')) return name.slice(0, -3) + 'y'
+  if (name.endsWith('s')) return name.slice(0, -1)
+  return name
+}
+
+function pickRecords(response: unknown): Record<string, unknown>[] {
+  if (Array.isArray(response)) return response as Record<string, unknown>[]
+  if (response && typeof response === 'object') {
+    const r = response as { data?: unknown; records?: unknown }
+    if (Array.isArray(r.data)) return r.data as Record<string, unknown>[]
+    if (Array.isArray(r.records)) return r.records as Record<string, unknown>[]
+  }
+  return []
+}
+
+function pickTotal(response: unknown, fallback: number): number {
+  if (response && typeof response === 'object') {
+    const r = response as { total?: unknown }
+    if (typeof r.total === 'number') return r.total
+  }
+  return fallback
+}
+
+export const flatRestConvention = new FlatRestConvention()

package/templates/advanced/__only_if_usePinoLogger__/src/observability/logger.ts

@@ -0,0 +1,62 @@
+/**
+ * Pino logger — starter scaffolded by `rune new --logger pino`.
+ *
+ * Re-exports a pino instance shaped to match the surface mcp-rune's built-in
+ * logger exposes: `info / warn / error / debug` + `setApp(name)` + `child(meta)`.
+ * Project code imports from this file; the framework keeps using its own
+ * logger internally.
+ */
+
+import pino from 'pino'
+
+type LogMethod = 'info' | 'warn' | 'error' | 'debug'
+
+interface ChildLogger {
+  info: (message: string, meta?: Record<string, unknown>) => void
+  warn: (message: string, meta?: Record<string, unknown>) => void
+  error: (message: string, meta?: Record<string, unknown>) => void
+  debug: (message: string, meta?: Record<string, unknown>) => void
+  child: (meta: Record<string, unknown>) => ChildLogger
+}
+
+const base = pino({
+  level: process.env.LOG_LEVEL ?? 'info',
+  formatters: {
+    level(label: string): { level: string } {
+      return { level: label }
+    }
+  }
+})
+
+let appName = process.env.MCP_SERVER_NAME ?? 'app'
+
+function emit(method: LogMethod, bound: Record<string, unknown>) {
+  return (message: string, meta: Record<string, unknown> = {}): void => {
+    base[method]({ app: appName, ...bound, ...meta }, message)
+  }
+}
+
+function buildChild(bound: Record<string, unknown>): ChildLogger {
+  return {
+    info: emit('info', bound),
+    warn: emit('warn', bound),
+    error: emit('error', bound),
+    debug: emit('debug', bound),
+    child(extra) {
+      return buildChild({ ...bound, ...extra })
+    }
+  }
+}
+
+export const logger = {
+  info: emit('info', {}),
+  warn: emit('warn', {}),
+  error: emit('error', {}),
+  debug: emit('debug', {}),
+  setApp(name: string): void {
+    appName = name
+  },
+  child(meta: Record<string, unknown> = {}): ChildLogger {
+    return buildChild(meta)
+  }
+}

package/templates/advanced/__only_if_useRansackSearch__/src/api-extensions/ransack-search-adapter.ts

@@ -0,0 +1,41 @@
+/**
+ * Ransack search request shaper — starter scaffolded by
+ * `rune new --search-adapter ransack`.
+ *
+ * Rails backends using the Ransack gem expect filters under a single `q`
+ * parameter with `field_predicate` suffixes (e.g. `q[name_eq]`,
+ * `q[created_at_gt]`). This subclass of the framework's
+ * `SearchRequestShaper` builds that envelope; tweak the predicate logic for
+ * your endpoint as needed.
+ *
+ * For complete Rails coverage (filter nesting + range mappings) consider
+ * `RailsSearchRequestShaper` from `@mcp-rune/mcp-rune/api-extensions/search`
+ * instead.
+ */
+
+import { SearchRequestShaper } from '@mcp-rune/mcp-rune/api-extensions/search'
+import type { Pagination, SearchConfig } from '@mcp-rune/mcp-rune/api-extensions/search'
+
+export class RansackSearchAdapter extends SearchRequestShaper {
+  override buildBody(
+    query: string | null,
+    filters: Record<string, unknown> | undefined,
+    { page, perPage }: Pagination,
+    searchConfig: SearchConfig
+  ): Record<string, unknown> {
+    const body: Record<string, unknown> = { page, per_page: perPage }
+
+    const q: Record<string, unknown> =
+      filters && Object.keys(filters).length > 0 ? { ...filters } : {}
+
+    if (query) {
+      const queryField = searchConfig?.query?.queryParam ?? 'name_cont'
+      q[queryField] = query
+    }
+
+    if (Object.keys(q).length > 0) body.q = q
+    return body
+  }
+}
+
+export const ransackSearchAdapter = new RansackSearchAdapter()

package/templates/advanced/__only_if_useSharedModelAttrs__/src/models/app-base-model.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared ModelLayer base — stub scaffolded by `rune new --shared-model-attrs`.
+ *
+ * Intermediate class between the framework's `BaseModel` and the per-resource
+ * models in `src/models/`. Put attributes / methods that apply across every
+ * model here (e.g. tenancy keys, audit timestamps, soft-delete fields) so
+ * each concrete model only declares what's unique to it.
+ *
+ * Scaffolded models still extend `BaseModel` directly today; switch their
+ * `extends` to `AppBaseModel` to pick this up.
+ */
+
+import type { AttributeDefinition } from '@mcp-rune/mcp-rune/models'
+import { BaseModel } from '@mcp-rune/mcp-rune/models'
+
+export class AppBaseModel extends BaseModel {
+  static override attributes: Record<string, AttributeDefinition> = {
+    // TODO: shared attributes, e.g.:
+    // created_at: { type: 'datetime', description: 'Created at' },
+    // updated_at: { type: 'datetime', description: 'Updated at' },
+  }
+}

package/templates/advanced/__only_if_useVectorStorage__/src/storage/vector-store.ts

@@ -0,0 +1,21 @@
+/**
+ * Vector storage — scaffolded by `rune new --vector-storage`.
+ *
+ * Call `enableVectorStorage(pool)` once at server startup (before ToolRegistry
+ * is constructed). Tools tagged `requiresVectorStorage` only appear in
+ * `tools/list` after this call succeeds.
+ *
+ * Retention options can be tuned via `createPgvectorAdapter` options:
+ *   toolMemoriesRetentionDays (default 30)
+ *   ingestedRecordsRetentionDays (default 7)
+ */
+
+import type { Pool } from 'pg'
+import { vectorStorage } from '@mcp-rune/mcp-rune/runtime'
+import { createPgvectorAdapter } from '@mcp-rune/mcp-rune/runtime/vendor/pgvector'
+
+export function enableVectorStorage(pool: Pool): void {
+  vectorStorage.initVectorStorage({
+    adapter: createPgvectorAdapter({ pool }),
+  })
+}

package/templates/advanced/__only_if_withAnalysis__/docker-compose.yml

@@ -0,0 +1,18 @@
+services:
+  db:
+    image: pgvector/pgvector:pg16
+    environment:
+      POSTGRES_PASSWORD: dev
+      POSTGRES_USER: postgres
+      POSTGRES_DB: {{projectName}}
+    ports:
+      - "5544:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD", "pg_isready", "-U", "postgres"]
+      interval: 1s
+      timeout: 3s
+      retries: 30
+volumes:
+  pgdata:

package/templates/advanced/__only_if_withDomain__/src/domain/registry.ts

@@ -0,0 +1,25 @@
+/**
+ * Domain registry — workflows, business rules, and domain knowledge.
+ *
+ * Organise domain items into DomainModule objects (one per domain area) and
+ * spread them into InMemoryDomainAdapter. Each module can export concepts,
+ * rules, and workflows together, replacing the separate per-resource files.
+ *
+ * The framework surfaces domain knowledge via the domain tools:
+ * `get_domain_context`, `get_workflow_step`, `suggest_workflow`, `check_business_rules`.
+ */
+
+import { DomainRegistry, InMemoryDomainAdapter } from '@mcp-rune/mcp-rune/domain'
+import type { DomainModule } from '@mcp-rune/mcp-rune/domain'
+
+// Define domain modules here or import them from ./modules/
+// Example: import { catchupModule } from './modules/catchup.js'
+const domainModules: DomainModule[] = [
+  // { concepts: [...], rules: [...], workflows: [...] }
+]
+
+export function createDomainRegistry(): DomainRegistry {
+  return new DomainRegistry({
+    adapter: new InMemoryDomainAdapter(domainModules)
+  })
+}

package/templates/advanced/config/schema.ts.ejs

@@ -0,0 +1,126 @@
+/**
+ * <%= projectName %> — Declarative Configuration Schema
+ *
+ * Single source of truth for all environment variables. Loaded via loadConfig()
+ * at startup. Every env var read in the codebase should be declared here.
+ */
+
+import type { ConfigSchema } from '@mcp-rune/mcp-rune/core'
+
+export const configSchema = {
+  api: {
+    url: {
+      env: 'API_URL',
+      default: 'http://localhost:4001/api/v1',
+      doc: 'Backend API base URL',
+    },
+  },
+
+<% if (hasHttp && !useStaticTokenAuth) { -%>
+  oauth: {
+    serverUrl: {
+      env: 'OAUTH_SERVER_URL',
+      default: 'http://localhost:4000',
+      doc: 'OAuth2 authorization server URL',
+    },
+    clientId: {
+      env: 'OAUTH_CLIENT_ID',
+      doc: 'OAuth2 client ID',
+    },
+    clientSecret: {
+      env: 'OAUTH_CLIENT_SECRET',
+      sensitive: true,
+      doc: 'OAuth2 client secret',
+    },
+    scopes: {
+      env: 'OAUTH_SCOPES',
+      default: 'read write',
+      doc: 'OAuth2 scopes',
+    },
+  },
+
+<% } -%>
+  database: {
+    url: {
+      env: 'DATABASE_URL',
+      sensitive: true,
+      doc: 'PostgreSQL connection string (optional; enables OAuth token persistence + analysis)',
+    },
+  },
+
+  analysis: {
+    enabled: {
+      env: 'ANALYSIS_ENABLED',
+      default: false,
+      type: 'boolean',
+      doc: 'Enable analysis tools. Requires DATABASE_URL pointing at Postgres with pgvector.',
+    },
+  },
+
+<% if (withDomain) { -%>
+  domain: {
+    enabled: {
+      env: 'DOMAIN_ENABLED',
+      default: true,
+      type: 'boolean',
+      doc: 'Enable domain intelligence tools (workflows, business rules).',
+    },
+  },
+
+<% } -%>
+  profile: {
+    name: {
+      env: 'MCP_PROFILE',
+      default: 'full',
+      doc: 'Tool exposure profile: full | chat | agent | classify',
+    },
+  },
+
+  transport: {
+<% if (hasStdio) { -%>
+    local: {
+      accessToken: {
+        env: 'ACCESS_TOKEN',
+        sensitive: true,
+        doc: 'Bearer token used by stdio for API calls',
+      },
+    },
+<% } -%>
+<% if (hasHttp) { -%>
+    remote: {
+      port: { env: 'PORT', type: 'integer', default: 4100, doc: 'HTTP server port' },
+      baseUrl: { env: 'BASE_URL', doc: 'Public base URL for the server' },
+      pathPrefix: { env: 'PATH_PREFIX', default: '', doc: 'Path prefix for all routes' },
+<% if (useStaticTokenAuth) { -%>
+      accessToken: {
+        env: 'HTTP_ACCESS_TOKEN',
+        sensitive: true,
+        doc: 'Static bearer token required by HTTP clients (replaces OAuth)',
+      },
+<% } -%>
+    },
+<% } -%>
+  },
+
+  http: {
+    corsOrigins: { env: 'CORS_ORIGINS', doc: 'Comma-separated list of allowed CORS origins' },
+    environment: { env: 'NODE_ENV', default: 'development', doc: 'Runtime environment' },
+  },
+
+  errorTracking: {
+    sentryDsn: { env: 'SENTRY_DSN', sensitive: true, doc: 'Sentry DSN for error tracking' },
+  },
+
+  tracing: {
+    langfusePublicKey: {
+      env: 'LANGFUSE_PUBLIC_KEY',
+      sensitive: true,
+      doc: 'Langfuse public key',
+    },
+    langfuseSecretKey: {
+      env: 'LANGFUSE_SECRET_KEY',
+      sensitive: true,
+      doc: 'Langfuse secret key',
+    },
+  },
+} satisfies ConfigSchema;

package/templates/advanced/package.json.ejs

@@ -0,0 +1,50 @@
+{
+  "name": "<%= projectName %>",
+  "version": "0.1.0",
+  "description": "MCP server scaffolded with @mcp-rune/create (advanced preset)",
+  "type": "module",
+  "private": true,
+  "engines": {
+    "node": "<%= nodeEngine %>"
+  },
+  "scripts": {
+<% if (hasHttp) { -%>
+    "start": "tsx src/servers/remote.ts",
+<% } else { -%>
+    "start": "tsx src/servers/local.ts",
+<% } -%>
+<% if (hasStdio) { -%>
+    "start:local": "tsx src/servers/local.ts",
+<% } -%>
+<% if (hasHttp) { -%>
+    "start:remote": "tsx src/servers/remote.ts",
+    "start:chat": "MCP_PROFILE=chat tsx src/servers/remote.ts",
+    "start:agent": "MCP_PROFILE=agent tsx src/servers/remote.ts",
+<% } -%>
+    "build": "tsc",
+    "inspect": "mcp-rune inspect",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "db:migrate": "tsx src/scripts/db-migrate.ts"<% if (withAnalysis) { %>,
+    "db:up": "docker compose up -d db && npm run db:migrate",
+    "db:down": "docker compose down"<% } %>
+  },
+  "dependencies": {
+    "@mcp-rune/mcp-rune": "<%= mcpRuneVersion %>",
+    "dotenv": "^17.3.1",
+<% if (useAxiosClient) { -%>
+    "axios": "^1.7.0",
+<% } -%>
+<% if (usePinoLogger) { -%>
+    "pino": "^9.5.0",
+<% } -%>
+    "pg": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.15.0",
+    "tsx": "^4.22.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.7"
+  }
+}