Programmatic API for parsing, validating, and working with Aexol specifications in TypeScript/JavaScript.
npm install @aexol/parser
import { Parser, Validator } from "@aexol/parser";
const ast = new Parser(`
type User {
id: string
name: string
email: string
}
`).parse();
const result = new Validator(ast).validate();
console.log(result.isValid); // true
| Export | Kind | Purpose |
|---|---|---|
Parser | Class | Parse source code into AST |
Validator | Class | Validate AST for semantic correctness |
Lexer | Class | Tokenize Aexol source |
Tokenizer | Class | Token stream with lookahead |
parseAexol | Function | Convenience parse function |
TokenType | Enum | Token type constants |
import { Parser } from "@aexol/parser";
const parser = new Parser(source, {
includePositions: true, // Attach line/column to AST nodes
recoverFromErrors: true, // Continue parsing after errors
});
const ast = parser.parse();
// ast.types, ast.visitors, ast.agents, ast.workflows, ast.roles, ast.enums
| Node | Key fields |
|---|---|
TypeDefinition | name, fields[] |
FieldDefinition | name, type, isArray, isOptional |
VisitorDefinition | name?, capabilities[], position? |
Capability | verb, target, conditions?[], nested?[] |
WorkflowDefinition | states, transitions |
AgentDefinition | name, role?, capabilities[] |
try {
parser.parse();
} catch (error) {
if (error instanceof SyntaxError) {
console.error(error.message, `line ${error.line}`);
}
}
const result = new Validator(ast).validate();
// result.isValid, result.errors[], result.warnings[], result.infos[]
interface Diagnostic {
severity: "error" | "warning" | "info";
message: string;
line?: number;
column?: number;
code?: string;
}
| Check | Error |
|---|---|
| Unique names | Types, visitors, agents, roles, workflows must be unique |
| Anonymous visitor | At most one unnamed visitor per spec |
| Valid references | Type references must resolve to existing types |
| Valid verbs | Capability verbs must be recognized |
| Workflow states | Transitions must reference defined states |
| Circular refs | No infinite recursion in required fields |
new Validator(ast, {
strictMode: true,
allowUnknownVerbs: false,
});
import { Parser, Validator } from "@aexol/parser";
async function processAexol(source: string) {
const ast = new Parser(source).parse();
const result = new Validator(ast).validate();
if (!result.isValid) {
for (const err of result.errors) {
console.error(`[${err.severity}] ${err.message}`);
}
return;
}
console.log(`Types: ${ast.types.length} | Visitors: ${ast.visitors.length}`);
console.log("✅ Valid specification!");
}
For AI assistant integration, use the backend MCP endpoint.
Endpoint: https://api.aexol.ai/mcp Protocol: JSON-RPC 2.0 Auth:
Authorization: Bearer sk-aexol-team-... Methods: initialize, ping,
tools/list, tools/call
| Tool | Category | Purpose |
|---|---|---|
remote_start_inference | Generation | Start artifact generation (single or batch) |
remote_get_inference_task | Generation | Retrieve/wait for generation results |
remote_list_inference_tasks | Generation | List generation tasks |
remote_cancel_inference_task | Generation | Cancel a running task |
remote_refine_inference_artifact | Refinement | Refine a generated artifact |
remote_refine_aexol_content | Refinement | Refine raw Aexol content |
remote_start_from | Import | Generate Aexol from text/document |
remote_get_from_task | Import | Retrieve/wait for import results |
remote_list_from_tasks | Import | List import tasks |
remote_ingest_cloud_document | Knowledge | Upload document to knowledge base |
remote_cloud_search | Knowledge | Search knowledge base chunks |
remote_list_cloud_documents | Knowledge | List cloud documents (paginated) |
remote_get_cloud_document | Knowledge | Get document by ID |
remote_update_cloud_document | Knowledge | Update document fields |
remote_delete_cloud_document | Knowledge | Delete document |
remote_set_context | Session | Set default team/project scope |
remote_get_context | Session | Get effective context |
remote_clear_context | Session | Clear session defaults |
remote_wait_task | Utility | Unified waiter for inference/from tasks |
Full setup: Remote MCP Configuration | Working with AI & IDEs
aexol analyze app.aexol
Outputs: type count, visitor count, workflow count, total capabilities, nesting depth, complexity rating.