Ascot

Ties together knowledge from across your ObjectScript code base.

A type checker and code intelligence engine for InterSystems ObjectScript.
Use it as a CLI tool, from AI agents via
MCP or LSP protocols
(including Claude Code plugins), or via the
InterSystems Language Server.

Features

• Diagnostics: flow-sensitive type checking — undefined-variable reads,
  assigned-but-never-read locals, argument count/mode mismatches, missing
  QUIT/RETURN, inconsistent variable declarations across branches, and
  more.
• Document/Workspace Symbols: navigate classes and class members within a
  file or across the workspace.
• Go to Definition/Find References: for classes, class members, and
  same-routine labels/gotos.
• Hover: type and signature info, or macro expansion (.mac/.int only) on
  hover.
• Inlay Hints: inferred types, argument names, and parameter default
  values shown inline.

Installation

GitHub release

Prebuilt ascot binaries for Linux, macOS and Windows are attached to each
GitHub release.

On macOS, Gatekeeper refuses to run the unsigned binary once a browser download
has quarantined it. Homebrew avoids this; otherwise
download it with curl:

curl -L https://github.com/intersystems-community/ascot/releases/latest/download/ascot-cli-universal-apple-darwin.tar.gz | tar xz

or clear the flag on a browser download:

xattr -d com.apple.quarantine path/to/ascot

Homebrew (macOS and Linux)

From the
InterSystems Community tap:

brew trust intersystems-community/tap # if Homebrew 5.1.15 or later
brew install intersystems-community/tap/ascot

Rust (crates.io)

From crates.io/crates/ascot:

cargo install ascot

On Windows, building also needs the Visual Studio C++ build tools, which newer
rustup installers offer to set up; a build failing on link.exe or
kernel32.lib is missing them, see rustup’s
MSVC prerequisites.

TypeScript/JavaScript (npm)

From
npmjs.com/package/@intersystems-community/ascot:

npm install @intersystems-community/ascot

A library; it does not provide an ascot executable.

Usage

ascot help

Lists the commands, and ascot help <COMMAND> (or
ascot <COMMAND> --help) shows one’s options; the IRIS, style and diagnostics
ones are the settings described under Advanced Usage.

ascot as a CLI tool

ascot analyze [--root DIR] ...

Loads every .cls/.mac/.int/.inc file under each PATH into one
workspace and prints diagnostics for all of them. With --root, the workspace
is every file under DIR instead, so cross-file references resolve, and the
PATHs choose whose diagnostics are printed; one outside DIR is skipped with
a warning. Exits non-zero if any error or warning was found, or if a PATH
doesn’t exist.

--format lsp prints the LSP diagnostic records per file instead of text, as
the language server publishes and the MCP check tool returns them, and
--format sarif one SARIF 2.1.0 document for code scanning. The summary stays
on stderr and the exit code is the same.

ascot as an MCP server

ascot mcp

Starts the MCP server (stdio), exposing workspace analysis as tools an AI agent
calls on demand: create_workspace takes the settings, insert
each document’s text (or, with a shared file system, its
file:// uri). Any MCP client that can launch a stdio server works: the command
is ascot (or its full path) and the single argument is mcp.

Claude Code:

claude mcp add ascot -- ascot mcp

OpenAI Codex CLI:

codex mcp add ascot -- ascot mcp

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) and
Gemini CLI (~/.gemini/settings.json) share one shape:

{
  "mcpServers": {
    "ascot": { "command": "ascot", "args": ["mcp"] }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "ascot": { "type": "stdio", "command": "ascot", "args": ["mcp"] }
  }
}

The tools and their parameters are documented on
docs.rs.
To try them by hand, the MCP Inspector
lists them and calls them from a browser:

npx @modelcontextprotocol/inspector ascot mcp

ascot as an LSP server

ascot lsp

Starts the LSP server (stdio). Its flags are the settings as
defaults: the client overrides them with initializationOptions and changes
them with workspace/didChangeConfiguration. A new iris re-checks the open
documents without re-reading them; a setting that can’t be applied is reported
with window/showMessage and left as it was. With a
shared file system, the workspace roots are loaded from
disk at startup.

Claude Code plugins

This repository is a Claude Code plugin marketplace with two plugins, both
expecting ascot on PATH: ascot-mcp registers the MCP server above, and
ascot-lsp runs the LSP server and feeds its diagnostics back into the
conversation after every edit.

claude plugin marketplace add intersystems-community/ascot
claude plugin install ascot-mcp@ascot-plugins
claude plugin install ascot-lsp@ascot-plugins

Advanced Usage

Settings

Which IRIS to ask, the style to check and the diagnostics to report are the same
three settings everywhere; the ascot-lsp plugin asks for them when enabled.

Documents on IRIS

Classes, routines and include files outside the workspace are resolved against
IRIS; iris says which:

• --iris latest (default): the newest declaration-only snapshot of IRIS this
  ascot knows, downloaded once (4 MB) from this repository’s
  declarations release
  into ~/.ascot.
• --iris <release>: the snapshot of that IRIS release, the tag of its
  iris-community image; --iris irishealth-community:<release>:HSLIB that of
  IRIS for Health’s HS and Ens classes (7 MB), the namespace after the tag
  and %SYS when left out; latest serves as the tag there too.
• --iris http://user:password@host:port[/prefix] with --iris-namespace
  (default %SYS): a live connection to IRIS through the Atelier REST API.
• --iris path/to/declarations.d.json: a declaration file, a released one or
  one you built yourself. No REST
  requests, and no instance needed.
• --iris none: no environment, so every class, routine or include outside the
  workspace is an error.

Build Your Own Declaration Files

ascot declare saves what a live connection would be asked for, so CI and
machines without the instance can check against it:

ascot declare --iris http://user:password@localhost:8080/iris --iris-namespace USER path/to/declaration.d.json

Without the file argument it writes ~/.ascot/<host>-<port>-<namespace>.d.json.

Style

style is a JSON object (for --style, a file holding it) saying how code
should be written; only what’s set is checked, as a warning. For example, with

{ "command": { "form": "Long", "case": "Pascal" }, "allow_quit_for_return": false }

$ ascot analyze --style style.json R.mac
warning: R.mac:3:2-3 - Command keyword `s` should be written `Set` [S2839]
warning: R.mac:4:2-8 - Use `Return` to leave a method or procedure; `Quit` is for loops and `Try` blocks [S4151]

Every rule is described in https://github.com/intersystems-community/ascot/blob/main/STYLE.md.

Diagnostics Filter

diagnostics is VERB:TARGETS values, as a list or separated by spaces (-d,
long form --diagnostics, is also repeatable), choosing which codes are
reported and at what severity. VERB is off, on (the code’s own severity) or
a severity (error, warning, information, hint); TARGETS is a
comma-separated list of codes, severities (every code currently reported at
one), or all. Values apply in order, a later one overriding an earlier one:

ascot analyze -d off:A5579,A4043 src/            # drop two codes
ascot analyze -d off:hint,information src/       # errors and warnings only
ascot analyze -d off:all -d on:A7095,A6851 src/  # report only two
ascot analyze -d hint:A4471 src/                 # report one as a hint

The exit code follows what is reported, so a dropped or downgraded warning no
longer fails a build.

Shared file system

Neither server assumes it shares a file system with its client; --shared-fs
says it does. mcp‘s insert then reads a file:// uri given without src
from disk, a single file or a whole directory of .cls/.mac/.int/.inc
files, and inserting a directory again re-reads it and drops the files no longer
there. lsp then loads the workspace roots from disk at startup, so cross-file
references resolve before their files are opened, and its style may be a
file’s path.

Contributing

Please open an issue
before starting a pull request. See https://github.com/intersystems-community/ascot/blob/main/CONTRIBUTING.md for the
development workflow, https://github.com/intersystems-community/ascot/blob/main/GOVERNANCE.md for how the project is
run, and https://github.com/intersystems-community/ascot/blob/main/SECURITY.md for reporting vulnerabilities.

License

This software is provided AS-IS, with no implied warranties, support, or
conditions of any kind.

Licensed under either of Apache License, Version 2.0 or
MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in this work by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.