insights/services/mcp/scripts/generate-exec-docs.ts

#!/usr/bin/env tsx
// Renders the exec tool's command reference into schema/exec-command-reference.md,
// a markdown fragment hanzo.ai fetches at build time and embeds in the MCP tools
// reference page, so the website documents the same syntax the server serves to
// agents at runtime.
import * as fs from 'node:fs'
import * as path from 'node:path'

import { LEARN_COMMAND_LINE } from '../src/tools/exec-help'

const SECTIONS_DIR = path.join(__dirname, '../src/templates/sections')
const OUTPUT_PATH = path.join(__dirname, '../schema/exec-command-reference.md')

function readSection(name: string): string {
    return fs.readFileSync(path.join(SECTIONS_DIR, name), 'utf8').trim()
}

// Throws rather than emitting an empty section, so a template edit that moves the marker
// fails the build instead of silently gutting the published page.
function extractFencedBlockAfter(markdown: string, source: string, marker: string): string {
    const markerIndex = markdown.indexOf(marker)
    if (markerIndex === -1) {
        throw new Error(`${source}: marker not found: ${marker}`)
    }
    const fence = markdown.slice(markerIndex).match(/```[\s\S]*?```/)
    if (!fence) {
        throw new Error(`${source}: no fenced code block after marker: ${marker}`)
    }
    return fence[0]
}

// The leading line only makes sense inside a tool parameter description; the replace is a
// no-op if the template wording changes, so drift shows up in review.
const cliSyntax = readSection('cli-syntax.md')
    .replace('CLI-style command string. Supported commands:', '')
    .replace('{extra_commands}', LEARN_COMMAND_LINE)
    .trim()

// The blurb is written for agents and repeats the tool catalog and schema rules the page
// already covers, so only its ordered command walkthrough is published.
const execWorkflow = extractFencedBlockAfter(
    readSection('exec-tool-blurb.md'),
    'exec-tool-blurb.md',
    '**Commands (in order):**'
)

const fragment = `<!-- Generated by services/mcp/scripts/generate-exec-docs.ts (part of \`insightscli build:openapi\`). Do not edit directly. -->

## CLI mode commands

In [CLI mode](/docs/model-context-protocol/faq#choosing-a-tool-mode), the default for most clients, the MCP server registers a single \`exec\` tool instead of one tool per endpoint. Agents pass it CLI-style command strings to list, search, inspect, and call the tools above on demand, which keeps context usage small.

${cliSyntax}

The \`learn\` command is only registered on hosts that use the guided help catalog (currently Claude web and desktop). On hosts that support MCP apps, CLI mode also registers a separate \`render-ui\` tool for rendering interactive visualizations.

### How agents use these commands

${execWorkflow}

### Tips

- Run \`info <tool_name>\` once when a schema isn't already in context, then reuse it. Running it before every call wastes context, and guessing a schema instead fails the call.
- When \`info\` returns fields carrying a \`hint\`, drill into each one with \`schema <tool_name> <field_path>\` before building that field's value.
- \`search\` matches tool names, titles, and descriptions, not input schemas. Search for the tool, then inspect its schema.
`

fs.writeFileSync(OUTPUT_PATH, fragment)
process.stdout.write(`Wrote ${path.relative(process.cwd(), OUTPUT_PATH)}\n`)