Tooling MCP

MCP Server

Connect AI clients to AuroraScript documentation, validation, execution, and diagnostics over MCP.

Applies to 4.0.0.

Home · Tooling

On this page

• Installation and Configuration
• Recommended Workflow
• Resources
• Tool Reference
• File-system Overlay Rules
• Next steps

Installation and Configuration

Install the global .NET tool:

dotnet tool install --global AuroraScript.Mcp --version 4.0.0

Add the MCP server in Codex:

codex mcp add aurora-script -- aurora-mcp

You can also write the following in Codex configuration. The usual Windows path is %USERPROFILE%\.codex\config.toml; the usual macOS/Linux path is ~/.codex/config.toml.

[mcp_servers.aurora-script]
type = "stdio"
command = "aurora-mcp"
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled = true

A locally published executable should use an absolute path and an explicit cwd.

[mcp_servers.aurora-script]
type = "stdio"
command = "D:\\mcp\\AuroraScript.Mcp.exe"
cwd = "D:\\mcp"
enabled = true

Recommended Workflow

1. Read aurora://docs/script-best-practices and aurora://schema/runtime-api first.
2. Use aurora_search_runtime_api or aurora_get_runtime_api instead of guessing API names.
3. Check generated code with aurora_check_script or aurora_check_file.
4. Use a run tool only when a result, stdout, or stderr is needed.
5. Use aurora_validate_best_practices to find common poor patterns in AI-authored scripts.

Resources

The server embeds the following stable URIs:

• aurora://docs/ai
• aurora://docs/script-best-practices
• aurora://docs/language
• aurora://docs/performance
• aurora://docs/host-integration
• aurora://schema/ebnf
• aurora://schema/features
• aurora://schema/runtime-api
• aurora://schema/host-api
• aurora://examples/manifest

Discover resources through MCP resources/list and read their contents through resources/read.

Tool Reference

Parameter names and descriptions are shown in English.

aurora_get_document

Reads language material by id or resource-relative path.

Parameters:

• id
  Required. A document id or resource-relative path; discover it with aurora_list_documents first.

Returns

Document text and MIME type.

{ "name": "aurora_get_document", "arguments": { "id": "script-best-practices" } }

aurora_list_documents

Lists embedded documents, schemas, and examples.

Parameters:

• prefix
  Optional. Filters by a relative-path prefix such as docs/, schema/, or examples/.

Returns

A list containing id, URI, path, name, description, and MIME type.

{ "name": "aurora_list_documents", "arguments": { "prefix": "schema/" } }

aurora_list_features

Returns structured language-feature metadata.

Parameters:

• None.

Returns

JSON text for the features schema.

{ "name": "aurora_list_features", "arguments": {} }

aurora_check_script

Compile-checks in-memory source as a full module or a CompileBlock body without executing it.

Parameters:

• source
  Required. AuroraScript source to check.
• mode
  Optional. module or block; module mode is the default.
• sourceName
  Optional. Virtual filename shown in diagnostics.
• parameters
  Optional. Positional parameter names for block mode.
• sources
  Optional. In-memory dependency sources keyed by path for import / include.

Returns

Compilation success and a diagnostic collection.

{
  "name": "aurora_check_script",
  "arguments": {
    "source": "@module(TEST); export func run() { return 42; }",
    "sourceName": "main.as"
  }
}

aurora_run_script

Compiles and runs in-memory source, suitable for a single module, module dependencies, or a CompileBlock.

Parameters:

• source
  Required. Source to compile.
• mode
  Optional. module or block.
• sourceName
  Optional. Virtual filename.
• moduleName
  Optional in module mode. Module name to execute; defaults to TEST.
• methodName
  Optional in module mode. Exported function to invoke; defaults to run.
• parameters
  Optional in block mode. CompileBlock parameter names.
• arguments
  Optional. Array of JSON values converted to AuroraScript arguments.
• sources
  Optional. In-memory dependency sources keyed by path.

Returns

Result, stdout, stderr, diagnostics, and runtime errors.

{
  "name": "aurora_run_script",
  "arguments": {
    "mode": "block",
    "source": "return left + right;",
    "parameters": ["left", "right"],
    "arguments": [20, 22]
  }
}

aurora_check_file

Checks a file-system entry script and its dependency graph without executing it.

Parameters:

• rootDirectory
  Required. File-system Resolver root.
• entryPath
  Required. Entry .as path relative to rootDirectory, or an absolute path under the root.
• extName
  Optional. Script extension; defaults to .as.
• sources
  Optional. In-memory overlays keyed by root-relative path; use /, and overlays win only when the resolved target lies under the root.

Returns

Compilation result and diagnostics.

{ "name": "aurora_check_file", "arguments": { "rootDirectory": "scripts", "entryPath": "main.as" } }

aurora_run_file

Compiles and runs a file-system entry script and its dependency graph.

Parameters:

• rootDirectory
  Required. File-system Resolver root.
• entryPath
  Required. Entry script path.
• moduleName
  Required. Exported module name to execute.
• methodName
  Optional. Exported function name; defaults to run.
• arguments
  Optional. JSON argument array.
• extName
  Optional. Script extension; defaults to .as.
• sources
  Optional. In-memory overlay sources.

Returns

Result, output, diagnostics, and runtime errors.

{
  "name": "aurora_run_file",
  "arguments": { "rootDirectory": "examples/tests", "entryPath": "main.as", "moduleName": "MAIN", "methodName": "run" }
}

aurora_build_workspace

Compiles every Resolver-visible script below a file-system root.

Parameters:

• rootDirectory
  Required. File-system Resolver root.
• extName
  Optional. Script extension; defaults to .as.
• sources
  Optional. In-memory overlay sources.

Returns

Workspace compilation result and diagnostics.

{ "name": "aurora_build_workspace", "arguments": { "rootDirectory": "scripts" } }

aurora_search_runtime_api

Searches the structured script runtime API index.

Parameters:

• query
  Required. Name or text such as String.trim, HashMap, or appendLine.
• limit
  Optional. Maximum result count; defaults to 20.

Returns

Matching runtime API entries.

{ "name": "aurora_search_runtime_api", "arguments": { "query": "StringBuffer", "limit": 10 } }

aurora_get_runtime_api

Reads one structured runtime entry by API path.

Parameters:

• path
  Required. Runtime API path such as Math, Array.push, String.trim, or HashMap.get.

Returns

The API entry with its signatures, parameters, and documentation.

{ "name": "aurora_get_runtime_api", "arguments": { "path": "Array.push" } }

aurora_list_examples

Lists valid, invalid, or all examples from the language-pack manifest.

Parameters:

• kind
  Optional. valid, invalid, or all.

Returns

Example manifest entries.

{ "name": "aurora_list_examples", "arguments": { "kind": "valid" } }

aurora_get_example

Reads an embedded example by manifest path.

Parameters:

• path
  Required. Example path such as valid/templates.as or invalid/const-assignment.as.

Returns

Example source text and MIME type.

{ "name": "aurora_get_example", "arguments": { "path": "valid/templates.as" } }

aurora_validate_best_practices

Checks AI-authored source for known authoring-pattern issues.

Parameters:

• source
  Required. Source to check.
• mode
  Optional. module or block.

Returns

A collection of best-practice warnings.

{
  "name": "aurora_validate_best_practices",
  "arguments": { "mode": "block", "source": "for (var i = 0; i < items.length; i++) { total += items[i]; } return total;" }
}

aurora_explain_diagnostic

Explains common AuroraScript compiler diagnostics and likely fixes.

Parameters:

• message
  Required. Compiler diagnostic message.

Returns

Diagnostic meaning and suggested fixes.

{ "name": "aurora_explain_diagnostic", "arguments": { "message": "Cannot assign to const value." } }

File-system Overlay Rules

aurora_check_file, aurora_run_file, and aurora_build_workspace place optional in-memory sources ahead of the disk Resolver. Keys are normalized with / and resolved relative to rootDirectory; earlier resolvers win, but an overlay only hits when the resolved target remains under the memory root. Different protocols or non-overlapping roots cannot override one another.

Next steps

• Tooling to compare the available integrations.
• Troubleshooting and Security if the server cannot start or communicate.