@ema.co/mcp-toolkit 0.2.0

package/dist/sdk/generation-schema.js

@@ -0,0 +1,189 @@
+/**
+ * Generation Schema
+ *
+ * Transforms AGENT_CATALOG into a compact format for workflow generation.
+ * This avoids the token waste of including full documentation in prompts.
+ *
+ * The auto-builder sends ~70K tokens of documentation per request.
+ * This schema reduces that to ~5K tokens of actionable constraints.
+ */
+import { AGENT_CATALOG } from "./knowledge.js";
+import { INPUT_SOURCE_RULES } from "./validation-rules.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Schema Generation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Build a compact agent lookup from the full catalog
+ */
+export function buildCompactAgents() {
+    const agents = {};
+    for (const agent of AGENT_CATALOG) {
+        const inputs = {};
+        for (const input of agent.inputs ?? []) {
+            inputs[input.name] = { type: input.type, required: input.required };
+        }
+        const outputs = {};
+        for (const output of agent.outputs ?? []) {
+            outputs[output.name] = output.type;
+        }
+        agents[agent.actionName] = {
+            name: agent.displayName,
+            category: agent.category,
+            inputs,
+            outputs,
+            constraints: agent.criticalRules,
+        };
+    }
+    return agents;
+}
+/**
+ * Build type compatibility rules
+ */
+export function buildTypeRules() {
+    return [
+        {
+            sourceType: "WELL_KNOWN_TYPE_CHAT_CONVERSATION",
+            targetTypes: ["WELL_KNOWN_TYPE_CHAT_CONVERSATION", "WELL_KNOWN_TYPE_ANY"],
+        },
+        {
+            sourceType: "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES",
+            targetTypes: ["WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", "WELL_KNOWN_TYPE_ANY"],
+        },
+        {
+            sourceType: "WELL_KNOWN_TYPE_SEARCH_RESULT",
+            targetTypes: ["WELL_KNOWN_TYPE_SEARCH_RESULT", "WELL_KNOWN_TYPE_ANY"],
+        },
+        {
+            sourceType: "WELL_KNOWN_TYPE_DOCUMENT",
+            targetTypes: ["WELL_KNOWN_TYPE_DOCUMENT", "WELL_KNOWN_TYPE_ANY"],
+        },
+        {
+            sourceType: "WELL_KNOWN_TYPE_ENUM",
+            targetTypes: ["WELL_KNOWN_TYPE_ENUM", "WELL_KNOWN_TYPE_ANY"],
+        },
+        // ANY can connect to ANY
+        {
+            sourceType: "WELL_KNOWN_TYPE_ANY",
+            targetTypes: ["WELL_KNOWN_TYPE_ANY", "WELL_KNOWN_TYPE_TEXT_WITH_SOURCES", "WELL_KNOWN_TYPE_SEARCH_RESULT"],
+        },
+    ];
+}
+/**
+ * Build structural constraints for workflow validation
+ */
+export function buildConstraints() {
+    return {
+        categorizers: [
+            "MUST have at least one outgoing edge for each category",
+            "MUST include a Fallback category",
+            "Output format: category::<CategoryName>",
+            "Target input: trigger_when",
+            "Category outputs are ONLY for control flow - cannot connect to WORKFLOW_OUTPUT",
+        ],
+        hitl: [
+            "MUST have both success and failure paths",
+            "Success path: source_output 'hitl_status_HITL Success' (note: space, not underscore)",
+            "Failure path: source_output 'hitl_status_HITL Failure' (note: space, not underscore)",
+            "Both paths must eventually reach WORKFLOW_OUTPUT",
+            "Unlike regular categorizers, NO Fallback category - only Success/Failure",
+        ],
+        outputs: [
+            "All user-visible outputs MUST connect to WORKFLOW_OUTPUT",
+            "Format: target_input = '<node_id>.<output_name>'",
+            "Every workflow path must reach WORKFLOW_OUTPUT",
+        ],
+    };
+}
+/**
+ * Generate the complete compact schema for workflow generation
+ */
+export function generateSchema() {
+    return {
+        agents: buildCompactAgents(),
+        typeRules: buildTypeRules(),
+        inputRules: INPUT_SOURCE_RULES.map(rule => ({
+            action: rule.actionPattern,
+            recommended: rule.recommended,
+            avoid: rule.avoid,
+            severity: rule.severity,
+        })),
+        constraints: buildConstraints(),
+    };
+}
+/**
+ * Generate a Markdown summary suitable for LLM prompts
+ * This is ~5K tokens vs ~70K for full documentation
+ */
+export function generateSchemaMarkdown() {
+    const schema = generateSchema();
+    let md = `# Workflow Generation Schema\n\n`;
+    // Agent summary table
+    md += `## Available Agents (${Object.keys(schema.agents).length})\n\n`;
+    md += `| Action | Category | Inputs | Outputs |\n`;
+    md += `|--------|----------|--------|--------|\n`;
+    for (const [actionName, agent] of Object.entries(schema.agents)) {
+        const inputs = Object.entries(agent.inputs)
+            .map(([name, { type, required }]) => `${name}${required ? "*" : ""}`)
+            .join(", ") || "-";
+        const outputs = Object.keys(agent.outputs).join(", ") || "-";
+        md += `| \`${actionName}\` | ${agent.category} | ${inputs} | ${outputs} |\n`;
+    }
+    // Type rules
+    md += `\n## Type Compatibility\n\n`;
+    for (const rule of schema.typeRules) {
+        const targets = rule.targetTypes.map(t => `\`${t}\``).join(", ");
+        md += `- \`${rule.sourceType}\` → ${targets}\n`;
+    }
+    // Input rules
+    md += `\n## Input Source Rules\n\n`;
+    md += `| Action | Recommended | Avoid | Severity |\n`;
+    md += `|--------|-------------|-------|----------|\n`;
+    for (const rule of schema.inputRules) {
+        const avoid = rule.avoid.length ? rule.avoid.join(", ") : "-";
+        md += `| \`${rule.action}\` | \`${rule.recommended}\` | ${avoid} | ${rule.severity} |\n`;
+    }
+    // Structural constraints
+    md += `\n## Structural Constraints\n\n`;
+    md += `### Categorizers\n`;
+    for (const c of schema.constraints.categorizers) {
+        md += `- ${c}\n`;
+    }
+    md += `\n### HITL (Human-in-the-Loop)\n`;
+    for (const c of schema.constraints.hitl) {
+        md += `- ${c}\n`;
+    }
+    md += `\n### Workflow Output\n`;
+    for (const c of schema.constraints.outputs) {
+        md += `- ${c}\n`;
+    }
+    return md;
+}
+/**
+ * Get compact agent info for a specific action
+ */
+export function getAgentSchema(actionName) {
+    const schema = generateSchema();
+    return schema.agents[actionName];
+}
+/**
+ * Validate if a connection is type-compatible
+ */
+export function isTypeCompatible(sourceType, targetType) {
+    // ANY accepts anything
+    if (targetType === "WELL_KNOWN_TYPE_ANY")
+        return true;
+    // Same type is always compatible
+    if (sourceType === targetType)
+        return true;
+    // Check explicit rules
+    const schema = generateSchema();
+    const rule = schema.typeRules.find(r => r.sourceType === sourceType);
+    return rule?.targetTypes.includes(targetType) ?? false;
+}
+/**
+ * Get recommended input source for an action
+ */
+export function getRecommendedInput(actionName) {
+    const rule = INPUT_SOURCE_RULES.find(r => actionName.toLowerCase().includes(r.actionPattern.toLowerCase()));
+    return rule?.recommended;
+}

package/dist/sdk/index.js

@@ -0,0 +1,39 @@
+/**
+ * Ema Toolkit SDK
+ *
+ * Core library providing programmatic access to:
+ * - EmaClient: API client for Ema platform
+ * - SyncSDK: Persona synchronization across environments
+ * - Config: Configuration loading and validation
+ * - Models: TypeScript types for API entities
+ */
+// API Client
+export { EmaClient, EmaApiError } from "./client.js";
+// Sync SDK
+export { SyncSDK, } from "./sync.js";
+// Sync Options (hierarchical config from .ema.yaml)
+export { loadSyncOptions, clearSyncOptionsCache, resolveSyncBehavior, getRoutingTargets, validateSyncOptions, } from "./sync-options.js";
+export { SYNC_METADATA_KEY } from "./models.js";
+export { loadConfig, loadConfigOptional, validateConfig, configToYaml, resolveBearerToken, getMasterEnv, getEnvByName } from "./config.js";
+// State Store
+export { StateStore } from "./state.js";
+// Auto Builder Knowledge Base
+export { 
+// Catalogs & References
+AGENT_CATALOG, WIDGET_CATALOG, WORKFLOW_PATTERNS, QUALIFYING_QUESTIONS, PLATFORM_CONCEPTS, WORKFLOW_EXECUTION_MODEL, COMMON_MISTAKES, DEBUG_CHECKLIST, GUIDANCE_TOPICS, VOICE_PERSONA_TEMPLATE, PROJECT_TYPES, 
+// Helper Functions
+getAgentsByCategory, getAgentByName, getWidgetsForPersonaType, checkTypeCompatibility, getQualifyingQuestionsByCategory, getRequiredQualifyingQuestions, getConceptByTerm, suggestAgentsForUseCase, validateWorkflowPrompt, 
+// Workflow Analysis Functions
+parseWorkflowDef, detectWorkflowIssues, validateWorkflowConnections, analyzeWorkflow, suggestWorkflowFixes, 
+// Validation Rules (Single Source of Truth)
+VALIDATION_INPUT_RULES, ANTI_PATTERNS, OPTIMIZATION_RULES, findInputSourceRule, findAntiPatternByIssueType, generateMarkdownDocumentation, exportRulesAsJSON, } from "./knowledge.js";
+// Workflow Compiler (Template-driven workflow generation)
+export { 
+// Core compiler
+compileWorkflow, 
+// Settings builders
+buildVoiceConfig, buildChatConfig, } from "./workflow-generator.js";
+// Workflow Intent (Normalization layer)
+export { parseInput, validateIntent, intentToSpec, detectInputType, parseNaturalLanguage, parsePartialSpec, } from "./workflow-intent.js";
+// Generation Schema (Compact format for LLM-based generation)
+export { generateSchema, generateSchemaMarkdown, buildCompactAgents, buildTypeRules, buildConstraints, getAgentSchema, isTypeCompatible, getRecommendedInput, } from "./generation-schema.js";