Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | /** |
| 2 | * Meta Tools Generator Script |
| 3 | * |
| 4 | * Reads public/data/meta-tools.json and generates: |
| 5 | * - /content/toolkits/meta-tools/meta.json (sidebar navigation) |
| 6 | * - /content/toolkits/meta-tools/index.mdx (overview page) |
| 7 | * - /content/toolkits/meta-tools/{name}.mdx (individual tool pages) |
| 8 | * |
| 9 | * Run: bun run generate:meta-tools |
| 10 | * |
| 11 | * Set COMPOSIO_META_TOOLS_SCHEMA_URL to refresh the snapshot from a |
| 12 | * production Platform schema export before rendering. |
| 13 | */ |
| 14 | |
| 15 | import { writeFile, readFile, mkdir, readdir, unlink } from 'fs/promises'; |
| 16 | import { join } from 'path'; |
| 17 | import { metaToolsSchema, type MetaTool } from '../lib/meta-tools-data'; |
| 18 | import { META_TOOL_OVERRIDES } from '../lib/meta-tool-overrides'; |
| 19 | import { encodeMarkdownTableCell, encodeYamlString } from '../lib/markdown-escaping'; |
| 20 | import { STAGING_HOSTS, stripStagingHosts } from './production-api.mjs'; |
| 21 | |
| 22 | const DATA_DIR = join(process.cwd(), 'public/data'); |
| 23 | const SNAPSHOT_PATH = join(DATA_DIR, 'meta-tools.json'); |
| 24 | const CONTENT_DIR = join(process.cwd(), 'content/toolkits/meta-tools'); |
| 25 | |
| 26 | type MetaToolPage = Pick<MetaTool, 'slug' | 'displayName' | 'description'>; |
| 27 | |
| 28 | async function readSchemaExport(source: string): Promise<string> { |
| 29 | const url = new URL(source); |
| 30 | if (url.protocol !== 'https:' || STAGING_HOSTS.includes(url.hostname)) { |
| 31 | throw new Error('COMPOSIO_META_TOOLS_SCHEMA_URL must point to a production HTTPS export'); |
| 32 | } |
| 33 | const response = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(30_000) }); |
| 34 | if (!response.ok) throw new Error(`Meta-tool schema export responded ${response.status}`); |
| 35 | return stripStagingHosts(await response.text()); |
| 36 | } |
| 37 | |
| 38 | /** Derive a short page slug from the tool slug: COMPOSIO_SEARCH_TOOLS -> search_tools */ |
| 39 | export function pageSlug(toolSlug: string): string { |
| 40 | return toolSlug.toLowerCase().replace('composio_', ''); |
| 41 | } |
| 42 | |
| 43 | /** Truncate description to first sentence for index table */ |
| 44 | export function briefDescription(description: string): string { |
| 45 | // Strip markdown and leading whitespace |
| 46 | const cleaned = description.replace(/\*\*/g, '').replace(/__/g, '').replace(/\n+/g, ' ').trim(); |
| 47 | const firstSentence = cleaned.split(/\.(\s|$)/)[0]; |
| 48 | if (firstSentence.length > 120) { |
| 49 | return firstSentence.slice(0, 117) + '...'; |
| 50 | } |
| 51 | return firstSentence; |
| 52 | } |
| 53 | |
| 54 | /** One-line summary for the index table. Prefer hand-written override copy, fall back to the API description. */ |
| 55 | function indexLine(tool: MetaToolPage): string { |
| 56 | const override = META_TOOL_OVERRIDES[tool.slug]; |
| 57 | if (override) { |
| 58 | // First sentence of the hand-written summary keeps the table tight. |
| 59 | const firstSentence = override.summary.split(/\.(\s|$)/)[0].trim(); |
| 60 | return encodeMarkdownTableCell(firstSentence); |
| 61 | } |
| 62 | return encodeMarkdownTableCell(briefDescription(tool.description)); |
| 63 | } |
| 64 | |
| 65 | /** Generate the index.mdx overview page — Modal-voice intro plus a one-line-per-tool table */ |
| 66 | export function generateIndexMdx(tools: MetaToolPage[]): string { |
| 67 | let content = `--- |
| 68 | title: Meta Tools |
| 69 | description: The system tools every Composio session gives your agent to discover, authenticate, execute, and process tools at runtime. |
| 70 | keywords: [meta tools, session] |
| 71 | --- |
| 72 | |
| 73 | {/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually. To change the intro prose or a tool's one-line summary, edit the template and the override map in lib/meta-tool-overrides.ts. */} |
| 74 | |
| 75 | import { Callout } from 'fumadocs-ui/components/callout'; |
| 76 | |
| 77 | Every Composio [session](/docs/how-composio-works) hands your agent a small set of meta tools instead of hundreds of raw tool definitions. The agent uses them to find the right tools for a task, connect the accounts those tools need, execute them, and process the results, all at runtime and all sharing one \`session_id\`. |
| 78 | |
| 79 | This keeps your context window small: you load a handful of meta tools, not a catalog of %TOOLKIT_COUNT% toolkits. The agent searches for what it needs when it needs it. |
| 80 | |
| 81 | A typical workflow runs in order: call \`COMPOSIO_SEARCH_TOOLS\` to discover tools and open a session, call \`COMPOSIO_MANAGE_CONNECTIONS\` if a toolkit is not yet connected, then run the tools with \`COMPOSIO_MULTI_EXECUTE_TOOL\`. Reach for the workbench and bash tools when responses are large enough to process out of context. |
| 82 | |
| 83 | | Tool | What it does | |
| 84 | |------|--------------| |
| 85 | `; |
| 86 | |
| 87 | for (const tool of tools) { |
| 88 | content += `| [\`${tool.slug}\`](/toolkits/meta-tools/${pageSlug(tool.slug)}) | ${indexLine(tool)} |\n`; |
| 89 | } |
| 90 | |
| 91 | content += ` |
| 92 | <Callout type="warn"> |
| 93 | These schemas are for reference only. We do not guarantee backward compatibility for parameter names or response shapes, so do not rely on them as structured type definitions in your code. |
| 94 | </Callout> |
| 95 | `; |
| 96 | |
| 97 | return content; |
| 98 | } |
| 99 | |
| 100 | /** |
| 101 | * A frontmatter title: plain when it is unambiguous YAML text, quoted otherwise, |
| 102 | * so a remote displayName cannot end the frontmatter or change its meaning. |
| 103 | */ |
| 104 | function yamlTitle(value: string): string { |
| 105 | const plain = /^\w(?:[\w ()-]*[\w)])?$/.test(value) && !/^(?:true|false|null|yes|no|on|off|[\d.+-]+)$/i.test(value); |
| 106 | return plain ? value : encodeYamlString(value); |
| 107 | } |
| 108 | |
| 109 | /** Generate an individual tool MDX page */ |
| 110 | export function generateToolMdx(tool: MetaToolPage): string { |
| 111 | // The API's search-tool description contains an outdated catalog count. |
| 112 | const description = tool.slug === 'COMPOSIO_SEARCH_TOOLS' |
| 113 | ? META_TOOL_OVERRIDES[tool.slug].summary |
| 114 | : tool.description; |
| 115 | const desc = encodeYamlString(briefDescription(description)); |
| 116 | |
| 117 | return `--- |
| 118 | title: ${yamlTitle(tool.displayName)} |
| 119 | description: ${desc} |
| 120 | keywords: [${tool.slug}, meta tool] |
| 121 | --- |
| 122 | |
| 123 | {/* Auto-generated by scripts/generate-meta-tools.ts — do not edit manually */} |
| 124 | |
| 125 | import { MetaToolDetailServer } from '@/components/meta-tools/meta-tool-page'; |
| 126 | |
| 127 | <MetaToolDetailServer slug="${tool.slug}" /> |
| 128 | `; |
| 129 | } |
| 130 | |
| 131 | /** Generate meta.json for sidebar navigation — index.mdx is the folder page */ |
| 132 | function generateMetaJson(tools: MetaToolPage[]): string { |
| 133 | const pages = tools.map(t => pageSlug(t.slug)); |
| 134 | return JSON.stringify({ title: 'Meta Tools', defaultOpen: true, pages }, null, 2) + '\n'; |
| 135 | } |
| 136 | |
| 137 | async function cleanGeneratedMdx() { |
| 138 | try { |
| 139 | const files = await readdir(CONTENT_DIR); |
| 140 | for (const file of files) { |
| 141 | if (file.endsWith('.mdx') || file === 'meta.json') { |
| 142 | await unlink(join(CONTENT_DIR, file)); |
| 143 | } |
| 144 | } |
| 145 | } catch { |
| 146 | // Directory doesn't exist yet, that's fine |
| 147 | } |
| 148 | } |
| 149 | |
| 150 | async function main() { |
| 151 | console.log('Starting meta tools generation...\n'); |
| 152 | |
| 153 | const source = process.env.COMPOSIO_META_TOOLS_SCHEMA_URL?.trim(); |
| 154 | const contents = source ? await readSchemaExport(source) : await readFile(SNAPSHOT_PATH, 'utf8'); |
| 155 | const snapshot: unknown = JSON.parse(contents); |
| 156 | const metaTools = metaToolsSchema.parse(snapshot); |
| 157 | metaTools.sort((a, b) => a.slug.localeCompare(b.slug)); |
| 158 | |
| 159 | if (source) { |
| 160 | await mkdir(DATA_DIR, { recursive: true }); |
| 161 | await writeFile(SNAPSHOT_PATH, JSON.stringify(snapshot, null, 2)); |
| 162 | console.log('Updated public/data/meta-tools.json from the schema export'); |
| 163 | } else { |
| 164 | console.log('Using the checked-in public/data/meta-tools.json snapshot'); |
| 165 | } |
| 166 | |
| 167 | await mkdir(CONTENT_DIR, { recursive: true }); |
| 168 | await cleanGeneratedMdx(); |
| 169 | |
| 170 | await writeFile(join(CONTENT_DIR, 'meta.json'), generateMetaJson(metaTools)); |
| 171 | console.log('Wrote content/toolkits/meta-tools/meta.json'); |
| 172 | |
| 173 | await writeFile(join(CONTENT_DIR, 'index.mdx'), generateIndexMdx(metaTools)); |
| 174 | console.log('Wrote content/toolkits/meta-tools/index.mdx'); |
| 175 | |
| 176 | for (const tool of metaTools) { |
| 177 | const filename = `${pageSlug(tool.slug)}.mdx`; |
| 178 | await writeFile(join(CONTENT_DIR, filename), generateToolMdx(tool)); |
| 179 | console.log(`Wrote content/toolkits/meta-tools/${filename}`); |
| 180 | } |
| 181 | |
| 182 | console.log(`\nGeneration complete! ${metaTools.length} meta tools.`); |
| 183 | console.log(`Tools: ${metaTools.map(t => t.slug).join(', ')}`); |
| 184 | } |
| 185 | |
| 186 | if (import.meta.main) { |
| 187 | main().catch(error => { |
| 188 | console.error('Fatal error:', error); |
| 189 | process.exit(1); |
| 190 | }); |
| 191 | } |