@frontera-sdk/cli 1.52.48 → 1.53.1

package/src/local/local-orphans.ts

@@ -28,13 +28,15 @@ import type { LocalCredentials } from './local-state'
  *                   switched on again when its file is deployed again
  *   knowledge base  left as it is: deleting one takes its documents with it and
  *                   cannot be undone, so `status` only says it
+ *   MCP server      archived (its Function runs keep naming it) — saved again,
+ *                   as a new server of the same slug, when its file returns
  *
  * An orphan the project never had (made in Studio, say) is only said: it may
  * be work someone means to pull into the files. A Function switched off with
  * no file is not one: it doesn't run, and there is nothing left to do.
  */
 
-export type OrphanKind = 'agent' | 'workflow' | 'function' | 'knowledge'
+export type OrphanKind = 'agent' | 'workflow' | 'function' | 'knowledge' | 'mcp-server'
 
 export interface Orphan {
   /** `agent/assistant`, `workflow/hello`, `function/word-count`, `knowledge/Field desk policies`. */
@@ -57,6 +59,7 @@ export interface RuntimeItems {
   workflows?: Array<{ slug: string }>
   functions?: Array<{ slug: string; enabled: boolean | null }>
   knowledge?: Array<{ id: string; name: string }>
+  mcpServers?: Array<{ slug: string }>
 }
 
 function rowsOf<T>(body: unknown): T[] {
@@ -95,13 +98,15 @@ export function orphanCalls(serviceUrl: string, creds: Pick<LocalCredentials, 'w
 
 /** The Agents, workflows, Functions and knowledge bases on the runtime; each kind that didn't answer is left out. */
 export async function runtimeItems(call: Call, workspaceId: string): Promise<RuntimeItems> {
-  const [agents, workflows, functions, knowledge] = await Promise.all([
+  const [agents, workflows, functions, knowledge, mcpServers] = await Promise.all([
     // The sync listing: drafts never published included, archived and platform Agents left out.
     call('/v1/sync/agents'),
     // Archived workflows are left out of the listing.
     call('/v1/workflows'),
     call('/v1/functions'),
     call(`/v1/workspace-knowledge?workspaceId=${encodeURIComponent(workspaceId)}`),
+    // Archived servers are left out of the listing.
+    call('/v1/mcp-servers'),
   ])
   const out: RuntimeItems = {}
   if (agents.ok) {
@@ -113,15 +118,20 @@ export async function runtimeItems(call: Call, workspaceId: string): Promise<Run
   if (workflows.ok) out.workflows = rowsOf<{ slug?: string; archivedAt?: string | null }>(workflows.body).filter((w) => w.slug && !w.archivedAt).map((w) => ({ slug: w.slug! }))
   if (functions.ok) out.functions = rowsOf<{ slug?: string; enabled?: boolean | null }>(functions.body).filter((f) => f.slug).map((f) => ({ slug: f.slug!, enabled: f.enabled ?? null }))
   if (knowledge.ok) out.knowledge = rowsOf<{ id?: string; name?: string }>(knowledge.body).filter((k) => k.id && k.name).map((k) => ({ id: k.id!, name: k.name! }))
+  if (mcpServers.ok) {
+    const data = (mcpServers.body as { data?: { servers?: unknown } } | null)?.data?.servers
+    out.mcpServers = (Array.isArray(data) ? data as Array<{ slug?: string }> : []).filter((m) => m.slug).map((m) => ({ slug: m.slug! }))
+  }
   return out
 }
 
 /** The names the project's files give each kind: an Agent's folder, a workflow's file, a Function's file or folder, a knowledge base's `name`. */
 export function projectNames(root: string): Record<OrphanKind, Set<string>> {
-  const out: Record<OrphanKind, Set<string>> = { agent: new Set(), workflow: new Set(), function: new Set(), knowledge: new Set() }
+  const out: Record<OrphanKind, Set<string>> = { agent: new Set(), workflow: new Set(), function: new Set(), knowledge: new Set(), 'mcp-server': new Set() }
   for (const t of allTargets(root)) {
     if (t.kind === 'agent') out.agent.add(t.slug)
     else if (t.kind === 'workflow') out.workflow.add(t.slug)
+    else if (t.kind === 'mcp-server') out['mcp-server'].add(t.name)
     else if (t.kind === 'function') {
       const slug = functionSlugOf(t.key)
       if (slug) out.function.add(slug)
@@ -143,6 +153,7 @@ export function appliedKeysOf(kind: OrphanKind, name: string): string[] {
   if (kind === 'agent') return [`agent:${name}`, `operating:${name}`, `bindings:${name}`, `lessons:${name}`]
   if (kind === 'workflow') return [`workflow:${name}`]
   if (kind === 'function') return [`function:${name}.ts`, `function:${name}/`]
+  if (kind === 'mcp-server') return [`mcp-server:${name}`]
   return []
 }
 
@@ -153,13 +164,14 @@ function wasApplied(kind: OrphanKind, name: string, applied: ReadonlySet<string>
   return appliedKeysOf(kind, name).some((k) => applied.has(k))
 }
 
-const WORDS: Record<OrphanKind, string> = { agent: 'Agent', workflow: 'workflow', function: 'Function', knowledge: 'knowledge base' }
+const WORDS: Record<OrphanKind, string> = { agent: 'Agent', workflow: 'workflow', function: 'Function', knowledge: 'knowledge base', 'mcp-server': 'MCP server' }
 
 /** The file an item of a kind would have in the project. */
 function fileOf(kind: OrphanKind, name: string): string {
   if (kind === 'agent') return `agents/${name}/agent.json`
   if (kind === 'workflow') return `workflows/${name}.yaml`
   if (kind === 'function') return `functions/${name}.ts`
+  if (kind === 'mcp-server') return `mcp-servers/${name}.yaml`
   return 'knowledge/<folder>/knowledge.json'
 }
 
@@ -183,6 +195,10 @@ export function findOrphans(root: string, items: RuntimeItems, applied: Readonly
       fix = deleted
         ? `\`frontera local dev\` switches it off (the runtime can’t remove a Function), or \`frontera function disable ${name}\` now`
         : `add its file to the project, or \`frontera function disable ${name}\` to switch it off (the runtime can’t remove a Function)`
+    } else if (kind === 'mcp-server') {
+      fix = deleted
+        ? '`frontera local dev` archives it (or `frontera mcp-server archive ' + name + '` now)'
+        : `add its file to the project (mcp-servers/${name}.yaml), or \`frontera mcp-server archive ${name}\` if it isn’t wanted`
     } else fix = 'add its folder to the project, or delete it from its page in Studio if it isn’t wanted: deleting a knowledge base takes its documents with it, so `frontera local dev` never does'
     out.push({ ref: `${kind}/${name}`, kind, name, ...(id ? { id } : {}), deleted, problem, fix })
   }
@@ -191,6 +207,7 @@ export function findOrphans(root: string, items: RuntimeItems, applied: Readonly
   // A Function switched off and with no file: it doesn't run, and the runtime can't remove it, so there is nothing to fix.
   for (const f of items.functions ?? []) if (f.enabled !== false) add('function', f.slug)
   for (const k of items.knowledge ?? []) add('knowledge', k.name, k.id)
+  for (const m of items.mcpServers ?? []) add('mcp-server', m.slug)
   return out
 }
 
@@ -274,6 +291,14 @@ export async function retireDeleted(project: Pick<LocalProject, 'stateDir'>, org
       }
       retired[o.ref] = { how: 'switched-off', at }
       lines.push(`  switched off Function ${o.name}: its file is gone from the project, and the runtime can’t remove a Function (it is switched on again if the file comes back)`)
+    } else if (o.kind === 'mcp-server') {
+      const res = await call(`/v1/mcp-servers/${encodeURIComponent(o.name)}`, { method: 'DELETE' })
+      if (!res.ok && res.status !== 404) {
+        lines.push(`  warning: MCP server ${o.name}’s file is gone, but it couldn’t be archived here: ${said(res)}`)
+        continue
+      }
+      retired[o.ref] = { how: 'archived', at }
+      lines.push(`  archived MCP server ${o.name}: its file is gone from the project, so clients can no longer connect to it (it is saved again if the file comes back)`)
     } else continue
     forget.push(...appliedKeysOf(o.kind, o.name))
   }

package/src/local/local-scaffold.ts

@@ -176,7 +176,7 @@ A Frontera project. Every file here is applied to a local runtime by
 | Path | What it is |
 |---|---|
 | \`agents/<slug>/agent.json\` | An Agent's draft: model, instructions, tools |
-| \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks |
+| \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks, handover reasons |
 | \`agents/<slug>/bindings.json\` | What it may use: Functions, workflows, Blueprint object types |
 | \`agents/<slug>/evals/*.yaml\` | Its test cases |
 | \`workflows/<slug>.yaml\` | A workflow |
@@ -301,7 +301,7 @@ Frontera deployment.
 | Path | What it is |
 |---|---|
 | \`agents/<slug>/agent.json\` | An Agent's draft: model, instructions, tools |
-| \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks |
+| \`agents/<slug>/operating.json\` | Its behavior: procedures, variables, focus, reply checks, handover reasons |
 | \`agents/<slug>/bindings.json\` | What it may use: the Functions and workflows it may start, the Blueprint object types it may query |
 | \`agents/<slug>/evals/*.yaml\` | Its test cases: a conversation and what a good reply does |
 | \`workflows/<slug>.yaml\` | A workflow |

package/src/local/local-schemas.ts

@@ -6,13 +6,14 @@ import { BLUEPRINT_SCHEMA_FILES, BLUEPRINT_SCHEMAS } from './local-blueprint-sch
 import type { LocalProject } from './local-project'
 import { isAlive, readState } from './local-state'
 import { PROCEDURE_TOOL_FORMS, PROCEDURE_TOOL_GROUPS } from './local-agent-checks'
+import { DEFAULT_HANDOVER_REASON_KEYS } from './local-operating'
 import { REF_KINDS, refPattern, type RefKind } from './local-sync-refs'
 
 /**
  * The formats of a project's files, as JSON Schema, for the coding agents and
  * editors working in it (`frontera local schema <kind>`).
  *
- * The service checks three of them, so their schemas come from the service
+ * The service checks four of them (an Agent, its behavior, a workflow, an MCP server), so their schemas come from the service
  * the runtime runs (`GET /v1/config/file-schemas/<kind>`), made from the same
  * zod schemas that check the files, then widened where a project file names a
  * resource by reference instead of id (`localizeServiceSchema`). The others
@@ -34,6 +35,7 @@ export const SCHEMA_KINDS = [
   'theme',
   'chat-app',
   'app',
+  'mcp-server',
   'knowledge',
   'skill',
   'blueprint-object-type',
@@ -60,6 +62,7 @@ export const SCHEMA_FILES: Record<SchemaKind, string> = {
   theme: 'themes/<name>/theme.json',
   'chat-app': 'chat-apps/<slug>.json',
   app: 'apps/<slug>.json',
+  'mcp-server': 'mcp-servers/<slug>.yaml',
   knowledge: 'knowledge/<name>/knowledge.json',
   skill: 'skills/<name>/SKILL.md (its front matter)',
   secrets: 'secrets.json',
@@ -888,6 +891,27 @@ function describeProjectFields(props: Record<string, unknown>): void {
   if ('dataScopes' in props && 'variables' in props) {
     describe(props, 'dataScopes', 'Optional. Narrows what the Agent reads of an object type to the records of the conversation: `[{ "objectType": "WorkOrder", "property": "customerId", "equals": "{{customer_id}}" }]`, at most one per object type. Every read of that type (query, fetch, aggregate, saved sets, links, media and metrics) sees only rows whose property equals the conversation variable; a conversation without the variable sees none. The variable is one in `variables`, and the property and variable are text or numbers. The object type must be granted in bindings.json `blueprint`. In an eval case, `variables` gives the conversation its values.')
   }
+  // Behavior settings (operating.json): why the Agent hands a conversation to people.
+  if ('handoverReasons' in props && 'variables' in props) {
+    const reasons = props.handoverReasons
+    const item = isRecord(reasons) && isRecord(reasons.items) ? reasons.items : null
+    if (isRecord(reasons) && item && isRecord(item.properties)) {
+      const inner = { ...item.properties }
+      describe(inner, 'key', 'The reason’s id: lower snake case (`order_problem`), at most 40 characters, unique in the list. Hand-over reports count by it, so keep it once the Agent is published; a handoff action names it in `handoverReason`.')
+      describe(inner, 'name', 'What people see in hand-over reports and the inbox (`Order problem`), 1 to 60 characters.')
+      describe(inner, 'whenToUse', 'What the Agent reads to choose this reason (`The customer reports a late, wrong or damaged order.`), 1 to 300 characters.')
+      props.handoverReasons = { ...reasons, items: { ...item, properties: inner } }
+    }
+    describe(props, 'handoverReasons', `Optional. Why the Agent hands a conversation to people; hand-over reports count by these. 1 to 15 reasons, each \`{ "key", "name", "whenToUse" }\`, keys unique, names unique ignoring case, and one must have the key \`other\` (rename it, never remove it). Leave the key out to use the default reasons (${DEFAULT_HANDOVER_REASON_KEYS.map((k) => `\`${k}\``).join(', ')}); a pull writes it only when the Agent has its own. \`frontera local dev\` refuses a list that breaks these rules, with each problem's path.`)
+  }
+  // A procedure's action (operating.json `procedures[].actions[]`): the reason a handoff records.
+  if ('handoverReason' in props && 'requiresFields' in props) {
+    describe(props, 'handoverReason', 'Optional, for a `handoff` action: the `key` of one of the Agent’s `handoverReasons` (the defaults when the file has none), recorded on the hand-over when a Step by step procedure runs the action. Absent: `other`. A key the Agent doesn’t have is reported by `frontera local dev` and refuses publishing.')
+  }
+  // A Step by step End step (operating.json `procedures[].blocks[].steps[]`): the reason one that hands over records.
+  if ('handoverReason' in props && 'outcome' in props) {
+    describe(props, 'handoverReason', 'Optional, for an End step with `outcome` `handoff`: the `key` of one of the Agent’s `handoverReasons` (the defaults when the file has none), recorded on the hand-over. Absent: `other`. A key the Agent doesn’t have is reported by `frontera local dev` and refuses publishing.')
+  }
   // An Agent (agent.json): the lists that name other resources.
   if ('modelConfigs' in props && 'knowledgeAttachments' in props) {
     describe(props, 'knowledgeAttachments', 'The knowledge bases the Agent searches: `[{ "knowledgeConfigId": "knowledge/<name>" }]`, one per base in knowledge/<name>/knowledge.json (`retrievalOverride` optional). `local dev` resolves each to this runtime’s id. When the key is present it is the Agent’s whole list (a base it leaves out is detached); leave the key out to keep the attachments made with `frontera knowledge attach`.', {

package/src/mcp/tools/docs-tools.ts

@@ -12,7 +12,7 @@ const DOCS_TOOLS = [
   { name: 'search_documentation', description: "Search Frontera's documentation for the release the local runtime runs. Returns guides with the best matching heading and a snippet; read one with read_documentation." },
   { name: 'read_documentation', description: 'Read a guide by its slug from a search result, whole or one heading of it.' },
   { name: 'list_documentation', description: 'List every guide: slug, title and description. Use it to browse an area, e.g. everything under "workflows/".' },
-  { name: 'read_file_schema', description: 'The exact format of a kind of project file (agent.json, operating.json, a workflow, the Blueprint), as JSON Schema, for the runtime\'s release. Read it before writing such a file.' },
+  { name: 'read_file_schema', description: 'The exact format of a kind of project file (agent.json, operating.json, a workflow, an MCP server, the Blueprint), as JSON Schema, for the runtime\'s release. Read it before writing such a file.' },
 ] as const
 
 export function docsTools(project: LocalProject, schemaFor: SchemaLookup): McpTool[] {