iris-agentic-dev -- Give Your AI a Live Connection to IRIS, Part 1: The Problem, the Tool, and Getting Started

Part 1 of a series. Part 2 covers the full tool catalog. Part 3 covers ObjectScript skills. Part 4 covers benchmarking and measuring what actually improves. The Problem Hiding in the Comments Thomas Mazur's post "Frogs, Chickens, AI, and VS Code" on VS Code productivity - Peacock, scoped workspace files, Copilot Agent mode - drew a sharper problem in the comments. Pietro Di Leo and Mike.W pointed out that when you work server-side in VS Code, the isfs:// workspace most production IRIS shops use, Copilot can only see the files open in your editor. It cannot index the virtual filesystem. On a mature IRIS application with thousands of classes, the AI works through a keyhole. John Murray pointed people at a project I've been building - iris-agentic-dev - and noted no Developer Community article existed for it yet. So here it is: why the problem exists, how the tool addresses it, and how to get it running in about five minutes. Why the AI Can't See Your Namespace When you open an isfs:// workspace, your IRIS classes live on the server, not on disk. The VS Code ObjectScript extension streams them to you on demand via the Atelier API - open a class, it fetches it; save it, it writes back. This works beautifully for editing. AI assistants such as Copilot work differently. They need a picture of the code around the file you're editing. Who calls this method? What inherits from this class? What other code touches this global? On a local project, the assistant can scan the files to answer those questions. An isfs:// workspace materializes files only when you open them, so there is nothing complete to scan. For a new project with a handful of classes, that may be tolerable. For a production IRIS system - ten thousand classes, Ensemble productions, custom %Library subclasses, business logic accumulated across years of development - the AI becomes nearly useless for the hard questions. It can help you write a new method if you paste in the surrounding context yourself. It cannot help you understand the system. Give the AI a different kind of connection, one that can ask IRIS directly instead of crawling the disk. What iris-agentic-dev Is iris-agentic-dev is an MCP server - a background process that gives AI assistants a set of tools they can call to interact with a live IRIS instance. It works with GitHub Copilot (via the VS Code extension), Claude Code, Cursor, and OpenCode. The IRIS instance can run natively on Windows or Linux, or in Docker. Once configured, the MCP server's tools are available directly from chat. VS Code 1.99 and later support MCP for Copilot Agent mode; Claude Code and OpenCode have supported it since launch. iris-agentic-dev connects to IRIS through the same Atelier REST API used by the ObjectScript extension. The assistant can then: - Search the entire namespace - full-text, regex, by category, without opening anything - Compile classes and get errors back with line numbers - Run ObjectScript and see the output - Execute SQL queries against any namespace - Introspect class definitions - properties, methods, parameters, inheritance chains - Inspect Ensemble productions - which items are running, what's wired to what, message bodies, business rule logic, and drift between the running config and source control - Run unit tests and report results - Debug - map INT line numbers back to original source lines, pull error logs Part 2 covers the complete tool catalog. Instead of guessing from a few open tabs, the assistant can ask IRIS about the namespace itself. --- Built With the Community I started the project after running into this limitation repeatedly in my own IRIS work. Community contributions have shaped it since - often from the same people who show up more than once. John Murray, who pointed people at this project in the Frogs and Chickens thread, also built the Server Manager authentication integration you'll use in Step 2 below: instead of typing credentials into a config file, the MCP server reads them straight from the OS keychain through the same AuthenticationProvider the Server Manager extension itself uses. Dorian TETU has contributed fixes across search accuracy, source control elicitation, and surgical-edit diffs. The project is open source under the intersystems-community GitHub organization. Contributions and bug reports are welcome, including "It doesn't work on my setup." Getting Started: VS Code + GitHub Copilot If you already use VS Code with the InterSystems ObjectScript extension, this is the fastest path. Prerequisites: VS Code, GitHub Copilot subscription, and the InterSystems ObjectScript extension (which you almost certainly already have). Step 1 - Install the VS Code extension Search for iris-agentic-dev in the VS Code Marketplace and install it. On first activation, the extension locates or downloads the MCP server binary: if you already have it on PATH (e.g. via brew install iris-agentic-dev ), it uses that; otherwise it downloads the right binary for your platform automatically. Either way, it registers itself with Copilot - no manual wiring required. The iris-agentic-dev tool set appears in Copilot's Agent mode after installation. Step 2 - Verify the connection Open Copilot Chat and switch to Agent mode. Ask: "Call check_config and show me the result." You should see your IRIS connection details - host, port, namespace, Atelier API version. If the InterSystems Server Manager extension is installed, iris-agentic-dev finds your server configuration and retrieves credentials from the OS keychain automatically. The VS Code extension follows the active objectscript.conn , so developers with several Server Manager entries keep using the connection selected for that workspace. When running the MCP server outside the VS Code extension, set IRIS_SERVER_NAME to the corresponding key from intersystems.servers if more than one server is configured. The check_config result shows which connection is active and which other servers were detected. check_config confirms the IRIS host, port, namespace, and connection source Copilot is using. Step 3 - Ask something that requires the whole namespace Now try a question that would be difficult to answer from open tabs alone: "Search for all classes in this namespace that extend %Persistent . How many are there?""What are the properties and methods on MyApp.SomeClass ?""Compile MyApp..cls and show me any errors." None of these requires you to open the relevant files first. The assistant gets the answers from IRIS. Getting Started: Claude Code Install the binary (Mac): brew tap intersystems-community/tap brew install iris-agentic-dev Or download directly from the releases page for Mac Intel, Linux, or Windows. Configure the connection. Create ~/.iris-agentic-dev.toml : host = "localhost" web_port = 52773 username = "_SYSTEM" password = "SYS" namespace = "USER" Register with Claude Code: claude mcp add --scope user iris-agentic-dev -- iris-agentic-dev mcp Then verify: > Call check_config and show me the result. Example: How iris-agentic-dev tools support analyzing an IRIS Interoperability application Here is a real exchange against the irisdemo-demo-readmission production - a health interop demo that processes hospital discharge events and scores patients for readmission risk. "How does an ADT A03 discharge message flow through this production?" Step 1: find what's compiled. iris_symbols("IRISDemo.") → 31 classes: BO., BP., BS., DTL., Util.*, and more Key classes: IRISDemo.BP.ReadmissionRisk.Process , IRISDemo.DTL.HL7Discharge , IRISDemo.DTL.HL7Update , IRISDemo.HISHL7v2FileFeedRoutingRule . Step 2: find the router's rule. extract_message_map_routing("IRISDemo.HISHL7v2FileFeedRoutingRule") → NOT_FOUND - Ens.Rule.Definition, not a routing table class Ens.Rule.Definition classes hold routing logic in XData. The tool can't map that structure, so read the class source directly: iris_doc("IRISDemo.HISHL7v2FileFeedRoutingRule.cls") → XData rules: Rule 1: docName=ADT_A01 or ADT_A08 → transform DTL.HL7Update, target Readmission Risk Process Rule 2: docName=ADT_A03 → transform DTL.HL7Update, target Readmission Risk Process A03 discharges go through IRISDemo.DTL.HL7Update , which stamps UpdateMessageType="A03" on the request - that field is what lets the business process branch differently for discharges vs. admits. Step 3: map the business process. extract_message_map_routing("IRISDemo.BP.ReadmissionRisk.Process") → kind: bpl, 4 outbound calls: Update Encounter → LACE SOAP Operation Calculate Risk with LACE → LACE SOAP Operation Calculate Risk with ML → Readmission ML Model Consumer EMR Readmission Update → HisDB Encounter Update Operation Step 4: get the full step tree. docs_introspect("IRISDemo.BP.ReadmissionRisk.Process") → xdata_flow: Call: Update Encounter → LACE SOAP Operation Call: Calculate Risk with LACE → LACE SOAP Operation Call: Calculate Risk with ML → Readmission ML Model Consumer Call: EMR Readmission Update → HisDB Encounter Update Operation [async] If: Discharge OK? (request.UpdateMessageType = "A03") && (context.UpdateEncounterResult = 1) If: Risk Alert? (context.RiskScore > 11) || (context.MLReadmissionRisk > 0.15) assign: Compose Alert Message Call: Add Patient to Risk Program → Care Team [async] Call: Alert Care Team → Risk Alert Email Operation sync: Follow up SLA 2 days If: No follow up? (synctimedout) The session also flagged that IRISDemo.DTL.HL7Discharge exists and maps 9 HL7 fields to a DischargeRequest - but the routing rule never sends A03 through it. Dead code, spotted without opening a file. The full exchange - every tool call, response, and reasoning step - is in this GitHub Gist. In four steps the assistant answered the question: A03 discharges hit the router, get transformed into an UpdateEncounterRequest with the trigger event stamped as the branch signal, and the business process runs LACE and ML risk scoring in sequence - alerting the care team and starting a 2-day follow-up if either score exceeds the threshold