@mcp-rune/create 0.11.0

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

@@ -0,0 +1,207 @@
+/**
+ * <%= projectName %> — shared configuration and startup wiring.
+ *
+ * Startup phases are wrapped with StartupTracker for clear boundary markers
+ * and scoped logging. Each phase gets a scoped child logger.
+ */
+
+import { loadConfig, readPackageInfo, StartupTracker } from '@mcp-rune/mcp-rune/core'
+import { createPromptCache } from '@mcp-rune/mcp-rune/prompts'
+import { createServer as createServerFactory } from '@mcp-rune/mcp-rune/server'
+<% if (hasHttp && !useStaticTokenAuth) { -%>
+import { _setAdapter, OAuthService, PostgresqlAdapter } from '@mcp-rune/mcp-rune/oauth2'
+<% } -%>
+<% if (usePinoLogger) { -%>
+import { errorTracking, tracing, vectorStorage } from '@mcp-rune/mcp-rune/runtime'
+<% } else { -%>
+import { errorTracking, logger, tracing, vectorStorage } from '@mcp-rune/mcp-rune/runtime'
+<% } -%>
+import { createPgvectorAdapter } from '@mcp-rune/mcp-rune/runtime/vendor/pgvector'
+
+import { configSchema } from '../config/schema.js'
+import { closeDatabase, initDatabase } from './db.js'
+<% if (withDomain) { -%>
+import { createDomainRegistry } from './domain/registry.js'
+<% } -%>
+import { MODEL_CLASSES } from './models/index.js'
+<% if (usePinoLogger) { -%>
+import { logger } from './observability/logger.js'
+<% } -%>
+import { getProfile } from './profiles.js'
+import { promptRegistry as basePromptRegistry } from './prompts/index.js'
+import { createToolRegistry } from './tools/index.js'
+
+/**
+ * Runtime-resolved shape of `configSchema`. Mirrors the schema tree; the
+ * library's `loadConfig` returns `Record<string, unknown>` so we narrow at
+ * the boundary with a single explicit cast and pay no cost downstream.
+ */
+interface AppConfig {
+  api: { url: string }
+<% if (hasHttp && !useStaticTokenAuth) { -%>
+  oauth: {
+    serverUrl: string
+    clientId: string
+    clientSecret: string
+    scopes: string
+  }
+<% } -%>
+  database: { url: string | undefined }
+  analysis: { enabled: boolean }
+<% if (withDomain) { -%>
+  domain: { enabled: boolean }
+<% } -%>
+  profile: { name: string }
+  transport: {
+<% if (hasStdio) { -%>
+    local: { accessToken: string | undefined }
+<% } -%>
+<% if (hasHttp) { -%>
+    remote: {
+      port: number
+      baseUrl: string | undefined
+      pathPrefix: string
+<% if (useStaticTokenAuth) { -%>
+      accessToken: string | undefined
+<% } -%>
+    }
+<% } -%>
+  }
+  http: { corsOrigins: string | undefined; environment: string }
+  errorTracking: { sentryDsn: string | undefined }
+  tracing: { langfusePublicKey: string | undefined; langfuseSecretKey: string | undefined }
+}
+
+const startup = new StartupTracker(logger)
+
+const { name: SERVER_NAME, version: SERVER_VERSION } = startup.phase(
+  'identity',
+  'Server identity',
+  (log) => {
+    const pkg = readPackageInfo(import.meta.url, '../package.json')
+    logger.setApp(pkg.name)
+    log.debug(`${pkg.name}@${pkg.version}`)
+    return pkg
+  }
+)
+
+export const config = startup.phase('config', 'Load configuration', (log) => {
+  const cfg = loadConfig(configSchema)
+  log.debug(cfg.toString())
+  return cfg as unknown as AppConfig & { toString(): string }
+})
+
+const isProduction = config.http.environment === 'production'
+
+startup.phase('error-tracking', 'Error tracking', () => {
+  // Vendor (Sentry) reads SENTRY_DSN + NODE_ENV from env directly; the
+  // public option type here is intentionally narrow.
+  errorTracking.initErrorTracking({
+    serviceName: SERVER_NAME,
+    version: SERVER_VERSION
+  })
+})
+
+startup.phase('tracing', 'Tracing', () => {
+  // Vendor (Langfuse) reads LANGFUSE_PUBLIC_KEY + LANGFUSE_SECRET_KEY from
+  // env directly; the public option type here is intentionally narrow.
+  tracing.initTracing({
+    serviceName: SERVER_NAME,
+    version: SERVER_VERSION
+  })
+})
+
+startup.phase('database', 'Database', (log) => {
+  const pool = initDatabase(config.database.url)
+  if (!pool) {
+    log.debug('DATABASE_URL not set — database features disabled')
+    return
+  }
+
+<% if (hasHttp && !useStaticTokenAuth) { -%>
+  _setAdapter(new PostgresqlAdapter({ pool }))
+  log.debug('OAuth token store connected')
+
+<% } -%>
+  if (config.analysis.enabled) {
+    vectorStorage.initVectorStorage({
+      adapter: createPgvectorAdapter({ pool }),
+      serviceName: SERVER_NAME,
+      version: SERVER_VERSION,
+    })
+    log.debug('Vector storage enabled')
+  }
+})
+
+<% if (hasHttp && !useStaticTokenAuth) { -%>
+export function createOAuthService({ redirectUri }: { redirectUri: string }): OAuthService {
+  return new OAuthService({
+    authServerUrl: config.oauth.serverUrl,
+    clientId: config.oauth.clientId,
+    clientSecret: config.oauth.clientSecret,
+    redirectUri,
+    scopes: config.oauth.scopes,
+    isProduction
+  })
+}
+
+<% } -%>
+const promptRegistry = startup.phase('prompts', 'Prompts', () => {
+  return createPromptCache(basePromptRegistry, { ttl: 5 * 60 * 1000, maxSize: 100 })
+})
+
+<% if (withDomain) { -%>
+const domainRegistry = config.domain.enabled
+  ? startup.phase('domain', 'Domain intelligence', () => createDomainRegistry())
+  : null
+<% } else { -%>
+const domainRegistry = null
+<% } -%>
+
+const serverContext = {
+  name: '<%= projectNamePascal %>',
+  namespace: '<%= projectName %>',
+  description: 'MCP server scaffolded with @mcp-rune/create'
+}
+
+const profile = getProfile(config.profile.name)
+
+const toolRegistry = startup.phase('tools', 'Tools', (log) => {
+  log.debug(`Profile: ${config.profile.name}`)
+  return createToolRegistry({
+    logger,
+    models: MODEL_CLASSES,
+    promptRegistry,
+    serverContext,
+    domainRegistry,
+    apiUrl: config.api.url,
+    profile
+  })
+})
+
+startup.done()
+
+export const mcpConfig = {
+  name: SERVER_NAME,
+  promptRegistry,
+  closeDatabase,
+
+  createServer({
+    sessionId: _sessionId,
+    getAccessToken
+  }: {
+    sessionId: string
+    transport: string
+    getAccessToken: () => Promise<string>
+  }) {
+    return createServerFactory({
+      name: SERVER_NAME,
+      version: SERVER_VERSION,
+      sessionId: _sessionId,
+      transport: 'stdio',
+      toolRegistry,
+      promptRegistry,
+      getAccessToken
+    })
+  }
+}

package/templates/advanced/src/db.ts.ejs

@@ -0,0 +1,35 @@
+import pg from 'pg'
+
+type Pool = InstanceType<typeof pg.Pool>
+<% if (usePinoLogger) { -%>
+import { logger } from './observability/logger.js'
+<% } else { -%>
+import { logger } from '@mcp-rune/mcp-rune/runtime'
+<% } -%>
+
+let pool: Pool | null = null
+
+export function initDatabase(url: string | undefined): Pool | null {
+  if (pool) return pool
+  if (!url) return null
+
+  pool = new pg.Pool({
+    connectionString: url,
+    max: 5,
+    idleTimeoutMillis: 30000,
+    connectionTimeoutMillis: 5000
+  })
+  logger.info('Database pool created', { service: '<%= projectName %>-db' })
+  return pool
+}
+
+export function getPool(): Pool | null {
+  return pool
+}
+
+export async function closeDatabase(): Promise<void> {
+  if (!pool) return
+  await pool.end()
+  pool = null
+  logger.info('Database pool closed', { service: '<%= projectName %>-db' })
+}

package/templates/advanced/src/models/_model_.ts.ejs

@@ -0,0 +1,25 @@
+import type { AttributeDefinition } from '@mcp-rune/mcp-rune/models'
+import { BaseModel } from '@mcp-rune/mcp-rune/models'
+
+export class <%= model.namePascal %> extends BaseModel {
+  static override description = '<%= model.description || `A ${model.name} record` %>'
+  static override api = { endpoint: '<%= model.endpoint || `${model.fileName}s` %>' }
+
+  static override attributes: Record<string, AttributeDefinition> = {
+<% for (const attr of model.attributes) { -%>
+    <%= attr.name %>: {
+      type: '<%= attr.type %>',
+<% if (attr.required) { -%>
+      required: true,
+<% } -%>
+<% if (attr.description) { -%>
+      description: '<%= attr.description %>',
+<% } -%>
+    },
+<% } -%>
+  }
+
+  static get attributesConfig(): Record<string, AttributeDefinition> {
+    return this.attributes
+  }
+}

package/templates/advanced/src/models/index.ts.ejs

@@ -0,0 +1,13 @@
+<% for (const m of models) { -%>
+import { <%= m.namePascal %> } from './<%= m.fileName %>.js'
+<% } -%>
+
+export const MODEL_CLASSES = {
+<% for (const m of models) { -%>
+  <%= m.fileName %>: <%= m.namePascal %>,
+<% } -%>
+}
+
+<% for (const m of models) { -%>
+export { <%= m.namePascal %> }
+<% } -%>

package/templates/advanced/src/profiles.ts

@@ -0,0 +1,44 @@
+/**
+ * Tool exposure profiles.
+ *
+ * Selected at startup via MCP_PROFILE. Same image, same binary, different surface.
+ *
+ * - `full`     — everything (default).
+ * - `chat`     — apps enabled; raw-JSON data tools hidden so the LLM doesn't echo
+ *                records that an app has already rendered.
+ * - `agent`    — apps disabled; data and action tools enabled for headless callers.
+ * - `classify` — only `update_model` is exposed (token-minimal classification).
+ *
+ * Each profile carries:
+ *   - `tools`        — allowlist of tool names (null = all enabled tools)
+ *   - `toolsExclude` — denylist applied after allowlist (null = no exclusions)
+ *   - `apps`         — 'enabled' | 'disabled'
+ */
+
+export interface Profile {
+  tools: string[] | null
+  toolsExclude: string[] | null
+  apps: 'enabled' | 'disabled'
+}
+
+export const PROFILES = {
+  full: { tools: null, toolsExclude: null, apps: 'enabled' },
+  chat: {
+    tools: null,
+    toolsExclude: ['find_records', 'search_records', 'list_models'],
+    apps: 'enabled'
+  },
+  agent: { tools: null, toolsExclude: null, apps: 'disabled' },
+  classify: { tools: ['update_model'], toolsExclude: null, apps: 'disabled' }
+} as const satisfies Record<string, Profile>
+
+export type ProfileName = keyof typeof PROFILES
+
+export function getProfile(name: string): Profile {
+  if (!(name in PROFILES)) {
+    throw new Error(
+      `Unknown MCP_PROFILE "${name}". Valid: ${Object.keys(PROFILES).join(', ')}`
+    )
+  }
+  return PROFILES[name as ProfileName]
+}

package/templates/advanced/src/prompts/_model_-prompt.ts.ejs

@@ -0,0 +1,27 @@
+import {
+  BasePrompt,
+  derivePromptSchema,
+  PromptContentBuilder
+} from '@mcp-rune/mcp-rune/prompts'
+import type { FormStrategyType } from '@mcp-rune/mcp-rune/prompts'
+
+import { <%= model.namePascal %> } from '../models/<%= model.fileName %>.js'
+
+export class <%= model.namePascal %>Prompt extends BasePrompt {
+  static override formStrategy: FormStrategyType = 'hybrid'
+
+  static {
+    const schema = derivePromptSchema(<%= model.namePascal %>)
+    this.fieldGroups = schema.fieldGroups
+    this.fieldDefinitions = schema.fieldDefinitions
+  }
+
+  override get promptContent(): string {
+    return PromptContentBuilder.for(<%= model.namePascal %>Prompt, '<%= model.fileName %>')
+      .add('# <%= model.namePascal %> guide')
+      .standard()
+      .toolUsage()
+      .attributeReference()
+      .build()
+  }
+}

package/templates/advanced/src/prompts/index.ts.ejs

@@ -0,0 +1,18 @@
+import { BasePromptRegistry } from '@mcp-rune/mcp-rune/prompts'
+
+<% for (const m of models) { -%>
+import { <%= m.namePascal %> } from '../models/<%= m.fileName %>.js'
+<% } -%>
+<% for (const m of models) { -%>
+import { <%= m.namePascal %>Prompt } from './<%= m.fileName %>-prompt.js'
+<% } -%>
+
+export const promptRegistry = new BasePromptRegistry()
+
+<% for (const m of models) { -%>
+promptRegistry.register('create_<%= m.fileName %>', <%= m.namePascal %>Prompt, {
+  description: <%= m.namePascal %>.description,
+  required: false,
+  model: '<%= m.fileName %>'
+})
+<% } -%>

package/templates/advanced/src/scripts/db-migrate.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Apply mcp-rune database migrations against DATABASE_URL.
+ * Tracks applied migrations in a schema_migrations table.
+ */
+import { resolve } from 'node:path'
+
+import { migrations } from '@mcp-rune/mcp-rune/db/migrations'
+import pg from 'pg'
+
+function maskUrl(url: string): string {
+  try {
+    const u = new URL(url)
+    if (u.username || u.password) {
+      u.username = '***'
+      u.password = ''
+    }
+    return u.toString().replace(/\/$/, '')
+  } catch {
+    return '***'
+  }
+}
+
+function loadEnv(): void {
+  try {
+    process.loadEnvFile(resolve('.env'))
+  } catch {
+    /* optional */
+  }
+}
+
+async function migrate(): Promise<void> {
+  loadEnv()
+  const url = process.env.DATABASE_URL
+  if (!url) {
+    console.log('DATABASE_URL not set — skipping')
+    return
+  }
+  console.log(`Connecting to ${maskUrl(url)} …`)
+  const pool = new pg.Pool({ connectionString: url })
+  try {
+    const client = await pool.connect()
+    try {
+      await client.query(`
+        CREATE TABLE IF NOT EXISTS schema_migrations (
+          version TEXT PRIMARY KEY,
+          name TEXT NOT NULL,
+          applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+        )
+      `)
+      const { rows } = await client.query<{ version: string }>(
+        `SELECT version FROM schema_migrations`
+      )
+      const applied = new Set(rows.map((r) => r.version))
+      let count = 0
+      for (const m of migrations) {
+        if (applied.has(m.version)) {
+          console.log(`  skip ${m.version}_${m.name}`)
+          continue
+        }
+        console.log(`  apply ${m.version}_${m.name}`)
+        await client.query('BEGIN')
+        try {
+          await client.query(m.up)
+          await client.query(
+            `INSERT INTO schema_migrations (version, name) VALUES ($1, $2)`,
+            [m.version, m.name]
+          )
+          await client.query('COMMIT')
+          count++
+        } catch (err) {
+          await client.query('ROLLBACK')
+          throw err
+        }
+      }
+      console.log(
+        count === 0 ? 'All migrations already applied.' : `Applied ${count} migration(s).`
+      )
+    } finally {
+      client.release()
+    }
+  } finally {
+    await pool.end()
+  }
+}
+
+migrate().catch((err: Error) => {
+  console.error(`Migration failed: ${err.message}`)
+  process.exit(1)
+})

package/templates/advanced/src/tools/index.ts.ejs

@@ -0,0 +1,133 @@
+/**
+ * Tool registry — wraps the library's `ToolRegistry` with an active-profile
+ * filter (MCP_PROFILE) so deployments can expose a narrower tool surface
+ * than the full set without touching the registry plumbing.
+ *
+ * The library's `ToolRegistry` already handles capability gating:
+ *   - `requiresVectorStorage`: skipped when vector storage isn't configured.
+ *   - `requiresDomainRegistry`: skipped when no `domainRegistry` is passed.
+ *   - `requiresPromptRegistry`: skipped when no `promptRegistry` is passed.
+ * The profile filter layers on top of that with per-deployment allow/deny lists.
+ */
+
+import type { ApiClient } from '@mcp-rune/mcp-rune/core'
+import type { DomainRegistry } from '@mcp-rune/mcp-rune/domain'
+import type { PromptRegistry } from '@mcp-rune/mcp-rune/prompts'
+import { vectorStorage } from '@mcp-rune/mcp-rune/runtime'
+import type { ModelsRegistry, ServerContext, ToolClassMap } from '@mcp-rune/mcp-rune/tools'
+import {
+  ANALYSIS_TOOL_CLASSES,
+  DATA_TOOL_CLASSES,
+  DOMAIN_TOOL_CLASSES,
+  FORM_STRATEGY_TOOL_CLASSES,
+  OPERATIONS_TOOL_CLASSES,
+  ToolRegistry
+} from '@mcp-rune/mcp-rune/tools'
+
+<% if (useFetchClient) { -%>
+import { FetchApiClient } from '../api/fetch-client.js'
+<% } -%>
+<% if (useAxiosClient) { -%>
+import { AxiosApiClient } from '../api/axios-client.js'
+<% } -%>
+<% if (useCustomApiClient) { -%>
+import { CustomApiClient } from '../api/custom-client.js'
+<% } -%>
+<% if (useFlatRestConvention) { -%>
+import { flatRestConvention } from '../conventions/flat-rest-convention.js'
+<% } -%>
+<% if (useCustomConvention) { -%>
+import { customConvention } from '../conventions/custom-convention.js'
+<% } -%>
+<% if (useRansackSearch) { -%>
+import { ransackSearchAdapter } from '../api-extensions/ransack-search-adapter.js'
+<% } -%>
+<% if (useCustomSearch) { -%>
+import { customSearchAdapter } from '../api-extensions/custom-search-adapter.js'
+<% } -%>
+
+const ALL_TOOL_CLASSES: ToolClassMap = {
+  ...FORM_STRATEGY_TOOL_CLASSES,
+  ...DATA_TOOL_CLASSES,
+  ...ANALYSIS_TOOL_CLASSES,
+  ...OPERATIONS_TOOL_CLASSES,
+  ...DOMAIN_TOOL_CLASSES
+}
+
+export interface Profile {
+  tools?: string[] | null
+  toolsExclude?: string[] | null
+}
+
+export interface CreateToolRegistryDeps {
+  logger: {
+    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
+  }
+  models: ModelsRegistry
+  promptRegistry: PromptRegistry
+  serverContext: ServerContext
+  domainRegistry: DomainRegistry | null
+  apiUrl: string
+  profile: Profile
+}
+
+function selectToolClasses(profile: Profile): ToolClassMap {
+  const all = Object.keys(ALL_TOOL_CLASSES)
+  const allow = profile.tools ? new Set(profile.tools) : null
+  const deny = profile.toolsExclude ? new Set(profile.toolsExclude) : null
+  const selected: ToolClassMap = {}
+  for (const name of all) {
+    if (allow && !allow.has(name)) continue
+    if (deny?.has(name)) continue
+    selected[name] = ALL_TOOL_CLASSES[name]!
+  }
+  return selected
+}
+
+export function createToolRegistry(deps: CreateToolRegistryDeps): ToolRegistry {
+  const createApiClient = (token: string): ApiClient => {
+<% const conventionExpr = useFlatRestConvention ? 'flatRestConvention' : useCustomConvention ? 'customConvention' : null -%>
+<% if (useFetchClient) { -%>
+    return new FetchApiClient({
+      baseUrl: deps.apiUrl,
+      accessToken: token<% if (conventionExpr) { %>,
+      convention: <%= conventionExpr %><% } %>
+    })
+<% } else if (useAxiosClient) { -%>
+    return new AxiosApiClient({
+      baseUrl: deps.apiUrl,
+      accessToken: token<% if (conventionExpr) { %>,
+      convention: <%= conventionExpr %><% } %>
+    })
+<% } else if (useCustomApiClient) { -%>
+    return new CustomApiClient({
+      baseUrl: deps.apiUrl,
+      accessToken: token<% if (conventionExpr) { %>,
+      convention: <%= conventionExpr %><% } %>
+    })
+<% } else { -%>
+    // TODO: replace with your real ApiClient. The Proxy makes a missing
+    // implementation fail loudly instead of silently no-oping.
+    return new Proxy({} as ApiClient, {
+      get() {
+        throw new Error(
+          `No ApiClient configured (token=${token.slice(0, 4)}…). Wire createApiClient in src/tools/index.ts.`
+        )
+      }
+    })
+<% } -%>
+  }
+
+  return new ToolRegistry({
+    toolClasses: selectToolClasses(deps.profile),
+    models: deps.models,
+    serverContext: deps.serverContext,
+    promptRegistry: deps.promptRegistry,
+    domainRegistry: deps.domainRegistry ?? undefined,
+    vectorStorageEnabled: vectorStorage.isVectorStorageEnabled(),
+    createApiClient
+  })
+}

package/templates/advanced/test/smoke.test.ts

@@ -0,0 +1,16 @@
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { describe, expect, it } from 'vitest'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+describe('scaffold smoke', () => {
+  it('package.json declares the design-mandated scripts', async () => {
+    const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
+    for (const name of ['start', 'test', 'typecheck', 'inspect']) {
+      expect(pkg.scripts[name], `missing script: ${name}`).toBeTypeOf('string')
+    }
+  })
+})

package/templates/advanced/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*.ts", "config/**/*.ts", "test/**/*.ts"]
+}

package/templates/simple/.env.example

@@ -0,0 +1,3 @@
+# Token used by the framework's CRUD tools when calling your API backend.
+# For local dev without a real backend, any non-empty value works.
+ACCESS_TOKEN=demo-token

package/templates/simple/.node-version

@@ -0,0 +1 @@
+24

package/templates/simple/README.md

@@ -0,0 +1,40 @@
+# {{projectName}}
+
+MCP server scaffolded with [`@mcp-rune/create`](https://github.com/mcp-rune/mcp-rune-cli).
+
+## Run
+
+```bash
+cp .env.example .env
+npm install
+npm run start:local
+```
+
+Inspect with the MCP Inspector:
+
+```bash
+npm run inspect
+```
+
+Other scripts:
+
+```bash
+npm run start         # same entry as start:local for the simple preset
+npm run test          # vitest smoke tests
+npm run typecheck     # tsc --noEmit
+```
+
+## Layout
+
+```
+src/
+├── server.js         StdioServer entry point
+├── config.js         Tool / prompt registry wiring
+├── models/           Domain model classes
+├── prompts/          Prompt classes (auto-derived from models)
+└── tools/            Tool registry (CRUD + strategy)
+```
+
+Add a new model by dropping a file under `src/models/` and registering it in `src/models/index.js`. The prompt scaffold is auto-derived.
+
+See the [mcp-rune docs](https://github.com/mcp-rune/mcp-rune) for the full framework reference.