{"name":"ek9_add_application","url":"https://ek9.io/mcp/ek9_add_application.html","category":"editor","description":"Appends the application to the file's 'defines application' block (created if absent), one 'register Component() as Interface' line per registration; answers status, edits[] and summary, with a would-fail carrying the compiler's own diagnostics.","whenToUse":"'Add a DI application DemoApp wiring V8 as Engine' is one call with file, name and registrations:[{component, as}] - no line needed. The same construct is production wiring (DemoApp) and test substitution (TestApp); there is no mocking framework.","whenNotToUse":["Defining the COMPONENT itself (the concrete or abstract base) - use ek9_new_construct mode:'component'; applications register components, they do not define them.","Authoring the program or @Test that binds via 'with application of <App>' - use ek9_add_program (isTest:true, application:'TestApp' for tests); author the application here first."],"details":"Registrations (>=1 required — a bare shell does not compile) take two forms: supply 'as' for 'register Component() as Interface' (bind concrete to trait/component interface), or omit 'as' for a bare 'register Component()' (service-genus / HTTP-routing targets); optional 'aspects' list renders 'with aspect of A(), B()' for AOP (a bare 'A' becomes 'A()', a constructor call like 'A(\"audit\")' is kept; 'as' is required with it), and components may be fully-qualified. Multiple applications share one 'defines application' block — the tool appends under an existing block or creates one. A duplicate application name in the SAME module (different modules are fine) or one interface bound twice in one app (E08230 DI_DUPLICATE_REGISTRATION) surfaces as would-fail from the dry-run gate.","arguments":[{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 module file the application is appended to (the 'defines application' block is created if absent)."},{"name":"name","type":"string","required":true,"description":"Application name (PascalCase), e.g. 'DemoApp'."},{"name":"registrations","type":"array of object","required":false,"description":"DI registrations (>=1): [{component, as?, aspects?}]. Two forms: omit 'as' for a bare 'register Component()' (inject the concrete type), or supply 'as' for 'register Component() as Interface' (inject via the interface); 'aspects' (needs 'as') add 'with aspect of A()[, B()]' for AOP."}],"lessons":["https://ek9.io/ide/depth-di-notifiers.html","https://ek9.io/ide/depth-guess-seam.html","https://ek9.io/ide/depth-aspect-order.html","https://ek9.io/ide/depth-price-book.html","https://ek9.io/ide/depth-aspect-exception.html","https://ek9.io/ide/depth-call-counter.html","https://ek9.io/ide/depth-serve-and-call.html","https://ek9.io/ide/depth-hello-notes.html","https://ek9.io/ide/depth-route-order.html","https://ek9.io/ide/depth-late-status.html","https://ek9.io/ide/depth-shop-tests.html","https://ek9.io/ide/application-and-di.html","https://ek9.io/ide/aspects.html","https://ek9.io/ide/web-services.html"],"fixes":[],"example":{"scenario":"Application aspect without interface rejected","request":{"dryRun":true,"file":"main.ek9","name":"AspectApp","registrations":[{"aspects":["SilentAspect()"],"component":"V8"}]},"response":{"conflicts":[],"edits":[],"error":{"message":"registration of 'V8' names an aspect but no 'as' interface - 'with aspect of' follows 'register X() as Interface', so give 'as' too"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"registration of 'V8' names an aspect but no 'as' interface - 'with aspect of' follows 'register X() as Interface', so give 'as' too","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_add_capability","url":"https://ek9.io/mcp/ek9_add_capability.html","category":"editor","description":"Answers with the edit that declares one gated-type capability in the 'capabilities <- [...]' List of a 'defines package' block, plus the resolved capability name.","whenToUse":"'Declare that this package may use Stdout' is one call with file:'package.ek9' and capability:'Stdout'. The full 'org.ek9.lang::Stdout' is accepted too; this is the fix for E12010 UNDECLARED_CAPABILITY on a publishable package.","whenNotToUse":["Adding an external LIBRARY dependency (a library, not a permission) - use ek9_add_dependency.","Revoking a capability - use ek9_remove_capability.","The 'defines package' block does not exist yet - ek9_new_construct with mode:'package' first."],"details":"capability is a gated type: the bare name ('TCP', 'Stdout', 'File') resolves to org.ek9.lang::<Name> and an associated type resolves to the capability that covers it (TCPConnection -> org.ek9.lang::TCP); the response's capability key is the spelling written. A bare name that is not a gated type is error 'unknown-capability' listing the pickable set; a missing package block is 'package-block-not-found'. The List is created in compact single-line form when absent - never as an empty '[]', which the grammar rejects. Enforcement (E12010, PRE_IR_CHECKS) applies only when publicAccess, version, license and capabilities are ALL declared; the dry run validates the identifier, it does not compile.","arguments":[{"name":"capability","type":"string","required":true,"description":"The gated type to permit: a bare name such as 'TCP' or 'Stdout' (resolved to org.ek9.lang::<Name>) or the fully-qualified 'org.ek9.lang::TCP'. A primary capability covers its group (TCP covers TCPConnection/TCPHandler/NetworkProperties), so the related types need no entry of their own."},{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."}],"lessons":["https://ek9.io/ide/depth-capability-greeter.html","https://ek9.io/ide/capabilities.html","https://ek9.io/ide/networking.html"],"fixes":[],"example":{"scenario":"Add capability multi line","request":{"capability":"org.ek9.lang::TCP","file":"package.ek9"},"response":{"capability":"org.ek9.lang::TCP","conflicts":[],"edits":[{"after":"      \"org.ek9.lang::TCP\",","endLine":10,"file":"package.ek9","startLine":10,"type":"insert"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Added capability org.ek9.lang::TCP","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_add_constructor","url":"https://ek9.io/mcp/ek9_add_constructor.html","category":"editor","description":"Inserts one constructor at the construct's canonical member position; answers status, edits[] and summary, a same-shape constructor as conflicts[] (constructor-already-exists, with its line).","whenToUse":"'Add a constructor to Order' is one call with symbol:'Order' and mode:'no-arg' | 'all-fields' | 'fields' (+ fields:[...]) - no file or line needed.","whenNotToUse":["Adding a regular METHOD or an operator like == / <=> - use ek9_add_method / ek9_add_operator.","Implementing trait methods on a class - use ek9_implement_methods.","The TYPE doesn't exist yet - create it with ek9_new_construct first, constructors second.","Target must be a class, record, or component - functions, traits, services, and enumerations have no constructors."],"details":"Modes: no-arg (emits a bodyless 'default' constructor; visibility default private, honours pure), all-fields (honours pure), fields (requires non-empty fields[]; purity auto-detected - greenfield defaults pure). In the field modes purity is auto-forced when any existing constructor is pure (mixed purity won't compile); assignment is ':' non-pure, ':=?' when pure (never the copy operator ':=:'). A duplicate parameter shape returns status:'conflicts' kind 'constructor-already-exists' naming the existing constructor's line and the insert_statements / change_signature / safe_delete routes (nothing written); a pure constructor over a field DECLARED with a value returns status:'error' (E08095) - declare those fields unset (String()/Integer()) or request non-pure.","arguments":[{"name":"fields","type":"array of string","required":false,"description":"fields mode - names of the fields to take as constructor parameters, in order."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"mode","type":"string: no-arg | all-fields | fields","required":false,"description":"no-arg: a bodyless 'default' constructor blocking default construction; all-fields: every field as a parameter; fields: the named subset (inferred when fields[] is given)."},{"name":"pure","type":"boolean","required":false,"description":"Add 'as pure'. Default false."},{"name":"symbol","type":"string","required":true,"description":"The class, record or component the constructor is added to - a bare name ('Order') finds its file workspace-wide; 'mod::Order' when the name is declared in two modules."},{"name":"visibility","type":"string: public | private | protected","required":false,"description":"no-arg only - the constructor's access. Default 'private' (the typical force-a-factory use)."}],"lessons":["https://ek9.io/ide/adding-members.html","https://ek9.io/ide/book-records.html","https://ek9.io/ide/book-scoreboard.html","https://ek9.io/ide/book-account.html","https://ek9.io/ide/book-polymorphism.html","https://ek9.io/ide/book-contacts.html","https://ek9.io/ide/book-traits.html","https://ek9.io/ide/book-operators.html","https://ek9.io/ide/book-versions.html","https://ek9.io/ide/book-promotion.html","https://ek9.io/ide/book-game.html","https://ek9.io/ide/depth-operator-split.html","https://ek9.io/ide/depth-shallow-copy.html","https://ek9.io/ide/depth-order-pipelines.html","https://ek9.io/ide/depth-json-sink.html","https://ek9.io/ide/depth-super-call.html","https://ek9.io/ide/depth-priced-ledger.html","https://ek9.io/ide/depth-shelf.html","https://ek9.io/ide/depth-constrained-record.html","https://ek9.io/ide/depth-inventory.html","https://ek9.io/ide/depth-payment-exceptions.html","https://ek9.io/ide/depth-resource-order.html","https://ek9.io/ide/depth-session-close.html","https://ek9.io/ide/depth-suppressed-close.html","https://ek9.io/ide/depth-json-documents.html","https://ek9.io/ide/depth-substitution.html"],"fixes":[],"example":{"scenario":"Default no arg apply","request":{"constructName":"Greeter","file":"Greeter.ek9","mode":"default-no-arg"},"response":{"conflicts":[],"edits":[{"after":"\n      default private Greeter()","endLine":7,"file":"Greeter.ek9","startLine":7,"type":"insert"}],"meta":{"serverMs":"<timing>"},"resolvedPath":"<workspace-root>/Greeter.ek9","risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Added default private no-arg constructor to Greeter","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_add_dependency","url":"https://ek9.io/mcp/ek9_add_dependency.html","category":"editor","description":"Answers with the edit that appends one runtime or dev dependency to the deps/devDeps Dict of a 'defines package' block - source only, nothing is fetched.","whenToUse":"'Add a dependency on ek9open.net.handy.tools 3.2.1-0' is one call with file:'package.ek9', bucket:'deps', module:'ek9open.net.handy.tools', version:'3.2.1-0'. Use bucket:'devDeps' for a test-only dependency.","whenNotToUse":["Removing a dependency - use ek9_remove_dependency.","Blocking a TRANSITIVE dependency that a parent pulls in - use ek9_exclude_transitive_dependency.","Declaring a security capability (a permission, not a library) - use ek9_add_capability.","Fetching the declared dependencies afterwards - ek9_resolve_dependencies (this tool edits the source only).","The 'defines package' block does not exist yet - ek9_new_construct with mode:'package' first."],"details":"bucket selects deps or devDeps and the Dict is created when absent; only the multi-line Dict form is edited (a single-line bucket is error 'single-line-bucket-unsupported'). conflicts[].kind: 'dependency-already-pinned' (same module, same version - a no-op) or 'version-conflict' (same module, different version - ask the human). A file with no 'defines package' block is error 'package-block-not-found'; a version that is not major.minor.patch-build adds an advisories[] 'non-standard-version-format' but is written. A dependency not installed in the library yet is the normal first step: the edit is applied (the compiler's E06263 on the line added is expected, and no other new error is) and advisories[] 'dependency-not-installed' names the next step - install the package by hand, then ek9_resolve_dependencies.","arguments":[{"name":"bucket","type":"string: deps | devDeps","required":true,"description":"Which Dict to extend: 'deps' (runtime, deployed) or 'devDeps' (dev/test only, not deployed)."},{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"module","type":"string","required":true,"description":"The dependency's module name, e.g. 'ek9open.network.support.utils' - the Dict key."},{"name":"version","type":"string","required":true,"description":"The version to pin, e.g. '1.6.1-9' (major.minor.patch-build; a feature-tagged major.minor.patch-feature-build is also accepted) - the Dict value."}],"lessons":["https://ek9.io/ide/package-block.html"],"fixes":[],"example":{"scenario":"Add dependency missing version","request":{"bucket":"deps","file":"package.ek9","module":"ek9open.new.shiny.lib"},"response":{"error":{"kind":"missing-argument","message":"Missing required parameter: version"},"meta":{"serverMs":"<timing>"},"nextStep":"re-call with version:'1.6.1-9'","status":"error","summary":"Missing required parameter: version"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_add_field","url":"https://ek9.io/mcp/ek9_add_field.html","category":"editor","description":"Inserts the field declaration at the construct's canonical field position; answers status, edits[] and summary, a clashing name as conflicts[] (name-collision).","whenToUse":"'Add a field to CustomerOrder' is one call with symbol:'CustomerOrder', fieldName and defaultValue (or rawDeclaration:'logger as Logger!') - no file or line.","whenNotToUse":["Adding a METHOD or CONSTRUCTOR, not a field - use ek9_add_method / ek9_add_constructor.","The target construct doesn't exist yet - create it with ek9_new_construct first.","Renaming or removing an existing field - use ek9_rename_field / ek9_remove_field.","Traits, functions, services, applications, programs, text - these grammatically have no fields; the tool returns a target-construct-is-not-fielded conflict."],"details":"Two forms: structured (fieldName + defaultValue; defaultValue REQUIRED for records) or raw (rawDeclaration as typed, e.g. `name as String?` or `logger as Logger!`); mode is inferred from which is given and a contradicting mode is a conflict. Visibility is genus-fixed: class/component fields are always private, record fields always public - no access-modifier syntax exists. A pre-existing field name is a name-collision conflict (structured) or hard error (raw); an UNINITIALISED field can trip E07175/E07170 (public no-arg ctor would build a partial object) → would-fail - fix with an initialiser, a private no-arg ctor, or an explicit ctor.","arguments":[{"name":"defaultValue","type":"string","required":false,"description":"Default value expression for the field, e.g. '0', '\"\"', 'String()'. Required for records in the structured form."},{"name":"fieldName","type":"string","required":false,"description":"The new field's name (structured form) - with 'type' or 'defaultValue'; a name alone renders a typeless field (E07110)."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"mode","type":"string: structured | raw","required":false,"description":"Optional - inferred: rawDeclaration → raw, fieldName → structured."},{"name":"rawDeclaration","type":"string","required":false,"description":"The whole declaration line as you would type it (raw form), e.g. 'name as String?' or 'logger as Logger!' (DI)."},{"name":"symbol","type":"string","required":true,"description":"The class, record or component the field is added to - a bare name ('Order') finds its file workspace-wide; 'mod::Order' when the name is declared in two modules."},{"name":"type","type":"string","required":false,"description":"The field's type in the structured form, e.g. 'Float', 'List of String' - rendered 'name as Type: Type()' (present, unset until assigned) unless defaultValue is given."},{"name":"withConstructor","type":"boolean","required":false,"description":"Insert a NEW pure constructor taking this field, in the SAME change - the fields-mode rendering ek9_add_constructor mode:'fields' uses. Only applies when the field is left with no value ('name as Type?' / rawDeclaration ending '?', or the structured form with 'type' and no 'defaultValue') - that is the one shape a publicly-constructible class can leave uninitialised (E07170/E08070/E08060) until a second ek9_add_constructor call lands one; any other form already has what it needs and the option is a no-op. Default false."}],"lessons":["https://ek9.io/ide/adding-members.html","https://ek9.io/ide/book-two-ways.html","https://ek9.io/ide/book-classes.html","https://ek9.io/ide/book-scoreboard.html","https://ek9.io/ide/book-account.html","https://ek9.io/ide/book-polymorphism.html","https://ek9.io/ide/book-traits.html","https://ek9.io/ide/book-game.html","https://ek9.io/ide/depth-super-call.html","https://ek9.io/ide/depth-priced-ledger.html","https://ek9.io/ide/depth-shelf.html","https://ek9.io/ide/depth-payment-exceptions.html","https://ek9.io/ide/depth-resource-order.html","https://ek9.io/ide/depth-session-close.html","https://ek9.io/ide/depth-suppressed-close.html","https://ek9.io/ide/depth-shared-tally.html","https://ek9.io/ide/depth-lost-result.html","https://ek9.io/ide/depth-consistent-order.html","https://ek9.io/ide/depth-lock-order-fixed.html","https://ek9.io/ide/depth-check-then-act.html","https://ek9.io/ide/depth-di-notifiers.html","https://ek9.io/ide/depth-guess-seam.html","https://ek9.io/ide/depth-aspect-order.html","https://ek9.io/ide/depth-price-book.html","https://ek9.io/ide/depth-call-counter.html","https://ek9.io/ide/depth-sync-key.html","https://ek9.io/ide/depth-late-status.html","https://ek9.io/ide/depth-substitution.html"],"fixes":["E05030"],"example":{"scenario":"Add structured field dry run ready","request":{"constructName":"Greeter","defaultValue":"0","dryRun":true,"fieldName":"cachedCount","file":"Greeter.ek9","mode":"structured"},"response":{"conflicts":[],"edits":[{"after":"      cachedCount <- 0","endLine":7,"file":"Greeter.ek9","startLine":7,"type":"insert"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"ready","summary":"Added field 'cachedCount' to Greeter","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_add_method","url":"https://ek9.io/mcp/ek9_add_method.html","category":"editor","description":"Inserts the method (signature, a require-guarded stub body and the return) at the construct's canonical member position; answers status, edits[] and summary, a same-signature method as conflicts[] (signature-collision). Records reject named methods.","whenToUse":"'Add a method to CustomerOrder' is one call with symbol:'CustomerOrder', name, parameters:['code as Integer'], returnType and statements:['rtn: ...'] (the body) - no file, no line, nothing left to fill.","whenNotToUse":["The member is an OPERATOR (==, <=>, ?, $, …) - use ek9_add_operator; a CONSTRUCTOR (the type's own name) - use ek9_add_constructor.","You want ALL trait methods added at once — use ek9_implement_methods (batch).","You want a FIELD, not a method — use ek9_add_field.","The target construct does not exist yet — create it with ek9_new_construct first."],"details":"Inserts exactly ONE method per call; a same-signature second call yields status:conflicts (kind 'signature-collision' — rename, change the parameter shape, or add override:true if overriding an inherited method). status:error when the target genus rejects methods (record/program/text/enumeration …) or isAbstract targets a non-abstract class/component. No override-inheritance analysis is performed — a bad override surfaces only on the apply-path verify compile as would-fail.","arguments":[{"name":"emptyBody","type":"boolean","required":false,"description":"When true, generate ONLY the signature (declaration + parameters + return-with-default) with no placeholder body - no 'require param?' preconditions, no '//AI' lead, for a body you then supply with ek9_insert_statements. NOTE: EK9 flags unused parameters, so a shell WITH parameters will would-fail on apply until a body uses them; only the no-parameter-with-return shape compiles standalone."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"isAbstract","type":"boolean","required":false,"description":"Add 'as abstract'. Only valid on traits and classes already marked 'as abstract'."},{"name":"name","type":"string","required":true,"description":"The new method's name (camelCase)."},{"name":"override","type":"boolean","required":false,"description":"Add 'override' prefix when overriding a parent or trait method."},{"name":"parameters","type":"array of any","required":false,"description":"Parameter list, each ONE item as DATA - {name:'code', type:'Integer'} - never a {name} and a {type} as two items, and never with '->' or '<-' in it; the tool writes the arrows and the layout. ('code as Integer' is also accepted.) A malformed item is rejected before anything is rendered. Empty / omitted means a no-arg method."},{"name":"pure","type":"boolean","required":false,"description":"Add 'as pure' modifier. Default false."},{"name":"returnType","type":"string","required":false,"description":"Return TYPE only, e.g. 'String', 'List of Integer' - never '<- rtn as String', never a name: the tool writes the '<- rtn as <Type>?' declaration, and the body assigns 'rtn: <expr>'. Omitted means no return."},{"name":"statements","type":"array of string","required":false,"description":"The body, one statement or one block per entry (assign 'rtn: <value>' on every path when there is a return): the method is complete in this call - no stub, no second ek9_insert_statements call. Parsed alone first; a problem names the entry and its fix."},{"name":"symbol","type":"string","required":true,"description":"The class, trait, component or service the method is added to - a bare name ('Order') finds its file workspace-wide; 'mod::Order' when the name is declared in two modules."},{"name":"visibility","type":"string: public | private | protected","required":false,"description":"The method's access. Default public."}],"lessons":["https://ek9.io/ide/adding-members.html","https://ek9.io/ide/own-generics.html","https://ek9.io/ide/book-two-ways.html","https://ek9.io/ide/book-classes.html","https://ek9.io/ide/book-scoreboard.html","https://ek9.io/ide/book-account.html","https://ek9.io/ide/book-polymorphism.html","https://ek9.io/ide/book-animals.html","https://ek9.io/ide/book-traits.html","https://ek9.io/ide/book-trait-clash.html","https://ek9.io/ide/book-allow-only.html","https://ek9.io/ide/book-components.html","https://ek9.io/ide/book-game.html","https://ek9.io/ide/depth-super-call.html","https://ek9.io/ide/depth-lru-cache.html","https://ek9.io/ide/depth-priced-ledger.html","https://ek9.io/ide/depth-shelf.html","https://ek9.io/ide/depth-payment-exceptions.html","https://ek9.io/ide/depth-session-close.html","https://ek9.io/ide/depth-suppressed-close.html","https://ek9.io/ide/depth-shared-tally.html","https://ek9.io/ide/depth-lost-result.html","https://ek9.io/ide/depth-consistent-order.html","https://ek9.io/ide/depth-lock-order-fixed.html","https://ek9.io/ide/depth-check-then-act.html","https://ek9.io/ide/depth-di-notifiers.html","https://ek9.io/ide/depth-guess-seam.html","https://ek9.io/ide/depth-aspect-order.html","https://ek9.io/ide/depth-price-book.html","https://ek9.io/ide/depth-aspect-exception.html","https://ek9.io/ide/depth-call-counter.html","https://ek9.io/ide/depth-sync-key.html","https://ek9.io/ide/depth-late-status.html","https://ek9.io/ide/depth-substitution.html","https://ek9.io/ide/application-and-di.html","https://ek9.io/ide/aspects.html"],"fixes":["E05260"],"example":{"scenario":"One of two trait members is progress","request":{"name":"area","override":true,"pure":true,"returnType":"Float","statements":["rtn: side * side"],"symbol":"Square"},"response":{"conflicts":[],"edits":[{"after":"\n      override area() as pure\n        <- rtn as Float?\n        rtn: side * side","endLine":23,"file":"task.ek9","startLine":23,"type":"insert"}],"meta":{"serverMs":"<timing>"},"resolvedPath":"<workspace-root>/task.ek9","risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Added method 'area' to Square","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_add_operator","url":"https://ek9.io/mcp/ek9_add_operator.html","category":"editor","description":"Inserts the operator declaration (or the bare 'default operator' block) at the construct's canonical operator position; answers status, edits[] and summary - 'unchanged', naming where it is, for a default operator the construct already declares; statements[] for an operator already written by hand replace its body, and body:'explicit' over one names the insert route in conflicts[].","whenToUse":"'Add operator $ to Point' is one call with symbol:'Point', operator:'$' and statements:['rtn: ...'] (its body); body:'default' synthesises a defaultable one (==, <=>, ?).","whenNotToUse":["The member is a regular METHOD with an ordinary identifier name - use ek9_add_method; a CONSTRUCTOR (the type's own name) - use ek9_add_constructor.","You want to CHECK whether an existing operator is contract-compliant - the compiler already reports it; use ek9_query_diagnostics / ek9_explain_error. (A NEW operator's purity is derived here, so E07500/E07510 cannot reach you from this tool.)","You want to implement TRAIT methods in bulk - use ek9_implement_methods.","The target type does not exist yet - use ek9_new_construct."],"details":"body:'default' with an operator emits 'default operator <sym>' for that one op; with no operator it emits the bare 'default operator' (compiler synthesises every missing defaultable op; errors if a default block already exists). body:'explicit' generates a field-based implementation stub you fill in (templates for the defaultable set plus the arithmetic/word-form ops; needs at least one field) and is the only form also allowed on traits. The operator is given in EK9 source form ('==' not '_eq'); pipeline keywords (sort, filter, …) are rejected and the deprecated '!=' is applied as '<>' (E07640) with the summary saying so. A duplicate operator symbol returns status:'conflicts' (kind 'signature-collision') naming the ek9_expand_default_operator route - operator semantics are load-bearing; surface to the human rather than retry (pre-check via ek9_query_construct → operators[]).","arguments":[{"name":"body","type":"string: default | explicit","required":false,"description":"default (the default): a 'default operator' declaration the compiler synthesises from the fields; explicit: a field-based stub for you to complete."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"operator","type":"string","required":false,"description":"The operator in EK9 source form: '==', '<=>', '<>', '?', '$', '#?', ':=:', '+', 'mod', … Omit it with body:'default' to default every defaultable operator at once."},{"name":"pure","type":"boolean","required":false,"description":"IGNORED for a known operator and not worth sending - purity is not a choice. The language fixes it: every non-mutating operator must be 'as pure' (E07500) and the ten mutators ':~: :^: :=: | += -= *= /= ++ --' must not be (E07510). It is derived and the response says so in 'corrected' when your value differed."},{"name":"statements","type":"array of string","required":false,"description":"The operator's body, one statement or one block per entry (assign 'rtn: <value>' on every path): the operator is complete in this call - override, pure and the language-fixed signature are filled in. Needs 'operator'; 'body' is then ignored. For an operator the construct already implements by hand, its body is REPLACED (the signature stays)."},{"name":"symbol","type":"string","required":true,"description":"The class, record, component, enumeration (or trait, for an explicit body) the operator is added to - a bare name ('Point') finds its file workspace-wide; 'mod::Point' when the name is declared in two modules."}],"lessons":["https://ek9.io/ide/adding-members.html","https://ek9.io/ide/book-two-ways.html","https://ek9.io/ide/book-records.html","https://ek9.io/ide/book-scoreboard.html","https://ek9.io/ide/book-contacts.html","https://ek9.io/ide/book-animals.html","https://ek9.io/ide/book-traits.html","https://ek9.io/ide/book-allow-only.html","https://ek9.io/ide/book-operators.html","https://ek9.io/ide/book-versions.html","https://ek9.io/ide/book-promotion.html","https://ek9.io/ide/book-game.html","https://ek9.io/ide/depth-operator-split.html","https://ek9.io/ide/depth-copy-merge-replace.html","https://ek9.io/ide/depth-shallow-copy.html","https://ek9.io/ide/depth-order-pipelines.html","https://ek9.io/ide/depth-json-sink.html","https://ek9.io/ide/depth-constrained-record.html","https://ek9.io/ide/depth-payment-exceptions.html","https://ek9.io/ide/depth-narrow-catch.html","https://ek9.io/ide/depth-resource-order.html","https://ek9.io/ide/depth-session-close.html","https://ek9.io/ide/depth-suppressed-close.html","https://ek9.io/ide/depth-shared-tally.html","https://ek9.io/ide/depth-lock-order-fixed.html","https://ek9.io/ide/depth-price-book.html","https://ek9.io/ide/depth-aspect-exception.html","https://ek9.io/ide/depth-json-documents.html","https://ek9.io/ide/depth-substitution.html"],"fixes":[],"example":{"scenario":"Add default equality apply","request":{"body":"default","constructName":"Point","file":"Point.ek9","operator":"=="},"response":{"conflicts":[],"edits":[],"error":{"message":"'==' on Point is generated from its '<=>' (E07181). If '==' should compare more, add those fields to '<=>' as tie-breakers."},"meta":{"serverMs":"<timing>"},"status":"error","summary":"'==' on Point is generated from its '<=>' (E07181). If '==' should compare more, add those fields to '<=>' as tie-breakers.","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_add_program","url":"https://ek9.io/mcp/ek9_add_program.html","category":"editor","description":"Appends the program (or @Test program) to the file's 'defines program' block, created if absent, with a stub body that references every parameter and injection; answers status, edits[] and summary.","whenToUse":"'Add a program Main that prints X' is one call with file, name and statements:['stdout <- Stdout()', 'stdout.println(...)'] - the body included, nothing left to fill; isTest:true makes it a @Test program.","whenNotToUse":["Authoring any OTHER top-level construct (class/record/trait/function/component/type/constant/service) - use ek9_new_construct.","Authoring the DI application a program binds to via 'application' - use ek9_add_application first, then reference it here by name.","Anchoring a @Test program that ALREADY exists to a requirement - use ek9_anchor_test (requirementId here is for a freshly-scaffolded test)."],"details":"parameters[].type must be one of the 18 whitelisted CLI arg types (String/Integer/Float/Boolean/Character/Bits/Date/Time/DateTime/Duration/Millisecond/Money/Colour/Resolution/Dimension/RegEx/GUID/List of String) — an invalid type (E07600), a typed primitive mixed with 'List of String' (E07610), or a program name already taken in the module all surface as would-fail from the dry-run gate. Programs may return only Integer (process exit code — E07590).","arguments":[{"name":"application","type":"string","required":false,"description":"Application to bind for DI — renders 'with application of <App>'. The application must resolve (define it with ek9_add_application first)."},{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 module file the program is appended to (the 'defines program' block is created if absent). For isTest:true this must be a dev source (dev/ subdirectory or QA####_dev_ file)."},{"name":"injections","type":"array of any","required":false,"description":"Components pulled from the application by injection, each ONE item as DATA - {name:'code', type:'Integer'} - never a {name} and a {type} as two items, and never with '->' or '<-' in it; the tool writes the arrows and the layout. ('code as Integer' is also accepted.) A malformed item is rejected before anything is rendered. ('logger as Logger' or 'logger as Logger!' both render 'logger as Logger!'). Each is referenced in the stub (an unused injection is E11018)."},{"name":"isTest","type":"boolean","required":false,"description":"When true, prepend the @Test directive and emit an assert-based stub. Only legal in a dev source (E81015)."},{"name":"name","type":"string","required":true,"description":"Program name (PascalCase), e.g. 'ShowInjection' or 'GreetingTest'."},{"name":"parameters","type":"array of any","required":false,"description":"Typed CLI argument parameters, each ONE item as DATA - {name:'code', type:'Integer'} - never a {name} and a {type} as two items, and never with '->' or '<-' in it; the tool writes the arrows and the layout. ('code as Integer' is also accepted.) A malformed item is rejected before anything is rendered. Each is referenced in the stub so it compiles (an unused arg is E08091)."},{"name":"requirementId","type":"string","required":false,"description":"Requirement id this test anchors, e.g. 'REQ:velocity-limit' - renders '@Test: \"REQ:velocity-limit\"'. Requires isTest:true; supplying it for a non-test program is rejected rather than ignored. The requirement need not exist yet (writing the test first is legitimate); ek9_check_requirements reports an id that names nothing as a dangling anchor."},{"name":"statements","type":"array of string","required":false,"description":"The program's body, one statement or one block per entry ('stdout <- Stdout()', 'stdout.println(...)'): the program is complete in this call - no stub, no ek9_insert_statements after it. Parsed alone first; a problem names the entry and its fix."}],"lessons":["https://ek9.io/ide/own-generics.html","https://ek9.io/ide/book-greeting.html","https://ek9.io/ide/book-values.html","https://ek9.io/ide/book-escapes.html","https://ek9.io/ide/book-mutation.html","https://ek9.io/ide/book-declarations.html","https://ek9.io/ide/book-weather.html","https://ek9.io/ide/book-switch.html","https://ek9.io/ide/book-grade.html","https://ek9.io/ide/book-counting.html","https://ek9.io/ide/book-countup.html","https://ek9.io/ide/book-functions-demo.html","https://ek9.io/ide/book-describe.html","https://ek9.io/ide/book-functions.html","https://ek9.io/ide/book-halve.html","https://ek9.io/ide/book-halve-nothing.html","https://ek9.io/ide/book-testing.html","https://ek9.io/ide/book-receipt.html","https://ek9.io/ide/book-deadline.html","https://ek9.io/ide/book-data-types.html","https://ek9.io/ide/book-constants.html","https://ek9.io/ide/book-constant-copy.html","https://ek9.io/ide/book-greetings.html","https://ek9.io/ide/book-greet.html","https://ek9.io/ide/book-env-greet.html","https://ek9.io/ide/book-order.html","https://ek9.io/ide/book-localisation.html","https://ek9.io/ide/book-collections.html","https://ek9.io/ide/book-list-and-dict.html","https://ek9.io/ide/book-inference.html","https://ek9.io/ide/book-integer-promotion.html","https://ek9.io/ide/book-json-taste.html","https://ek9.io/ide/book-guards.html","https://ek9.io/ide/book-defaulting.html","https://ek9.io/ide/book-safe-min-max.html","https://ek9.io/ide/book-for-expression.html","https://ek9.io/ide/book-phone.html","https://ek9.io/ide/book-optional-result.html","https://ek9.io/ide/book-streams.html","https://ek9.io/ide/book-shop.html","https://ek9.io/ide/book-two-ways.html","https://ek9.io/ide/book-records.html","https://ek9.io/ide/book-enumerations.html","https://ek9.io/ide/book-day-operators.html","https://ek9.io/ide/book-rules.html","https://ek9.io/ide/book-constrained.html","https://ek9.io/ide/book-promote.html","https://ek9.io/ide/book-increment.html","https://ek9.io/ide/book-classes.html","https://ek9.io/ide/book-scoreboard.html","https://ek9.io/ide/book-account.html","https://ek9.io/ide/book-polymorphism.html","https://ek9.io/ide/book-contacts.html","https://ek9.io/ide/book-animals.html","https://ek9.io/ide/book-traits.html","https://ek9.io/ide/book-trait-clash.html","https://ek9.io/ide/book-allow-only.html","https://ek9.io/ide/book-components.html","https://ek9.io/ide/book-generics.html","https://ek9.io/ide/book-operators.html","https://ek9.io/ide/book-versions.html","https://ek9.io/ide/book-promotion.html","https://ek9.io/ide/book-notes.html","https://ek9.io/ide/book-programs.html","https://ek9.io/ide/book-game.html","https://ek9.io/ide/depth-settings-lookup.html","https://ek9.io/ide/depth-iteration.html","https://ek9.io/ide/depth-result-states.html","https://ek9.io/ide/depth-safe-shapes.html","https://ek9.io/ide/depth-operator-split.html","https://ek9.io/ide/depth-purity-rules.html","https://ek9.io/ide/depth-copy-merge-replace.html","https://ek9.io/ide/depth-aliasing.html","https://ek9.io/ide/depth-shallow-copy.html","https://ek9.io/ide/depth-then-guard.html","https://ek9.io/ide/depth-pure-shapes.html","https://ek9.io/ide/depth-impure-twins.html","https://ek9.io/ide/depth-own-function-type.html","https://ek9.io/ide/depth-tax-rules.html","https://ek9.io/ide/depth-order-pipelines.html","https://ek9.io/ide/depth-sink-replace-append.html","https://ek9.io/ide/depth-json-sink.html","https://ek9.io/ide/depth-async-lookups.html","https://ek9.io/ide/depth-super-call.html","https://ek9.io/ide/depth-lru-cache.html","https://ek9.io/ide/depth-priced-ledger.html","https://ek9.io/ide/depth-shelf.html","https://ek9.io/ide/depth-generic-functions.html","https://ek9.io/ide/depth-range-over-t.html","https://ek9.io/ide/depth-constrained-record.html","https://ek9.io/ide/depth-inventory.html","https://ek9.io/ide/depth-comments.html","https://ek9.io/ide/depth-payment-exceptions.html","https://ek9.io/ide/depth-narrow-catch.html","https://ek9.io/ide/depth-try-expression.html","https://ek9.io/ide/depth-resource-order.html","https://ek9.io/ide/depth-session-close.html","https://ek9.io/ide/depth-suppressed-close.html","https://ek9.io/ide/depth-require-exit.html","https://ek9.io/ide/depth-fatal-exit.html","https://ek9.io/ide/depth-returned-exit.html","https://ek9.io/ide/depth-pipeline-failures.html","https://ek9.io/ide/depth-shared-tally.html","https://ek9.io/ide/depth-worker-totals.html","https://ek9.io/ide/depth-lost-result.html","https://ek9.io/ide/depth-consistent-order.html","https://ek9.io/ide/depth-lock-order-fixed.html","https://ek9.io/ide/depth-check-then-act.html","https://ek9.io/ide/depth-di-notifiers.html","https://ek9.io/ide/depth-guess-seam.html","https://ek9.io/ide/depth-aspect-order.html","https://ek9.io/ide/depth-price-book.html","https://ek9.io/ide/depth-aspect-exception.html","https://ek9.io/ide/depth-call-counter.html","https://ek9.io/ide/depth-echo-in-process.html","https://ek9.io/ide/depth-line-echo.html","https://ek9.io/ide/depth-udp-echo.html","https://ek9.io/ide/depth-udp-pipeline.html","https://ek9.io/ide/depth-check-destinations.html","https://ek9.io/ide/depth-note-links.html","https://ek9.io/ide/depth-serve-and-call.html","https://ek9.io/ide/depth-hello-notes.html","https://ek9.io/ide/depth-json-documents.html","https://ek9.io/ide/depth-route-order.html","https://ek9.io/ide/depth-sync-key.html","https://ek9.io/ide/depth-late-status.html","https://ek9.io/ide/depth-package-greeter.html","https://ek9.io/ide/depth-capability-greeter.html","https://ek9.io/ide/depth-package-shapes.html","https://ek9.io/ide/depth-shop-tests.html","https://ek9.io/ide/depth-postage.html","https://ek9.io/ide/depth-substitution.html","https://ek9.io/ide/depth-tri-state.html","https://ek9.io/ide/depth-literals.html","https://ek9.io/ide/application-and-di.html","https://ek9.io/ide/aspects.html","https://ek9.io/ide/web-services.html","https://ek9.io/ide/networking.html"],"fixes":[],"example":{"scenario":"Test program non dev rejected","request":{"dryRun":true,"file":"main.ek9","isTest":true,"name":"BadTest"},"response":{"conflicts":[],"edits":[],"error":{"message":"@Test programs are only allowed in a dev source — move the target into a 'dev/' subdirectory or rename it to the QA####_dev_ pattern (E81015). Got: main.ek9"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"@Test programs are only allowed in a dev source — move the target into a 'dev/' subdirectory or rename it to the QA####_dev_ pattern (E81015). Got: main.ek9","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_add_route","url":"https://ek9.io/mcp/ek9_add_route.html","category":"editor","description":"Inserts the web operation (`byId() as GET for :/{id}` or `operator += for :/`) with a compiling stub body into the service; answers status, edits[] and summary, a duplicate route as conflicts[] (route-collision).","whenToUse":"'Add GET /{id} to OrdersService' is one call with symbol:'OrdersService', name:'byId', uri:'/{id}' and parameters:[{name:'id', in:'PATH'}] - no file or line.","whenNotToUse":["Target is a class, trait, or component (a normal method, not a web operation) - use ek9_add_method.","The service does not exist yet - create it with ek9_new_construct (service mode) first, then add routes here.","You want a value-type operator (==, <=>, ?, …) on a class/record, not an operator-form HTTP route - use ek9_add_operator."],"details":"Renders via the SAME operation spec + renderer as ek9_new_construct service mode (ServiceOperationParser + ConstructScaffolder.renderServiceOperation), so a route added here is byte-identical to one created with the service. ONE route per call: an obvious duplicate (same operator or same named handler) is a conflicts kind 'route-collision', but this is not a full overload analyser — pre-check with ek9_query_effective_api. An unbound PATH var, unresolved param type, or unresolved 'constrain by' gate surfaces as would-fail; a non-service target is an error naming its actual genus.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"name","type":"string","required":false,"description":"Named-route handler name (camelCase), e.g. 'byId'. Provide this OR 'operator'."},{"name":"operator","type":"string","required":false,"description":"Operator form of the route: += (POST), -= (DELETE), :^: (PUT), :~: (PATCH), ? (HEAD). Provide this OR 'name'."},{"name":"parameters","type":"array of object","required":false,"description":"Operation parameters: [{name, type, in:PATH|QUERY|HEADER|CONTENT|REQUEST|CONTEXT, source?, sanitized?}] - each ONE object (this list's items carry 'in', so the bare 'name as Type' form does not apply); 'type' defaults to String when omitted. PATH/QUERY/HEADER are auto-captured into the response and referenced in content() so they compile."},{"name":"response","type":"object","required":false,"description":"Response customisations: {status?, contentType?, contentLanguage?, cacheControl? | cache:{maxAge, visibility:public|private, mustRevalidate?, noStore?}}. Only set fields are overridden; HTTPResponse defaults the rest."},{"name":"security","type":"string","required":false,"description":"Per-operation security posture ('open' or 'constrain by <Gate>'). Omit to inherit the service posture."},{"name":"symbol","type":"string","required":true,"description":"The service the route is added to - a bare name ('OrdersService') finds its file workspace-wide; 'mod::OrdersService' when the name is declared in two modules."},{"name":"uri","type":"string","required":false,"description":"Operation path, e.g. '/{id}' or '/'. Path variables must be bound by a PATH param of the same name."},{"name":"verb","type":"string: GET | POST | PUT | DELETE | PATCH | HEAD | OPTIONS","required":false,"description":"HTTP verb for the named form. Default GET. Ignored for the operator form."}],"lessons":["https://ek9.io/ide/web-services.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_add_to_sealed_allowlist","url":"https://ek9.io/mcp/ek9_add_to_sealed_allowlist.html","category":"editor","description":"Rewrites the sealed type's 'allow only' line with the new subtypes appended; answers status, edits[] and summary, each bad entry as conflicts[] (target-not-sealed, entry-does-not-extend-target, entry-already-in-allowlist).","whenToUse":"'Let Pentagon and Hexagon into sealed Shape' is one call with symbol:'Shape' and allowOnly:['Pentagon','Hexagon'] - every unlisted subtype at once, no line.","whenNotToUse":["Target is NOT yet sealed (no 'allow only' clause) - use ek9_seal_type for the initial seal; it writes the whole list.","Removing the seal entirely rather than extending the list - use ek9_unseal_type.","The entry does not yet extend/implement the target - add the extends / with trait of clause to the entry's class first (else 'entry-does-not-extend-target'), then re-call.","The entry is abstract, or a dispatcher over the target lacks a handler for it - ek9_make_concrete / ek9_generate_dispatcher / ek9_add_method first (else post-apply E05250 / E05260 would-fail)."],"details":"conflicts kinds (all bad entries reported at once, not just the first): 'target-not-sealed' (mechanical - switch to ek9_seal_type), 'entry-does-not-extend-target' (escalation - add extends / with trait of first), 'entry-already-in-allowlist' (mechanical no-op - drop it from allowOnly). Abstract entry (E05250) and dispatcher-non-exhaustive (E05260) are NOT pre-checked - they surface as would-fail. Entries de-duplicated, appended in the order given; the typical baseline is already E05240-errored, and since apply verifies only NEW diagnostics, clearing it yields 'applied'.","arguments":[{"name":"allowOnly","type":"array of string","required":true,"description":"Concrete subtype names to add to the target's 'allow only' list, appended in the order given. Pass every unlisted subtype you intend to permit."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":true,"description":"The sealed class or trait - a bare name ('Shape') finds its file and declaration workspace-wide; 'mod::Shape' when the name is declared in two modules."}],"lessons":["https://ek9.io/ide/unseal-type.html"],"fixes":["E05240"],"example":{"scenario":"Add to sealed allowlist already in allowlist","request":{"entries":["Circle"],"file":"shapes.ek9","line":6},"response":{"conflicts":[{"entry":"Circle","kind":"entry-already-in-allowlist","message":"Circle is already permitted — nothing to add"}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Circle cannot be added to Shape's allow only list","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_adopt_trait","url":"https://ek9.io/mcp/ek9_adopt_trait.html","category":"editor","description":"Appends 'with trait of <Trait>' (or '… by <field>') to the construct's declaration and, when implementing, one override stub per abstract trait method; answers status, edits[] and summary, an already-adopted trait as conflicts[] (trait-already-adopted).","whenToUse":"'Make Greeter implement Speakable' is one call with symbol:'Greeter' and traitName:'Speakable' - stubs to fill in, or delegateFieldName to forward to a field.","whenNotToUse":["The class ALREADY declares the trait and only the 'by <field>' forwarding is missing - use ek9_generate_delegation.","Renaming or restructuring a method rather than adopting a trait - use ek9_rename_symbol or ek9_change_signature.","The target is a record / function / enumeration - trait composition is classes/components only.","Defining the trait itself, or pulling members out of a class into a new trait - use ek9_new_construct / ek9_extract_trait.","Adding a plain method or field (no trait contract) - use ek9_add_method / ek9_add_field."],"details":"mode is inferred: delegateFieldName present → delegate, else implement; a contradicting mode is a mode-contradicts-arguments conflict. delegate errors if delegateFieldName names no existing field; a sealed ('allow only') trait that excludes the construct also errors. conflicts kinds: 'trait-already-adopted' and 'target-cannot-adopt-trait' (record/enumeration); a concrete-method clash across traits does NOT block - implement emits an override stub with '//AI: Resolve conflict' guidance instead. A trait from another module gets a references entry added automatically; a delegate field whose type doesn't satisfy the trait surfaces as would-fail from the scratch compile.","arguments":[{"name":"delegateFieldName","type":"string","required":false,"description":"To DELEGATE instead of implementing: the existing field on the construct to forward every trait method to (its type must satisfy the trait)."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"mode","type":"string: implement | delegate","required":false,"description":"Optional - inferred: delegateFieldName present → delegate, else implement (override stubs)."},{"name":"symbol","type":"string","required":true,"description":"The class or component that adopts the trait - a bare name ('Greeter') finds its file workspace-wide; 'mod::Greeter' when the name is declared in two modules."},{"name":"traitName","type":"string","required":true,"description":"The EXISTING trait to adopt (must resolve in the workspace); 'mod::Trait' when the name is declared in two modules."}],"lessons":["https://ek9.io/ide/book-animals.html","https://ek9.io/ide/book-traits.html","https://ek9.io/ide/book-trait-clash.html","https://ek9.io/ide/book-allow-only.html","https://ek9.io/ide/depth-priced-ledger.html","https://ek9.io/ide/depth-price-book.html","https://ek9.io/ide/depth-sync-key.html","https://ek9.io/ide/depth-late-status.html","https://ek9.io/ide/adopt-trait.html"],"fixes":["E05030"],"example":{"scenario":"Implement trait apply","request":{"constructName":"Greeter","file":"Greeter.ek9","mode":"implement","traitName":"Speakable"},"response":{"conflicts":[],"edits":[{"after":"    Greeter with trait of Speakable","before":"    Greeter","endLine":10,"file":"Greeter.ek9","startLine":10,"type":"replace"},{"after":"      override speak() as pure\n        <- rtn as String: String()\n        //AI: Implement speak","endLine":13,"file":"Greeter.ek9","startLine":13,"type":"insert"}],"meta":{"serverMs":"<timing>"},"resolvedPath":"<workspace-root>/Greeter.ek9","risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":2,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Adopted trait Speakable on Greeter with 1 method stub(s)","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_advise_loop","url":"https://ek9.io/mcp/ek9_advise_loop.html","category":"enquiry","description":"Answers first: directions[] (each with summary such as 'candidate-stream-aggregation' or 'keep-as-loop', candidateShape, confidence), then the loop{} facts, outputs[], resources[] and unknowns[] - read-only.","whenToUse":"Should this for/while loop become a stream pipeline, and how - one call with file + line on the loop header (or file + symbol:'<loop variable>'). Any line inside the body also anchors it. Advisory only: the loop is never rewritten.","whenNotToUse":["The method's overall control-flow structure (branches, guards, dead code) rather than loop-to-stream advice - use ek9_query_flow.","The body is already a stream pipeline and you want stage-level analysis - use ek9_query_pipeline.","You just want a type's operator surface (operator |, <=>, #?) with no loop context - use ek9_query_effective_api.","You have read the advice and are ready to synthesise a stage function / collector operator / record - use ek9_create_dynamic_function, ek9_add_operator, ek9_new_construct."],"details":"Scope is always the single nearest enclosing loop: parse-tree mutation facts always work (PRE_IR_CHECKS, no symbols), while Tier-2 symbol facts (elementType, pipeEligible, bodyCallPurity, readAfterLoop) appear only when the workspace is resolved. pipeEligible mirrors the compiler's own `collect as` verdict — true means `collect as <type>` compiles with zero collector synthesis. directions[] are advisory candidateShapes, not committed edits; a line not on any loop returns an empty loop plus a single 'not-a-loop' direction (not an error); and quiet facts are not proven safety — always read unknowns[] (commutativity, aliasing, iterator single-consumption).","arguments":[{"name":"file","type":"string","required":true,"description":"The EK9 source file path"},{"name":"line","type":"integer","required":false,"description":"1-based line of the for/while loop header or any line inside the loop body - OMIT it and pass symbol:'<loop variable>' to let the tool find the line."},{"name":"symbol","type":"string","required":false,"description":"A name on the loop header (the loop variable, e.g. 'i') - the tool finds its line, so you never count lines."}],"lessons":[],"fixes":[],"example":{"scenario":"Advise shape","request":{"file":"Loops.ek9","line":8},"response":{"directions":[{"candidateShape":"<result> <- cat 1 ... 10 | <stage>... | collect as Integer","confidence":"medium","observation":"Loop body accumulates [running] from source `1 ... 10`. Element type is `Integer`. `running`'s type `Integer` already implements 'operator |', so `collect as Integer` works directly (no collector synthesis needed).","requiresSynthesis":["a dynamic function for any conditional filter/map stage (EK9 has no arrow lambdas)"],"suggestedTools":["ek9_create_dynamic_function","ek9_add_operator","ek9_new_construct"],"summary":"candidate-stream-aggregation"},{"candidateShape":null,"confidence":"low","observation":"If the accumulation is used once and locally, the imperative loop may read as clearly as a pipeline.","requiresSynthesis":[],"suggestedTools":[],"summary":"keep-as-loop"}],"loop":{"bodyCallPurity":"pure","containsNestedLoops":false,"control":null,"elementType":"Integer","headerGuard":null,"line":8,"loopKind":"for-range","loopVarMutated":false,"loopVariable":"i","source":"1 ... 10","writes":[{"conditional":false,"declaredInsideLoop":false,"guard":null,"kind":"compound-assign","line":9,"name":"running","rhs":"i","via":"+="}]},"meta":{"serverMs":"<timing>"},"outputs":[{"conditionalWrite":false,"declaredLine":7,"declaredType":"Integer","interpretation":"accumulation -> candidate 'collect as' (collection) or a collector ('operator |') if reducing to one scalar","mutationKinds":["compound-assign"],"name":"running","pipeEligible":true,"readAfterLoop":true,"writeLines":[9]}],"resources":{"references":[{"pointer":"ek9 -q collect as custom aggregator","topic":"custom collectors via 'operator |'"},{"pointer":"ek9 -q stream pipeline filter map collect","topic":"stream pipelines (filter/map/collect)"},{"pointer":"ek9 -q dynamic function capture","topic":"dynamic functions (EK9 has no lambdas)"}],"workedExample":"compiler-main/src/test/resources/examples/parseAndCompile/streams/StreamsCollectAs.ek9"},"unknowns":["Commutativity/associativity of the accumulation operator is NOT checked — a reduction is only stream-safe if reordering elements preserves the result (Integer '+' commutes; String '+' and user-defined operators may not).","'pipeEligible' is tested against the SOURCE element type; if a map stage changes the element type, re-check 'operator |' against the mapped type.","Single-consumption of the source iterator and aliasing of the accumulator are not analysed."]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_anchor_test","url":"https://ek9.io/mcp/ek9_anchor_test.html","category":"editor","description":"Rewrites the @Test directive line above the program to '@Test: \"REQ:x\"' (the execution group kept); answers status, edits[] and summary, an unchanged directive as conflicts[] (already-anchored).","whenToUse":"'Anchor test VelocityBreachesAboveFive to REQ:velocity-limit' is one call with file, symbol (the @Test program) and requirementId - omit it to clear.","whenNotToUse":["The test does not exist yet - use ek9_add_program (isTest:true, requirementId:…) to create it already anchored, rather than create-then-anchor.","You want to change the requirement itself, not which test proves it - use ek9_update_requirement (anchors live on the @Test; requirement nodes never list their tests).","The requirement node does not exist - use ek9_create_requirement (you may anchor first; it reports as a dangling anchor until created)."],"details":"Cursor-free: symbol is resolved through the symbol table, not by searching source text. The execution group survives — @Test: \"database\" becomes @Test: \"REQ:x\": \"database\" (id first, group second), read from the compiler's parsed TEST_DIRECTIVE so a serialised test is never silently rescheduled to the parallel pool. The requirement need not exist yet (dangling anchor, not faulted), but a mistyped prefix like RREQ:foo is rejected — it would otherwise pass as a legal execution GROUP name and silently drop the anchor; status:'error' when no such @Test in the file or no directive line above it (recompile); a directive that already reads as requested is conflicts[] kind 'already-anchored'.","arguments":[{"name":"file","type":"string","required":true,"description":"The dev source holding the @Test program (workspace-relative; an absolute path inside the workspace is accepted)."},{"name":"requirementId","type":"string","required":false,"description":"Requirement id to anchor to, e.g. 'REQ:velocity-limit'. Omit to CLEAR the anchor, leaving a plain @Test."},{"name":"symbol","type":"string","required":true,"description":"The @Test program's name, e.g. 'VelocityBreachesAboveFive' - a @Test program declared in this file."}],"lessons":[],"fixes":[],"example":{"scenario":"Anchor malformed rejected","request":{"file":"dev/tests.ek9","requirementRef":"RREQ:velocity-limit","symbol":"PlainTest"},"response":{"conflicts":[],"edits":[],"error":{"message":"'RREQ:velocity-limit' is not a valid requirement id. Expected <PREFIX>:<slug> with PREFIX one of REQ, CTRL, CAP, CON and slug matching [a-z0-9-]+, e.g. 'REQ:velocity-limit'."},"meta":{"serverMs":"<timing>"},"status":"error","summary":"'RREQ:velocity-limit' is not a valid requirement id. Expected <PREFIX>:<slug> with PREFIX one of REQ, CTRL, CAP, CON and slug matching [a-z0-9-]+, e.g. 'REQ:velocity-limit'.","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_apply_guard_pattern","url":"https://ek9.io/mcp/ek9_apply_guard_pattern.html","category":"editor","description":"Rewrites the construct's head to 'if x <- f()' (or ':=?', or ':=' with an explicit 'then x?', as the source assignment dictates) and deletes the standalone assignment and the redundant 'x?' check; answers status, edits[] and summary, an unsafe or unsupported shape as conflicts[].","whenToUse":"Turn 'x <- f()' followed by 'if x?' into the EK9 guard 'if x <- f()' - one call with file and symbol:'x' (the variable), or line on the control line.","whenNotToUse":["There is no surrounding control construct yet - use ek9_surround_with to wrap first.","You just want an expression pulled into a local (no gating intent) - use ek9_extract_variable.","The lifted local must survive past the construct as per-instance state - use ek9_introduce_field."],"details":"No mode parameter - the head operator is DERIVED from the source: '<-' stays '<-', ':=?' stays ':=?' (both gate the body per PreFlowCanSkipBody), a blind ':='/'='/':' stays ':=' with the gate explicit ('if x := f() then x?', 'while x := f() then x? and (cond)') and is refused before switch/try/for/do (kind blind-assignment-cannot-gate). Per-construct fold: switch guards on the MATCH SUBJECT ('v <- getV()'+'switch v' -> 'switch v <- getV()'); try/function has no control so folds bare ('try r <- open()'); loops keep their control/iteration as a 'then' clause ('while x <- src() then cond', 'for x <- src() then item in coll') and the guard is evaluated ONCE at loop entry, not per iteration. A compound 'if x? and cond' (isSet on either side of a two-operand 'and') lifts with the other operand preserved as a 'then' residual; an 'or', a three-way 'and', or nested 'x?' stays a compound-control-not-supported conflict (other kinds: switch-subject-not-the-guard-var, already-a-guard).","arguments":[{"name":"file","type":"string","required":true,"description":"The EK9 source file (workspace-relative; an absolute path inside the workspace is accepted)."},{"name":"line","type":"integer","required":false,"description":"IDE refinement: the 1-based line of the control construct's opening line (if/while/do-while/for/switch/try). Omit it and pass symbol."},{"name":"symbol","type":"string","required":false,"description":"The variable to lift into the guard ('customer'); the tool finds the control construct that tests it. Prefer this to line."}],"lessons":["https://ek9.io/ide/book-guards.html","https://ek9.io/ide/lift-into-guard.html"],"fixes":[],"example":{"scenario":"Lift declaration dryrun","request":{"dryRun":true,"file":"Guarding.ek9","line":16},"response":{"conflicts":[],"edits":[{"after":"      if name <- lookup(id)","before":"      if name?","endLine":16,"file":"Guarding.ek9","startLine":16,"type":"replace"},{"before":"      name <- lookup(id)","endLine":15,"file":"Guarding.ek9","startLine":15,"type":"delete"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":2,"touchesPublicApi":false,"touchesTests":false},"status":"ready","summary":"Lift 'name <- lookup(id)' into the guard at if (line 16): 'if name <- lookup(id)' — the redundant 'name?' check is subsumed by the guard.","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_apply_symbolic_fix","url":"https://ek9.io/mcp/ek9_apply_symbolic_fix.html","category":"editor","description":"Inserts the 'require <divisor> <> 0' line guard-first (an inline-initialised return becomes '<- rtn as T?' + ':=?'), re-finding the counterexample server-side, and migrates a pinning @Test to assertPanic in the same changeset; answers status, edits[] and summary.","whenToUse":"After ek9_verify_method reports DIV_BY_ZERO, 'add the guard' is one call with symbol:'safeAverage' - it inserts the 'require <divisor> <> 0' precondition. V1: DIV_BY_ZERO only.","whenNotToUse":["You want to FIND whether a function is safe, not change it - use ek9_verify_method (the read-only dual).","You want to PIN the failing boundary as a test rather than fix it - use ek9_generate_edge_case_tests (mode:'verify' writes a directed test per counterexample).","You want to add a PARAMETER, not a precondition - use ek9_change_signature (shares the same guard-first return machinery)."],"details":"V1 scope: DIV_BY_ZERO only (single named-parameter divisor); other obligations (CALLEE_REQUIRE, CONSTRAINED_CONSTRUCTION) are rejected with a message, not a guessed edit. The finding is re-found by re-running the engine at apply time and matched by obligation+witness on the function at line — a drifted or already-discharged line errors, several fixable divisions demand a witness ('<param>=<value>') to pick one, and the require line is derived server-side (no free-text guard param). Pinned-test migration is off-when-unsure: a hand-edited test it does not recognise is left untouched and named for manual migration.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"obligation","type":"string","required":false,"description":"Optional counterexample selector when the function has several findings. V1 accepts only 'DIV_BY_ZERO'."},{"name":"symbol","type":"string","required":true,"description":"The function (or 'Type.method') to fix - a bare name finds its file workspace-wide; 'mod::name' when the name is declared in two modules."},{"name":"witness","type":"string","required":false,"description":"Optional counterexample selector ('<param>=<value>', e.g. 'quantity=0') when the function has several fixable divisions."}],"lessons":[],"fixes":[],"example":{"scenario":"Apply unsupported obligation","request":{"file":"Maths.ek9","line":5,"obligation":"CALLEE_REQUIRE"},"response":{"conflicts":[],"edits":[],"error":{"message":"Apply-fix V1 handles DIV_BY_ZERO only; 'CALLEE_REQUIRE' is not yet supported."},"meta":{"serverMs":"<timing>"},"status":"error","summary":"Apply-fix V1 handles DIV_BY_ZERO only; 'CALLEE_REQUIRE' is not yet supported.","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_ask","url":"https://ek9.io/mcp/ek9_ask.html","category":"enquiry","description":"Returns the best-matching curated Q&A entries: 'match: strong|weak|id' first, then per entry the id, question, category, Oracle tool, the answer and last the compiled EK9 example (capped by default).","whenToUse":"'How do I ... in EK9' or 'why does EK9 ...' is one call with query:'<the question>' - the curated, compiled Q&A corpus, no workspace needed. Pass the question as free text, or 'Q1043' to fetch one entry by id; the corpus covers idioms, rationale and migration.","whenNotToUse":["A type's methods and operators or one keyword's page ('what does String offer') - use ek9_help.","A specific error code (E07235, E08100) - use ek9_explain_error.","Priming a fresh AI session with the EK9 paradigm - use ek9_paradigm.","A construct in THIS workspace rather than the corpus - use ek9_query_construct / ek9_query_workspace / ek9_query_effective_api; for a workspace error, ek9_query_diagnostics."],"details":"Plain text. verbosity: 'summary' (default for a free-text search) = the answer's opening paragraph and the first 15 lines of the example; 'full' (default for a Q<id> fetch) = the whole answer, the whole example and its companion sources; 'none' = only the headline lines (id, question, category, Oracle tool). includeMigration:true appends each entry's cross-language migration note where one exists (entries without one are not filtered out). match: 'strong' when at least half of the query's content words appear in the matched question, else 'weak' with a hint; 'id' for a Q<id> fetch. maxResults caps entries (default 3). Static corpus, independent of workspace compile state; a no-match is a successful empty result.","arguments":[{"name":"includeMigration","type":"boolean","required":false,"description":"Append each entry's cross-language migration note where one exists (default false)."},{"name":"maxResults","type":"integer","required":false,"description":"Maximum entries returned (default 3)"},{"name":"mode","type":"string: summary | detailed | migration","required":false,"description":"Retained alias: 'summary' = verbosity:'summary', 'detailed' = verbosity:'full', 'migration' = includeMigration:true. Prefer the two parameters it expands to."},{"name":"query","type":"string","required":true,"description":"The question in natural language, or an entry id ('Q1043', '1043')"},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size: 'summary' (default for a search) = opening answer paragraph + first 15 example lines; 'full' (default for a Q<id> fetch) = whole answer, whole example, companion sources; 'none' = headline lines only."}],"lessons":["https://ek9.io/ide/asking-the-ide.html","https://ek9.io/ide/book-collections.html","https://ek9.io/ide/book-list-and-dict.html","https://ek9.io/ide/book-inference.html","https://ek9.io/ide/book-json-taste.html","https://ek9.io/ide/book-defaulting.html","https://ek9.io/ide/book-for-expression.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_change_signature","url":"https://ek9.io/mcp/ek9_change_signature.html","category":"editor","description":"Rewrites the declaration and EVERY call site atomically (add / remove / reorder parameters, change the return type, toggle 'as pure'); answers status, edits[] and summary with the call-site count, a blocking call site as conflicts[] (callsite-incompatible-with-new-signature).","whenToUse":"'Add a parameter to Order.total and fix every caller' is one call with symbol:'Order.total' and mutations:[{kind:'add-parameter', parameter:{...}}]. A constructor is 'Order.Order' - its 'Order(...)' calls are updated the same way.","whenNotToUse":["Renaming the method - use ek9_rename_symbol; removing it entirely - use ek9_safe_delete; adding a brand-new method - use ek9_add_method.","Extracting a code block into a NEW method - use ek9_extract_method.","Promoting an in-body expression to a parameter - use ek9_introduce_parameter.","Operators (fixed contracts) - use ek9_safe_delete + ek9_add_operator; a brand-new constructor beside the existing ones - use ek9_add_constructor; a purity COMPILE ERROR to reconcile - use ek9_fix_purity_contract."],"details":"EK9 has NO default parameter values, so add-parameter REQUIRES valueForExistingCalls (an EK9 expression injected at every existing call site) and injects a 'require <name>?' guard + //AI: block (E08091 bans unused params) unless the target is an override. When the post-change count reaches 4+, all positional call sites auto-rewrite to named-argument form (name: value) per E11062. Targeting a leaf override resolves UP to its root contract and cascades the whole family (resolved-to-contract advisory); semantic cascades (purity E05150/E05160, return-type incompatibility, override cascades) surface as would-fail from the scratch compile in V1, not structured conflict kinds.","arguments":[{"name":"column","type":"integer","required":false,"description":"IDE cursor offset (0-based) on 'line'. Omit it - pass symbol instead."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"mutations","type":"array of any","required":true,"description":"One or more mutations applied atomically, in order. Each: {kind: 'add-parameter' (+ parameter: {name, type, position?, valueForExistingCalls: the expression every existing call passes - REQUIRED whenever anything calls it, EK9 has no default parameter values}), 'remove-parameter' (+ removeParameterName, + optional dropCallSiteArguments: true to drop the argument expression at every call site — without it live call sites block the removal), 'reorder-parameters' (+ newParameterOrder: [names]), 'change-return-type' (+ newReturnType — null removes the return clause; OMIT the mutation to keep the return type), 'change-purity' (+ pure: true | false)}. position omitted = append."},{"name":"symbol","type":"string","required":true,"description":"The method or function - 'Order.total' or a bare function name finds its file and declaration workspace-wide; with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/change-signature.html"],"fixes":[],"example":{"scenario":"Change signature bad permutation error","request":{"column":5,"file":"main.ek9","line":13,"mutations":[{"kind":"reorder-parameters","newParameterOrder":["first"]}]},"response":{"conflicts":[],"edits":[],"error":{"message":"newParameterOrder must be a permutation of existing parameter names — missing: [second], extra: []"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"newParameterOrder must be a permutation of existing parameter names — missing: [second], extra: []","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_change_visibility","url":"https://ek9.io/mcp/ek9_change_visibility.html","category":"editor","description":"Rewrites the method's declaration line with the new access modifier (public = none); answers status, edits[] and summary, an unchanged method as conflicts[] (already-<visibility>). Method-only: fields, operators and trait methods have fixed visibility.","whenToUse":"'Make Order.decorate private' is one call with symbol:'Order.decorate' and visibility:'private' | 'protected' | 'public' - no file, line or column needed.","whenNotToUse":["The visibility change is part of a wider signature change (params / return type) - use ek9_change_signature.","The method shouldn't exist at all - use ek9_safe_delete rather than restricting access.","Factoring part of a method into a private helper - use ek9_extract_method (extracted methods are private by default).","The target is a field, an operator, or a trait method - their visibility is fixed in EK9 (class/component fields private, record fields public, operators and trait methods public); this tool returns status:'error'."],"details":"visibility:'public' REMOVES the modifier (public is EK9's default; writing it explicitly is E07280). A method already at the requested visibility is conflicts[] kind already-public / already-private / already-protected (nothing written). Structurally-impossible changes - an override (visibility locked to its parent), protected on a component/service method, protected on a non-open class method (E07260), any non-public modifier on a trait method (E07270) - are refused up-front as status:'error' by the shared VisibilityChangePredicate, the same rule core the compiler enforces. Narrowing (to private / protected) that leaves a call site unable to reach the member is NOT an up-front error - the scratch compile surfaces it as status:'would-fail' with the E06180 NOT_ACCESSIBLE diagnostics.","arguments":[{"name":"column","type":"integer","required":false,"description":"IDE cursor offset (0-based) on 'line'. Omit it - pass symbol instead."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":true,"description":"The method - 'Order.total' finds its file and declaration workspace-wide; with file (+ line), the identifier you mean there."},{"name":"visibility","type":"string: public | protected | private","required":true,"description":"The new access modifier."}],"lessons":["https://ek9.io/ide/change-visibility.html"],"fixes":[],"example":{"scenario":"Change visibility operator error","request":{"column":7,"file":"main.ek9","line":23,"visibility":"private"},"response":{"conflicts":[],"edits":[],"error":{"message":"Operators are always public in EK9 and cannot carry an access modifier"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"Operators are always public in EK9 and cannot carry an access modifier","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_check_module_cycles","url":"https://ek9.io/mcp/ek9_check_module_cycles.html","category":"enquiry","description":"Answers first: hasCycles and cycleCount, then cycles[] (each a closed module path with edges[].via naming the source files) and moduleCount - the whole workspace module graph.","whenToUse":"Are there circular references between the modules of this package - one call, no arguments; hasCycles and cycleCount answer it.","whenNotToUse":["Cycles BETWEEN published packages (cross-package) - use ek9_check_package_dependency_cycles.","The full module dependency graph, not just cycles - use ek9_query_module_dependencies (cycles are a subset of that data).","Dependency-injection wiring cycles (compile error E08190) - use ek9_query_diagnostics."],"details":"cycles[].modules uses the closed-path convention ([\"A\",\"B\",\"A\"] means A -> B -> A; the repeated first module marks closure, not a distinct node). moduleCount is how many modules the walk covered. edges[].via lists the source files whose imports create each cycle (jump-to-source); reliable detection and via-attribution need a compile that reached SYMBOL_DEFINITION or later — at syntax_only hasCycles is only a lower bound.","arguments":[],"lessons":["https://ek9.io/ide/modules.html"],"fixes":[],"example":{"scenario":"Clean shape","request":{},"response":{"cycleCount":0,"cycles":[],"hasCycles":false,"meta":{"serverMs":"<timing>"},"moduleCount":1}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_check_package_dependency_cycles","url":"https://ek9.io/mcp/ek9_check_package_dependency_cycles.html","category":"enquiry","description":"Answers with hasCycles, cycleCount and the cycles (closed package paths with their edges) across every package declared in the workspace, plus packagesAnalysed and sccCount.","whenToUse":"'Do any packages in this workspace depend on each other in a loop' is one call with no arguments. The pre-release check: a cross-package cycle makes versioning incoherent and blocks independent release.","whenNotToUse":["The full dependency tree, who brings in what - use ek9_query_dependency_tree.","Cycles between MODULES inside one package - use ek9_check_module_cycles.","DI wiring cycles (compile error E08190) - use ek9_query_diagnostics."],"details":"Needs a compiled workspace: status:'not-compiled' with nextStep otherwise. Only edges whose target package is also in the workspace are walked (scope: 'workspace-wide'). cycles[].modules uses the closed-path convention - the first package is repeated at the end (['A','B','A'] means A->B->A), so edgeCount, not the array length, is the true edge count; cycles[].edges attribute each hop (from/to are package names, via the from-package's source files). sccCount deduplicates cycles by package set (one per strongly connected component) and is > 0 iff hasCycles.","arguments":[],"lessons":["https://ek9.io/ide/modules.html"],"fixes":[],"example":{"scenario":"Clean shape","request":{},"response":{"cycleCount":0,"cycles":[],"hasCycles":false,"meta":{"serverMs":"<timing>"},"packagesAnalysed":1,"sccCount":0,"scope":"workspace-wide","status":"ok","summary":"no package cycles across 1 package(s)"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_check_requirements","url":"https://ek9.io/mcp/ek9_check_requirements.html","category":"enquiry","description":"Answers status (healthy | violations | dangling-anchors) and healthy first, then requirementCount, developedCount, outstandingCount, violations[] (the store is broken), danglingAnchors[] (a @Test names a requirement that does not exist), outstanding[] (the backlog) and unanchoredTests[] (the authoring work-list) - the whole graph, nothing to verify.","whenToUse":"'Is the requirement graph healthy, and what is still outstanding?' is one call: {} - no cursor, no id; the whole store plus the last compile's @Test anchors.","whenNotToUse":["Reading ONE requirement in depth (title, children, anchors) - use ek9_query_requirement (mode=detail).","Anchoring a test to a requirement from the work-list — use ek9_anchor_test with the file + testName this tool reports.","Confirming a requirement is actually FIT (passing/adequate tests) — developed means 'someone claimed it', not correct; use ek9_run_tests and the quality report."],"details":"Four disjoint findings: violations[] (store broken, fix a file; kind is GraphViolation kebab-cased), danglingAnchors[] (a @Test names a non-existent requirement — most urgent), outstanding[] (nothing anchors it yet — backlog, carries title), unanchoredTests[] (NOT a fault — the authoring work-list, each entry ready for ek9_anchor_test). A requirement is DEVELOPED when a @Test names it, a rule anchor binds it, or every live child is developed (viaChildren separates the last case). anchorsResolved distinguishes '0 anchors' from 'nothing compiled'; errors when no workspace is configured (cannot locate .ek9-ai/requirements/).","arguments":[{"name":"includeDeveloped","type":"boolean","required":false,"description":"List every developed requirement with its anchoring tests, not just the counts. Verbose on a large graph."}],"lessons":[],"fixes":[],"example":{"scenario":"Check requirements developed","request":{},"response":{"anchorsResolved":true,"danglingAnchors":[],"developedCount":1,"healthy":true,"meta":{"serverMs":"<timing>"},"outstanding":[],"outstandingCount":0,"requirementCount":1,"status":"healthy","unanchoredTestCount":0,"unanchoredTests":[],"violations":[]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_clean","url":"https://ek9.io/mcp/ek9_clean.html","category":"execution","description":"Wipes the on-disk .ek9/ artefacts the scope names and resets the server JVM's in-memory coverage/profiling runtimes; answers status:ok with cleanedSources[] listing what was wiped or reset, in order.","whenToUse":"'Start this measurement from a pristine project' is one call: {scope:'coverage'} (or profiling / release / full) on the workspace root - projectDir only for another root.","whenNotToUse":["Running tests - ek9_run_tests already cleans with scope coverage first, so a preceding ek9_clean is redundant.","Just wanting a fresh recompile without deleting lib/, the target executable, or resetting runtimes - use ek9_compile (mode=full), which re-emits all bytecode."],"details":"Scope maps to state sources: coverage = wipe generated/ + reset CoverageRuntime; profiling = also reset ProfilingRuntime (profiling registers probes via CoverageRuntime, so both reset); release/full = also wipe lib/ + target executable + props (identical on disk today, kept distinct so future caches can join full). Disk wipe + runtime reset are one coordinated step so they never drift (historically a registry-only reset let orphaned .class files re-register stale probes and pollute coverage). The response's cleanedSources lists what was wiped/reset in execution order.","arguments":[{"name":"file","type":"string","required":false,"description":"The entry-point .ek9 source file (absolute, or relative to projectDir). Omit to auto-detect the shallowest non-dev .ek9 file - enough to locate the .ek9/ directory."},{"name":"projectDir","type":"string","required":false,"description":"Project root holding the .ek9 sources - absolute, or relative to the workspace root. Omit to use the workspace root itself (the first root ek9_compile was given)."},{"name":"scope","type":"string: coverage | profiling | release | full","required":false,"description":"What to make pristine: coverage (generated/ + coverage runtime), profiling (coverage + profiling runtime), release and full (also lib/, the target executable and props)."}],"lessons":[],"fixes":[],"example":{"scenario":"Clean coverage scope","request":{"projectDir":"<workspace-root>","scope":"coverage"},"response":{"cleanedSources":["generated","coverageRuntime"],"mainSource":"main.ek9","meta":{"serverMs":"<timing>"},"projectDir":"<workspace-root>","scope":"coverage","status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_collapse_to_default_operator","url":"https://ek9.io/mcp/ek9_collapse_to_default_operator.html","category":"editor","description":"Replaces the operator's declaration and body with the one-line 'default operator <sym>' form (the inverse of ek9_expand_default_operator); answers status, edits[] and summary.","whenToUse":"'Collapse Order's hand-written == back to default operator ==' is one call with symbol:'Order' and operator:'==' - the body must be default-equivalent.","whenNotToUse":["You want the OPPOSITE - turn 'default operator <sym>' into an explicit body so you can customise it - use ek9_expand_default_operator.","The operator should be REMOVED entirely, not collapsed - use ek9_safe_delete.","The operator's signature/purity is wrong and needs structural change - use ek9_change_signature.","The body is genuinely customised - the tool does NOT diff it against the synthesis and will silently discard the custom behaviour; review with ek9_read_construct first."],"details":"Class/record/component only; the defaultable set is <=> == ? $ $$ #? :=: - <> < <= > >= are generated from the sameness and never written or requested (E07181; E07180 where the type has no <=> to generate them from), and any other operator errors ('cannot be defaulted'). The operator's declaration is found by name; two explicit declarations of the same symbol (overloads) are a conflict listing their lines - pass line to pick one. The whole declaration + body is replaced without being diffed against the compiler's synthesis, so a customised body is silently lost. The verify compile only catches breakage the collapse itself introduces (e.g. E07030 default-on-trait, E07190 super missing '<=>', a field type lacking the operator).","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"IDE refinement: the 1-based line of the operator declaration. Omit it - the declaration is found by symbol + operator; needed only when two overloads declare the same operator."},{"name":"operator","type":"string","required":true,"description":"The operator to collapse, in EK9 source form ('==', '<=>', '$'); must be in the defaultable set."},{"name":"symbol","type":"string","required":true,"description":"The class, record or component holding the operator - a bare name ('Order') finds its file workspace-wide; 'mod::Order' when the name is declared in two modules."}],"lessons":["https://ek9.io/ide/adding-members.html","https://ek9.io/ide/expand-default-operator.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_compile","url":"https://ek9.io/mcp/ek9_compile.html","category":"execution","description":"Compiles the workspace and answers status (ok | failed | found-no-sources | blocked), sourceCount, errorCount, warningCount and diagnostics[] - each with file, line, column, severity, errorCode and message, the ek9_query_diagnostics record - for every discovered .ek9 file.","whenToUse":"'Does the workspace compile, and what are the errors?' is one call: {} recompiles the initialised workspace, {projectDir:'.'} points it at a project root first.","whenNotToUse":["Reading the last compile's cached diagnostics without recompiling - use ek9_query_diagnostics.","Running a program - use ek9_run_program (it compiles first).","Running tests - use ek9_run_tests (it compiles first).","Canonical source formatting - use ek9_format."],"details":"Two orthogonal dimensions: `mode` = cache strategy (default full; in V1 incremental/full/clean share the full-workspace compile path and only check-only differs - no artefacts) and artifact-intent flags (includeDev, withDebug, withProfiling, noLink, optimisation o0/o2-default/o3, phaseUpTo - any CompilationPhase name, default PRE_IR_CHECKS). Guards: includeDev implies withDebug; withProfiling implies withDebug and requires explicit optimisation:o0 (the o2 default blocks it); withDebug+o3 and withProfiling+noLink are blocked (status:'blocked' with a kebab-case reason). A success with zero discovered sources is status:'found-no-sources' (misconfigured projectDir); the .ek9 cache is not flag-keyed (use mode:full after switching debug/profile/opt). A failed compile with E07235 (fields but no '?') gets 'default operator ?' applied through the verified write and is compiled again - corrected[] and edits[] say where; repair:false only compiles.","arguments":[{"name":"errorLevel","type":"integer","required":false,"description":"Error detail level: 0 minimal, 1 visual, 2 + fuzzy suggestions, 3 + rich explanations."},{"name":"includeDev","type":"boolean","required":false,"description":"Include dev-only code (test sources, fixtures). Implies withDebug per the CLI -cd family bundling rule."},{"name":"mode","type":"string: incremental | full | check-only | clean","required":false,"description":"Cache strategy: incremental and full both compile the whole workspace today (incremental does not yet reuse earlier results), check-only (compile + analyse without emitting artefacts), clean (wipe artefacts + dependencies before compile)."},{"name":"noLink","type":"boolean","required":false,"description":"Compile + analyse without producing an executable artefact. Equivalent to mode: check-only when paired with mode: incremental or full. Rejected with withProfiling."},{"name":"optimisation","type":"string: o0 | o2 | o3","required":false,"description":"o0 (none - fastest compile, max debug fidelity), o2 (balanced), o3 (aggressive - inlining, DCE, loop opts; breaks debug attributes and profiling probes). Auto-set to o0 when withProfiling: true."},{"name":"phaseUpTo","type":"string: READING | PARSING | SYMBOL_DEFINITION | DUPLICATION_CHECK | REFERENCE_CHECKS | EXPLICIT_TYPE_SYMBOL_DEFINITION | TYPE_HIERARCHY_CHECKS | FULL_RESOLUTION | POST_RESOLUTION_CHECKS | PRE_IR_CHECKS | PLUGIN_RESOLUTION | SYMBOLIC_ANALYSIS | IR_GENERATION | IR_ANALYSIS | IR_OPTIMISATION | CODE_GENERATION_PREPARATION | CODE_GENERATION_CONSTANTS | CODE_GENERATION_APPLICATIONS | CODE_GENERATION_AGGREGATES | CODE_OPTIMISATION | PLUGIN_LINKAGE | APPLICATION_PACKAGING | PACKAGING_POST_PROCESSING","required":false,"description":"Stop after the named compilation phase (e.g. FULL_RESOLUTION, IR_GENERATION) for pipeline-stage diagnostics."},{"name":"projectDir","type":"string","required":false,"description":"Project root to discover .ek9 files from - absolute, or relative to the workspace root; (re)initialises the workspace before compiling. Omit to reuse the initialised workspace. Shorthand for roots:[projectDir]."},{"name":"repair","type":"boolean","required":false,"description":"Apply the fixes the language leaves no choice about, then compile again: a slip with one reading (e.g. '-> a as Integer, b as String', 'Type?: value', a stray ')'), and 'default operator ?' for a class, record or component with fields and no '?' (E07235) - each listed in corrected[] and edits[]. false compiles only, and changes nothing."},{"name":"roots","type":"array of string","required":false,"description":"Several project roots at once, each as projectDir. Omit for one root (use projectDir) or to reuse the initialised workspace."},{"name":"traceCompiler","type":"boolean","required":false,"description":"Emit verbose compile-pipeline tracing to the build log."},{"name":"withDebug","type":"boolean","required":false,"description":"Emit debug info / SMAP for breakpoint + variable inspection. Compatible with optimisation o0 (max fidelity) or o2 (safe). Rejected with o3 (aggressive optimisation strips debug attributes)."},{"name":"withProfiling","type":"boolean","required":false,"description":"Emit per-function profiling probes for hot-path / call-graph data. Forces optimisation: o0. Rejected with o2 / o3 (probes get inlined away). Rejected with noLink (no artefact to profile). Implies withDebug for source-line attribution."}],"lessons":["https://ek9.io/ide/fixing-errors.html","https://ek9.io/ide/the-terminal.html"],"fixes":[],"example":{"scenario":"Pre ir checks shape","request":{"phaseUpTo":"PRE_IR_CHECKS","roots":["<workspace-root>"]},"response":{"diagnostics":[],"errorCount":0,"flags":{"includeDev":false,"mode":"full","noLink":false,"optimisation":"o2","phaseUpTo":"PRE_IR_CHECKS","withDebug":false,"withProfiling":false},"meta":{"serverMs":"<timing>"},"sourceCount":1,"status":"ok","summary":"Compilation succeeded (mode: full, phase: PRE_IR_CHECKS, optimisation: o2): 1 source, 0 errors, 0 warnings","warningCount":0}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_convert_constructor","url":"https://ek9.io/mcp/ek9_convert_constructor.html","category":"editor","description":"Replaces the no-arg constructor with its other spelling - 'default Name()' ↔ an explicit 'this.field :=? Type()' default-setter body - purity and visibility preserved; answers status, edits[] and summary.","whenToUse":"'Expand Person's default constructor so I can customise it' (or collapse it back) is one call with symbol:'Person' - mode is inferred from the constructor.","whenNotToUse":["The constructor doesn't exist yet - use ek9_add_constructor to create one.","You want to round-trip an OPERATOR (==, <=>, $, …), not a constructor - use ek9_expand_default_operator / ek9_collapse_to_default_operator.","The constructor takes parameters and its signature is wrong - use ek9_change_signature (this is a no-arg form swap, not a structural change).","The constructor should be removed entirely - use ek9_safe_delete."],"details":"Class/record only; the no-arg constructor is found by name (parser-authoritative) and mode is inferred from its form - a 'default' constructor expands, an explicit one collapses; an explicit mode that contradicts the form is status:error. expand emits the guarded ':=?' default-setter, skipping injected ('name as Type!') fields and any field whose declaration already supplies a value (its ':=?' would be dead code, E08095), and errors when no field is left to set (keep 'default'). collapse returns would-fail when losing the explicit body would break the compile - e.g. uninitialised 'as Type?' fields with no co-initialising value ctor (E08070/E07175).","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"IDE refinement: the 1-based line of the constructor declaration. Omit it - the no-arg constructor is found by symbol; needed only when two exist."},{"name":"mode","type":"string: expand | collapse","required":false,"description":"Optional - inferred from the constructor found: a 'default' constructor expands (→ explicit 'this.field :=? Type()' body), an explicit no-arg one collapses (→ 'default')."},{"name":"symbol","type":"string","required":true,"description":"The class or record owning the no-arg constructor - a bare name ('Person') finds its file workspace-wide; 'mod::Person' when the name is declared in two modules."}],"lessons":["https://ek9.io/ide/convert-constructor.html"],"fixes":[],"example":{"scenario":"By name before compile","request":{"dryRun":true,"symbol":"Account"},"response":{"conflicts":[],"edits":[],"error":{"kind":"not-compiled","message":"symbol:'Account' is found in the compiled workspace, and nothing has been compiled yet - run ek9_compile, then resend this call unchanged (or pass file:'<path>' with the symbol)."},"meta":{"serverMs":"<timing>"},"nextStep":"ek9_compile","status":"error","summary":"symbol:'Account' is found in the compiled workspace, and nothing has been compiled yet - run ek9_compile, then resend this call unchanged (or pass file:'<path>' with the symbol).","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_create_dynamic_class","url":"https://ek9.io/mcp/ek9_create_dynamic_class.html","category":"editor","description":"Inserts `variableName <- (captures) trait of T as class` (or the tuple / generic form) with its members after the line, auto-adding `default operator ?` for captures; answers status, edits[] and summary, with a would-fail carrying the compiler's own diagnostics (unimplemented abstract methods named).","whenToUse":"'An inline class implementing Describable over the captured prefix' is one call with file, line (the body line it goes after), variableName and traits:[{name}].","whenNotToUse":["You need a closure/lambda (an abstract-function impl), not a class - use ek9_create_dynamic_function.","Authoring a NAMED top-level class reusable across the module, or one extending a non-generic concrete class (dynamic classes cannot) - use ek9_new_construct mode:'class'.","Adding a trait to, or implementing methods on, an EXISTING declared type - use ek9_adopt_trait / ek9_implement_methods."],"details":"Form is set by `form` or auto-detected (traits present -> trait; baseType present -> generic; else tuple); className is a module-level TYPE distinct from the variableName receiver — mandatory for tuple, optional (anonymous) for trait/generic. Scratch-compilation is the sole validator: would-fail carries the compiler's own diagnostics (unresolved trait/base, unimplemented abstract methods, name collision E01040, purity, capture syntax E06230/E06240/E02040), while the fresh binding's expected E08090 (scaffold not yet referenced) is tolerated so a clean insert stays ready. conflicts kinds: target-not-function-body (bad anchor), dynamic-body-not-supported (nesting into a dynamic body, v1 limit).","arguments":[{"name":"baseType","type":"string","required":false,"description":"Generic-extension form: the parameterised base (e.g. `Iterator of Integer`, `Function of (String, Integer)`)."},{"name":"captures","type":"array of object","required":false,"description":"Capture list (may be empty). Each entry: {fieldName?, sourceExpression}. Captures are by-pointer-value — mutating a captured object inside the class is visible to the caller (copy via :=: before capture for isolation). A non-empty list auto-adds `default operator ?`."},{"name":"className","type":"string","required":false,"description":"The dynamic class's own name — the grammar identifier, a module-level TYPE, distinct from variableName. REQUIRED for the tuple form; optional (anonymous when omitted) for trait/generic forms."},{"name":"file","type":"string","required":true,"description":"The .ek9 source file containing the host body (workspace-relative; an absolute path inside the workspace is accepted)."},{"name":"form","type":"string: trait | tuple | generic","required":false,"description":"Which grammar alternative to emit. Auto-detected when omitted: traits present → trait; baseType present → generic; otherwise tuple."},{"name":"inheritanceKeyword","type":"string: is | extends","required":false,"description":"Generic-extension form only: `is` and `extends` are synonyms. Default: `is`."},{"name":"line","type":"integer","required":true,"description":"1-based line AFTER which the dynamic class is inserted (read it from ek9_read_file lineNumbers:true). Must be inside a function/program/method body and AFTER the captured variables are declared (a class with captures cannot be hoisted above them)."},{"name":"members","type":"string","required":false,"description":"Multi-line aggregateParts body: fields, then methods, then operators, in grammar order (the caller owns ordering). Required for the tuple form UNLESS at least one capture is supplied (captures become the tuple's fields + an auto `default operator ?`). Omit for trait/generic to scaffold header-only (the dryRun would-fail then names the abstract methods to implement). If you author an `operator ?`, the auto `default operator ?` is suppressed."},{"name":"stubAbstractMethods","type":"boolean","required":false,"description":"When true, scaffold the OUTSTANDING abstract methods the base owes, each as a compiling `override … //AI: complete method` stub (require-guarded params, guard-first return). Generic form: the base type's abstract methods with conceptual type parameters substituted (`Iterator of Integer` -> `next() as Integer`). Trait form: the traits' unimplemented abstract methods. Tuple form has no abstract obligations (no-op). Deduped against methods you already supply in `members` — only the missing ones are added. The result is a SCAFFOLD: bodies are placeholders behind `//AI:` markers, and the fresh variable's E08090 (not-yet-referenced) is tolerated so the dryRun is `ready`. Leave false to instead have the would-fail simply NAME the methods to add."},{"name":"traits","type":"array of object","required":false,"description":"Trait form: the traits to implement or delegate. Each {name, by?}. Order preserved."},{"name":"variableName","type":"string","required":true,"description":"Local variable that receives the instance (e.g. wrapper, iterator1). Emitted as `variableName <- …`."}],"lessons":["https://ek9.io/ide/create-dynamic-class.html"],"fixes":[],"example":{"scenario":"Conflict not function body","request":{"captures":[{"sourceExpression":"prefix"}],"file":"Dyn.ek9","insertAfterLine":2,"traits":[{"name":"Describable"}],"variableName":"w"},"response":{"conflicts":[{"kind":"target-not-function-body","message":"Line 2 is not inside a function, program or method body — a dynamic class has no host to live in there. Pick a line inside a callable body, after the captured variables are declared."}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Cannot insert dynamic class w — 1 conflict","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_create_dynamic_function","url":"https://ek9.io/mcp/ek9_create_dynamic_function.html","category":"editor","description":"Inserts `variableName <- (captures) is|extends Base as [pure] function` with its body (or an inline `(expr)`, or an //AI: stub) after the line; answers status, edits[] and summary, with a would-fail carrying the compiler's own diagnostics.","whenToUse":"'A closure gt over the captured min implementing discriminator' is one call with file, line (the line it goes after), variableName, baseType and bodyExpression.","whenNotToUse":["You need a trait implementation (with trait of T) or a tuple-style class - use ek9_create_dynamic_class.","You are authoring a NAMED, module-level reusable function - use ek9_new_construct mode:'function'.","You are factoring an existing block of code into a function - use ek9_extract_method; this tool creates from scratch."],"details":"Single-mode - the syntactic variant is derived from the args: body -> multi-line block; bodyExpression -> inline `(expr)` for a named base, promoted to block for a parameterised base (grammar makes `function` mandatory there); both omitted -> `//AI:` scaffold stub. pure and inheritanceKeyword (is|extends) auto-detect from the base (is + non-pure for a user base; extends + pure for a pure built-in super), both overridable. Conflict kinds: target-not-function-body (escalation - anchor line not inside a callable body), dynamic-body-not-supported (nesting inside a dynamic body, V1 refusal), bodyless-stub-needs-body (a no-return base like Consumer/Acceptor needs a body); everything else - base unresolved, purity mismatch, capture syntax E06230/E06240/E02040 - surfaces as the scratch-compile's own diagnostics (the fresh binding's expected E08090 is tolerated).","arguments":[{"name":"baseType","type":"string","required":true,"description":"The abstract function being implemented: a user-defined function name in scope, or a parameterised built-in (e.g. `Function of (Integer, String)`, `Predicate of Integer`, `Consumer of String`)."},{"name":"body","type":"string","required":false,"description":"Multi-line body. Mutually exclusive with bodyExpression. Refers to the base function's parameter names and its return-variable name. Omit BOTH body and bodyExpression to scaffold a `//AI: provide implementation` stub (block form + default-initialised inherited return) — supported only for a base that RETURNS a value; a no-return base (Consumer/BiConsumer/Acceptor/BiAcceptor) requires a body and a bodyless request is refused."},{"name":"bodyExpression","type":"string","required":false,"description":"Single-expression inline body (e.g. `rtn: number > threshold`). Mutually exclusive with body. For a NAMED base emitted inline as `(<expr>)`; for a PARAMETERISED base it is promoted to the block form (EK9's grammar makes the `function` keyword mandatory there)."},{"name":"captures","type":"array of object","required":false,"description":"Capture list (may be empty). Each entry: {fieldName?, sourceExpression}. Captures are by-pointer-value — mutating the captured object inside the closure is visible to the caller (copy via :=: before capture for isolation)."},{"name":"file","type":"string","required":true,"description":"The .ek9 source file containing the host body (workspace-relative; an absolute path inside the workspace is accepted)."},{"name":"inheritanceKeyword","type":"string: is | extends","required":false,"description":"`is` and `extends` are synonyms. Default: `extends` for a parameterised (generic) base, `is` otherwise."},{"name":"line","type":"integer","required":true,"description":"1-based line AFTER which the dynamic function is inserted (read it from ek9_read_file lineNumbers:true). Must be inside a function/program/method body and AFTER the captured variables are declared (a closure with captures cannot be hoisted above them)."},{"name":"pure","type":"boolean","required":false,"description":"Emit `as pure`. Default: auto — true for a pure built-in super (Predicate/Function/Consumer/...), false otherwise. Must match the base's purity or the scratch-compile reports a purity mismatch."},{"name":"variableName","type":"string","required":true,"description":"Local variable that receives the closure (e.g. gt, transformer, predicate1)."}],"lessons":["https://ek9.io/ide/create-dynamic-function.html"],"fixes":[],"example":{"scenario":"Parameterised inline promoted","request":{"baseType":"Predicate of String","bodyExpression":"r: t?","dryRun":true,"file":"Dyn.ek9","insertAfterLine":12,"variableName":"gt"},"response":{"conflicts":[],"edits":[{"after":"      gt <- () extends Predicate of String as pure function\n        r: t?","endLine":13,"file":"Dyn.ek9","startLine":13,"type":"insert"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"ready","summary":"Would insert dynamic function gt (extends Predicate of String, pure, block) at line 13","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_create_requirement","url":"https://ek9.io/mcp/ek9_create_requirement.html","category":"editor","description":"Writes the requirement nodes as flat markdown files under .ek9-ai/requirements/ (one atomic batch, each keyed by its frozen slug) and answers the editor envelope: status (applied | ready | conflicts), written, edits[] and summary naming the ids created.","whenToUse":"'Record a new requirement' is one call: {nodes:[{slug, title, body}]} for a root, add parentId:'REQ:x' for a child; several nodes naming each other make a whole subtree.","whenNotToUse":["Editing an existing node's body/title/position, or retiring or deleting it - use ek9_update_requirement (it cannot rename a slug: create a replacement here, then retire the old node with supersededBy).","Anchoring an EXISTING @Test program to a requirement - use ek9_anchor_test (ek9_add_program's requirementId covers only a freshly-scaffolded test)."],"details":"Slug is FROZEN at creation ([a-z0-9-]+) and is the key every @Test and parentId joins on; a collision against the derived id-set is REFUSED, never auto-suffixed — pick a distinctive slug and re-call. prefix is the closed set REQ/CTRL/CAP/CON, immutable once set; timestamps, version and changelog are server-stamped, never caller-supplied. Atomic: one bad node (invalid-slug, slug-collision, duplicate-in-batch, parent-not-found, parent-retired, batch-cycle) blocks the whole batch, and only the child file is ever written — parents are never edited.","arguments":[{"name":"dryRun","type":"boolean","required":false,"description":"When true nothing is written; the response shows the would-be edits with status:'ready'."},{"name":"nodes","type":"array of object","required":true,"description":"The requirements to create, in intended order. A member's parentId may name an existing requirement OR another member of this same batch, which is what lets a whole subtree be created in one call."},{"name":"terse","type":"boolean","required":false,"description":"Retained boolean alias for verbosity:'summary'."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size: full (default) carries each edit's full content; summary drops the edit bodies; none collapses edits[] to a count."}],"lessons":[],"fixes":[],"example":{"scenario":"Create requirement conflicts","request":{"nodes":[{"authorKind":"human","authorName":"Steve Limb","body":"# Intent\n\nFine.","slug":"perfectly-fine","title":"Fine"},{"authorKind":"human","authorName":"Steve Limb","body":"# Intent\n\nBad.","slug":"Not A Slug","title":"Bad"}]},"response":{"conflicts":[{"detail":"a slug must match [a-z0-9-]+ and the prefix must be from the closed registry","kind":"invalid-slug","subject":"Not A Slug"}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Would create nothing — 1 conflict(s); a create is atomic","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_debug_control","url":"https://ek9.io/mcp/ek9_debug_control.html","category":"execution","description":"Continues, pauses, steps or sets breakpoints in the current debug session; answers its new runState, sequence and stops.","whenToUse":"'Run on', 'pause' or 'step' the current debug session is one call: {action:'continue'} (also starts a debuggee waiting at its start), {action:'pause'}, {action:'stepOver'}, or {action:'setBreakpoints', file, lines}. Stop only when i == 6, on the 3rd hit, or print and run on: {action:'setBreakpoints', file, breakpoints:[{line, condition, hitCondition, logMessage}]}. Stop when a value changes: {action:'setDataBreakpoint', path}. Feed a program reading stdin: {action:'sendInput', text}, then {action:'endInput'} (Ctrl-D). Run on to a line: {action:'runTo', file, line}. A crash stops where it is thrown (uncaught, the default); {action:'setExceptionBreakpoints', stopOn:'all'|'none'}.","whenNotToUse":["Starting a session - use ek9_debug_session {action:'launch'}.","Running to a condition while collecting values - use ek9_debug_observe."],"details":"threadId picks the stopped thread to act on (default: the most recent stop). pause stops every thread running EK9 code where it is, each with a stop of its own (the main thread is the default after it); a thread already stopped keeps its stop; it ends an observation in progress. setBreakpoints replaces that file's breakpoints (removedBreakpoints names any it took away); a line still set keeps its id. Each of 'breakpoints' may have a condition (the typed condition ek9_debug_observe takes: comparison, setCheck, all, any), judged by field at each hit - never by running the program; a hitCondition {op:'==' | '>=' | '%', count} counting the hits where the condition held; a logMessage, printed with {path} replaced, which never stops. A condition that cannot be judged stops and says why. setDataBreakpoint watches the OBJECT the path reads in the stopped frame (frameId, default the top frame) through any variable, stopping once just after each change; a variable later pointed at another object is not followed, and every write to that field type slows while it is set. A step waits up to about 2 s for its landing stop; if the step runs on past that, wait with ek9_debug_session.","arguments":[{"name":"action","type":"string: continue | pause | stepOver | stepInto | stepOut | setBreakpoints | setDataBreakpoint | clearDataBreakpoint | sendInput | endInput | runTo | setExceptionBreakpoints","required":true,"description":"what to do."},{"name":"breakpoints","type":"array of object","required":false,"description":"setBreakpoints: breakpoints that say when they stop, with lines: {line, condition?, hitCondition?: {op, count}, logMessage?}."},{"name":"file","type":"string","required":false,"description":"setBreakpoints: the .ek9 file - its path from projectDir, or its name when unique."},{"name":"frameId","type":"integer","required":false,"description":"setDataBreakpoint: the frame the path is read in (default: the top frame)."},{"name":"id","type":"integer","required":false,"description":"clearDataBreakpoint: the data breakpoint's id."},{"name":"line","type":"integer","required":false,"description":"runTo: the line to run on to (with file)."},{"name":"lines","type":"array of integer","required":false,"description":"setBreakpoints: every line to break on in that file (empty clears them)."},{"name":"path","type":"string","required":false,"description":"setDataBreakpoint: the value to watch, read in the stopped frame: total, rex, names."},{"name":"stopOn","type":"string: none | uncaught | all","required":false,"description":"setExceptionBreakpoints: stop on an EK9 Exception or Panic where it is thrown - only when nothing in the program catches it (the launch default), every one, or none."},{"name":"text","type":"string","required":false,"description":"sendInput: what the program reads from stdin; a line ends with \\n, added when missing."},{"name":"threadId","type":"integer","required":false,"description":"the stopped thread to act on (default: the most recent stop)."}],"lessons":["https://ek9.io/ide/breakpoints-and-stepping.html","https://ek9.io/ide/breakpoint-conditions.html","https://ek9.io/ide/watches.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_debug_inspect","url":"https://ek9.io/mcp/ek9_debug_inspect.html","category":"execution","description":"Reads what runs recorded - a failure's account, where a value first went wrong, failing and passing runs compared, a report to share - and the current debug session by field (the recorded stop, a frame's locals, path values, the threads), never running the debuggee.","whenToUse":"After a journalled run or sweep: 'what led to the failure?' is {action:'leadingTo', hypothesis:'...'}; 'when did it first go wrong?' is {action:'firstWhere', condition:'total < 0', hypothesis:'...'}; 'what do the failing runs have that the passing ones do not?' is {action:'compare', hypothesis:'...'}; 'write it up for the team' is {action:'report', hypothesis:'...', finding:'the cause and fix, citing t5 and Orders.ek9:36'} - one page to share. At a stop: 'what is happening where it stopped?' is {action:'stop'}; {action:'evaluate', frameId, paths:['rex.legs', 'names[0]', 'total?']} reads values; {action:'locals', frameId} lists a frame's locals.","whenNotToUse":["Collecting values at every hit of a line - use ek9_debug_observe.","Static questions about the code - use ek9_query_construct or ek9_query_flow."],"details":"stop answers from the record made AT the stop, so it is exact even after the thread resumes (lastStop). locals and evaluate read the live frame and need the thread still stopped; frame ids are valid until it resumes. A path is name ('.' field | '[' index ']')* ('?')?; one that cannot be followed gives its reason, never a guess. leadingTo reads the run's change journal (the current session's run, or runId from the same project), never the live program, so it answers after the run has ended: the account is every change to the objects the symptom read - their owners' changes and where the value itself came from - with the inputs, the logged calls and earlier symptoms, oldest first; each line opens with its tick. Cite those ticks for every claim. envelope says what the account cannot hold (missed hits, gaps, steps past limit).","arguments":[{"name":"action","type":"string: stop | locals | evaluate | threads | leadingTo | firstWhere | history | routes | slice | compare | report","required":false,"description":"what to read; leadingTo, firstWhere, history, routes and slice reduce the run's change journal (history: every change to ONE object, named by its #N), compare (and routes with runs) several runs' journals; report writes those runs as a page to hand a person (index.html, and report.json with the same facts)."},{"name":"condition","type":"string","required":false,"description":"firstWhere: when the value is wrong, as a breakpoint condition: 'total < 0', 'not total?', 'total > 100 and before.total <= 100'; the property's name is its value after a change, before.<name> before it."},{"name":"failing","type":"string: uncaught | anySymptom | exitCode | changeCheck","required":false,"description":"compare, report: what makes a run a failing one (default uncaught: an Exception or Panic the program did not catch; changeCheck: its journal.changeCheck broke)."},{"name":"finding","type":"string","required":false,"description":"report: your conclusion - the cause and the fix - citing ticks (t5) and lines (Orders.ek9:36); shown as yours in the report's Finding, which the report never writes itself (default: none)."},{"name":"frameId","type":"integer","required":false,"description":"locals / evaluate: a frame id from a stop's frames; locals also takes a value's 'reference' and lists what it holds (a List's items, a Dict's values, an object's fields)."},{"name":"from","type":"integer","required":false,"description":"history, slice: the first tick to include."},{"name":"hypothesis","type":"string","required":false,"description":"leadingTo, firstWhere, history, routes, slice, compare: REQUIRED - what you expect the answer to confirm or refute, in a sentence; it is kept with the question."},{"name":"limit","type":"integer","required":false,"description":"leadingTo, history (compare: how many differences; routes: how many routes; slice: how many rows, the first): how many change steps to show, the most recent (default 40); the rest are counted in envelope."},{"name":"object","type":"string","required":false,"description":"history (required): whose changes to list - an object's identity #N as an earlier answer shows it, e.g. #4 from leadingTo's 't2 change #4.total 0 -> 100' (the owner) or a value's identity; the values one property took are its owner's changes to it."},{"name":"paths","type":"array of string","required":false,"description":"evaluate: paths such as 'total', 'rex.legs', 'names[0]', 'scores[\"bob\"]', 'total?'."},{"name":"projectDir","type":"string","required":false,"description":"leadingTo, firstWhere, history, routes, slice, compare: the project whose journals to read (default: the session's) - absolute, or relative to the workspace root. With it they answer after terminate, and in a server that never ran the session."},{"name":"property","type":"string","required":false,"description":"routes: one of the watched properties, by field ('total') or 'Type.field' (default: every one, each route tagged with its own)."},{"name":"runId","type":"string","required":false,"description":"leadingTo, firstWhere, history, routes, slice: another run's journal in the same project (default: the current session's run, or with projectDir and no session there, the most recent run)."},{"name":"runs","type":"array of string","required":false,"description":"compare, report: the run ids (default: the most recent 20 runs in this project journalling the same property of the same program); routes: the runs to count each route across (default: the one run)."},{"name":"symptom","type":"integer","required":false,"description":"leadingTo: the tick of the symptom to explain (default: the first uncaught exception, else the last symptom); the answer lists the others."},{"name":"to","type":"integer","required":false,"description":"history: the last tick to include; slice: the tick to stop BEFORE (required)."}],"lessons":["https://ek9.io/ide/book-game-journal.html","https://ek9.io/ide/watches.html","https://ek9.io/ide/journal-one-run.html","https://ek9.io/ide/journal-comparing.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_debug_observe","url":"https://ek9.io/mcp/ek9_debug_observe.html","category":"execution","description":"Runs the current debug session until a condition holds or the budget bites, reading the watched paths at every hit of the given lines; answers stoppedBecause, exact hits and the rows.","whenToUse":"'Run until total goes unset and show me how it got there' is one call: {points:[{file, line}], watch:['total','i'], until:{kind:'setCheck', path:'total', negated:true}, budget:{maxHits, maxWallClockMs}}. 'How did total become wrong?' is one call too, while stopped: {changesOf:['total'], budget} answers every change with before, after and the line that made it.","whenNotToUse":["Stopping at a line to look around - set a breakpoint with ek9_debug_session or ek9_debug_control.","Recording every write in a hot loop - that is the compiled-in probes' job, not a JDWP observation."],"details":"Starts the debuggee if it waits at its start, and resumes any stopped thread. until is optional (without it the observation runs to the budget or the program's end) and is {kind:'hits', count} or a v1 condition: {kind:'comparison', path, op (== <> < <= > >=), literal} or {kind:'setCheck', path, negated}. The literal's JSON type matters: a number compares with an Integer or Float, a string with a String or Character, true/false with a Boolean (3 and '3' differ). A comparison with an unset value is not met; a condition that cannot be judged ends the observation with the reason. budget is required: maxHits and maxWallClockMs (at most 95000). It ends on until, the budget, a user breakpoint (which still stops) or the program ending - stoppedBecause 'ended' when it finished with exit code 0, 'died' when it failed; ending at a hit leaves that thread stopped there. A point on a line with no code is refused, with the nearest lines that have code. hits is exact; rows keep the values of the first and last 10 hits unless keep says otherwise (at most 100 each), in the compact form unless format is 'records'.","arguments":[{"name":"budget","type":"object","required":true,"description":"required: {maxHits, maxWallClockMs} (maxWallClockMs at most 95000)."},{"name":"changesOf","type":"array of string","required":false,"description":"paths read where the program is stopped now ('total', 'counter'): every change to each is recorded - before, after, the line that made it, the thread - and never stops. With changesOf, points may be empty; the observation then ends with the budget or the program."},{"name":"format","type":"string: compact | records","required":false,"description":"compact: each row is {tick, values:[...]} in watch order, with what every row shares said once (a path unreadable at every hit is in 'unreadable' and 'absent' in the rows, one unreadable at some hits is {error}); records: each row is the full runtime-journal record (SPEC 3.2) with isSet and the object identity #N of every value, or {path, error} for a path it could not read."},{"name":"keep","type":"object","required":false,"description":"how many of the first and last hits keep their values (default {first:10, last:10}, each at most 100); hits stays exact whatever is kept."},{"name":"points","type":"array of object","required":false,"description":"EK9 source lines, each {file:'main.ek9', line:12}; the file is its path from projectDir ('orders/main.ek9'), or just its name when only one source has it."},{"name":"until","type":"object","required":false,"description":"optional - without it the observation runs until the budget bites or the program ends. {kind:'hits', count} or a condition: {kind:'comparison', path, op, literal} or {kind:'setCheck', path, negated}. literal is typed JSON: a number (100) for an Integer or Float, a string ('x') for a String or Character, true/false for a Boolean."},{"name":"watch","type":"array of string","required":false,"description":"paths to read at every hit: 'total', 'rex.legs', 'names[0]', 'scores[\"bob\"]', 'total?'."}],"lessons":[],"fixes":[],"example":{"scenario":"Until a condition","request":{"budget":{"maxHits":100,"maxWallClockMs":30000},"points":[{"file":"countdown.ek9","line":10}],"until":{"kind":"comparison","literal":4,"op":"==","path":"i"},"watch":["i","total"]},"response":{"completeness":"hits are exact; values kept for every hit","elapsedMs":"<timing>","hits":4,"meta":{"serverMs":"<timing>"},"msPerHit":"<timing>","nextStep":"ek9_debug_inspect {action:'stop'} to look at the thread stopped at the last hit","rows":[{"tick":1,"values":["1","0"]},{"tick":2,"values":["2","1"]},{"tick":3,"values":["3","3"]},{"tick":4,"values":["4","6"]}],"runId":"<timing>","runState":"stopped","sequence":"<sequence>","siteId":"countdown.ek9:10","status":"ok","stoppedBecause":"until","summary":"4 hit(s); stopped because until","thread":"main","truncated":false,"watch":["i","total"]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_debug_session","url":"https://ek9.io/mcp/ek9_debug_session.html","category":"execution","description":"Runs a program under the debugger - several inputs at once with a change journal (sweep), one run to its end, or step by step - and reports, waits on or ends THE debug session (one per server); answers status, runState, sequence, the stops, breakpoints and nextStep.","whenToUse":"'Why does this input fail when that one works?' is ONE call: {action:'sweep', inputs:[[<failing args>], [<passing args>]], journal:{property:'Type.field', hypothesis}} - every change to the value, on every object, recorded in each run, and the runs compared. 'Run it and tell me what happened' is ONE call too: {action:'launch', run:'toEnd', journal:{property, hypothesis}}. Neither stops the program; ek9_debug_inspect then reads the journals (leadingTo, compare, report). 'Debug this program' step by step starts with {action:'launch'} (breakpoints optional); the debuggee waits at its start until ek9_debug_control continues it or ek9_debug_observe runs it, and {action:'wait', since:N} returns when the session changes.","whenNotToUse":["Just running a program for its output - use ek9_run_program.","Running @Test programs - use ek9_run_tests."],"details":"One current session (no ids). launch builds the project with debug information in-process and starts the debuggee with a debug thread cap (maxThreads, default 64). wait blocks until the session's sequence moves past 'since' (by default the last sequence a debug tool answered), or its time limit (default 30 s, at most 100 s); the dispatcher is serial, so nothing else is served while it waits. Every time limit counts from when the call reached the server - a build, a launch and any wait behind another call included; an answer that queued says so (queued). An edit to any source of the jar ends the session (stale); 15 minutes without a debug call ends it too. sweep builds the project ONCE and runs it to its end once per input set, one after another, each with its own journal, within one time limit (timeoutMs, default and at most 100 s, for the whole sweep); sets it had no time for are listed as notRun, to sweep again. Every call is recorded in .ek9/debug-questions.jsonl.","arguments":[{"name":"action","type":"string: launch | status | wait | terminate | sweep","required":false,"description":"launch a new session, report it, wait for it to change, or end it; sweep runs the program once per input set and compares the runs."},{"name":"args","type":"array of string","required":false,"description":"launch: the program's arguments, as strings, one per parameter; a count that does not fit is refused, naming the parameters."},{"name":"breakpoints","type":"array of object","required":false,"description":"EK9 source lines, each {file:'main.ek9', line:12}; the file is its path from projectDir ('orders/main.ek9'), or just its name when only one source has it."},{"name":"env","type":"object","required":false,"description":"launch: environment variables for the debuggee only."},{"name":"failing","type":"string: uncaught | anySymptom | exitCode | changeCheck","required":false,"description":"sweep: what makes a run a failing one (default uncaught: an Exception or Panic the program did not catch; changeCheck: its journal.changeCheck broke) - as compare judges it."},{"name":"inputs","type":"array of array of string","required":false,"description":"sweep: the input sets, each the program's arguments as strings, one per parameter - every set is checked against the program before any run starts."},{"name":"journal","type":"object","required":false,"description":"launch, sweep: record every change to this property, on every instance, from the start of the run - before, after, the line and the EK9 stack that made it - into .ek9/debug-journal/<runId>.jsonl, never stopping the program. Caught at every line the compiler says can change it (ek9_query_references' writeSites); a store from any other line is recorded too, marked gap (gapNet). A line stops being journalled after siteCap hits (a capped row; capped in the answers), so a hot loop cannot use up the run's time. The answers carry journal:{file, changes, gaps, bySite, byRoute, missed}. Every row has a tick: cite the ticks of the rows that show each claim you make, and never infer a value from the code alone."},{"name":"maxThreads","type":"integer","required":false,"description":"launch: the debug thread cap - at most this many task threads alive (default 64)."},{"name":"program","type":"string","required":false,"description":"launch: module::Program (or a bare name only one program has) when the project declares several; a program that is not there is refused, listing the programs."},{"name":"projectDir","type":"string","required":false,"description":"Project root holding the .ek9 sources - absolute, or relative to the workspace root. Omit to use the workspace root itself (the first root ek9_compile was given)."},{"name":"run","type":"string: toEnd","required":false,"description":"launch: 'toEnd' starts it and answers once - when the program has ended (with the journal's counts and, if something failed, its leadingTo account), when a breakpoint of yours stops it, or at timeoutMs. Exceptions do not stop it unless stopOnExceptions is given; a journal records them as symptoms."},{"name":"seed","type":"integer","required":false,"description":"launch, sweep: the random seed the program's SystemRandom and OS.random draw from, so a run can be repeated exactly (a sweep gives every set the same one). Left out, one is chosen; every answer says which (seed), and a journal records it as an input row. To check a cause, launch again with the same seed and the suspected input changed."},{"name":"since","type":"integer","required":false,"description":"wait: the sequence to wait past (default: the last one a debug tool answered, so a stop that landed before the wait arrived is answered at once)."},{"name":"stopOnExceptions","type":"string: none | uncaught | all","required":false,"description":"launch: stop on an EK9 Exception or Panic where it is thrown - only when nothing in the program catches it, every one, or none."},{"name":"timeoutMs","type":"integer","required":false,"description":"wait: how long to wait (default 30000, at most 100000); launch with run: and sweep, for every run together (default and at most 100000). Counted from when the call reached the server."},{"name":"until","type":"string: all | firstFailure","required":false,"description":"sweep: run every set, or stop after the first failing run."}],"lessons":["https://ek9.io/ide/book-game.html","https://ek9.io/ide/breakpoints-and-stepping.html","https://ek9.io/ide/journal-investigations.html"],"fixes":[],"example":{"scenario":"Launch waits at its start","request":{"action":"launch","projectDir":"<workspace-root>"},"response":{"breakpoints":[],"meta":{"serverMs":"<timing>"},"nextStep":"ek9_debug_control {action:'continue'} to run it, or ek9_debug_observe to run and observe","runState":"waiting-to-start","seed":"<seed>","sequence":"<sequence>","started":false,"status":"ok","stopOnExceptions":"uncaught","stops":[],"summary":"launched; the debuggee waits at its start"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_delete_directory","url":"https://ek9.io/mcp/ek9_delete_directory.html","category":"editor","description":"Answers first: status (applied | ready | conflicts), written and edits[{file, type:delete, kind:directory}] - removes an EMPTY workspace directory, never a populated tree.","whenToUse":"You want an EMPTY directory gone - one call with path; a directory with any entry is refused (directory-not-empty), there is no recursive delete.","whenNotToUse":["Removing a FILE, not a directory - use ek9_delete_file (path).","Relocating the directory's contents rather than deleting the folder — use ek9_move_file.","Recursively deleting a POPULATED tree — deliberately unsupported; empty the directory first (ek9_delete_file / ek9_move_file per entry) then retry, or use shell rm -r / git rm -r outside this tool."],"details":"Empty-only is a HARD gate: any entry (including hidden/dot files) yields a directory-not-empty conflict (mechanical — empty the directory, then retry); there is no recursive/force mode. Workspace-bounded: the target must resolve inside a watched root and the root itself is refused. Errors: missing path, not-a-directory, outside-workspace, is-root, disk error.","arguments":[{"name":"dryRun","type":"boolean","required":false,"description":"When true nothing is deleted; the response shows the would-be deletion or the not-empty conflict."},{"name":"expectedWorkspaceHash","type":"string","required":false,"description":"The workspaceHash a prior dry run returned; a mismatch adds a drift warning (the delete still proceeds)."},{"name":"path","type":"string","required":true,"description":"Directory path: workspace-relative (preferred) or absolute inside the workspace. Must exist, be a directory, and not be the workspace root itself."},{"name":"terse","type":"boolean","required":false,"description":"Retained alias of verbosity:summary - prefer verbosity."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"full (default) returns the complete response; summary drops each edit's before/after bodies; none collapses edits[] to editCount."}],"lessons":["https://ek9.io/ide/project-files.html"],"fixes":[],"example":{"scenario":"Delete empty directory apply","request":{"path":"obsolete"},"response":{"conflicts":[],"edits":[{"file":"obsolete","kind":"directory","type":"delete"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Deleted empty directory obsolete","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_delete_file","url":"https://ek9.io/mcp/ek9_delete_file.html","category":"editor","description":"Answers first: status (applied | ready | conflicts | would-fail), written and, on a refusal, referenceCount + referencingFiles[] before the per-site conflicts[]; edits[{file, type:delete, disposition}].","whenToUse":"You want whole files gone - path for one, paths:[...] for several deleted together (references between files of the set do not count). A .ek9 file is refused while files outside the set still reference its constructs, or while the workspace has compile errors (the check cannot be trusted) - force:true deletes anyway, with warnings for what breaks. The refusal lists the referencing files as referencingFiles.","whenNotToUse":["Deleting ONE construct inside a file that has others you keep - use ek9_safe_delete (symbol:'Name', per-construct reference check).","Relocating rather than removing the file — use ek9_move_file.","Only wanting to KNOW the reference impact without deleting — use ek9_query_references.","Deleting a whole directory — use ek9_delete_directory (this tool rejects directories)."],"details":"Give exactly one of path (one file) or paths (several, judged as one set: a reference from a file of the set is not external; without force nothing is deleted unless every file can go, and files[] says where each stands - ready, conflicts, unchecked, error). Paths must resolve inside the workspace root; directories are rejected — files only. With compile errors and force false a .ek9 delete is refused (status:error) - force:true deletes, warning 'force-delete-references-unchecked'. For .ek9 files a per-construct reference sweep (same-file refs excluded) yields status:'conflicts' (kind 'file-has-external-references', with referenceCount and referencingFiles first) when external refs exist and force is false, or status:'would-fail' on a forced dry-run with wouldBeDiagnostics kind 'broken-reference-after-force-delete' (one per site); non-.ek9 files delete directly with no check. useTrash=true routes via the OS trash when supported, else falls back to permanent deletion with a 'trash-unsupported-fell-back-to-permanent' warning — otherwise deletion is irreversible unless version-controlled.","arguments":[{"name":"force","type":"boolean","required":false,"description":"When false (default), the .ek9 reference check refuses deletion if workspace references point at constructs in the file. When true, the deletion proceeds REGARDLESS of references — the response includes warnings listing every reference that will fail to resolve. Also deletes while the workspace has compile errors (the reference check cannot be trusted), with a warning saying so."},{"name":"path","type":"string","required":false,"description":"File path: workspace-relative (preferred) or absolute inside the workspace. Must exist and be a file (directories: ek9_delete_directory). Give path or paths, not both."},{"name":"paths","type":"array of string","required":false,"description":"Several files to delete TOGETHER, instead of path - each a file path, workspace-relative (preferred) or absolute inside the workspace. References between files of the set do not count; the answer has files[], one entry per file."},{"name":"useTrash","type":"boolean","required":false,"description":"When true AND the runtime supports trash semantics, the file is moved to the OS trash rather than permanently deleted. Falls back to permanent deletion with a warning otherwise."}],"lessons":["https://ek9.io/ide/project-files.html"],"fixes":[],"example":{"scenario":"Delete non ek9 file apply","request":{"path":"NOTES.txt"},"response":{"conflicts":[],"edits":[{"disposition":"permanent","file":"NOTES.txt","type":"delete"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Deleted NOTES.txt","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_deploy_package","url":"https://ek9.io/mcp/ek9_deploy_package.html","category":"execution","description":"Answers with status and bundlePath after packaging one package's SOURCE bundle, generating missing signing keys, and signing it locally; there is no remote repository to push to yet, so nothing leaves this machine.","whenToUse":"'Prepare this package for the registry' is one call with file:'package.ek9' and confirm:true. Today it packages, generates missing signing keys, and signs the bundle locally - there is no remote repository to push to yet, so nothing leaves this machine.","whenNotToUse":["Building the bundle with no signing - use ek9_package.","Installing into the LOCAL library rather than preparing a release - use ek9_install_package.","Bumping the version first - ek9_increment_version, then deploy."],"details":"Today's result never leaves this machine: there is no remote repository client yet, so the bundle and its signed hash are written under <project>/.ek9/ and nothing is uploaded. Pushes nothing anywhere (no registry parameter). Failures are named by stage - compile-failed (exit 8), tests-failed, coverage-low, timed-out after 120s, or a signing failure.","arguments":[{"name":"confirm","type":"boolean","required":true,"description":"Must be true: acknowledges this is the release step. Kept as a guard because the push, once a secure repository exists to push to, will make the package visible to every consumer and hard to retract; today's run never leaves this machine."},{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size. The default answers with status, summary and bundlePath; 'full' adds the CLI's stdout, argv, exitCode, elapsedMs and timedOut."}],"lessons":["https://ek9.io/ide/build-and-deploy.html"],"fixes":[],"example":{"scenario":"Missing confirm guard","request":{"file":"<workspace-root>/package.ek9"},"response":{"error":{"kind":"missing-confirmation","message":"Deployment is the release step - once a secure repository exists to push to, this becomes visible to every consumer and cannot be retracted; confirm must be true"},"meta":{"serverMs":"<timing>"},"nextStep":"re-call with confirm:true","status":"refused","summary":"refused: Deployment is the release step - once a secure repository exists to push to, this becomes visible to every consumer and cannot be retracted; confirm must be true"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_edit_file","url":"https://ek9.io/mcp/ek9_edit_file.html","category":"editor","description":"Answers first: status (applied | ready | would-fail | conflicts), written, edits[{file, startLine, endLine, before, after}], wouldBeDiagnostics from the verifying compile and contentHash on an applied edit - an atomic batch of text edits to one file, or to several as one apply.","whenToUse":"You want a few exact text changes in an EXISTING file - one call with path + edits:[{mode:'find-replace', find:'old', replace:'new'}]. The line-replace and regex-replace modes mix freely in the same atomic batch, and files:[{path, edits}] lands several files as one apply. Cheaper than ek9_write_file for small surgical changes; untouched bytes are preserved exactly.","whenNotToUse":["You hold the FULL content of the file (a new file, or an editor tool returned modifiedSource) - use ek9_write_file.","Renaming an EK9 identifier (class/method/field/local) — use ek9_rename_symbol; it rewrites the workspace-wide reference graph, this tool is text-only and single-file.","Structural EK9 edits (changing a signature, adding a method, extracting a variable) — use the semantic editor (ek9_change_signature, ek9_add_method, ek9_extract_variable, …); it understands EK9 grammar, this tool does not.","Removing the whole file — use ek9_delete_file."],"details":"find-replace is literal + case-sensitive (whitespace/indentation must match exactly - it is NOT re-indented), guarded by expectedOccurrences (integer, default 1, or 'all' — regex-replace shares the guard); line-replace takes 1-based inclusive startLine/endLine + replace (empty deletes) and a replacement written flush-left is re-indented to the replaced range's indentation (relative indentation kept; a later line shallower than the range is kept where written when only that compiles, said in corrected[]); a 'default operator X' line for a construct that already declares X is left out, and a find-replace whose find is gone because what it adds is already in the file is not applied - both said in corrected[] (nothing else to write is status:'unchanged'); regex-replace takes a Java pattern + replace with $1 backreferences. Every mode reads find/replace (replacement, replaceWith, newText, search, oldText and kind are accepted spellings). Edits apply sequentially (edits[1] sees edits[0]'s output) - a batch whose line-replace ranges were all numbered against the file as read, and fails in order but compiles applied bottom-up, is applied that way and says so in corrected[]; validation failures return status:'conflicts' (NO edits applied) with per-edit, mechanically repairable kinds — edit-position-out-of-range / find-not-found (carries a whitespace near-miss hint) / expected-occurrences-mismatch / cascading-edit-conflict / regex-invalid. Non-.ek9 targets are written without compile checking (non-ek9-file-not-compile-checked advisory); expectedContentHash gives whole-file lost-update protection.","arguments":[{"name":"edits","type":"array of object","required":false,"description":"Ordered edit operations, applied sequentially (edits[1] sees edits[0]'s output); one object per edit with mode + find/replace, or startLine/endLine + replace, or pattern + replace."},{"name":"expectedContentHash","type":"string","required":false,"description":"The contentHash ek9_read_file returned for the file's CURRENT content; the call is refused when the on-disk content differs (lost-update protection, same semantics as ek9_write_file)."},{"name":"files","type":"array of object","required":false,"description":"MULTI-FILE form: [{path, edits}] instead of path + edits - every file's edits are applied and the workspace compiled ONCE, so a change that only compiles when several files move together (a signature changed here, its callers there) lands as one atomic apply; any file failing rolls back all of them. Use it whenever a single-file edit would be rolled back for diagnostics in OTHER files."},{"name":"path","type":"string","required":false,"description":"File path: workspace-relative (preferred) or absolute inside the workspace. Must exist."}],"lessons":[],"fixes":[],"example":{"scenario":"Find equals replace unchanged","request":{"edits":[{"find":"stdout.println(report(100.0, 0.25))","mode":"find-replace","replace":"stdout.println(report(100.0, 0.25))"}],"path":"task.ek9"},"response":{"conflicts":[],"corrected":["edits[0]: its find and replace are the same text, so it changes nothing - nothing is written for it"],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"unchanged","summary":"Nothing to apply: task.ek9 already has what the edits would write","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_edit_localized_text","url":"https://ek9.io/mcp/ek9_edit_localized_text.html","category":"editor","description":"Rewrites the `defines text for \"<locale>\"` blocks of one text type in every locale that defines it (one atomic edit, so E07150 locale-completeness holds) and answers the editor envelope: status (applied | ready | would-fail | conflicts | error), written, edits[], summary, and translationDebt[] naming each {textType, locale, method} left placeholder-stubbed.","whenToUse":"'Add / change / remove a translatable text method or locale' is one call: pick mode (create-text-type, add-text-method, add-locale, update-text-method, remove-text-method, remove-locale) and name the textTypeName.","whenNotToUse":["Promoting a hard-coded string literal in EK9 source into a text method - use ek9_extract_to_localized_text (it rewrites the call site too).","Authoring a `defines class`/`record`/etc. - text is a distinct construct kind; use ek9_new_construct instead.","A regular method on a class/trait/component — text methods are localized-string bodies, structurally different; use ek9_add_method instead.","Changing an existing translated method's SIGNATURE — update-text-method rejects it (signature-change-not-allowed); do remove-text-method + add-text-method instead (ek9_change_signature cascades over type hierarchies, not locale groups).","Non-uniform locale coverage (one locale needs different params) — EK9 rejects this via E07150; author two separate text types by hand instead."],"details":"Enforcement of per-text-type locale completeness is the distinguishing trait: adding a method to one locale without the others fires E07150, so create / add-text-method / add-locale / remove-text-method succeed across every locale defining the text type or block entirely; update-text-method is the only per-locale-subset mode (signature immutable); remove-locale is module-wide, blocking on literal-locale constructor calls and on would-orphan-text-type (escalation — last defining locale). Text methods can overload - when methodName matches >1 overload you MUST supply parameters or it blocks with method-ambiguous-supply-params (candidateOverloads[] lists signatures); locale identifiers must match [a-z]+(_[A-Z]+)?. Auto-stubbed bodies emit a two-line placeholder (`//AI: translate the message` + empty `\"\"`) surfaced in translationDebt[], and update-text-method rewrites the whole method block, discarding in-body comments.","arguments":[{"name":"includeTextTypes","type":"array of string","required":false,"description":"For add-locale: limit the clone to these text types; omit for every text type referenceLocale defines."},{"name":"locale","type":"string","required":false,"description":"For remove-locale: the locale code to discontinue module-wide (e.g. fr, fr_FR, ja_JP) - every `defines text for \"<locale>\"` block matching it goes."},{"name":"methodBodies","type":"object","required":false,"description":"For add-text-method and update-text-method: locale -> body, e.g. {en_GB:'`Goodbye ${name}`', de:'`Auf Wiedersehen ${name}`'}; add-text-method stubs any locale left out, update-text-method leaves it alone."},{"name":"methodName","type":"string","required":false,"description":"For add-text-method: the new method's name; for update-text-method and remove-text-method: the existing method (supply parameters when the name is overloaded)."},{"name":"methods","type":"array of object","required":false,"description":"For create-text-type: the text methods to author, each {name, parameters, body}."},{"name":"mode","type":"string: create-text-type | add-text-method | add-locale | update-text-method | remove-text-method | remove-locale","required":true,"description":"Which operation to perform."},{"name":"module","type":"string","required":false,"description":"The module to operate on. Default: the first module that defines any text type; supply it when several modules carry i18n. Derived from targetFile when that is given."},{"name":"newLocale","type":"string","required":false,"description":"For add-locale: the locale to bring up (e.g. fr_FR) - every text type in referenceLocale gets a block, placeholder-stubbed."},{"name":"parameters","type":"array of any","required":false,"description":"For add-text-method: the new method's parameters, 'name as Type' each; for update/remove-text-method: the overload to pick when methodName is ambiguous."},{"name":"primaryLocale","type":"string","required":false,"description":"For create-text-type: the locale whose bodies are authored (e.g. en_GB); every other supportedLocale gets a placeholder-stubbed body listed in translationDebt[]."},{"name":"referenceLocale","type":"string","required":false,"description":"For add-locale: the existing locale whose text types and method signatures the new locale clones."},{"name":"supportedLocales","type":"array of string","required":false,"description":"For create-text-type: every locale to define the text type in, primaryLocale included (e.g. ['en_GB','de'])."},{"name":"targetFile","type":"string","required":false,"description":"Destination: the workspace-relative file the new text type lands in - required for create-text-type when no locale block exists yet. Optional for every other mode (they are workspace-wide and find the existing blocks through the module catalogue); supply it, or `module`, when the workspace has more than one module."},{"name":"textTypeName","type":"string","required":false,"description":"The text type (PascalCase) - the one to create for create-text-type, the existing one for add/update/remove-text-method; for add-locale and remove-locale see includeTextTypes / locale."}],"lessons":["https://ek9.io/ide/book-greetings.html","https://ek9.io/ide/book-greet.html","https://ek9.io/ide/book-env-greet.html","https://ek9.io/ide/book-order.html","https://ek9.io/ide/book-localisation.html","https://ek9.io/ide/localisations.html"],"fixes":[],"example":{"scenario":"Conflict unknown reference locale","request":{"mode":"add-locale","newLocale":"fr","referenceLocale":"es_ES","targetFile":"text.ek9"},"response":{"conflicts":[{"kind":"reference-missing","reason":"reference-locale-missing","suggestedRepair":"Pick a referenceLocale that already contains the text types you want to clone"}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Reference locale 'es_ES' contains no text types","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_exclude_transitive_dependency","url":"https://ek9.io/mcp/ek9_exclude_transitive_dependency.html","category":"editor","description":"Answers with the edit that adds an excludeDeps entry (module -> viaModule) to a 'defines package' block, blocking a transitive dependency a parent pulls in.","whenToUse":"'Block the transitive ek9open.bad.pack that ek9open.util pulls in' is one call with file:'package.ek9', module:'ek9open.bad.pack' and viaModule:'ek9open.util'.","whenNotToUse":["Declaring a direct runtime or dev dependency - use ek9_add_dependency.","Lifting an existing exclusion - use ek9_remove_transitive_exclusion.","The module is a DIRECT deps/devDeps entry, not a transitive - drop it with ek9_remove_dependency (this tool conflicts with 'direct-dependency-cannot-be-excluded-as-transitive').","The 'defines package' block does not exist yet - ek9_new_construct with mode:'package' first."],"details":"The excludeDeps Dict is created when absent; module is the KEY and viaModule the VALUE (the parent it arrives through, never a version), so there is at most one exclusion per transitive - to re-route via a different parent, ek9_remove_transitive_exclusion then re-add. Never returns would-fail: the dry run skips the scratch compile because exclusion validity is a resolver concern. Edits the source only - chain ek9_resolve_dependencies (it cleans the cache) to purge the cached transitive.","arguments":[{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"module","type":"string","required":true,"description":"The transitive module to block, e.g. 'ek9open.some.bad.dependency.pack' - the excludeDeps Dict key."},{"name":"viaModule","type":"string","required":true,"description":"The parent module whose dependency on 'module' is blocked, e.g. 'ek9open.org.supertools.util' - the excludeDeps Dict value (a module name, not a version)."}],"lessons":["https://ek9.io/ide/package-block.html"],"fixes":[],"example":{"scenario":"Exclude transitive dependency apply","request":{"file":"package.ek9","module":"ek9open.legacy.crufty.lib","viaModule":"ek9open.net.handy.tools"},"response":{"conflicts":[],"edits":[{"after":"      \"ek9open.legacy.crufty.lib\" : \"ek9open.net.handy.tools\",","endLine":15,"file":"package.ek9","startLine":15,"type":"insert"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Excluded transitive ek9open.legacy.crufty.lib (via ek9open.net.handy.tools)","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_expand_default_operator","url":"https://ek9.io/mcp/ek9_expand_default_operator.html","category":"editor","description":"Replaces the 'default operator' declaration with the explicit body the compiler would synthesise from the fields, ready to customise; answers status, edits[] and summary, a missing default line as conflicts[] (target-not-a-default-operator).","whenToUse":"'Expand Order's default operator <=> so I can customise it' is one call with symbol:'Order' and operator:'<=>' - omit operator to expand the bare block.","whenNotToUse":["Going the OTHER way - replacing an explicit operator body with the 'default operator' form (cleanup) - use ek9_collapse_to_default_operator.","The operator doesn't exist on the target yet (default OR explicit) - use ek9_add_operator to author from scratch.","The operator should be REMOVED entirely, not expanded - use ek9_safe_delete.","Operator outside the defaultable set (==, <>, <=>, <, >, <=, >=, $, $$, ?, #?, :=:) - no default form exists; author it with ek9_add_operator body:'explicit'."],"details":"Class / record / component targets with at least one field - traits and field-less constructs are refused (no properties to derive a body from). mode is inferred (operator → one, none → all); a contradicting mode is a mode-contradicts-arguments conflict. The 'after' body mirrors the compiler's synthesis: == ANDs each property's ==, <=> cascades to the first non-zero in declaration order (< <= > >= delegate to <=>), ? ANDs each _isSet, #? XORs each _hashcode, $ interpolates the fields, :=: copies each field; all emit 'as pure' except :=:, chaining via super.<op>(...) first when a real superclass declares the operator. Conflict kinds: target-not-a-default-operator (no such 'default operator' line - a hand-written body is changed with ek9_insert_statements), target-operator-not-supported-for-default; the all form skips operators already explicitly declared and errors when none remain.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"IDE refinement: the 1-based line of the 'default operator' declaration. Omit it - the declaration is found by symbol + operator."},{"name":"mode","type":"string: one | all","required":false,"description":"Optional - inferred: operator given → one, none → all."},{"name":"operator","type":"string","required":false,"description":"The one operator to expand, in EK9 source form ('==', '<=>', '$'). Omit it to expand the bare 'default operator' block into every defaultable operator."},{"name":"symbol","type":"string","required":true,"description":"The class, record or component holding the default operator - a bare name ('Order') finds its file workspace-wide; 'mod::Order' when the name is declared in two modules."}],"lessons":["https://ek9.io/ide/adding-members.html","https://ek9.io/ide/expand-default-operator.html"],"fixes":[],"example":{"scenario":"Single finds line by name apply","request":{"constructName":"Order","cursorLine":7,"file":"Order.ek9","mode":"single","operator":"$"},"response":{"conflicts":[],"edits":[{"after":"      operator $ as pure\n        <- rtn as String: `Order(${name})`","endLine":8,"file":"Order.ek9","startLine":8,"type":"replace"}],"meta":{"serverMs":"<timing>"},"resolvedPath":"<workspace-root>/Order.ek9","risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Expanded 'default operator $' to skeleton in Order","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_explain_error","url":"https://ek9.io/mcp/ek9_explain_error.html","category":"enquiry","description":"Returns the curated rich explanation for one EK9 error code - [DIAGNOSIS], [EXAMPLES] (as ek9_ask 'Q<id>' routes), the first example's source inlined as [WORKED EXAMPLE Q<id>], [ACTION], [SEE ALSO] and, when tooling is mapped, [REMEDIATION].","whenToUse":"'What does E07235 mean and how do I fix it' is one call with errorCode:'E07235' - the curated diagnosis, action steps and compilable examples. Take the code verbatim from ek9_compile / ek9_query_diagnostics; call once per distinct code before proposing a fix.","whenNotToUse":["What is currently broken in the workspace (the errors themselves) - use ek9_query_diagnostics.","A keyword, type or topic with no error code involved - use ek9_help.","Conceptual 'why does EK9 do X?' questions not tied to a code - use ek9_ask (also the fallback when a syntax error carries no code).","Priming a session with broad EK9 design rationale - use ek9_paradigm."],"details":"Exact lookup against the bundled rich-error corpus after normalisation: case, a missing 'E' and missing leading zeros are corrected and announced (e07235, E7235, 7235 all reach E07235); anything that is not digits after an optional E is a miss. A miss is an ERROR naming what a code looks like and where a real one comes from - syntax errors arrive with no code at all, so nothing invented for them will resolve. Sections beyond [DIAGNOSIS]/[ACTION]/[SEE ALSO] vary by code ([COMMON CAUSES]/[RATIONALE] are optional); [WORKED EXAMPLE Q<id>] inlines the first cited example's whole source when it is 60 lines or fewer (a longer one stays a pointer - ek9_ask 'Q<id>' returns it whole); [REMEDIATION] lists mapped MCP tools in recommended order, or a deliberate no-tool note. Pure static read - no workspace, no compile phase; identical output whether or not the workspace compiles.","arguments":[{"name":"errorCode","type":"string","required":true,"description":"The error code, E + 5 digits (e.g. 'E01010', 'E05030'); 'e5030' and '5030' are resolved to 'E05030'"}],"lessons":["https://ek9.io/ide/fixing-errors.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_extract_constant","url":"https://ek9.io/mcp/ek9_extract_constant.html","category":"editor","description":"Appends `name <- literal` to the module's `defines constant` block (created if absent) and replaces every occurrence of the literal in the file with the name; answers status, edits[] and summary with the occurrence count, a clashing name as conflicts[] (constant-name-collision).","whenToUse":"'Turn the magic \"Hello\" into a named constant' (the fix for E11065) is one call with file, literal:'\"Hello\"' and name:'greeting' - no line or column.","whenNotToUse":["The selection is NOT a single literal - a variable, call, or compound expression - use ek9_extract_variable.","The selection is an interpolated backtick string (`x is ${y}`) - a runtime expression, not a compile-time literal - extract the embedded expression with ek9_extract_variable.","You want to hoist an already-named local/expression to a constant rather than a raw literal - use ek9_promote_to_constant.","You just want existing scattered constants consolidated (E11066/E11067), not a new one extracted - use ek9_organize_constants."],"details":"Only a literal may be extracted (EK9 grammar `constantInitialiser : literal`): the selection must be one of the 18 Ek9LiteralTypes (Integer, Float, String, Money, Date, Colour, Duration, RegEx, …) and its exact source syntax is preserved verbatim (12.50#USD, #FF0000, PT2H). The literal is found at its first occurrence outside a comment (on 'line' when given); an IDE may pass the 1-based startColumn/endColumn pair instead. Placement appends to an existing `defines constant` block even when it lives in ANOTHER file (avoiding E11066/E11067 scattering; with 2+ blocks it picks the richest and attaches a 'constants-scattered' advisory), creating a block only when the module has none - so a changeset can span two files, though occurrence replacement covers the literal's OWN file only (V1). Conflict kinds: selection-is-not-a-literal, interpolated-string-not-constant, selection-is-already-a-constant, constant-name-collision; banned/placeholder identifiers are hard errors.","arguments":[{"name":"endColumn","type":"integer","required":false,"description":"1-based EXCLUSIVE column of the END of the span (an IDE selection). Omit it - pass the text instead."},{"name":"file","type":"string","required":true,"description":"The .ek9 source file holding the literal (workspace-relative; an absolute path inside the workspace is accepted)."},{"name":"line","type":"integer","required":false,"description":"Optional 1-based line of the occurrence to anchor on. Omit it - the literal text is enough."},{"name":"literal","type":"string","required":true,"description":"The literal exactly as written in the source, quotes included for a string ('\"Hello\"', '42', '12.50#USD'); its first occurrence is extracted and every occurrence in the file replaced."},{"name":"name","type":"string","required":true,"description":"Identifier for the new constant. Must not clash with an existing constant; placeholder names (temp/data/value/…) are rejected."},{"name":"startColumn","type":"integer","required":false,"description":"1-based column of the START of the span on 'line' (an IDE selection). Omit it - pass the text instead."}],"lessons":["https://ek9.io/ide/extract-constant.html"],"fixes":["E11064","E11065"],"example":{"scenario":"Extract constant terse dry run ready","request":{"constantName":"greeting","dryRun":true,"endColumn":29,"file":"magic.ek9","line":7,"startColumn":22,"terse":true},"response":{"conflicts":[],"edits":[{"endLine":7,"file":"magic.ek9","startLine":7,"type":"replace"},{"endLine":8,"file":"magic.ek9","startLine":8,"type":"replace"},{"endLine":3,"file":"magic.ek9","startLine":3,"type":"insert"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":3,"touchesPublicApi":false,"touchesTests":false},"status":"ready","summary":"Extract `\"Hello\"` to constant greeting (2 occurrences replaced, 3 edits)","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_extract_method","url":"https://ek9.io/mcp/ek9_extract_method.html","category":"editor","description":"Inserts the new method (parameters and return inferred from variable data-flow) and replaces the block with a call to it; answers status, edits[] and summary, an ambiguous or boundary-crossing block as conflicts[].","whenToUse":"'Pull this block of a method, function or program into computeSubtotal' is one call with file, fromText and toText (the block's first and last line as written - no line counting) and name; parameters and the return are inferred, and copies of the block in the same body become calls too.","whenNotToUse":["Extracting an EXPRESSION into a local - use ek9_extract_variable; a literal into a constants block - use ek9_extract_constant.","Extracting MEMBERS into a new trait rather than a code block - use ek9_extract_trait.","Writing a fresh method rather than lifting existing code - use ek9_add_method.","Turning a loop body into a stream pipeline - use ek9_advise_loop."],"details":"Parameters = outer-scope vars read/written in the block; return = a var produced in the block and read after (or the enclosing return var written in the block); 'as pure' whenever the new member compiles pure - the compiler's purity rules decide (printing through Stdout is pure in EK9; mutation and non-pure calls are not) - and always from a pure source member. Conflict kinds (all mechanical): 'return-type-ambiguous' (≥2 outflows, supply multiReturn=formal-record|formal-class|dynamic-class, AI-chosen from downstream intent), 'block-spans-control-flow' (multi-exit selection - narrow to one scope), 'variable-flows-in-and-out' (in-out accumulator - EK9 forbids param reassignment; narrow so the var is only-consumed or only-produced), 'extracted-block-references-outer-state'. V1 scope: member methods + top-level functions; containerName defaults to <Name>Result. A selection ending in the enclosing member's return line returns that member's whole result - the summary says so with the range without it; returnType:'Integer' takes that range when it returns the type asked for (corrected[]), else refuses (return-type-not-produced).","arguments":[{"name":"containerName","type":"string","required":false,"description":"Optional name for the synthesized container type (PascalCase). Defaults to <Name>Result."},{"name":"endLine","type":"integer","required":false,"description":"Or the last line of the block (inclusive, 1-based). Same body as startLine."},{"name":"file","type":"string","required":true,"description":"The .ek9 source file (workspace-relative; an absolute path inside the workspace is accepted)."},{"name":"fromText","type":"string","required":false,"description":"The block's FIRST line exactly as written (indentation ignored) - instead of counting startLine. Must name one line; add more of it when it occurs twice."},{"name":"multiReturn","type":"string: formal-record | formal-class | dynamic-class","required":false,"description":"When ≥2 values flow out of the block, the container shape that packages them into ONE return: 'formal-record' (top-level record, public fields, call site reads bundle.field), 'formal-class' (top-level class with accessor methods, bundle.field()), or 'dynamic-class' (inline captured class, no separate construct). Omit for a single value out; ≥2 out without it → return-type-ambiguous conflict listing these options. AI-directed: pick the shape from downstream intent (incidental bundle vs data carrier vs domain type)."},{"name":"name","type":"string","required":true,"description":"Name for the new method (camelCase)."},{"name":"replaceDuplicates","type":"boolean","required":false,"description":"Default true: every other copy of the selected statements in the same body that is PROVEN the same computation (same shape, names mapped one-to-one, same types, only the same value flowing out) is replaced with the call too; near misses are listed in duplicates[] with the reason, never replaced."},{"name":"returnType","type":"string","required":false,"description":"Optional: the type the new member returns ('Integer'). A selection ending in the enclosing member's 'rtn: ...' line returns that member's whole result; when that is not the type asked for, the one other reading - those trailing return lines stay where they are - is taken if it returns the type asked for (said in corrected[]), else refused naming what each reading returns."},{"name":"startLine","type":"integer","required":false,"description":"Or the first line of the block (inclusive, 1-based) - an IDE selection. Inside a method, function or program body."},{"name":"toText","type":"string","required":false,"description":"The block's LAST line as written - the first line matching it at or after fromText. Omit it for a one-line block."}],"lessons":["https://ek9.io/ide/extract-method.html"],"fixes":[],"example":{"scenario":"Name the lexer cannot read","request":{"dryRun":true,"file":"task.ek9","fromText":"count <- length prices","name":"count-prices"},"response":{"conflicts":[],"edits":[],"error":{"message":"Invalid identifier: 'count-prices' — must start with a letter and contain only letters, digits or '_'"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"Invalid identifier: 'count-prices' — must start with a letter and contain only letters, digits or '_'","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_extract_to_localized_text","url":"https://ek9.io/mcp/ek9_extract_to_localized_text.html","category":"editor","description":"Replaces the selected string literal with `<localeAccessor>.<name>(args)` and adds the text method to every locale of the i18n file in one atomic changeset, answering the editor envelope: status (applied | ready | would-fail | conflicts | error), written, edits[], summary and translationDebt[] naming the locales left placeholder-stubbed.","whenToUse":"'Move this hard-coded user-facing string into the i18n text type' is one call: {file, startLine, startColumn, endLine, endColumn (1-based) over the literal, textTypeName, name, localeAccessor}.","whenNotToUse":["The string is already in the i18n surface and you want to change a body - use ek9_edit_localized_text (update-text-method).","Greenfield i18n authoring with no source call-site to rewrite — use ek9_edit_localized_text (add-text-method / create-text-type).","The selection is a `+`-style concatenation (\"a\" + var + \"b\"), not a single literal — run ek9_rewrite_string_concat first to make it a backtick interpolation, THEN re-run this tool on the rewritten range.","The string is not user-facing (debug log, internal diagnostic, assert message) — leave it."],"details":"Parameter inference from `${...}`: simple ref → symbol name+type; property access (${p.x}) → receiver name+type; method call (${items.size()}) → return-type heuristic ('count'), receiver-name fallback - a parameters override must match the inferred COUNT and ORDER (types can widen, names can differ). textTypeName discovery is cross-module — resolved through the module's references block, so a centralized text type is found and extended, not duplicated. Conflicts are all mechanical and caller-repairable — notably selection-is-concat-not-literal (run ek9_rewrite_string_concat first), no-text-type-instance-in-scope, and i18n-file-supplied-for-existing-text-type (drop i18nFile — the existing block locations govern); when the type already spans multiple locales an omitted primaryLocale silently defaults to the first locale, so supply it. translationDebt[] lists the non-primary locales stubbed with the primary body plus an //AI: translate directive.","arguments":[{"name":"endColumn","type":"integer","required":false,"description":"1-based column of the literal's closing quote or backtick, inclusive."},{"name":"endLine","type":"integer","required":false,"description":"1-based line the literal ends on (the same line for a one-line literal)."},{"name":"file","type":"string","required":true,"description":"The .ek9 source file holding the literal - workspace-relative (absolute inside the workspace accepted)."},{"name":"i18nFile","type":"string","required":false,"description":"Destination: required when textTypeName does NOT yet exist in the module. Workspace-relative path where the new text type lands."},{"name":"localeAccessor","type":"string","required":true,"description":"Name of an existing variable in scope at the selection site whose type is the target text type. The rewritten call site becomes `<localeAccessor>.<name>(<args>)`."},{"name":"name","type":"string","required":true,"description":"Name for the new text method."},{"name":"parameters","type":"array of any","required":false,"description":"Optional override of the auto-inferred parameter signature. Supplied parameters must match the inferred count AND order; names can differ; types can widen."},{"name":"primaryLocale","type":"string","required":false,"description":"Required when textTypeName does NOT yet exist. Strongly recommended whenever the text type already exists in multiple locales."},{"name":"selection","type":"object","required":false,"description":"IDE alias for the four flat keys: {startLine, startCol, endLine, endCol}, 1-based inclusive."},{"name":"startColumn","type":"integer","required":false,"description":"1-based column of the literal's opening quote or backtick, inclusive."},{"name":"startLine","type":"integer","required":false,"description":"1-based line the string literal starts on."},{"name":"supportedLocales","type":"array of string","required":false,"description":"Optional for new text type creation."},{"name":"textTypeName","type":"string","required":true,"description":"Target text type (PascalCase). If it exists in the module, the method is added via add-text-method semantics internally. If it does not exist, the tool creates it."}],"lessons":["https://ek9.io/ide/book-greetings.html","https://ek9.io/ide/book-greet.html","https://ek9.io/ide/book-env-greet.html","https://ek9.io/ide/book-order.html","https://ek9.io/ide/book-localisation.html","https://ek9.io/ide/extract-to-localized-text.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_extract_trait","url":"https://ek9.io/mcp/ek9_extract_trait.html","category":"editor","description":"Appends a new 'defines trait' block declaring the chosen methods as abstract, adds 'with trait of <Name>' to the class header and 'override' to each method; answers status, edits[] and summary, a non-extractable member as conflicts[] (member-not-extractable-to-trait).","whenToUse":"'Pull validate out of CustomerOrder into a Validatable trait' is one call with symbol:'CustomerOrder', members:['validate'] and name:'Validatable'.","whenNotToUse":["Extracting a CODE BLOCK into a method on the SAME class, not a method into a trait - use ek9_extract_method.","The trait already EXISTS and you want to add its implementation on a class that declares it - use ek9_implement_methods.","The class should DELEGATE to a trait via a field ('with trait of T by field'), not BE the impl - use ek9_generate_delegation.","Promoting a method to a SUPERCLASS rather than a separate trait - use ek9_pull_up.","The member is private/protected - traits are public-only (E07270); raise visibility first with ek9_change_visibility, or keep it on the class."],"details":"Class targets only - records/components/functions error. A named method that is not a public, non-operator method of the class (not found, private/protected, an operator, or a field per E07075) returns status:'conflicts' (kind 'member-not-extractable-to-trait'), not an error. 'override' is always prepended on the class per E05120 - no opt-out; V1 appends the new 'defines trait' block to the SAME file, declaring the methods 'as abstract' (the class keeps its bodies).","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"members","type":"array of string","required":true,"description":"Names of PUBLIC methods on the class to extract into the trait."},{"name":"name","type":"string","required":true,"description":"The new trait's identifier (PascalCase by convention). Must not already exist in the file."},{"name":"symbol","type":"string","required":true,"description":"The class whose methods move to the trait - a bare name ('CustomerOrder') finds its file and declaration workspace-wide; 'mod::CustomerOrder' when the name is declared in two modules."}],"lessons":["https://ek9.io/ide/extract-trait.html"],"fixes":[],"example":{"scenario":"Non class error","request":{"file":"rec.ek9","line":6,"methods":["x"],"traitName":"HasPoint"},"response":{"conflicts":[],"edits":[],"error":{"message":"'Point' is a record — extract-trait targets classes only"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"'Point' is a record — extract-trait targets classes only","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_extract_variable","url":"https://ek9.io/mcp/ek9_extract_variable.html","category":"editor","description":"Inserts `name <- expression` before the first occurrence and replaces every matching occurrence in the enclosing block with the name; answers status, edits[] and summary, a side-effecting multi-occurrence expression as conflicts[].","whenToUse":"'Name the repeated items.sum() * taxRate as subtotal' is one call with file, expression:'items.sum() * taxRate' and name:'subtotal' - no line or column.","whenNotToUse":["A LITERAL that belongs in the module `defines constant` block - use ek9_extract_constant.","A multi-statement BLOCK of code, not a single expression - use ek9_extract_method.","The value should outlive the local - a class FIELD (use ek9_introduce_field) or a PARAMETER propagated to call sites (use ek9_introduce_parameter).","Collapsing an existing local back into its uses (the inverse) - use ek9_inline_variable."],"details":"Anchored by the outermost expression parse-node that EXACTLY spans the located text (its first occurrence outside a comment, on 'line' when given, or the IDE's 1-based startColumn..endColumn); a misaligned span returns status:'conflicts' (kind 'expression-spans-statement-boundaries'), a line outside any body is an error. Replacement is whitespace-insensitive and confined to the anchor's nearest enclosing instruction block (nested sub-blocks included). A call-bearing expression with multiple occurrences under replaceAll returns status:'conflicts' (kind 'expression-has-side-effects-and-multiple-occurrences' - the call would run once instead of N times); set replaceAll:false to take just the anchor; a name colliding in scope conflicts as 'name-collision'.","arguments":[{"name":"endColumn","type":"integer","required":false,"description":"1-based EXCLUSIVE column of the END of the span (an IDE selection). Omit it - pass the text instead."},{"name":"explicitType","type":"string","required":false,"description":"Optional. Emits `name as <Type>: expression` instead of the inferred `name <- expression` form."},{"name":"expression","type":"string","required":true,"description":"The expression exactly as written in the source ('base * base'); its first occurrence is the anchor."},{"name":"file","type":"string","required":true,"description":"The .ek9 source file (workspace-relative; an absolute path inside the workspace is accepted)."},{"name":"line","type":"integer","required":false,"description":"Optional 1-based line of the occurrence to anchor on. Omit it - the expression text is enough."},{"name":"name","type":"string","required":true,"description":"Identifier for the new local. camelCase by EK9 convention; placeholder names (temp/data/value/…) are rejected."},{"name":"replaceAll","type":"boolean","required":false,"description":"When true (default) replaces EVERY matching occurrence in the enclosing block; when false replaces only the located occurrence."},{"name":"startColumn","type":"integer","required":false,"description":"1-based column of the START of the span on 'line' (an IDE selection). Omit it - pass the text instead."}],"lessons":["https://ek9.io/ide/book-values.html","https://ek9.io/ide/extract-variable.html"],"fixes":["E11064"],"example":{"scenario":"Expression in two functions no line refused","request":{"expression":"price * rate","file":"task.ek9","name":"charge"},"response":{"conflicts":[],"edits":[],"error":{"message":"expression 'price * rate' is on lines [11, 18], in different bodies - pass line (one of [11, 18]) to say which one to extract."},"meta":{"serverMs":"<timing>"},"status":"error","summary":"expression 'price * rate' is on lines [11, 18], in different bodies - pass line (one of [11, 18]) to say which one to extract.","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_find_constructs_by_name","url":"https://ek9.io/mcp/ek9_find_constructs_by_name.html","category":"enquiry","description":"Answers first: matchCount, then matches[] (name, fullyQualifiedName, module, genus, file, line, column) - workspace-wide; matches:[] when no top-level construct has that name.","whenToUse":"Where is a construct named X declared (file, line, module) - one call with name:'X', or name:'Cust*' for a case-insensitive prefix.","whenNotToUse":["The construct's detail rather than its location - ek9_query_construct, ek9_query_type_hierarchy, ek9_query_effective_api and ek9_query_call_graph all take symbol:'X' directly, no lookup first.","A built-in language type (String, List, Optional, …) — those live in the language not the workspace; use ek9_help <Type> instead.","You already have file+line+column — no name lookup needed; use ek9_inspect_symbol_at_cursor.","Not a name lookup at all: free-text search over source content (comments, strings) is ek9_search_text; a whole-workspace overview is ek9_query_workspace."],"details":"Mode is selected purely by the value: exact case-sensitive match by default, case-insensitive prefix with a trailing `*` (a bare `*` is an error, not a list-all). Each match carries name, fullyQualifiedName (module `::` construct — preserve the `::` when chaining), module (always the DEFINING module; matches deduplicated by FQN), genus, file (workspace-relative), line and 0-based column. No matches is success with matchCount:0 and matches:[], never an error; requires the workspace to have reached SYMBOL_DEFINITION.","arguments":[{"name":"name","type":"string","required":true,"description":"Unqualified name to search for. Append `*` for case-insensitive prefix matching (e.g. \"Cust*\"). Without `*`, exact case-sensitive match."}],"lessons":[],"fixes":[],"example":{"scenario":"Find by exact name shape","request":{"name":"MyRecord"},"response":{"matchCount":1,"matches":[{"column":4,"file":"MyRecord.ek9","fullyQualifiedName":"com.example::MyRecord","genus":"RECORD","line":5,"module":"com.example","name":"MyRecord"}],"meta":{"serverMs":"<timing>"},"mode":"exact","query":"MyRecord","status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_find_inline_candidates","url":"https://ek9.io/mcp/ek9_find_inline_candidates.html","category":"enquiry","description":"Answers candidates[] (file, line, name, tier worth-inlining | safe, useCount) ranked slop-first, with counts{} - every local '<-' declaration in scope examined.","whenToUse":"'Which local temps add nothing over their initialiser' is one call, no arguments (fileFilter or module to scope it) - an empty list is a convergence signal.","whenNotToUse":["Applying the inline - use ek9_inline_variable to perform each transform.","Finding callables to DELETE (dead code) - use ek9_find_unused_code (the delete mirror).","A local with NO references - this tool skips those; use ek9_safe_delete instead."],"details":"Classified with VariableInliner.classify(), the SAME rules as the ek9_inline_variable transform, so every finding is actionable. Two tiers: 'worth-inlining' = a trivial initialiser (literal / bare name / dotted access, no call or operator) used EXACTLY once - a redundant temp; 'safe' = mechanically inlinable but the name may still document intent (non-trivial single use, a pure value reused, or trivial-but-multi-use, where inlining can trip magic-literal E11065). Never surfaced: control-flow guards, reassigned locals, multi-line initialisers, locals with no references, and call-bearing initialisers used more than once; needs only a PARSED workspace (run ek9_compile first), no call graph.","arguments":[{"name":"fileFilter","type":"string","required":false,"description":"Optional case-insensitive substring on the source path to scope the scan (per-file or per-directory). Omit to scan all source."},{"name":"module","type":"string","required":false,"description":"Optional exact module name to scope the scan (per-module). Omit to scan all modules."}],"lessons":["https://ek9.io/ide/inline-candidates.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_find_symbols","url":"https://ek9.io/mcp/ek9_find_symbols.html","category":"enquiry","description":"Answers first: symbolCount, symbolNames, withinNames (Type.method each belongs to), siteCount, byKind, byUse, sites as file.ek9:LINE - then each symbol (kind, within, declaredAt, renameable, counts) with its declared/read/written sites.","whenToUse":"Which symbols are NAMED like X, of which kinds, and where each is declared / read / written - one call: {name:'productId', kinds:['loop_variable']}. Pre-flight for a pattern rename (renameTo), a naming audit (kinds:['variables'], name:'tmp'), or 'is anything still reading X' after an edit.","whenNotToUse":["Every use of ONE symbol you can already name, with call structure, inferred-type uses and property writes by any route (alias, view, impure method) - ek9_query_references (symbol:'Type.member').","Text in comments and Strings - ek9_search_text.","Where a construct is declared, by name or prefix - ek9_find_constructs_by_name (lighter).","Applying a rename - ek9_rename_symbol (this tool only prepares the request)."],"details":"A name matches by 'match': exact (the whole name, default), contains, or regex (Java, tested against the name - anchor it yourself). caseSensitive defaults true; otherCaseNames lists what ignoring case would add. kinds take single kinds (class ... loop_variable) and the group words constructs / members / variables; default all. uses keeps only the declared / read / written sites and drops a symbol left with none. 'written' is the name assigned (':', ':=', '=', ':=?') or a mutating operator ('+=', ':=:', '++', ...) at that site - not the property write-site analysis (that is ek9_query_references). Scope: file, module (every file of it), or neither for the workspace; a symbol declared outside the scope but used in it is found with its in-scope sites. Built-ins are never returned. A construct carries fullyQualifiedName (module::Name); a member or variable carries within ('Order', 'OrderProcessor.processOrder'). Answers from the LAST compile: filesWithErrors lists the searched files that did not compile clean - names in their broken parts may be missing. Lines are 1-based, columns 0-based. renameTo returns renameRequest (the ek9_rename_symbol arguments, dryRun:true, the first symbol plus alsoRename) with each new name as the IDE gives it ('Count'->'Total' turns itemCount into itemTotal; regex may use $1); operators and constructors, and names left unchanged, are in renameSkipped.","arguments":[{"name":"caseSensitive","type":"boolean","required":false,"description":"Default true."},{"name":"file","type":"string","required":false,"description":"Scope: this one file. Omit file and module for the whole workspace."},{"name":"kinds","type":"array of string: class | record | trait | component | function | abstract_function | enumeration | type | text | service | program | application | property | method | operator | constructor | parameter | return | local | loop_variable | guard | capture | constant | constructs | members | variables","required":false,"description":"Kinds to find: single kinds and/or the groups constructs, members, variables. Default all."},{"name":"match","type":"string: exact | contains | regex","required":false,"description":"exact (whole name, default), contains (anywhere in the name), or regex (Java, against the name)."},{"name":"maxSymbols","type":"integer","required":false,"description":"Default 200, max 2000. The answer is the first maxSymbols symbols; a cut one says truncated:true and moreSymbols (how many more)."},{"name":"module","type":"string","required":false,"description":"Scope: every file of this module."},{"name":"name","type":"string","required":true,"description":"The name pattern - matched against symbol NAMES, never comments or Strings."},{"name":"renameTo","type":"string","required":false,"description":"Also return renameRequest - the ek9_rename_symbol arguments renaming every symbol found. Nothing is applied."},{"name":"sourceLines","type":"boolean","required":false,"description":"Give each site its source line (text). Default false."},{"name":"uses","type":"array of string: declared | read | written","required":false,"description":"Which sites: declared, read, written. Default all three."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"full (default): each symbol with its sites; summary: each symbol without its sites; none: the headline alone."}],"lessons":[],"fixes":[],"example":{"scenario":"Case sensitive other case names","request":{"kinds":["members"],"match":"contains","name":"count"},"response":{"basis":"last compile","byKind":{},"byUse":{},"fileCount":0,"filesWithErrors":[],"meta":{"serverMs":"<timing>"},"nextStep":"caseSensitive:false also finds itemCount","note":"No property/method/operator/constructor named containing 'count' in the workspace (from the last compile).","otherCaseNames":["itemCount"],"siteCount":0,"sites":[],"status":"not-found","symbolCount":0,"symbols":[]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_find_unused_code","url":"https://ek9.io/mcp/ek9_find_unused_code.html","category":"enquiry","description":"Answers first: deadNames and deadByOwner (owner -> its dead members), complete workspace-wide - then each finding classified.","whenToUse":"'What can I delete' / 'which methods of X are never called' is one call, no arguments - every construct, method and constant nothing reaches, by owner.","whenNotToUse":["Checking usage of ONE specific symbol, not a whole-workspace scan - use ek9_query_references.","Actually removing a construct once found unused - use ek9_safe_delete.","You want compiler errors/warnings (incl. unused-parameter E08091/E11018), not the reachability scan - use ek9_query_diagnostics.","You want the inventory of EXISTING constructs, not the unused subset - use ek9_query_workspace."],"details":"Covered kinds: 'construct' (dead top-level functions) + 'method' (dead methods/constructors); 'field'/'reference' return empty+note (not yet wired), 'parameter' is compiler-owned (E08091/E11018). Each finding carries reachability (dead|production-dead|test-helper|dead-test|untested-public-api), recommendation (delete|relocate-to-test|none|add-test), definedIn, reachedBy, reason and ONE nextStep (for 'delete' the literal ek9_safe_delete(symbols:[...]) call); a dead callable still called names its callers in calledOnlyFrom - each itself dead, deleted with it by that nextStep; library-aware - with no production roots (programs/service operations) the tests are the root set, while application mode adds ungroundedTests[] (@Test programs whose closure never touches production code a release runs). Requires the workspace to reach PRE_IR_CHECKS (where the call graph is built); below that the tool errors rather than guessing.","arguments":[{"name":"among","type":"array of string","required":false,"description":"Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched)."},{"name":"excludePublic","type":"boolean","required":false,"description":"When true, excludes public-visibility findings (intentional library API). Default false. Useful when scanning a library."},{"name":"fileFilter","type":"string","required":false,"description":"Optional source-file substring to scope the scan. Omit to scan all source."},{"name":"kind","type":"string: all | construct | method | constant | field | reference | parameter","required":false,"description":"Filter by what kind of unused code to find. Default 'all'. 'construct' = dead top-level functions; 'method' = dead members (methods/constructors); 'constant' = a 'defines constant' entry nothing references (each finding carries the ek9_safe_delete call). 'field'/'reference' are not yet covered (empty + note); 'parameter' is owned by the compiler (E08091/E11018)."}],"lessons":["https://ek9.io/ide/unused-code.html"],"fixes":[],"example":{"scenario":"Scan kind parameter note","request":{"kind":"parameter"},"response":{"byKind":{},"deadByOwner":{},"deadNames":[],"deadNamesCover":"every construct, method and constant no program or test reaches - workspace-wide, nothing to verify","findings":[],"meta":{"serverMs":"<timing>"},"note":"Unused parameters are already a compile error in EK9 (E08091 / E11018) — the compiler owns this; nothing for the scan to report.","reachabilityComplete":true,"scanCount":0,"status":"empty"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_fix_purity_contract","url":"https://ek9.io/mcp/ek9_fix_purity_contract.html","category":"editor","description":"Adds or removes 'as pure' on the callable the diagnostic names, with the override cascade applied; answers status, edits[] and summary, the horizontal cascade as advisories[] and a mode/diagnosis mismatch as conflicts[].","whenToUse":"The compiler reported E05150 / E05160 / E08130 - 'fix the purity contract' is one call with file and the diagnostic's line; mode is inferred except for E08130.","whenNotToUse":["Proactively deciding a function should be pure (no compile error yet) - use ek9_change_signature's change-purity mutation.","Purity change is part of a broader signature edit (params / return type / purity together) - use ek9_change_signature.","The real fix is to factor pure logic out from impure logic - use ek9_extract_method, then re-run this on the residual error."],"details":"Modes: make-callee-pure / remove-pure-from-caller (E08130, opposite intents - pick by whether the callee body is genuinely pure-eligible; omitting mode there is a mode-required conflict listing both); add-pure-to-override (E05150) and remove-pure-from-override (E05160) are inferred when omitted. Conflicts gate the fix: no-purity-error-at-line, target-not-method-or-function, callee-not-resolvable; for E08130 modes an override anchor is refused (override-cascade-blocks-fix, pointing at the contract root) and an oversized transitive blast radius as cascade-too-large. The vertical override cascade is applied automatically; sub-threshold horizontal cascade sites come back as a purity-cascade advisory (chain this tool per site), and cascade-too-large is a design call - extract a pure core or pick the opposite mode.","arguments":[{"name":"column","type":"integer","required":false,"description":"IDE cursor offset (0-based) on 'line'. Omit it - pass symbol instead."},{"name":"file","type":"string","required":false,"description":"The .ek9 source file with the purity diagnostic (workspace-relative; an absolute path inside the workspace is accepted). Optional when symbol names the callable."},{"name":"line","type":"integer","required":false,"description":"1-based line the compiler flagged (the diagnostic's own line). Omit it and pass symbol for an override (E05150/E05160), whose declaration IS the flagged line."},{"name":"mode","type":"string: make-callee-pure | remove-pure-from-caller | add-pure-to-override | remove-pure-from-override","required":false,"description":"The fix direction. Optional for E05150 (add-pure-to-override) and E05160 (remove-pure-from-override) - inferred from the diagnostic; required for E08130: make-callee-pure or remove-pure-from-caller."},{"name":"symbol","type":"string","required":false,"description":"The flagged callable - 'Shape.area' or a bare function name finds its file and declaration workspace-wide; with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/purity-contract.html"],"fixes":["E05150","E05160","E08130"],"example":{"scenario":"No purity error conflicts","request":{"file":"c.ek9","line":5,"mode":"make-callee-pure"},"response":{"conflicts":[{"kind":"no-purity-error-at-line","message":"No purity error (E08130 / E05150 / E05160) at c.ek9:5 — this tool is reactive; run it on the exact line the compiler flagged."}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Cannot fix purity contract - 1 conflict","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_format","url":"https://ek9.io/mcp/ek9_format.html","category":"editor","description":"Rewrites the file in canonical EK9 style (indentation, spacing, blank-line and line-break conventions); answers status, edits[] (one per changed line) and summary, an unparseable file as conflicts[] (source-not-parseable).","whenToUse":"'Reformat customer.ek9 to canonical style' is one call with file - the whole file is re-rendered, never a region, and nothing the code does changes.","whenNotToUse":["Checking whether the code is VALID (types/references/errors), not just styled - use ek9_compile; format is structure only.","Asking what is wrong (compile errors / warnings) - use ek9_query_diagnostics.","Targeted find/replace edits to specific lines rather than a whole-file re-render - use ek9_edit_file."],"details":"Deterministic and idempotent: format-twice yields byte-identical output. edits[] carries one REPLACE per changed line, INSERT per added line, DELETE per removed line, and doubles as a training signal for canonical EK9 style. A file that does not parse is repaired first where each fault has exactly one reading (tabs, indent width, shebang, comma-separated parameters, ...), each repair in corrected[]. The only conflict kind is 'source-not-parseable' (a syntax error with no one-reading repair - resolve via ek9_compile first).","arguments":[{"name":"file","type":"string","required":true,"description":"The .ek9 source file to format (workspace-relative; an absolute path inside the workspace is accepted)."}],"lessons":["https://ek9.io/ide/comments-and-format.html"],"fixes":[],"example":{"scenario":"Format dry run shape","request":{"dryRun":true,"file":"seed.ek9"},"response":{"conflicts":[],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"ready","summary":"File seed.ek9 is already canonical - no changes","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_generate_delegation","url":"https://ek9.io/mcp/ek9_generate_delegation.html","category":"editor","description":"Rewrites the class header's 'with trait of <Trait>' clause to '... by <field>' so the compiler forwards every trait method (no bodies generated); answers status, edits[] and summary.","whenToUse":"'Forward every Processor method of DelegatingProcessor to its inner field' is one call with symbol, traitName:'Processor' and delegate:'inner'.","whenNotToUse":["The class does NOT yet declare the trait at all - use ek9_adopt_trait with delegateFieldName, which appends 'with trait of <Trait> by <field>' in one step.","The delegate field doesn't exist yet - add it first with ek9_add_field, then call this.","You want stub bodies to fill in rather than compiler-generated forwarding - use ek9_implement_methods (mode=stubs).","You want to override ONE trait method's behaviour - wire delegation here first, then ek9_add_method for the explicit override (it shadows the forwarded method)."],"details":"Modifies ONE line - the class declaration - because 'by' attaches to the trait reference at class-declaration time, not per-method (per-method 'name by field' syntax does not exist). status:'error' for validation failures: target not a class, class declares no traits, trait not declared on the class, ambiguous trait name, delegate field missing, trait already delegated, or a malformed class-header line (the grammar keeps the whole header on one physical line, so a multi-line clause cannot occur). A non-conforming delegate field type is NOT blocked - the tool proceeds and notes it; a genuine mismatch surfaces as status:'would-fail' from the whole-workspace verify (never 'conflicts'; no banned-identifier check since the field already exists).","arguments":[{"name":"delegate","type":"string","required":true,"description":"The name of an existing field on the class to delegate to. Its declared type should implement the trait (the compile gate confirms)."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":true,"description":"The class that declares the trait - a bare name ('DelegatingProcessor') finds its file and declaration workspace-wide; 'mod::Name' when the name is declared in two modules."},{"name":"traitName","type":"string","required":true,"description":"The trait already declared on the class via 'with trait of'. Simple name (Processor) when unambiguous; fully-qualified (com.acme::Processor) when needed."}],"lessons":["https://ek9.io/ide/generate-delegation.html"],"fixes":[],"example":{"scenario":"Delegate field missing","request":{"delegate":"nope","file":"processors.ek9","line":16,"traitName":"Processor"},"response":{"conflicts":[],"edits":[],"error":{"message":"delegate field 'nope' not found on class 'DelegatingProcessor'"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"delegate field 'nope' not found on class 'DelegatingProcessor'","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_generate_dispatcher","url":"https://ek9.io/mcp/ek9_generate_dispatcher.html","category":"editor","description":"Inserts the '<name>() as dispatcher' entry with its fallback body plus one same-named handler overload per subtype of the base type; answers status, edits[] and summary naming any existing handlers kept.","whenToUse":"'Give ShapeProcessor a describe() dispatcher over Shape' is one call with symbol:'ShapeProcessor', name:'describe' and baseType:'Shape'.","whenNotToUse":["Adding ONE method rather than a dispatcher + handler set - use ek9_add_method.","Registering a NEW subtype on the sealed base (not generating handlers) - use ek9_add_to_sealed_allowlist.","INSPECTING existing dispatcher tables, not generating new ones - use ek9_query_dispatchers.","The dispatcher CLASS does not exist yet - create it with ek9_new_construct first, then run this on it."],"details":"Class targets only (errors on record/trait/component); handlers REUSE the entry's name - overload-by-parameter-type IS the dispatch mechanism (E05260), there is no '<name>For<Subtype>' convention. The entry is concrete: its guard-first fallback body ('require' guard, '//AI:' marker, and for a returning dispatcher '<- rtn as T?' assigned only after the guard) is also the runtime default when no handler matches; sealed base → one handler per 'allow only' subtype (compiler enforces exhaustiveness), non-sealed base → known concrete subtypes only with the fallback covering the rest (errors if none known). Never returns 'conflicts': an existing dispatcher on the class (E07820) or a same-named non-dispatcher method taking the base type is an error; an existing per-subtype handler is silently skipped and named in the summary.","arguments":[{"name":"additionalParameters","type":"array of any","required":false,"description":"Optional extra parameters added to BOTH the entry and every handler, after the auto-added subtype parameter; each ONE item as DATA - {name:'code', type:'Integer'} - never a {name} and a {type} as two items, and never with '->' or '<-' in it; the tool writes the arrows and the layout. ('code as Integer' is also accepted.) A malformed item is rejected before anything is rendered."},{"name":"baseType","type":"string","required":true,"description":"The type the dispatcher dispatches on. If SEALED, its 'allow only' subtypes drive handlers (exhaustive); if NON-SEALED, its known concrete subtypes do (entry fallback covers the rest). Fully-qualified (com.acme::Animal) when needed; simple name when unambiguous."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"name","type":"string","required":true,"description":"The dispatcher method name (e.g. describe, sound, route). ALL generated handlers share this exact name."},{"name":"returnType","type":"string","required":false,"description":"Optional shared return type for the entry + every handler. Omit for a void dispatcher."},{"name":"symbol","type":"string","required":true,"description":"The class the dispatcher is scaffolded on - a bare name ('ShapeProcessor') finds its file and declaration workspace-wide; 'mod::Name' when the name is declared in two modules."},{"name":"visibility","type":"string: private | public | protected","required":false,"description":"The handlers' access (default 'private' - handlers are implementation details). The entry is always public."}],"lessons":["https://ek9.io/ide/generate-dispatcher.html"],"fixes":["E05260"],"example":{"scenario":"Non class target","request":{"baseType":"Shape","dispatcherMethodName":"describe","file":"shapes.ek9","line":6,"returnType":"String"},"response":{"conflicts":[],"edits":[],"error":{"message":"'Shape' is a trait - a dispatcher lives on a class only"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"'Shape' is a trait - a dispatcher lives on a class only","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_generate_edge_case_tests","url":"https://ek9.io/mcp/ek9_generate_edge_case_tests.html","category":"execution","description":"Writes a compile-checked edge-case @Test program file for one .ek9 source and answers status (applied | ready | unchanged | blocked | error), written, testCount, the echoed seed and modifiedFiles[] - every harvested constructor, method, operator and function gets the tri-state UNSET value among its inputs.","whenToUse":"'Give this file systematic edge-case tests' is one call: {file:'account.ek9', outputFile:'dev/account_tests.ek9'} sprays type-aware edge values (always UNSET) over every public surface.","whenNotToUse":["ONE specific test you already know how to write - use ek9_add_program(isTest:true).","You already have tests and just want to run them - use ek9_run_tests.","The counterexample + a paste-ready directed test for ONE function at a cursor - use ek9_verify_method (this tool's mode:'verify' is its whole-file dual).","Business-logic / contract assertions the generator can't infer - hand-author the test."],"details":"Two modes share one compile-filter/assemble/write engine: 'edge' is type-aware fuzz (seed echoed - pass it back to reproduce a survivor set; maxResults defaults 200), 'verify' is deterministic (seed/maxResults ignored). The editor envelope: applied (written:true) | ready (dryRun, written:false) | unchanged (reason no-candidates or no-counterexamples - nothing to write) | blocked (output-exists / output-not-dev-source / no-testable-symbols / source-compile-failed / invalid-test-module / outside-workspace) | error (write-failed, or assembled-compile-failed where the file IS written for inspection, written:true). Intent-dependent set-state asserts carry an //AI-REVIEW marker. The GENERATION is workspace-independent: each call compiles the source against a fresh builtins-only program, so no prior ek9_compile is needed - but file/outputFile PATH RESOLUTION is not: once a workspace is initialised (ek9_compile) a relative path resolves against its first root and one outside every root is refused; with no workspace initialised, only absolute paths are accepted (the given path is the only anchor).","arguments":[{"name":"dryRun","type":"boolean","required":false,"description":"Default false. Preview only: harvest, generate, compile-filter and assemble exactly as a real run, but write NOTHING. Returns status 'ready' with testCount and the full fileContent that a committing call would write. Re-invoke without dryRun to commit. Use this to check testCount > 0 before writing."},{"name":"file","type":"string","required":true,"description":"The .ek9 source file to generate tests for - absolute, or relative to the first workspace root once one is initialised (ek9_compile); with no workspace, only an absolute path works. Refused when it resolves outside every workspace root. (The GENERATION itself runs against a fresh builtins-only program, not the workspace's compiled one.)"},{"name":"includeGeneratedTests","type":"boolean","required":false,"description":"Default false. When true, include a compact [{name, description}] index of the surviving tests for inline curation (full bodies are written to outputFile)."},{"name":"maxResults","type":"integer","required":false,"description":"Max candidate tests to generate before compile-filtering; testCount will be <= this."},{"name":"mode","type":"string: edge | verify","required":false,"description":"Default 'edge' — spray type-aware edge values (fuzz). 'verify' — run bounded-model verification per function and synthesise a directed test for each counterexample (seed/count are ignored in this mode)."},{"name":"outputFile","type":"string","required":true,"description":"Destination: the generated test file - absolute, or relative to the workspace root exactly as 'file' is; refused when it resolves outside every workspace root. MUST be a dev source — under a 'dev/' subdirectory or a QA####_dev_ filename — because the generated @Test/assert constructs only compile there (E81015); a non-dev path is blocked. Also blocked if it already exists unless overwrite:true."},{"name":"overwrite","type":"boolean","required":false,"description":"Default false. Replace outputFile if it exists."},{"name":"seed","type":"integer","required":false,"description":"Reproducibility seed. Default: random (always echoed in the response). Pass the echoed seed back to regenerate the exact same survivor set after a source edit."},{"name":"targets","type":"array of string","required":false,"description":"Optional. Restrict generation to these construct names (types and/or functions, e.g. [\"Location\"]). Tests are generated ONLY for the named constructs, but nested arguments still use the full source for fidelity. Omit or empty = all testable constructs."},{"name":"testModule","type":"string","required":false,"description":"Module to declare the generated @Test programs in. Omit to DETECT: whichever module already holds tests referencing the source's module wins, else a conventional '<sourceModule>.tests' if the project has one, else the source's own module. When it differs from the source's module the file gains an alphabetically-ordered references block (E11026) and its edge-value constants are de-duplicated against that module, not the source's. Validated when supplied: an illegal module name is rejected up front with status 'blocked' / reason 'invalid-test-module'. Note a segment may not be a reserved keyword EK9 excludes from moduleSegment — 'some.other.mod' is illegal ('mod' is an operator), 'some.other.place' is fine."},{"name":"verbose","type":"boolean","required":false,"description":"Default false. Verbose compiler reporting."}],"lessons":["https://ek9.io/ide/book-testing.html","https://ek9.io/ide/edge-case-tests.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_generate_signing_keys","url":"https://ek9.io/mcp/ek9_generate_signing_keys.html","category":"execution","description":"Answers with keysGenerated and publicKeyPath after ensuring the user-global signing keypair (~/.ek9/private.pem + public.pem) that ek9_deploy_package signs with exists; an existing pair is never overwritten.","whenToUse":"'Set up the signing keys for this machine' is one call with no arguments. A once-per-developer or once-per-CI-environment step; ek9_deploy_package does it itself when the keys are missing, so it is rarely needed explicitly.","whenNotToUse":["Signing and publishing a package - use ek9_deploy_package (it generates missing keys).","Bumping a package version before publishing - use ek9_increment_version."],"details":"No parameters; -Gk takes no source file. The keys are a user-global 1024-bit RSA pair at ~/.ek9/private.pem and ~/.ek9/public.pem, reused by every project on the machine; to rotate, delete the two .pem files and re-call. keysGenerated is true only when the pair did not exist before the call and exists after it; a generation failure is status:bad-arguments (exit 2) with the CLI's stderr.","arguments":[{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size. The default answers with status, summary, keysGenerated and publicKeyPath; 'full' adds the CLI's stdout, argv, exitCode, elapsedMs and timedOut."}],"lessons":["https://ek9.io/ide/build-and-deploy.html"],"fixes":[],"example":{"scenario":"Generate shape","request":{},"response":{"keysGenerated":false,"meta":{"serverMs":"<timing>"},"publicKeyPath":"~/.ek9/public.pem","status":"ok","summary":"signing keys already present - not regenerated"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_add","url":"https://ek9.io/mcp/ek9_git_add.html","category":"execution","description":"Reports stagedPaths and stagedPathCount (what this call staged), then indexAfter and indexAfterCount (everything now staged) and a summary line.","whenToUse":"'Stage these files for the next commit' - one call with paths:[...] or all:true; the first step of stage, commit, push. Staging copies the CURRENT content, so edits made afterwards need staging again.","whenNotToUse":["recording the staged changes - use ek9_git_commit (its paths:[...] stages and commits in one call).","seeing what is staged, modified or untracked - use ek9_git_status.","undoing a mis-stage - use ek9_git_restore mode:'unstage'."],"details":"stagedPaths / stagedPathCount are what THIS call staged; indexAfter / indexAfterCount are the whole index afterwards, so one call can never be read as having staged the earlier entries. At least one of paths / all is required; a path outside the workspace, a path git cannot find, or a non-git workspace is refused with the route in nextStep.","arguments":[{"name":"all","type":"boolean","required":false,"description":"Stage every change including deletions (git add -A). Default false."},{"name":"paths","type":"array of string","required":false,"description":"Workspace-relative paths to stage."}],"lessons":["https://ek9.io/ide/git-basics.html"],"fixes":[],"example":{"scenario":"Named path into existing index","request":{"paths":["new.txt"]},"response":{"all":false,"indexAfter":["new.txt","tracked.txt"],"indexAfterCount":2,"meta":{"serverMs":"<timing>"},"stagedPathCount":1,"stagedPaths":["new.txt"],"status":"staged","summary":"Staged 1 path; the index now holds 2 paths","written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_blame","url":"https://ek9.io/mcp/ek9_git_blame.html","category":"enquiry","description":"Answers first: lineCount and the range, then one record per line (line, sha, author, email, date, subject, text); verbosity:'summary' collapses them to same-commit runs.","whenToUse":"'Who wrote this line, in which commit?' - one call with path; startLine/endLine narrow the slice, ref blames an older revision. The regression-hunting primitive.","whenNotToUse":["the commits that touched the file - use ek9_git_log.","the content of one commit - use ek9_git_diff with ref:'<sha>'.","a file's current content with no authorship - use ek9_read_file."],"details":"Headline first: status, summary, path, ref (HEAD unless given), lineCount, commitCount (distinct shas), rangeStart/rangeEnd; then lines[]. verbosity:'summary' collapses consecutive same-commit lines into runs[] {fromLine, toLine, sha, author, date, subject} without the text. Refusals: a file git does not track (file-not-tracked), a binary file, an unknown ref, an inverted range.","arguments":[{"name":"endLine","type":"integer","required":false,"description":"1-based last line of the slice, inclusive (with startLine)."},{"name":"path","type":"string","required":true,"description":"Workspace-relative path of a tracked file."},{"name":"range","type":"object","required":false,"description":"IDE alias: the same slice as one object {startLine, endLine}."},{"name":"ref","type":"string","required":false,"description":"Commit, tag or branch to blame at. Default HEAD."},{"name":"startLine","type":"integer","required":false,"description":"1-based first line of the slice to blame (with endLine). Default: the whole file."}],"lessons":["https://ek9.io/ide/git-history.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_branch","url":"https://ek9.io/mcp/ek9_git_branch.html","category":"enquiry","description":"Answers first: current, branchCount and branchNames, then per-branch records (name, current, upstream, ahead/behind, gone, sha).","whenToUse":"'Which branches exist, what am I on?' - one call, no arguments; pattern:'feature/*' filters, includeRemote:true adds remote-tracking branches.","whenNotToUse":["moving to or creating a branch - use ek9_git_switch.","the working-tree state of the current branch - use ek9_git_status.","commit history - use ek9_git_log."],"details":"Headline first: status, summary, current, branchCount and branchNames; then branches[] as {name, current, upstream, ahead, behind, gone, sha} - ahead/behind only with an upstream, gone:true when that upstream no longer exists, sha the 8-hex short form shared with ek9_git_log and ek9_git_blame. verbosity:'summary' keeps the names and drops the records.","arguments":[{"name":"includeRemote","type":"boolean","required":false,"description":"Also list remote-tracking branches (origin/...). Default false."},{"name":"pattern","type":"string","required":false,"description":"Glob (* and ?) matched against the short branch name, e.g. 'feature/*'. Default: every branch."}],"lessons":["https://ek9.io/ide/git-basics.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_commit","url":"https://ek9.io/mcp/ek9_git_commit.html","category":"execution","description":"Reports newSha and previousSha, branch, subject, changedFiles and changedFileCount; local history only, nothing is published until ek9_git_push.","whenToUse":"'Commit this' - one call with message; paths:[...] stages and commits in one step, all:true stages tracked edits, amend:true rewrites the last commit. The middle step of stage, commit, push.","whenNotToUse":["publishing to the remote - use ek9_git_push.","staging without recording - use ek9_git_add.","checking what would be committed - use ek9_git_status."],"details":"message is required unless amend:true (then omitted = keep the previous message). all:true stages tracked modifications only - a new file needs paths or ek9_git_add. Shas are the 8-hex short form shared across the family. A clean index is refused as nothing-to-commit with the route; a missing user.name/user.email is git's own refusal, surfaced under error.message.","arguments":[{"name":"all","type":"boolean","required":false,"description":"Stage every tracked modification first (git commit -a); untracked files are not included. Default false."},{"name":"amend","type":"boolean","required":false,"description":"Rewrite the previous commit instead of creating a new one. Default false."},{"name":"message","type":"string","required":false,"description":"Commit message. Required unless amend:true, which then keeps the previous commit's message."},{"name":"paths","type":"array of string","required":false,"description":"Workspace-relative paths to stage before committing (stage + commit in one call)."}],"lessons":["https://ek9.io/ide/git-basics.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_diff","url":"https://ek9.io/mcp/ek9_git_diff.html","category":"enquiry","description":"Answers first: summary, fileCount, additions/deletions and changedFiles names, then per-file hunks with fromLine/toLine and the unified-diff text (dropped at verbosity:'summary').","whenToUse":"'What did I change?' - one call, no arguments for the working tree; scope:'staged', ref:'<sha>' for one commit, or from/to for a range. Narrow to a file or directory with path.","whenNotToUse":["the list of changed files with their state - use ek9_git_status.","commit messages, authors and dates - use ek9_git_log.","per-line authorship of a file - use ek9_git_blame.","a file's current content - use ek9_read_file."],"details":"Headline first: summary, scope, fromRef/toRef, fileCount, additions, deletions and the changedFiles names; then files[] as {file, change, additions, deletions, hunks[]} with change one of modified / added / deleted / renamed / copied and each hunk carrying fromLine/fromCount/toLine/toCount plus the unified-diff text. verbosity:'summary' keeps the per-file counts and drops the hunks. ref is the one-commit shorthand for scope:'commit' + from.","arguments":[{"name":"contextLines","type":"integer","required":false,"description":"Unchanged lines around each hunk. Default 3."},{"name":"from","type":"string","required":false,"description":"Start ref for scope:'range' (with to), or the commit for scope:'commit'."},{"name":"path","type":"string","required":false,"description":"Workspace-relative file or directory to narrow the diff to. Default: everything."},{"name":"ref","type":"string","required":false,"description":"One commit to show (sha, tag, HEAD~1) - shorthand for scope:'commit' with from."},{"name":"scope","type":"string: working | staged | range | commit","required":false,"description":"What to compare. Default working (working tree vs HEAD); staged (index vs HEAD); commit (one commit vs its parent, needs ref or from); range (from..to)."},{"name":"to","type":"string","required":false,"description":"End ref for scope:'range'."}],"lessons":["https://ek9.io/ide/git-history.html"],"fixes":[],"example":{"scenario":"Working tree hunks","request":{"scope":"working"},"response":{"additions":1,"changedFiles":["tracked.txt"],"deletions":0,"fileCount":1,"files":[{"additions":1,"change":"modified","deletions":0,"file":"tracked.txt","hunks":[{"diff":"@@ -1,2 +1,3 @@\n v1\n v2\n+v3-added\n","fromCount":2,"fromLine":1,"toCount":3,"toLine":1}],"status":"M"}],"fromRef":"HEAD","meta":{"serverMs":"<timing>"},"scope":"working","status":"ok","summary":"1 file changed, +1 -0 (working tree vs HEAD)","toRef":"WORKING"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_fetch","url":"https://ek9.io/mcp/ek9_git_fetch.html","category":"execution","description":"Reports updated, upstream, behind and ahead, a summary line and a nextStep when behind; git's own report under gitReport.","whenToUse":"'Is there anything new upstream?' - one call, no arguments; updates remote-tracking refs only and reports behind/ahead without touching the working tree. The safe pre-flight before ek9_git_pull.","whenNotToUse":["integrating the upstream commits into the branch - use ek9_git_pull.","the local working-tree state (no network) - use ek9_git_status.","history already present locally - use ek9_git_log."],"details":"Safe by construction: fetch only advances remote-tracking refs (origin/main, ...) so it cannot conflict or leave a half-done tree. updated is true when git reported ref updates; upstream/behind/ahead appear only when the current branch has an upstream and match ek9_git_status exactly; gitReport is git's own report. Refusals: no-remote (add one first), timed-out.","arguments":[{"name":"allRemotes","type":"boolean","required":false,"description":"Fetch every remote (--all) instead of one. Default false."},{"name":"prune","type":"boolean","required":false,"description":"Drop remote-tracking refs deleted on the remote (--prune). Default false."},{"name":"remote","type":"string","required":false,"description":"Remote name. Default origin."}],"lessons":[],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_init","url":"https://ek9.io/mcp/ek9_git_init.html","category":"execution","description":"Reports branch and gitignoreCreated (a .gitignore for the generated .ek9/ directory is scaffolded when absent); refuses when already a repository.","whenToUse":"'Put this project under git' - one call, no arguments; the only ek9_git_* tool valid outside a repository (the answer to not-a-repository). The optional branch names the initial branch, default main.","whenNotToUse":["a project already under git - use ek9_git_status.","the first commit after init - use ek9_git_add then ek9_git_commit.","cloning an existing remote - not supported (there is no clone tool)."],"details":"written:true with branch, gitignoreCreated (an existing .gitignore is never clobbered) and a nextStep for the first commit. The only parameter is the optional initial branch (default main).","arguments":[{"name":"branch","type":"string","required":false,"description":"Initial branch name. Default main."}],"lessons":[],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_log","url":"https://ek9.io/mcp/ek9_git_log.html","category":"enquiry","description":"Answers first: commitCount and commitTotal with a truncation note, then commits (sha, author, date, subject, body, parents; files with includeFileList:true).","whenToUse":"'What commits touched this file, since when, by whom?' - one call; path, author, since/until, from/to and maxResults are all optional. Pass allBranches:true to log every ref in topological order for a graph view.","whenNotToUse":["who wrote a particular line - use ek9_git_blame.","the content of a change - use ek9_git_diff with ref:'<sha>'.","the current working-tree state - use ek9_git_status."],"details":"A cut result opens with truncated:true and a truncationNote naming the call that restores it; then status, summary, branch (null with allBranches:true), commitCount (commitTotal only when truncated), filtersApplied echoing every filter sent, and commits[] as {sha, author, email, date, subject, body, parents} with 8-hex shas, plus files[] when includeFileList:true. from/to must be paired and AND-compose with since/until. verbosity:'summary' drops body and files from each commit.","arguments":[{"name":"allBranches","type":"boolean","required":false,"description":"Log every ref in topological order (the full DAG) instead of one branch. Default false."},{"name":"author","type":"string","required":false,"description":"Author name or email substring."},{"name":"branch","type":"string","required":false,"description":"Branch or ref to log from. Default: the current HEAD."},{"name":"from","type":"string","required":false,"description":"Range start ref (pair with to)."},{"name":"includeFileList","type":"boolean","required":false,"description":"Attach files[] to each commit. Default false."},{"name":"maxResults","type":"integer","required":false,"description":"Most commits to return. Default 50, limit 1000."},{"name":"path","type":"string","required":false,"description":"Workspace-relative file or directory - only commits touching it."},{"name":"since","type":"string","required":false,"description":"Commits on or after - a date (2026-09-01) or git's relative form ('2 weeks ago')."},{"name":"to","type":"string","required":false,"description":"Range end ref (pair with from)."},{"name":"until","type":"string","required":false,"description":"Commits on or before - a date (2026-09-01) or git's relative form ('yesterday')."}],"lessons":["https://ek9.io/ide/git-history.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_merge","url":"https://ek9.io/mcp/ek9_git_merge.html","category":"execution","description":"Reports status and outcome (already-up-to-date, fast-forward, clean-merge or conflict), newSha/previousSha, commitsMerged, changedFiles and conflictFiles; a conflicting merge aborts with the tree restored.","whenToUse":"'Merge feature-x into this branch' - one call with branch; dryRun:true predicts the outcome and the conflicting files without merging. Use mode:'merge-commit' to keep the branch visible in the graph, mode:'ff-only' to refuse a real merge.","whenNotToUse":["integrating the REMOTE upstream - use ek9_git_pull mode:'merge'.","just moving to the branch - use ek9_git_switch.","undoing a commit - use ek9_git_revert."],"details":"outcome shares one vocabulary between preview and apply: already-up-to-date / fast-forward / clean-merge / conflict (conflict only in a preview - the real merge aborts it). Apply status: merged / fast-forward / already-up-to-date with dryRun:false; preview status: ready / conflicts / unchanged with dryRun:true (an in-memory merge-tree, git 2.38+). A dirty tree is refused (dirty-tree); a conflicting merge is aborted with treeRestored:true. noFastForward:true is the IDE alias of mode:'merge-commit'.","arguments":[{"name":"branch","type":"string","required":true,"description":"The local branch to merge into the current branch."},{"name":"dryRun","type":"boolean","required":false,"description":"Predict the outcome, the changed and the conflicting files without merging. Default false."},{"name":"message","type":"string","required":false,"description":"Merge-commit message. Default: git's own."},{"name":"mode","type":"string: auto | merge-commit | ff-only","required":false,"description":"Default auto (fast-forward when possible, else a merge commit); merge-commit always records one (--no-ff); ff-only refuses when a merge commit would be needed."},{"name":"noFastForward","type":"boolean","required":false,"description":"IDE alias of mode:'merge-commit'."}],"lessons":["https://ek9.io/ide/git-history.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_pull","url":"https://ek9.io/mcp/ek9_git_pull.html","category":"execution","description":"Reports commitsPulled, newSha and previousSha, changedFiles and changedFileCount; a dirty tree is refused and a rebase/merge conflict is aborted with the tree restored.","whenToUse":"'Get the latest from upstream' - one call, no arguments; the default mode:'ff-only' never conflicts, mode:'rebase' or 'merge' when the branch has diverged. Operates on the current branch.","whenNotToUse":["checking what is upstream without changing the branch - use ek9_git_fetch.","a dirty working tree - commit (ek9_git_commit) or stash (ek9_git_stash) first; pull refuses it and never auto-stashes.","publishing local commits - use ek9_git_push."],"details":"status is one of up-to-date / fast-forward / rebased / merged; commitsPulled and changedFiles cover previousSha..HEAD; shas are the 8-hex short form; default remote origin. mode:'ff-only' only advances the pointer, and on divergence is refused so you choose mode:'rebase' (linear, rewrites local shas - never on already-pushed commits) or mode:'merge' (records a merge commit). A dirty tree is refused (dirty-tree); a rebase/merge conflict is aborted with treeRestored:true, never a half-done state.","arguments":[{"name":"mode","type":"string: ff-only | rebase | merge","required":false,"description":"How to integrate. Default ff-only (advance the pointer only, never conflicts); rebase (linear, rewrites local shas); merge (records a merge commit)."},{"name":"remote","type":"string","required":false,"description":"Remote name. Default origin."}],"lessons":["https://ek9.io/ide/git-basics.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_push","url":"https://ek9.io/mcp/ek9_git_push.html","category":"execution","description":"Reports remote, branch, upstream, upToDate and a summary line, with git's own report under gitReport; outward-facing and not trivially reversible, so confirm intent first.","whenToUse":"'Publish my commits' - one call, no arguments for the current branch to origin; setUpstream:true on a new branch's first push. The last step of stage, commit, push and outward-facing: confirm intent before calling.","whenNotToUse":["changes not yet committed - use ek9_git_commit first.","checking ahead/behind before publishing - use ek9_git_status or ek9_git_fetch.","undoing an already-pushed commit - use ek9_git_revert, never amend plus force."],"details":"Defaults: remote origin, the current branch. force:true is --force-with-lease (refuses to clobber un-fetched upstream work); a bare --force is deliberately not exposed. Refusals name the route: no-remote (add one), rejected (ek9_git_fetch then ek9_git_pull, then push again), timed-out.","arguments":[{"name":"branch","type":"string","required":false,"description":"Branch to push. Default: the current branch."},{"name":"force","type":"boolean","required":false,"description":"Replace the remote branch with --force-with-lease (refuses when the remote moved since the last fetch). Default false."},{"name":"remote","type":"string","required":false,"description":"Remote name. Default origin."},{"name":"setUpstream","type":"boolean","required":false,"description":"Set the upstream tracking ref (-u) - the first push of a new branch. Default false."}],"lessons":["https://ek9.io/ide/git-basics.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_restore","url":"https://ek9.io/mcp/ek9_git_restore.html","category":"execution","description":"Reports mode, paths and pathCount and a summary line; ref restores content from that commit instead of the index or HEAD.","whenToUse":"'Unstage this' or 'throw away my edits' - one call with paths:[...]; mode:'unstage' (default, safe) or mode:'discard' (destructive). Pass ref to restore the content from that commit instead.","whenNotToUse":["undoing a commit that is already made - use ek9_git_revert.","staging changes - use ek9_git_add (this tool is its inverse).","moving between branches - use ek9_git_switch.","seeing what is staged or modified first - use ek9_git_status."],"details":"mode:'unstage' takes the paths out of the index and leaves the working tree alone; mode:'discard' overwrites the working tree from the index (or from ref); mode:'both' does both from HEAD. discard is a one-way door for edits made outside the workspace tools. The IDE aliases staged:true / worktree:true map to unstage / discard; sending them alongside a contradicting mode is refused. An untracked path is refused as path-not-tracked with the route.","arguments":[{"name":"mode","type":"string: unstage | discard | both","required":false,"description":"Default unstage (take out of the index, keep the working-tree edits); discard (overwrite the working-tree edits - DESTRUCTIVE); both."},{"name":"paths","type":"array of string","required":true,"description":"Workspace-relative paths to restore."},{"name":"ref","type":"string","required":false,"description":"Commit to restore content from. Default: the index for discard, HEAD for unstage."},{"name":"staged","type":"boolean","required":false,"description":"IDE alias: true means mode:'unstage'."},{"name":"worktree","type":"boolean","required":false,"description":"IDE alias: true means mode:'discard' (with staged:true, mode:'both')."}],"lessons":[],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_revert","url":"https://ek9.io/mcp/ek9_git_revert.html","category":"execution","description":"Reports newSha, revertedSha, previousSha, branch, subject, changedFiles and changedFileCount; a conflicting revert aborts with the tree restored.","whenToUse":"'Undo that commit safely' - one call with ref (a sha, HEAD, a tag); records a NEW inverse commit, so it is safe on already-pushed history. For a merge commit add mainline (the parent to keep, usually 1).","whenNotToUse":["changes not yet committed - use ek9_git_restore.","fixing the LAST commit when it is not pushed - use ek9_git_commit amend:true.","moving branches - use ek9_git_switch."],"details":"ref is verified first (rev-parse) so an unknown ref is refused before any mutation (ref-not-found, with ek9_git_log as the route); a merge commit without mainline is refused (mainline-required), mainline on a non-merge likewise. A revert that hits conflicts is aborted with treeRestored:true - never a half-done state. Shas are the 8-hex short form shared across the family.","arguments":[{"name":"mainline","type":"integer","required":false,"description":"For a merge commit only: the parent number to keep (usually 1). Omit for an ordinary commit."},{"name":"ref","type":"string","required":true,"description":"The commit to revert - a short or full sha, HEAD, a tag or any ref."}],"lessons":[],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_stash","url":"https://ek9.io/mcp/ek9_git_stash.html","category":"execution","description":"Reports status (stashed, popped, applied, dropped or nothing-to-stash) and the stash ref; mode:'list' returns stashCount and stashes; a conflicting pop keeps the entry (stashPreserved:true).","whenToUse":"'Set my changes aside for now' - one call with mode:'push' (or pop, apply, list, drop); never runs automatically, every stash move is explicit. The answer when ek9_git_switch or ek9_git_pull refused a dirty tree.","whenNotToUse":["work that is finished - record it with ek9_git_commit.","throwing the changes away - use ek9_git_restore mode:'discard'.","seeing what is dirty - use ek9_git_status."],"details":"mode:'push' parks the changes (message and includeUntracked apply); 'pop' restores and removes the entry; 'apply' restores and keeps it; 'list' returns stashCount and stashes[] {index, ref, message, branch}; 'drop' deletes an entry (destructive). index (default 0, the most recent) targets pop/apply/drop as stash@{N}; a missing entry is refused as no-stash-entry with the route.","arguments":[{"name":"includeUntracked","type":"boolean","required":false,"description":"Also stash untracked files (push only). Default false."},{"name":"index","type":"integer","required":false,"description":"Entry for pop/apply/drop, as in stash@{N}. Default 0 (the most recent)."},{"name":"message","type":"string","required":false,"description":"Label for the entry (push only)."},{"name":"mode","type":"string: push | pop | apply | list | drop","required":true,"description":"push (park the changes), pop (restore and remove), apply (restore and keep), list, drop (delete an entry)."}],"lessons":["https://ek9.io/ide/git-history.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_status","url":"https://ek9.io/mcp/ek9_git_status.html","category":"enquiry","description":"Answers first: summary, branch, ahead/behind, isClean, then stagedFiles / modifiedFiles / untrackedFiles / deletedFiles / conflictFiles names and changedFileCount, then the per-file records with change words.","whenToUse":"'What have I changed, what is staged, what branch am I on?' - one call, no arguments; path narrows to a subtree. The pre-commit and pre-push check, and the first call when picking up a workspace.","whenNotToUse":["the content of the changes - use ek9_git_diff.","commit history - use ek9_git_log.","per-line authorship of a file - use ek9_git_blame.","compiler errors and warnings - use ek9_query_diagnostics."],"details":"Headline first: summary, branch (null on a detached HEAD, with detachedAt), upstream with ahead/behind, isClean, changedFileCount and the name arrays stagedFiles / modifiedFiles / untrackedFiles / deletedFiles / conflictFiles. Then the records: staged / modified / deleted / conflicts entries are {file, change} with change one of modified / added / deleted / typechange / conflict; renamed / copied entries are {oldPath, newPath, change, similarity}. verbosity:'summary' keeps the names and drops the records.","arguments":[{"name":"includeIgnored","type":"boolean","required":false,"description":"Include .gitignore-matched files. Default false."},{"name":"includeUntracked","type":"boolean","required":false,"description":"Include untracked files. Default true."},{"name":"path","type":"string","required":false,"description":"Workspace-relative file or directory to scope the status to. Default: the whole workspace."}],"lessons":["https://ek9.io/ide/git-basics.html"],"fixes":[],"example":{"scenario":"Dirty tree","request":{},"response":{"branch":"main","changedFileCount":2,"conflictFiles":[],"conflicts":[],"copied":[],"deleted":[],"deletedFiles":[],"isClean":false,"meta":{"serverMs":"<timing>"},"modified":[{"change":"modified","file":"tracked.txt","status":"M"}],"modifiedFiles":["tracked.txt"],"renamed":[],"staged":[],"stagedFiles":[],"status":"ok","summary":"main; 1 modified, 1 untracked","untracked":[{"file":"untracked.txt"}],"untrackedFiles":["untracked.txt"],"upstream":null}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_git_switch","url":"https://ek9.io/mcp/ek9_git_switch.html","category":"execution","description":"Reports status (switched or created), branch and previousBranch; a dirty tree that would be overwritten is refused with the route (commit, stash or restore first), never auto-stashed.","whenToUse":"'Switch to branch X' or 'start a branch for this work' - one call with branch; create:true creates it from HEAD (or ref) and switches. Branch here BEFORE committing onto the default branch.","whenNotToUse":["listing the branches that exist - use ek9_git_branch.","unstaging or discarding file changes - use ek9_git_restore.","parking uncommitted changes so a switch can proceed - use ek9_git_stash.","recording changes on the current branch - use ek9_git_commit."],"details":"Uses git switch (never checkout, which can silently discard working-tree changes). ref is only meaningful with create:true. No auto-stash: a dirty tree that would be overwritten is refused as dirty-tree with the route (commit, stash or restore first); branch-not-found and already-exists are refused with theirs.","arguments":[{"name":"branch","type":"string","required":true,"description":"Branch to switch to (or to create with create:true)."},{"name":"create","type":"boolean","required":false,"description":"Create the branch first (git switch -c). Default false."},{"name":"ref","type":"string","required":false,"description":"Commit, tag or branch to create the new branch from (with create:true). Default: the current HEAD."}],"lessons":["https://ek9.io/ide/git-basics.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_help","url":"https://ek9.io/mcp/ek9_help.html","category":"enquiry","description":"Returns the reference page for one keyword, built-in type or topic - hover summary, the full type API for a built-in type, usage examples - or the keyword index when no keyword is given.","whenToUse":"'What is X' or 'what does String offer' is one call with keyword:'String' - the language reference for one keyword, built-in type or topic. Spelling and case are resolved for you ('stdout' -> 'Stdout'); omit keyword for the index of every page.","whenNotToUse":["How-to or why questions ('how do I write a switch', 'why no break?') - use ek9_ask.","A construct in THE USER'S workspace (their own class/function/module) - use ek9_query_construct, or ek9_query_effective_api for its full API.","Priming a session with the whole EK9 paradigm - use ek9_paradigm.","One error code's meaning (E07235) - use ek9_explain_error."],"details":"Plain text. Resolution order: exact page, EK9 error code (E + 5 digits, answered with the rich explanation), case-insensitive page ('list' -> List), then the closest page within four edits - a correction is announced on the first line. Operators are looked up by their symbol (keyword:'<=>' or '#?'). A true miss is an error (not an empty success) listing related topics from the concept registry. Static reference content, independent of workspace compile state; the type API is introspected from org.ek9.lang once per server.","arguments":[{"name":"keyword","type":"string","required":false,"description":"The keyword, type name, operator symbol or topic (e.g. 'String', 'switch', '<=>', 'E05030'); case and near spellings are resolved. Omit for the index of every page."}],"lessons":["https://ek9.io/ide/asking-the-ide.html","https://ek9.io/ide/book-data-types.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_implement_methods","url":"https://ek9.io/mcp/ek9_implement_methods.html","category":"editor","description":"Inserts an 'override' stub for every abstract trait method the class has not implemented; answers status and edits[] (one INSERT block), or an error carrying the resolutions[] a concrete-diamond collision needs.","whenToUse":"'Implement every missing trait method on Order' is one call with symbol:'Order' - no file, line or mode needed. Use it when a CLASS declares traits (`with trait of X, Y`) and its unimplemented abstract trait methods should be stubbed in one batch.","whenNotToUse":["Adding ONE specific method - use ek9_add_method; a trait-declared OPERATOR - use ek9_add_operator (this tool batches methods only).","You only want to ENUMERATE what is missing without inserting — use ek9_query_effective_api (read-only).","You want CLASS-LEVEL trait delegation (`with trait of X by field`) — use ek9_generate_delegation; `by` is class-header only, there is no per-method form.","The target class does not exist yet — use ek9_new_construct."],"details":"Every generated stub carries `override` (trait methods are never bare, per E05120); an all-abstract multi-trait collision auto-resolves to a single override, while a concrete diamond (at least one trait supplies a BODY) makes stubs mode return status:error with a ready-to-edit resolutions[] payload — retry with resolutions[], each picking source 'trait:<Name>' (delegate to that body; rejected if that trait declares it abstract) or 'override' (your own stub, whose //AI: lead names the trait bodies to combine). An already-implemented method is a no-op with EMPTY edits[] — never a conflicts status. would-fail = a generated stub references an unresolvable type; errors on non-class targets (record/trait/component/enum).","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"members","type":"array of any","required":false,"description":"Optional - only implement these methods (each must be an unimplemented trait method). A name gets a placeholder body; {name, statements:[...]} is written WITH that body, so one call implements the trait. Omit to implement all outstanding with placeholders."},{"name":"mode","type":"string: stubs | conflict-resolution","required":false,"description":"Optional: stubs (the default - placeholder bodies for every outstanding method) or conflict-resolution (inferred whenever resolutions[] is sent)."},{"name":"resolutions","type":"array of object","required":false,"description":"One {methodName, source} per conflicting method; source is 'trait:<TraitName>' or 'override'. Sending it selects conflict-resolution mode."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/implement-methods.html"],"fixes":[],"example":{"scenario":"Non class target refused","request":{"file":"shapes.ek9","line":6,"mode":"stubs"},"response":{"conflicts":[],"edits":[],"error":{"message":"Cannot implement methods on a trait — applies to classes only"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"Cannot implement methods on a trait — applies to classes only","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_increment_version","url":"https://ek9.io/mcp/ek9_increment_version.html","category":"execution","description":"Answers with the new version and previousVersion after bumping one component of the 'defines package' version literal, plus written and line.","whenToUse":"'Bump the package version' is one call with file:'package.ek9' and component:'patch' (or major, minor, build). Pick the component by intent: build for a CI snapshot, patch for a bugfix, minor for a feature, major for a breaking change.","whenNotToUse":["Setting an explicit version rather than bumping the current one - use ek9_set_version.","Switching to a feature-tagged version (X.Y.Z-feature) - use ek9_set_feature_version.","Reading the current version without changing it - use ek9_query_package_version."],"details":"Cascading reset: major zeros minor/patch/build; minor zeros patch/build; patch zeros build; build increments only. The current format is preserved - plain (major.minor.patch-build) or feature-tagged (major.minor.patch-feature-build). The version literal is read before and after the rewrite, so version, previousVersion, written and line are facts from the file, not the CLI's log. An unknown component is refused before the fork (the CLI would silently rewrite the file unchanged). Typical release chain: ek9_run_tests -> ek9_increment_version -> ek9_deploy_package.","arguments":[{"name":"component","type":"string: major | minor | patch | build","required":false,"description":"Which component to increment; the lower ones reset to 0."},{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size. The default answers with status, summary, version, previousVersion, written and line; 'full' adds the CLI's argv, exitCode, elapsedMs and timedOut."}],"lessons":["https://ek9.io/ide/package-block.html"],"fixes":[],"example":{"scenario":"Increment minor component","request":{"component":"minor","file":"<workspace-root>/package.ek9"},"response":{"file":"package.ek9","line":5,"meta":{"serverMs":"<timing>"},"previousVersion":"1.0.0-0","status":"ok","summary":"version 1.0.0-0 -> 1.1.0-0","version":"1.1.0-0","written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_inline_function","url":"https://ek9.io/mcp/ek9_inline_function.html","category":"editor","description":"Replaces every call to a FUNCTION or METHOD with its parameter-substituted body and deletes the declaration; answers status, edits[] (one REPLACE per call site + the DELETE) and conflicts[] (kind 'variable-clash' with {name, suggestedName}).","whenToUse":"'Inline the function formatLabel everywhere' is one call with symbol:'formatLabel' - no file or line needed. Use it on a trivial FUNCTION or METHOD ('Type.method') whose name no longer earns its abstraction.","whenNotToUse":["The function has ZERO call sites - just delete it with ek9_safe_delete (inline returns conflict no-call-sites).","You want the OPPOSITE — factor a block OUT into a new function — use ek9_extract_method.","The target is a LOCAL VARIABLE, not a function — use ek9_inline_variable.","Operator/constructor/abstract (error), recursive (direct or mutual), or dispatcher/override/trait-dispatch targets — no inlinable expansion; refactor or keep the abstraction.","A METHOD called on another object (obj.method()) or whose body reads 'this' or a field — conflicts receiver-qualified-callsite / this-or-field-capture; it needs its object."],"details":"scope: all-call-sites (default; inline everywhere then delete decl) | single-call-site (requires callSiteFile/Line, callSiteColumn defaults to 1; decl kept). An expression-bodied function (name() <- rtn as T: EXPR) inlines at any call context; a multi-statement body inlines only where the call is the whole statement (bare, or RHS of <- / :=), its rtn mapping to the assignment target. A donor-local clash returns conflicts kind 'variable-clash' with clashes[] of {name, suggestedName} — rename via ek9_rename_symbol then re-run (the tool never auto-renames); recursion, dispatcher/override, this/field capture, named arguments and discarded return refuse cleanly as other conflict kinds, and anything subtler (e.g. an E08130 purity violation) surfaces as would-fail — never silent broken source.","arguments":[{"name":"callSite","type":"object","required":false,"description":"single-call-site only: {file, line} of the ONE call to inline - the function's name on that line is found for you; column (0-based, an IDE cursor) is optional. The flat callSiteFile / callSiteLine / callSiteColumn (1-based) are the IDE form of the same thing."},{"name":"callSiteColumn","type":"integer","required":false,"description":"IDE form - column (1-based) on the call name; the name is found on the line when omitted."},{"name":"callSiteFile","type":"string","required":false,"description":"IDE form of callSite.file - workspace-relative file of the target call."},{"name":"callSiteLine","type":"integer","required":false,"description":"IDE form of callSite.line - line (1-based) of the target call."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"scope","type":"string: all-call-sites | single-call-site","required":false,"description":"all-call-sites (default): inline every call (via the Phase-5 call graph, across files) and remove the declaration. single-call-site: inline just the call at callSite:{file, line} and keep the declaration."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/inline-function.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_inline_variable","url":"https://ek9.io/mcp/ek9_inline_variable.html","category":"editor","description":"Deletes a single-assignment local's declaration and substitutes its initialiser at every use site (including `${...}` holes); answers status, edits[] and conflicts[] (variable-reassigned, impure-initialiser-multi-use, ...).","whenToUse":"'Inline the local subtotal' is one call with file + symbol:'subtotal' - no line needed; 'inline both locals' is one call with symbols:['prefix','message']. Use it on a LOCAL whose name adds no clarity over its short initialiser, or one an earlier refactor extracted and no longer needs.","whenNotToUse":["Variable has ZERO references - nothing to inline; use ek9_safe_delete to remove it.","You want the OPPOSITE (lift an expression INTO a new local) — use ek9_extract_variable.","Target is a FUNCTION, not a variable — use ek9_inline_function.","Target is a field, parameter, module constant or `<- rtn` return variable — locals only; no inline tool exists for those."],"details":"A call-free initialiser inlines at any number of uses; a call-bearing one only at a SINGLE use site (V1 refuses multi-use: impure-initialiser-multi-use). Other conflict kinds: variable-reassigned, multi-line-initialiser, variable-is-guard, variable-has-no-references; fields, parameters, return variables and lines not on a local declaration return status:error. Pairs with ek9_extract_method to collapse the destructuring locals a multiReturn container leaves at the call site.","arguments":[{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 source file holding the local declaration."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"The identifier you mean (e.g. 'total'); the tool finds its declaration line in file. Pass line only to anchor one specific occurrence."},{"name":"symbols","type":"array of string","required":false,"description":"Several locals to inline as ONE change, in this order (e.g. ['prefix','message']) - all or none. Instead of symbol."}],"lessons":["https://ek9.io/ide/book-values.html","https://ek9.io/ide/inline-variable.html","https://ek9.io/ide/inline-candidates.html"],"fixes":[],"example":{"scenario":"Two locals one change","request":{"file":"task.ek9","symbols":["prefix","message"]},"response":{"conflicts":[],"edits":[{"after":"      rtn: \"Hello, \" + name","before":"      prefix <- \"Hello, \"\n      message <- prefix + name\n      rtn: message","endLine":11,"file":"task.ek9","startLine":9,"type":"replace"}],"meta":{"serverMs":"<timing>"},"resolvedPath":"<workspace-root>/task.ek9","risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":3,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Would inline 'prefix' (1 use) — remove declaration + substitute 1 line; Would inline 'message' (1 use) — remove declaration + substitute 1 line","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_insert_coalescing","url":"https://ek9.io/mcp/ek9_insert_coalescing.html","category":"editor","description":"Splices `LEFT <op> RIGHT` in place of a selected single-line left operand using one of the EK9 coalescing / elvis operators; answers status, edits[] (one REPLACE) and conflicts[] (kind 'selection-not-an-expression'), with a type-incompatible pairing surfacing as would-fail.","whenToUse":"'Default name to \"Anonymous\" when unset' is one call with file, the LEFT operand as written (operand:'name'), operator:'?:' and rightOperand:'\"Anonymous\"'. Use it to wrap an existing single-line expression in one of EK9's null-safe operators (?: <? >?) without hand-writing tokens.","whenNotToUse":["Inserting a whole new statement/expression rather than wrapping an existing operand - use ek9_insert_statements.","Adding a set-check guard to an if/while/for/switch/try head (not an inline expression) — use ek9_apply_guard_pattern.","Lifting an expression into a local rather than coalescing it — use ek9_extract_variable."],"details":"The splice is syntactic but gated by a semantic scratch-compile: `?:` works on any tri-state type, while `<?`/`>?` need the operand's type to define `<=>` (`_cmp`), so a bad pairing or type-incompatible rightOperand surfaces as status:'would-fail' with the compiler diagnostic, not a broken edit. A compound left operand (e.g. `a + b`) is parenthesised for unambiguous binding, as is a compound rightOperand (`count ?: (base + 1)`) and the whole new expression when the operand sits inside another operator (`x + (a <? c)`), so the value never silently changes. The operand text names its occurrence; when it is an operand on several lines and no line is given, the call is refused naming them. A declaration's LHS is an identifier, not an expression (status:'conflicts', kind 'selection-not-an-expression') — and V1 supports a single-line left operand only.","arguments":[{"name":"endColumn","type":"integer","required":false,"description":"1-based EXCLUSIVE column of the END of the span (an IDE selection). Omit it - pass the text instead."},{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 source file containing the expression."},{"name":"line","type":"integer","required":false,"description":"Optional 1-based line of the operand. Needed only when the operand text is an operand on more than one line."},{"name":"operand","type":"string","required":false,"description":"The LEFT operand exactly as written in the source ('name', 'a + b')."},{"name":"operator","type":"string: ?: | <? | >?","required":true,"description":"The coalescing operator to insert: `?:` first SET - the one that defaults an unset value ('name ?: \"Anonymous\"'); `<?` min, `>?` max (the LEFT operand on a tie)."},{"name":"rightOperand","type":"string","required":true,"description":"The RIGHT operand expression as source text — e.g. a fallback literal (`\"Anonymous\"`), another variable (`y`), or a further chained expression (`b ?: c`). Spliced verbatim."},{"name":"startColumn","type":"integer","required":false,"description":"1-based column of the START of the span on 'line' (an IDE selection). Omit it - pass the text instead."}],"lessons":["https://ek9.io/ide/book-defaulting.html","https://ek9.io/ide/book-safe-min-max.html","https://ek9.io/ide/wrap-with-coalescing.html"],"fixes":[],"example":{"scenario":"Operand text ambiguous without line","request":{"file":"Bounds.ek9","operand":"alpha","operator":"<?","rightOperand":"beta"},"response":{"conflicts":[],"edits":[],"error":{"message":"operand 'alpha' is on lines [9, 10] - pass line (one of [9, 10]) to say which one to coalesce."},"meta":{"serverMs":"<timing>"},"status":"error","summary":"operand 'alpha' is on lines [9, 10] - pass line (one of [9, 10]) to say which one to coalesce.","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_insert_statements","url":"https://ek9.io/mcp/ek9_insert_statements.html","category":"editor","description":"Splices EK9 statement(s) into a named method/function/operator body at anchor top, bottom, replace or a body line, re-indented by the tool; answers status, edits[] (one INSERT), insertedLineRange and resultingBodySnippet, or error.problems[] naming the entry that does not parse.","whenToUse":"'Add a statement to the end of Greeter.hello' is one call with file, symbol:'Greeter.hello', anchor:'bottom', statements:[...] - the tool owns indent and formatting. Use it to ADD statement(s) into an existing method/function/operator body (a log line, a guard at the head, a new field's first use) without a full-text rewrite.","whenNotToUse":["Adding a whole METHOD/FIELD/constructor declaration - use ek9_add_method / ek9_add_field / ek9_add_constructor; this tool only fills existing bodies.","WRAPPING existing statements in try/if/for - use ek9_surround_with; REMOVING statements - use ek9_remove_statements (symmetric pair; replace = remove then insert).","Adding a `<- rtn` return-value declaration - that is a signature change, use ek9_change_signature (conflicts here as inserted-content-includes-return-value-declaration).","Body inside a `defines text for` block - use ek9_edit_localized_text; target line not inside any body (references block, package metadata, comment) - use ek9_edit_file."],"details":"anchor: position top/bottom, or afterLine/beforeLine (a line inside the body). Statement text is re-indented to body level (common leading whitespace stripped, relative indent kept), one top-level statement per statements[] entry - an entry MAY be a multi-line block (switch/if/for/try/while, with '\\n' and two-space nesting). Every entry is parsed alone BEFORE the splice: a syntax error or a tab is status:error, written:false, error.problems[{path:'statements[i]', line, message}] with nothing written (the compile gate stays the semantic check). position:top resolves to the first valid statement position (after any `<- rtn` declaration) and REPLACES a scaffold's placeholder body (the require guards survive; appliedAnchor.replacedPlaceholder:true). Conflict kinds: dynamic-body-not-supported (dynamic function/class bodies rejected fail-fast) and inserted-content-includes-return-value-declaration; unknown construct/method surfaces as status:error, and success carries appliedIndent, appliedAnchor, insertedLineRange and resultingBodySnippet (±2-line window; includeBodySnippet:true swaps in the full post-insert body — check bodySnippetSource).","arguments":[{"name":"anchor","type":"any","required":true,"description":"WHERE in the body: 'top' (first statement position; replaces a scaffold's placeholder), 'bottom' (after the last statement), 'replace' (the whole body - re-implement the member), a bare line number N (= {afterLine:N}), or {beforeLine:N} - a 1-based line INSIDE the body; with ek9_remove_statements(startLine, endLine) this replaces lines in the middle of a body."},{"name":"file","type":"string","required":false,"description":"Workspace-relative path to the .ek9 source file containing the target body (optional - found from symbol when omitted)."},{"name":"includeBodySnippet","type":"boolean","required":false,"description":"When true, response.resultingBodySnippet carries the entire method/function body post-insert (delegated to ConstructSourceExtractor against the post-write program). Default false returns a ±2-line context window around the insert — usually enough to eyeball indent and position. Always check response.bodySnippetSource to confirm which path produced the snippet: \"extractor\" = full body delivered; \"contextWindowFallback\" = opt-in requested but the response carries the cheap window despite your request (typically because this call was dryRun:true — no file written, so no post-write extractor probe runs)."},{"name":"memberName","type":"string","required":false,"description":"Method or operator name within symbol when symbol is the bare type ('Greeter' + memberName:'hello' is the same as symbol:'Greeter.hello'). OMIT for a program or a top-level function - do not send the string \"null\"."},{"name":"statements","type":"array of string","required":true,"description":"Ordered list of EK9 statements to insert. Each entry is ONE top-level statement and MAY span several lines with '\\n' - a switch, an if, a for, a try - with its relative indentation preserved (two spaces per level); the tool owns the absolute indent. Write a block as ONE entry: \"switch code\\n  case 1\\n    rtn: \\\"active\\\"\\n  default\\n    rtn: \\\"unknown\\\"\" (one line per entry also works when the nested lines are indented deeper than the first entry). Every entry is parsed alone before anything is written; a syntax error is rejected as error.problems[{path:'statements[i]', line}] with nothing written. Spaces only - a tab is rejected."},{"name":"symbol","type":"string","required":true,"description":"The body's owner: a program or top-level function by name ('Main', 'findLabel'), or a member as 'Type.member' ('Greeter.hello', an operator by its bare symbol: 'Order.$'). 'mod::Name' is understood."}],"lessons":[],"fixes":[],"example":{"scenario":"After line anchor outside body","request":{"anchor":{"afterLine":3},"construct":"Main","file":"Hello.ek9","statements":["stdout.println(\"Middle\")"]},"response":{"conflicts":[],"edits":[],"error":{"message":"afterLine 3 is not inside this body (its statements are lines 6-8); use position:'top'/'bottom' or a line in that range"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"afterLine 3 is not inside this body (its statements are lines 6-8); use position:'top'/'bottom' or a line in that range","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_inspect_symbol_at_cursor","url":"https://ek9.io/mcp/ek9_inspect_symbol_at_cursor.html","category":"enquiry","description":"Answers first: name, fullyQualifiedName, kind, type, state, declaredAt, then the modifiers, flags, scope, purityContext and the type's operators - one symbol, cursor-precise.","whenToUse":"What exactly is the identifier at this cursor - kind, type, tri-state, declaration, scope - one call with file + symbol:'<name>'. An IDE cursor passes file + line + column instead.","whenNotToUse":["The WHOLE construct containing the cursor (class/record/etc.), not the precise symbol at it — use ek9_query_construct.","The FULL callable API of a type (methods + operators + constructors, inherited members) — use ek9_query_effective_api on the returned type.","Enumerating ALL symbols in scope at a position — use ek9_list_visible_symbols.","Language reference for a built-in type rather than a workspace symbol — use ek9_help."],"details":"Resolved symbols carry symbol:'found' with a uniform core (kind, type, state, mutable, purityContext, modifiers, declaredAt, scope, flags); kind is FIELD or PARAMETER where applicable, otherwise the symbol category (VARIABLE/METHOD/FUNCTION/TYPE/...), and METHOD adds methodDetails (parameters, returns, pure, abstract). state is the symbol's STATIC declared tri-state, not flow-sensitive (an assignment lines earlier still reads unset) — except state:'absent', which IS position-aware: a REAL variable out of lexical scope here (reason scope-closed or before-declaration) is recovered from its declaration with an absence block, while a name declared nowhere stays not_found. declaredAt is line+column only (no file yet); operators lists the type's operators only (?, $, <=>, ==, ...) — plain methods are deliberately excluded. displayName appears only when it differs from name (a parameterised or synthetic symbol).","arguments":[{"name":"column","type":"integer","required":false,"description":"0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim."},{"name":"file","type":"string","required":true,"description":"The EK9 source file path"},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"The identifier you mean on 'line' (e.g. 'sayHello'); the tool finds its column. Prefer this to column - a column is a 0-based character offset an IDE supplies."}],"lessons":[],"fixes":[],"example":{"scenario":"Inspect shape","request":{"file":"MyRecord.ek9","line":5},"response":{"callSite":false,"category":"TYPE","declaredAt":{"column":4,"line":5},"flags":{"abstract":false,"constant":false,"field":false,"incomingParameter":false,"initialised":true,"injectionExpected":false,"mutable":false,"pure":false,"returningParameter":false},"fullyQualifiedName":"com.example::MyRecord","genus":"RECORD","kind":"TYPE","meta":{"serverMs":"<timing>"},"modifiers":[],"mutable":false,"name":"MyRecord","operators":[{"defaulted":true,"operator":"?","pure":true,"returns":"Boolean"},{"defaulted":true,"operator":"$","pure":true,"returns":"String"},{"defaulted":true,"operator":"$$","pure":true,"returns":"JSON"},{"defaulted":true,"operator":":=:","pure":false,"returns":"Void"},{"defaulted":true,"operator":"<=>","pure":true,"returns":"Integer"},{"defaulted":true,"operator":"==","pure":true,"returns":"Boolean"},{"defaulted":true,"operator":"<>","pure":true,"returns":"Boolean"},{"defaulted":true,"operator":"<","pure":true,"returns":"Boolean"},{"defaulted":true,"operator":"<=","pure":true,"returns":"Boolean"},{"defaulted":true,"operator":">","pure":true,"returns":"Boolean"},{"defaulted":true,"operator":">=","pure":true,"returns":"Boolean"},{"defaulted":true,"operator":"#?","pure":true,"returns":"Integer"}],"purityContext":"non-pure","scope":"module:com.example","state":"set","symbol":"found","type":"MyRecord","typeFullyQualified":"com.example::MyRecord"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_install_package","url":"https://ek9.io/mcp/ek9_install_package.html","category":"execution","description":"Answers with installedTo (under ~/.ek9/lib) and bundlePath after packaging one package and installing its SOURCE bundle into the LOCAL library cache - not a remote registry push.","whenToUse":"'Install this package into the local library for other workspaces on this machine' is one call with file:'package.ek9'. It packages first, then copies the bundle into ~/.ek9/lib.","whenNotToUse":["Only building the bundle, no install - use ek9_package.","Publishing to the REMOTE registry rather than the local cache - use ek9_deploy_package.","Fetching this package's DECLARED dependencies (the consumer direction) - use ek9_resolve_dependencies."],"details":"Wraps ek9 -I: the same packaging pipeline as ek9_package (compile + tests + 80% coverage gate), then the versioned zip and its .sha256 are copied into ~/.ek9/lib/ - never a remote registry. installedTo is reported only when the copy exists on disk after the run. Consumers' compilers build the installed SOURCE on first use.","arguments":[{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size. The default answers with status, summary, bundlePath and installedTo; 'full' adds the CLI's stdout, argv, exitCode, elapsedMs and timedOut."}],"lessons":["https://ek9.io/ide/depth-package-greeter.html","https://ek9.io/ide/depth-package-shapes.html","https://ek9.io/ide/build-and-deploy.html"],"fixes":[],"example":{"scenario":"Installed shape","request":{"file":"<workspace-root>/package.ek9"},"response":{"bundlePath":".ek9/com.example.pkg-1.0.0-0.zip","checksumPath":".ek9/com.example.pkg-1.0.0-0.zip.sha256","file":"package.ek9","installedTo":"~/.ek9/lib/com.example.pkg-1.0.0-0.zip","meta":{"serverMs":"<timing>"},"status":"ok","stderr":"Install : <workspace-root>/.ek9/lib/com.example.pkg-1.0.0-0.zip installed\n","summary":"installed: com.example.pkg-1.0.0-0.zip"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_introduce_field","url":"https://ek9.io/mcp/ek9_introduce_field.html","category":"editor","description":"Lifts a local and its initialiser to a same-named field of the enclosing class/record/component and deletes the local (adding `default operator ?` when it is the first field); answers status, edits[] and conflicts[] (no-promotable-declaration, not-inside-fielded-aggregate, field-name-collision).","whenToUse":"'Make the local counter a field' is one call with file + symbol:'counter' - no line needed. Use it when a local declared inside a method/operator/constructor should become per-instance state shared by the construct's other members; the field keeps the name.","whenNotToUse":["Lifting a `name <- literal` to a MODULE constant, not a field - use ek9_promote_to_constant.","Scaffolding a brand-new field rather than lifting an existing local — use ek9_add_field.","Wanting a DIFFERENT field name — introduce keeps the name; run ek9_rename_symbol afterwards.","The local is not inside a class/record/component (e.g. a top-level function) — no fielded aggregate, so there is nowhere to lift to."],"details":"Name is kept verbatim, so in-construct references still resolve (to the field) and simple cases keep compiling; the two hard cases surface as would-fail via the scratch-compile gate: an initialiser referencing a parameter/local (E04050 for a complex expression, E50001 for a bare reference) and another method's same-named local now duplicating the field (E50050). When the aggregate has no own `?` operator (typically this is its first field), `default operator ?` is also appended (E07235 tri-state requirement). conflicts kinds: no-promotable-declaration (line is not a single-line initialised local), not-inside-fielded-aggregate (not inside a class/record/component), field-name-collision (aggregate already declares that field). Fields take the construct's natural visibility (class/component private, record public) — no visibility parameter.","arguments":[{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 source file holding the local declaration."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"The identifier you mean (e.g. 'total'); the tool finds its declaration line in file. Pass line only to anchor one specific occurrence."}],"lessons":["https://ek9.io/ide/introduce-field.html"],"fixes":[],"example":{"scenario":"Introduce subsequent field apply","request":{"file":"Account.ek9","line":9},"response":{"conflicts":[],"edits":[{"before":"        limit <- 100","endLine":9,"file":"Account.ek9","startLine":9,"type":"delete"},{"after":"      limit <- 100","endLine":7,"file":"Account.ek9","startLine":7,"type":"insert"}],"meta":{"serverMs":"<timing>"},"resolvedPath":"<workspace-root>/Account.ek9","risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":2,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Introduce field `limit <- 100` on Account (2 edits)","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_introduce_parameter","url":"https://ek9.io/mcp/ek9_introduce_parameter.html","category":"editor","description":"Appends a new parameter to the enclosing method/function, replaces the selected in-body expression with it and passes the ORIGINAL expression at every call site (Fowler \"Introduce Parameter\"); answers status, edits[] and conflicts[] (value-expression-not-a-single-expression, type-not-inferable, ...).","whenToUse":"'Give greet a parameter greeting and use it instead of the literal \"Hello \"' is one call with file, expression:'\"Hello \"' and name:'greeting' - the body uses the parameter and every existing call site is passed the original value. Use it (not ek9_change_signature, which adds the parameter but leaves the body unchanged) when a body hard-codes a value callers should be able to vary - in a statement or in the '<- rtn as T: ...' initialiser.","whenNotToUse":["The value should be a LOCAL variable in the same method - use ek9_extract_variable.","The value should become a CLASS FIELD (per-instance state, not per-call) - use ek9_introduce_field.","The value should be a module-level CONSTANT (immutable, shared) - use ek9_extract_constant.","You need broader signature changes - explicit position, several parameters at once, return type, or purity - use ek9_change_signature; this tool only APPENDS one parameter."],"details":"Parameter type is inferred from the expression unless parameterType is supplied; V1 always APPENDS (no position arg), and when the post-change parameter count reaches 4+ all call sites are rewritten to named-argument form per E11062. Promoting in a method that overrides a trait/supertype contract resolves to the root contract and cascades the parameter across the whole override family (resolved-to-contract advisory). would-fail (gate-caught): the expression references a method-local unresolvable at call sites (E50001) or hides impurity in a pure method (E08130); conflicts: value-expression-not-a-single-expression (bad/partial span), expression-not-in-body, type-not-inferable (supply parameterType), no-promotable-declaration; a name colliding with an existing parameter is an error.","arguments":[{"name":"endColumn","type":"integer","required":false,"description":"1-based EXCLUSIVE column of the END of the span (an IDE selection). Omit it - pass the text instead."},{"name":"expression","type":"string","required":false,"description":"The expression to turn into the parameter, exactly as written (e.g. '\"Hello \"' - quotes included for a string). Its first occurrence in file, or on 'line' when given."},{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 source file holding the expression (and its enclosing method/function)."},{"name":"line","type":"integer","required":false,"description":"Optional 1-based line holding the expression - when it occurs more than once."},{"name":"name","type":"string","required":true,"description":"Identifier for the new parameter (camelCase by convention); kept verbatim. Rename later with ek9_rename_symbol."},{"name":"parameterType","type":"string","required":false,"description":"Optional explicit parameter type. Inferred from the expression when omitted; supply when inference yields type-not-inferable or you want a wider type than the expression's."},{"name":"startColumn","type":"integer","required":false,"description":"1-based column of the START of the span on 'line' (an IDE selection). Omit it - pass the text instead."}],"lessons":["https://ek9.io/ide/introduce-parameter.html"],"fixes":[],"example":{"scenario":"Introduce bad span conflict","request":{"dryRun":true,"endColumn":17,"file":"Report.ek9","line":8,"newParameterName":"amount","startColumn":16},"response":{"conflicts":[{"kind":"value-expression-not-a-single-expression","message":"The range on line 8 (columns 16–17) does not span a single complete EK9 expression. Adjust startColumn/endColumn to the exact bounds of one expression."}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Cannot introduce parameter on function report — 1 conflict","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_list_files","url":"https://ek9.io/mcp/ek9_list_files.html","category":"enquiry","description":"Answers first: entryCount and paths[] (workspace-relative, the value ek9_read_file takes), then entries[{path, name, kind, size, lastModified}] - never content; direct children unless pathPattern recurses.","whenToUse":"You want to know what files exist - one call with no arguments for the workspace root, path:'src' for a directory, pathPattern:'**/*.ek9' to recurse. The discovery primitive when you don't yet know exact filenames.","whenNotToUse":["You want a file's CONTENT, not just its existence/metadata — use ek9_read_file with an entry's path.","You want keyword search across file CONTENTS — use ek9_search_text.","You want the logical workspace structure (modules/packages) not a raw filesystem listing — use ek9_query_workspace.","You want EK9-module-level structure (constructs, deps) not raw files — use ek9_query_module."],"details":"Default (no pathPattern) lists DIRECT CHILDREN only — recurse via pathPattern:'**/*'; glob mode returns files only, while direct listings also include directories (kind 'directory', size:null). Every entry's path is workspace-relative — the exact value ek9_read_file / ek9_edit_file take. Entries are sorted by path. maxResults defaults 500 (clamped to 5000); a cut listing opens with truncated:true and entryTotal — narrow the glob or raise maxResults. Errors until ek9_compile has established workspace roots; beyond that, compile-state independent.","arguments":[{"name":"includeHidden","type":"boolean","required":false,"description":"When true, includes dot-files and otherwise-excluded build directories."},{"name":"maxResults","type":"integer","required":false,"description":"Cap on entries[] (default 500, max 5000). A cut listing opens with truncated:true and entryTotal."},{"name":"path","type":"string","required":false,"description":"Directory path: workspace-relative (preferred) or absolute inside the workspace. Defaults to the workspace root."},{"name":"pathPattern","type":"string","required":false,"description":"Optional glob (e.g. \"**/*.ek9\", \"test/**/*Test.ek9\"), applied recursively from path; files only."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"full (default) returns entries[] records; summary keeps paths[] and the counts; none collapses the lists to counts."}],"lessons":[],"fixes":[],"example":{"scenario":"List recursively by path pattern","request":{"pathPattern":"**/*.md"},"response":{"directory":".","entries":[{"kind":"file","lastModified":"<timing>","name":"README.md","path":"README.md","size":9},{"kind":"file","lastModified":"<timing>","name":"NOTES.md","path":"docs/NOTES.md","size":8}],"entryCount":2,"meta":{"serverMs":"<timing>"},"pathPattern":"**/*.md","paths":["README.md","docs/NOTES.md"],"status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_list_visible_symbols","url":"https://ek9.io/mcp/ek9_list_visible_symbols.html","category":"enquiry","description":"Answers first: scopeChain[] innermost to outermost, each scope with its symbols (name, kind, type, state, roles), then activeGuards and purityConstraint.","whenToUse":"What names can I use at this position - every variable, field, method, type and constant in scope - one call with file + symbol:'<name on that line>'. Pass file + line instead from an IDE cursor.","whenNotToUse":["One specific symbol AT the cursor, not the whole list — use ek9_inspect_symbol_at_cursor (cursor-precise, single result, and the only path that reports 'absent').","The members of a KNOWN type (e.g. all methods on Customer) — use ek9_query_effective_api.","The structure of the enclosing construct (class/record) — use ek9_query_construct.","Not anchored to a position — use ek9_query_workspace for a workspace-wide structure overview, or ek9_find_constructs_by_name to locate a known construct NAME."],"details":"scopeChain is ordered innermost→outermost with per-scope purityContext; purityConstraint is the effective (innermost) purity — check it before proposing mutations. Free top-level functions are kind FUNCTION, NOT METHOD; mutability is the string \"mutable\" inside roles[], not a top-level key; omitted fields are absent (presence-detection, not null-checks). A block scope carries scope:'block' and no name. The module rung spans the whole module — a constant declared in a sibling file appears with an extra 'file' key (its 'line' is a line in THAT file). verbosity:'summary' keeps each scope's symbolNames only.","arguments":[{"name":"column","type":"integer","required":false,"description":"0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim."},{"name":"file","type":"string","required":true,"description":"The EK9 source file path"},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"The identifier you mean on 'line' (e.g. 'sayHello'); the tool finds its column. Prefer this to column - a column is a 0-based character offset an IDE supplies."}],"lessons":["https://ek9.io/ide/one-construct.html"],"fixes":[],"example":{"scenario":"Cross file module symbols","request":{"file":"orders.ek9","line":8},"response":{"activeGuards":[],"meta":{"serverMs":"<timing>"},"purityConstraint":"non-pure","scopeChain":[{"purityContext":"non-pure","scope":"block","symbols":[{"kind":"VARIABLE","line":7,"name":"stdout","roles":["initialised","mutable"],"state":"set","type":"Stdout"}],"type":"block"},{"name":"_main","pure":false,"purityContext":"non-pure","returnVariable":{"kind":"PARAMETER","line":6,"name":"_rtn","roles":["return","mutable"],"state":"unset","type":"Void"},"scope":"method:_main","type":"method"},{"name":"Orders","purityContext":"non-pure","scope":"aggregate:Orders","symbols":[{"kind":"METHOD","line":6,"name":"_main","state":"unset","type":"Void"},{"kind":"METHOD","line":6,"name":"Orders","roles":["initialised"],"state":"set","type":"Orders"}],"type":"aggregate"},{"name":"com.example","purityContext":"non-pure","scope":"module:com.example","symbols":[{"kind":"TYPE","line":6,"name":"Orders","roles":["initialised"],"state":"set","type":"Orders"},{"file":"constants.ek9","kind":"VARIABLE","line":5,"name":"SERVICE_NAME","roles":["initialised"],"state":"set","type":"String"},{"file":"constants.ek9","kind":"VARIABLE","line":6,"name":"MAX_RETRIES","roles":["initialised"],"state":"set","type":"Integer"}],"type":"module"}],"status":"found"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_list_workflows","url":"https://ek9.io/mcp/ek9_list_workflows.html","category":"enquiry","description":"Returns every named multi-tool workflow - workflowCount, workflowNames, then each workflow's summary and full step sequence.","whenToUse":"'Which workflows exist' is one call with {} - workflowNames first, then every workflow's full step sequence. The registry is static, so call once per session and cache.","whenNotToUse":["One workflow by name - use ek9_query_workflow name:'release' (the same registry, one entry).","The tool inventory - use ek9_query_tool_catalogue."],"details":"Pure static read of the workflow registry: no compile-state coupling, deterministic at every phase, never fails (an empty registry returns workflowCount:0). Each workflow carries its complete ordered sequence[] of {tool, reason} steps; every step names a registered tool. Identical to ek9_query_workflow called with no name.","arguments":[],"lessons":[],"fixes":[],"example":{"scenario":"Workflows list shape","request":{},"response":{"meta":{"serverMs":"<timing>"},"status":"ok","workflowCount":4,"workflowNames":["release","feature_branch_start","investigate_build_failure","investigate_runtime_defect"],"workflows":[{"name":"release","sequence":[{"reason":"Bump the appropriate version part (typically patch after a fix).","tool":"ek9_increment_version"},{"reason":"Verify nothing regressed; produces the coverage report as a side effect.","tool":"ek9_run_tests"},{"reason":"Run full quality checks — coverage, complexity, readability, DI — to confirm nothing has degraded since the last release.","tool":"ek9_run_quality_checks"},{"reason":"Build the deployable artefact at the new version.","tool":"ek9_package"},{"reason":"Install into ~/.ek9/lib so sibling workspaces can pick it up.","tool":"ek9_install_package"},{"reason":"Verify the installed version matches what was bumped.","tool":"ek9_query_package_version"}],"summary":"Bump version + run tests with coverage + build artefact + install locally + verify."},{"name":"feature_branch_start","sequence":[{"reason":"Mark the package as on a feature branch (e.g. 2.1.0-PAYINTEG-0).","tool":"ek9_set_feature_version"},{"reason":"Declare each new package dependency the feature requires.","tool":"ek9_add_dependency"},{"reason":"Pull the new dependencies into ~/.ek9/lib.","tool":"ek9_resolve_dependencies"},{"reason":"Verify the package still compiles with the new deps.","tool":"ek9_compile"},{"reason":"Verify existing tests still pass before any feature work begins.","tool":"ek9_run_tests"}],"summary":"Set feature-branch version + add new dependencies + resolve + verify."},{"name":"investigate_build_failure","sequence":[{"reason":"Read the specific compiler/resolver error messages.","tool":"ek9_query_diagnostics"},{"reason":"See the resolved tree with version selections and any rejection reasons.","tool":"ek9_query_dependency_tree"},{"reason":"Rule out a transitive cycle in the published-package graph.","tool":"ek9_check_package_dependency_cycles"},{"reason":"Re-resolve after any fix to the package directive.","tool":"ek9_resolve_dependencies"},{"reason":"Confirm the build now succeeds.","tool":"ek9_compile"}],"summary":"Diagnose dependency-resolution or compilation failure: diagnostics → tree → cycles → fix → re-resolve."},{"name":"investigate_runtime_defect","sequence":[{"reason":"{action:'launch', run:'toEnd', args:<the failing input>}: reproduce the failure once - its message usually names the value that went wrong (a Panic on 'require total >= NOTHING' in Order.invoice -> watch Order.total).","tool":"ek9_debug_session"},{"reason":"{action:'sweep', inputs:[...], journal:{property:'Type.property', hypothesis}}: one run per input set, all with ONE seed. Include inputs you expect to PASS as well as the failing one - compare needs both; every change to the value, on every object, is recorded. Its answer already carries compare's top differences, and the investigation id.","tool":"ek9_debug_session"},{"reason":"{action:'compare', runs, hypothesis}: what only the failing runs did - a step they took, a step they LEFT OUT (onlyInPassing), or none (then the values differ). A tie or thin evidence means more inputs, not a verdict. Cite each difference by its run and ticks.","tool":"ek9_debug_inspect"},{"reason":"{action:'leadingTo', runId:<a failing run>, hypothesis}: the account - the changes that led to its failure, each with the line, the values and the calls that made it. Cite ticks for every claim.","tool":"ek9_debug_inspect"},{"reason":"{action:'firstWhere', runId, condition:'total < 0', hypothesis}: the step where the value first went wrong - usually the line to fix.","tool":"ek9_debug_inspect"},{"reason":"{action:'launch', run:'toEnd', seed:<the sweep's>, args:<one input changed>, journal}: confirm the suspect - the same run with only the suspect's input changed should pass. Without this, a difference is a suspect, not a cause.","tool":"ek9_debug_session"},{"reason":"{action:'report', runs, hypothesis, finding:'cause and fix, citing t5 and Orders.ek9:36'}: write the investigation up for the person (index.html, report.json); the finding is shown as yours.","tool":"ek9_debug_inspect"}],"summary":"A runtime failure whose cause is earlier: journal the value over failing AND passing runs -> compare -> leadingTo -> firstWhere -> confirm with one input changed -> report with a finding."}]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_make_abstract","url":"https://ek9.io/mcp/ek9_make_abstract.html","category":"editor","description":"Rewrites the declaration to 'as abstract' (replacing any 'as open') so the construct can no longer be instantiated; answers status, edits[] and wouldBeDiagnostics with every direct construction site (E10030).","whenToUse":"'Make Shape abstract' is one call with symbol:'Shape' - no file or line needed. Use it when a class/record/component/function should be a subclassing base that is never instantiated bare; abstract is implicitly open, so no separate 'as open' is needed.","whenNotToUse":["Removing 'as abstract' so the class can be instantiated again - use ek9_make_concrete.","Wanting subclassability but STILL allowing direct instantiation — use ek9_make_open ('as open' alone, not abstract).","Wanting a fixed allow-only list of subtypes — use ek9_seal_type (it keeps an existing 'as abstract' but never adds one; run this tool first for abstract+sealed).","Filling in abstract methods rather than locking them as abstract — use ek9_implement_methods (opposite intent)."],"details":"Rewrites only the declaration line: strips any existing 'as open' (the two modifiers are mutually-exclusive grammar alternatives) and appends 'as abstract'; function style handled too ('myFunc() as pure' → 'myFunc() as pure abstract', reclassifying the genus to an abstract function). Breakage surfaces as would-fail — direct construction sites become E10030 CONSTRUCTOR_USED_ON_ABSTRACT_TYPE, and concrete-subclass cascades appear as new diagnostics. An already-abstract target is status:conflicts with kind 'already-abstract'; no supported declaration at the anchor, or a trait target (always abstract), is status:error.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/make-abstract.html"],"fixes":[],"example":{"scenario":"Make abstract already noop","request":{"file":"main.ek9","line":15},"response":{"conflicts":[{"kind":"already-abstract","message":"Class is already abstract — no change needed"}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Class is already abstract — no change needed","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_make_closed","url":"https://ek9.io/mcp/ek9_make_closed.html","category":"editor","description":"Strips 'as open' from the declaration so the construct can no longer be extended; answers status, edits[] and conflicts[] naming every subtype (kind 'subtype') that would break with E05030.","whenToUse":"'Close Animal to extension' is one call with symbol:'Animal' - no file or line needed. Use it on an 'as open' class/record/component/function with NO subtypes to return it to EK9's closed-by-default.","whenNotToUse":["Opting INTO subclassability (the opposite) - use ek9_make_open.","Removing 'as abstract' from an abstract class — use ek9_make_concrete (abstract is implicitly open and cannot be closed directly).","The construct is sealed ('allow only …') — use ek9_unseal_type first (E05270 requires a sealed class stay open).","Subtypes exist and block closure — remove/refactor them first with ek9_safe_delete (or convert to composition via 'with trait of')."],"details":"Supports class/record/component/function (all carry the optional 'as open'); traits are always open and rejected as an unsupported construct. status:'conflicts' with kind:'subtype' (an escalation — human must decide) when any workspace subtype would hit E05030 (NOT_OPEN_TO_EXTENSION), and kind:'already-closed' when there is nothing to do; status:'error' when the target is abstract (hint: ek9_make_concrete) or sealed (hint: ek9_unseal_type). Closed is the ABSENCE of 'as open' — there is no 'as closed' keyword.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/make-closed.html"],"fixes":[],"example":{"scenario":"Make closed abstract refused","request":{"file":"main.ek9","line":15},"response":{"conflicts":[],"edits":[],"error":{"message":"Cannot close an abstract class — remove 'as abstract' first (make concrete)"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"Cannot close an abstract class — remove 'as abstract' first (make concrete)","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_make_concrete","url":"https://ek9.io/mcp/ek9_make_concrete.html","category":"editor","description":"Removes 'as abstract' from the declaration (keeping 'as open' unless keepOpen:false) so the construct can be instantiated; answers status, edits[] and conflicts[] listing every remaining abstract member (kind 'abstract-method').","whenToUse":"'Make Shape concrete' is one call with symbol:'Shape' - no file or line needed. Use it on an 'as abstract' class/record/component/function whose abstract members are all implemented, to allow direct instantiation.","whenNotToUse":["Opting INTO forced-subclassing (the opposite) - use ek9_make_abstract.","Removing subclassability (closing) — that's the 'as open' modifier; use ek9_make_closed on a concrete class, or keepOpen:false here to go concrete-and-closed in one step.","The class still HAS abstract methods to implement first — use ek9_implement_methods for trait-derived abstracts, or ek9_add_method per member, then re-call.","Unsealing a sealed ('allow only') type — the sealed constraint stays; use ek9_unseal_type (and keep keepOpen:true — sealed needs 'as open' per E05270)."],"details":"keepOpen (default true) emits 'as open' to preserve the extensibility abstract implied per QA0102 — removing abstract alone would silently CLOSE the class; keepOpen:false makes it concrete-and-closed in one step (avoid on sealed types, which need 'as open' per E05270). Traits are always abstract and are rejected as an unsupported construct. Conflicts carry kind 'abstract-method' with name/signature/line (mechanical: implement each body, then re-call) or 'already-concrete'; would-fail flags subclass cascade errors.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"keepOpen","type":"boolean","required":false,"description":"Whether the resulting concrete class should be 'as open' (default true) or closed (false)."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/make-concrete.html"],"fixes":["E05250"],"example":{"scenario":"Make concrete empty abstract","request":{"file":"main.ek9","line":24},"response":{"conflicts":[],"edits":[{"after":"    EmptyAbstract as open","before":"    EmptyAbstract as abstract","endLine":24,"file":"main.ek9","startLine":24,"type":"replace"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"high","fileCount":1,"lineCount":1,"touchesPublicApi":true,"touchesTests":false},"status":"applied","summary":"Changed class EmptyAbstract → as open (concrete)","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_make_open","url":"https://ek9.io/mcp/ek9_make_open.html","category":"editor","description":"Appends 'as open' to the declaration so the construct can be extended; answers status and edits[] (one REPLACE on the declaration line), or conflicts[] when it is already open.","whenToUse":"'Open Animal for extension' is one call with symbol:'Animal' - no file or line needed. Use it when a closed (EK9's default) class/record/component/function must permit subclassing - a widening change that never breaks existing compile and resolves E05030.","whenNotToUse":["Removing 'as open' to lock a class down - use ek9_make_closed.","Wanting 'as abstract' (implicitly open AND forces subclasses to supply bodies) — use ek9_make_abstract.","Wanting a SEALED class ('as open' + 'allow only A, B, C', open to a fixed subclass list) — use ek9_seal_type, which applies both modifications atomically.","Traits — always open already; rejected as an unsupported construct."],"details":"Accepts class, record, component and function (both concrete and abstract functions). When the target is sealed ('allow only') but missing 'as open' (the E05270 contradiction), adding the modifier fixes it. An already-open or already-abstract (implicitly open) target is status:conflicts with kind 'already-open' / 'already-abstract'; an unsupported genus is status:error.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/make-open.html"],"fixes":["E05030"],"example":{"scenario":"Make open already open noop","request":{"file":"main.ek9","line":5},"response":{"conflicts":[{"kind":"already-open","message":"Class is already open — no change needed"}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Class is already open — no change needed","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_move_construct","url":"https://ek9.io/mcp/ek9_move_construct.html","category":"editor","description":"Relocates one top-level construct to another .ek9 file, rewriting every workspace 'references' entry when the move changes module; answers status, edits[] (source DELETE, target INSERT, one rewrite per referring file) and conflicts[].","whenToUse":"'Move CustomerOrder into shared/order.ek9' is one call with symbol:'CustomerOrder', targetFile:'shared/order.ek9' - no source file, line or mode needed (the mode is derived from the two files' 'defines module' lines). Use it to relocate ONE top-level class/record/trait/function/component to another .ek9 file.","whenNotToUse":["Renaming the construct (name unchanged by a move) - use ek9_rename_symbol; combine by moving first, then renaming.","Renaming the .ek9 FILE while keeping its constructs in place — use ek9_rename_file.","Only wanting to KNOW where the construct is referenced (not move it) — use ek9_query_references; run it first to gauge cross-module blast radius.","Changing a construct's visibility/openness rather than its file — use ek9_change_visibility / ek9_make_open."],"details":"Module membership is set by the target file's 'defines module' line, NOT by directory layout; the tool reads both files' declarations to derive same-module vs cross-module, and rejects a sent mode that mismatches the actual pair. Same module keeps the FQN and yields two edits only; cross-module changes the FQN and atomically rewrites every `references oldModule::Thing` edge workspace-wide. Conflict kinds: 'name-collision-in-module' (mechanical — pick another target or rename first); 'construct-references-not-resolvable-in-new-module' and 'circular-dependency-introduced' (escalation — restructure required); anything the up-front checks miss is caught as would-fail by the scratch-compile gate.","arguments":[{"name":"file","type":"string","required":false,"description":"The .ek9 file currently containing the construct - OPTIONAL when symbol is a construct name (the tool finds it workspace-wide)."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"mode","type":"string: same-module | cross-module","required":false,"description":"Optional - derived from the two files' 'defines module' lines: same-module (relocation) or cross-module (relocation + workspace-wide reference rewriting). A sent value that contradicts the files is rejected."},{"name":"sourceFile","type":"string","required":false,"description":"Alias of file (the file currently containing the construct)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."},{"name":"targetFile","type":"string","required":true,"description":"Destination: workspace-relative path the construct should move to. Must already exist; its 'defines module' declaration determines the target module."}],"lessons":["https://ek9.io/ide/move-construct.html"],"fixes":[],"example":{"scenario":"Move construct no construct error","request":{"line":2,"mode":"cross-module","sourceFile":"from.ek9","targetFile":"to.ek9"},"response":{"conflicts":[],"edits":[],"error":{"message":"No top-level construct at: from.ek9:2 — place the line on (or inside the body of) the construct you want to move"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"No top-level construct at: from.ek9:2 — place the line on (or inside the body of) the construct you want to move","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_move_file","url":"https://ek9.io/mcp/ek9_move_file.html","category":"editor","description":"Answers first: status (applied | ready | conflicts), written and edits[{file, newFile, type:move}] - a pure file-system relocation of any workspace file, contents untouched.","whenToUse":"You want a file somewhere else or under another name - one call with oldPath + newPath; any file kind, contents untouched. A .ek9 file keeps its module identity (the 'defines module' line, not the directory).","whenNotToUse":["Moving a CONSTRUCT between files (FQ-name change + reference rewriting), not a whole file - use ek9_move_construct (symbol:'Name', targetFile).","A .ek9-only rename that must refuse a non-.ek9 destination - ek9_rename_file is the same move with that extension check (it performs the rename).","You want a copy + delete (distinct from a move — loses inode identity / VCS history) — use ek9_write_file + ek9_delete_file.","The file should be REMOVED, not moved — use ek9_delete_file."],"details":"For .ek9 files the 'defines module' line (not the directory) sets module identity, so a move never changes fully-qualified names or breaks references. HARD dev/ exit guard, no override: a .ek9 file leaving a dev/ directory for production is refused (conflict kind 'dev-exit-contains-tests') when it contains @Test or assert*; a marker-free dev/ file is promoted with a 'dev-exit-promotion' advisory. Directory moves are out of scope, and a destination collision (overwrite:false) or missing parent (createIntermediateDirs:false) returns status:error, not conflicts.","arguments":[{"name":"createIntermediateDirs","type":"boolean","required":false,"description":"When true (default), missing parent directories at the destination are created (mkdir -p). When false, the tool errors if the destination's parent doesn't exist."},{"name":"newPath","type":"string","required":true,"description":"Destination: may be in a different directory; must not exist unless overwrite:true. Workspace-relative (preferred) or absolute inside the workspace."},{"name":"oldPath","type":"string","required":true,"description":"File path: workspace-relative (preferred) or absolute inside the workspace. The file as it is now; must exist."},{"name":"overwrite","type":"boolean","required":false,"description":"When false (default), the tool errors if a file already exists at newPath. When true, the existing file is replaced (its prior content is lost). Use cautiously."}],"lessons":["https://ek9.io/ide/rename-and-move-file.html"],"fixes":[],"example":{"scenario":"Move non ek9 file apply","request":{"newPath":"docs/NOTES.txt","oldPath":"NOTES.txt"},"response":{"conflicts":[],"edits":[{"file":"NOTES.txt","newFile":"docs/NOTES.txt","type":"move"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"moderate","fileCount":2,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Moved NOTES.txt → docs/NOTES.txt","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_new_construct","url":"https://ek9.io/mcp/ek9_new_construct.html","category":"editor","description":"Scaffolds one top-level construct (class/record/trait/component/function/type/constant/service) into an EXISTING module file, or a new package.ek9 for mode:'package'; answers status, edits[] (one INSERT, or one CREATE for a package), stubs[] to fill with ek9_insert_statements, added[] and nextStep.","whenToUse":"'Create a class Order with its operators and a program Main that prints it' is ONE call: targetFile plus constructs:[{mode:'class', name:'Order', fields, operators, statements...}, {mode:'program', name:'Main', statements:[...]}] - bodies included, compiled once; a single construct is mode + name at the top level. mode:'package' creates the file instead. Pick the mode by intent: class=state+behaviour, record=value+operators, trait=API contract, function=stateless computation, component=DI-wired, type=enum/constrained/alias, service=REST routes, constant, package=publishable metadata; every mode but package appends into the module file (creating the 'defines <genus>' block if absent).","whenNotToUse":["Authoring a program, application, or localized text block — those have their own dedicated tools: ek9_add_program (tests via isTest:true), ek9_add_application, ek9_edit_localized_text.","Authoring an INLINE closure or dynamic construct inside a function/program body — use ek9_create_dynamic_function or ek9_create_dynamic_class (inline-only, not top-level).","The construct already exists and you want to add MEMBERS — use ek9_add_method / ek9_add_field / ek9_add_constructor / ek9_add_operator.","Adding a route to an EXISTING service — use ek9_add_route (symbol-table-bound), not a fresh service scaffold."],"details":"name is required for every mode (for package it is the MODULE name, com.acme.orders; 'module' is accepted); genus rules are validated before render — record rejects named methods, trait rejects fields, component rejects trait composition. Classes and traits are closed-by-default ('is'/'extends' are synonyms via inheritanceKeyword; pass modifiers:['as open'] for an extensible base — an unresolved or non-open parent is caught by the compile gate); fields-bearing aggregates auto-get 'default operator ?' (E07235) and trait operators render as abstract contracts (Any-provided ?,==,$,$$,#?,<=> skipped + reported). service requires operations[] (>=1 — a route-less service does not compile) and defaults its security posture to bare 'open', not 'as open', when omitted (E12050); package capability enforcement turns on only when publicAccess + version + license + capabilities are ALL set.","arguments":[{"name":"allowOnly","type":"array of string","required":false,"description":"Sealed-hierarchy implementors (class + trait) — renders 'allow only A, B' after the header, restricting who may extend/implement."},{"name":"applyStandardExcludes","type":"boolean","required":false,"description":"When true, EK9 standard excludes are merged with excludeFiles. Default false — must opt in. The directive is only emitted when this is explicitly true."},{"name":"applyStandardIncludes","type":"boolean","required":false,"description":"When true, EK9 standard includes (all .ek9 files in source tree) are merged with includeFiles. Default false — must opt in. The directive is only emitted when this is explicitly true."},{"name":"baseType","type":"string","required":false,"description":"type/constrained + type/alias: the underlying base type."},{"name":"body","type":"string","required":false,"description":"Raw EK9 source for the package-block body. When supplied, the structured fields below are ignored and the body is emitted verbatim inside the defines package wrapper. Indent each line with four spaces relative to column 0."},{"name":"capabilities","type":"array of string","required":false,"description":"Fully-qualified gated-type names (e.g. 'org.ek9.lang::Stdout', 'org.ek9.lang::TCP', 'org.ek9.lang::HTTPRequest'). Presence of this list — alongside publicAccess + version + license — turns on compile-time supply-chain capability enforcement for the package. EK9 forbids empty list literals; pass null/omit the parameter for a pure-computation library."},{"name":"constraint","type":"string","required":false,"description":"type/constrained: the expression after 'constrain as' (e.g. '>= 16 and <= 100')."},{"name":"constructors","type":"array of object","required":false,"description":"Constructors [{parameters:['price as Float', ...], pure?, default?, visibility?}] — one parameter per field, each assigned to the property (':=?' when pure). default:true renders a synthesised 'default Name()' (no body); visibility 'private'/'protected' prefixes the declaration."},{"name":"constructs","type":"array of object","required":false,"description":"SEVERAL constructs in ONE call - each item has the same keys as this tool's top level (mode, name, fields, constructors, methods, operators, traits, parameters, returnType, statements, value, ...), mode:'program' with statements is allowed here, and an item may name its own targetFile (default: the call's) - a file that does not exist yet is created around the item's (or the call's) module. Rendered in order into their 'defines' blocks, every body pre-flighted, every touched file compiled ONCE: 'a trait, the classes over it and the program that drives them' is one call. What compiles is written; a construct that does not is named in refused[] with its diagnostics mapped to the statements[] entry (partial:true) - resend only that one."},{"name":"deps","type":"object","required":false,"description":"Runtime dependencies as module-name → version-string mapping. Becomes an EK9 Dict literal. Example: { 'ek9open.network.support.utils': '1.6.1-9' }."},{"name":"description","type":"string","required":false,"description":"Package description (becomes a quoted EK9 String literal)."},{"name":"devDeps","type":"object","required":false,"description":"Development-only dependencies as module-name → version-string mapping. Same format as deps. Used for build/test dependencies that don't ship with the package."},{"name":"enumValues","type":"array of string","required":false,"description":"type/enumeration: the enum value names."},{"name":"excludeDeps","type":"object","required":false,"description":"Transitive dependency exclusions: bad-module → context-module mapping. Example: { 'ek9open.some.bad.dependency.pack': 'ek9open.org.supertools.util' }."},{"name":"excludeFiles","type":"array of string","required":false,"description":"Glob patterns of files to exclude."},{"name":"extends","type":"string","required":false,"description":"Parent type for class/record/trait/component, OR the abstract function a function extends (function inheritance: 'f() extends abstractFunction'). Pair with inheritanceKeyword for is-vs-extends. Closed-by-default: an unresolved or non-'as open' parent surfaces as a would-fail on dry-run."},{"name":"fields","type":"array of any","required":false,"description":"Field declarations as DATA: {name, type, defaultValue?, injected?} with BOTH name and type (the EK9 text 'name as Type' / 'name as Type: default' / 'name as Type!' / 'name <- default' is also accepted). A field without a type or default is rejected before anything is rendered. Not valid on traits. A typed field with no default is declared unset ('as Type?') and the compiler-required no-arg constructor is added for you (reported under 'added')."},{"name":"fileMode","type":"string: auto | create-file | overwrite","required":false,"description":"mode:package - auto (default; conflict 'file-exists' when the file exists), create-file (alias for auto), overwrite (replace the existing file)."},{"name":"includeFiles","type":"array of string","required":false,"description":"Glob patterns of files to include in the package (e.g. '**.{cal}', 'License.txt'). Use alongside or instead of applyStandardIncludes."},{"name":"inheritanceKeyword","type":"string: extends | is","required":false,"description":"'extends' (default) or 'is' — synonyms; choice is stylistic (conventionally 'is' for components)."},{"name":"license","type":"string","required":false,"description":"License identifier (e.g. 'MIT', 'Apache-2.0'). Becomes a quoted EK9 String literal. One of the four publishable conditions for capability enforcement."},{"name":"methods","type":"array of object","required":false,"description":"Methods [{name, parameters:[{name, type}, ...], returnType?, pure?, isAbstract?, override?, visibility?, dispatcher?, statements?}]. Each parameter is ONE item as DATA - {name:'code', type:'Integer'} - never a {name} and a {type} as two items, and never with '->' or '<-' in it: the tool writes the arrows and the layout. ('code as Integer' is also accepted.) Not valid on records (operators only). dispatcher:true renders 'as dispatcher' (double-dispatch root). Give the body as statements[] (each entry one statement or one block, assign 'rtn: <value>' on every path) and the member is complete in this call; without it the body is a stub listed under 'stubs' for ek9_insert_statements to fill."},{"name":"mode","type":"string: package | class | record | trait | component | function | type | constant | service | program","required":false,"description":"Construct kind. class/record/trait/component/function/type/constant/service/program append into an EXISTING .ek9 module file via the gated changeset path (omitted with parameters/returnType/statements and no fields = function); package creates a new file."},{"name":"modifiers","type":"array of string","required":false,"description":"Trailing modifiers verbatim, e.g. ['as open'], ['as abstract']. All four aggregate genera (class/record/trait/component) accept open|abstract — closed by default."},{"name":"module","type":"string","required":false,"description":"mode:package - the EK9 module name (FQ format like com.acme.orders); the same value as name, accepted in either. With constructs[] - the module a targetFile that does not exist yet is created around (an item's own 'module' wins)."},{"name":"name","type":"string","required":false,"description":"Construct name - PascalCase for type-shaped genera, camelCase for a function or constant; for mode:package the MODULE name (com.acme.orders; 'module' is accepted)."},{"name":"operations","type":"array of object","required":false,"description":"service mode (required, >=1): the web operations/routes. Each: {name | operator, verb?, uri, security?, params?, response?}. Use 'name' (+ optional 'verb' GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS, default GET) for a named route, or 'operator' (+= POST, -= DELETE, :^: PUT, :~: PATCH, ? HEAD) for the operator form. 'uri' is the operation path (e.g. '/{id}'). params: [{name, type, in: PATH|QUERY|HEADER|CONTENT|REQUEST|CONTEXT, source?, sanitized?}] — named extractions (PATH/QUERY/HEADER) are auto-captured + referenced so they compile. response: {status?, contentType?, contentLanguage?, cacheControl? | cache:{maxAge, visibility:public|private, mustRevalidate?, noStore?}} — only the fields you set are overridden; HTTPResponse defaults the rest."},{"name":"operators","type":"array of any","required":false,"description":"Operators to declare. RULE OF THUMB: a string ('?', '$', 'all') means 'let the compiler synthesise it' (default operator); if the task describes what the operator RETURNS or DOES, you need the object form with custom:true, which renders a stub body for ek9_insert_statements(method:'<sym>') to fill. A plain string (or {symbol}) renders the terse 'default operator <sym>'; 'all' / '*' renders the bare 'default operator' (all defaultable). A CUSTOM operator object {symbol, custom:true, override?, pure?, parameters:[{name,type}], returnType?} renders a CONCRETE operator with a //AI-marked body — for operators the compiler cannot synthesise (a hand-rolled '$', an overriding '?', a mutating '+='). On a trait, default operators render as ABSTRACT contracts ('operator <sym> [as pure] as abstract' with resolved param/return) — Any-provided operators (?,==,$,$$,#?,<=>) are skipped + reported. Valid on class/record/trait/component. A fields-bearing aggregate auto-gets 'default operator ?' if one isn't requested (E07235)."},{"name":"parameters","type":"array of any","required":false,"description":"function mode: input parameters, each ONE item - 'code as Integer' or {name:'code', type:'Integer'}. 'params' is accepted as an alias."},{"name":"publicAccess","type":"boolean","required":false,"description":"When true, the package can be deployed to the EK9 repository (or a private repository when false-and-published). One of the four publishable conditions. Default false."},{"name":"pure","type":"boolean","required":false,"description":"Pure-construction mode (class/record/component). Renders every field unset ('as Type?', any defaultValue relocated), forces every constructor 'as pure' (assigning via ':=?'), and — when no no-arg constructor was supplied and the construct has assignable fields — adds a public no-arg default-setter, so the construct is constructible in a pure context. Default false."},{"name":"returnType","type":"string","required":false,"description":"Return TYPE only, e.g. 'String', 'List of Integer' - never '<- rtn as String', never a name: the tool writes the '<- rtn as <Type>?' declaration and the body assigns 'rtn: <expr>'. Omitted means no return."},{"name":"security","type":"string","required":false,"description":"service mode: the security posture rendered after the base URI — 'open' or 'constrain by Gate [and Cors]'. Mandatory at service or operation level (E12050); defaults to 'open' when neither is given."},{"name":"serviceUri","type":"string","required":false,"description":"service mode (required): the base URI, e.g. '/addresses' — renders 'Name for :/addresses <posture>'. Base URIs cannot contain path variables (E07680)."},{"name":"statements","type":"array of string","required":false,"description":"mode:function - the function's body, one statement or one block per entry (assign 'rtn: <value>' on every path when there is a return): the function is complete in this call, no stub to fill."},{"name":"tags","type":"array of string","required":false,"description":"Tag list — used for repository search."},{"name":"targetFile","type":"string","required":true,"description":"Destination: workspace-relative path of the .ek9 file - for package the NEW file to create (conflict 'file-exists' unless fileMode:'overwrite'); for every other mode the EXISTING module file the construct is appended to (its 'defines <genus>' block is created if absent). With constructs[] it is the default for items that name no targetFile of their own."},{"name":"traits","type":"array of object","required":false,"description":"'with trait of' composition (class/trait only). Each {trait, byField?}; byField delegates the trait to a field."},{"name":"typeForm","type":"string: enumeration | constrained | alias","required":false,"description":"type mode (required): 'enumeration' | 'constrained' | 'alias'."},{"name":"typeParameters","type":"array of object","required":false,"description":"Conceptual type parameters for a GENERIC class or function: [{name, constrainBy?}] → 'of type T' or 'of type (K, V)', each optionally 'constrain by <Type>'. Member signatures may reference the parameter names (T/K/V) as types. The parameterised header is grammar-incompatible with extends/with-trait-of/allow-only, so those are omitted when present."},{"name":"value","type":"string","required":false,"description":"constant mode: the literal verbatim (e.g. '\"localhost\"', '42', '3.14') — emitted as 'NAME <- value'."},{"name":"version","type":"string","required":false,"description":"Package version literal (Version type, not a String). Strict semver: MAJOR.MINOR.PATCH-BUILD or MAJOR.MINOR.PATCH-FEATURE-BUILD. Default '1.0.0-0'."}],"lessons":["https://ek9.io/ide/new-constructs.html","https://ek9.io/ide/own-generics.html","https://ek9.io/ide/book-decisions.html","https://ek9.io/ide/book-functions-demo.html","https://ek9.io/ide/book-describe.html","https://ek9.io/ide/book-functions.html","https://ek9.io/ide/book-halve.html","https://ek9.io/ide/book-halve-nothing.html","https://ek9.io/ide/book-testing.html","https://ek9.io/ide/book-data-types.html","https://ek9.io/ide/book-constants.html","https://ek9.io/ide/book-constant-copy.html","https://ek9.io/ide/book-integer-promotion.html","https://ek9.io/ide/book-guards.html","https://ek9.io/ide/book-defaulting.html","https://ek9.io/ide/book-phone.html","https://ek9.io/ide/book-optional-result.html","https://ek9.io/ide/book-streams.html","https://ek9.io/ide/book-shop.html","https://ek9.io/ide/book-two-ways.html","https://ek9.io/ide/book-records.html","https://ek9.io/ide/book-enumerations.html","https://ek9.io/ide/book-day-operators.html","https://ek9.io/ide/book-rules.html","https://ek9.io/ide/book-constrained.html","https://ek9.io/ide/book-promote.html","https://ek9.io/ide/book-increment.html","https://ek9.io/ide/book-classes.html","https://ek9.io/ide/book-scoreboard.html","https://ek9.io/ide/book-account.html","https://ek9.io/ide/book-polymorphism.html","https://ek9.io/ide/book-contacts.html","https://ek9.io/ide/book-animals.html","https://ek9.io/ide/book-traits.html","https://ek9.io/ide/book-trait-clash.html","https://ek9.io/ide/book-allow-only.html","https://ek9.io/ide/book-components.html","https://ek9.io/ide/book-generics.html","https://ek9.io/ide/book-operators.html","https://ek9.io/ide/book-versions.html","https://ek9.io/ide/book-promotion.html","https://ek9.io/ide/book-notes.html","https://ek9.io/ide/book-game.html","https://ek9.io/ide/depth-settings-lookup.html","https://ek9.io/ide/depth-result-states.html","https://ek9.io/ide/depth-safe-shapes.html","https://ek9.io/ide/depth-operator-split.html","https://ek9.io/ide/depth-purity-rules.html","https://ek9.io/ide/depth-copy-merge-replace.html","https://ek9.io/ide/depth-shallow-copy.html","https://ek9.io/ide/depth-then-guard.html","https://ek9.io/ide/depth-pure-shapes.html","https://ek9.io/ide/depth-impure-twins.html","https://ek9.io/ide/depth-own-function-type.html","https://ek9.io/ide/depth-tax-rules.html","https://ek9.io/ide/depth-order-pipelines.html","https://ek9.io/ide/depth-sink-replace-append.html","https://ek9.io/ide/depth-json-sink.html","https://ek9.io/ide/depth-async-lookups.html","https://ek9.io/ide/depth-super-call.html","https://ek9.io/ide/depth-lru-cache.html","https://ek9.io/ide/depth-priced-ledger.html","https://ek9.io/ide/depth-shelf.html","https://ek9.io/ide/depth-generic-functions.html","https://ek9.io/ide/depth-range-over-t.html","https://ek9.io/ide/depth-constrained-record.html","https://ek9.io/ide/depth-inventory.html","https://ek9.io/ide/depth-comments.html","https://ek9.io/ide/depth-payment-exceptions.html","https://ek9.io/ide/depth-narrow-catch.html","https://ek9.io/ide/depth-try-expression.html","https://ek9.io/ide/depth-resource-order.html","https://ek9.io/ide/depth-session-close.html","https://ek9.io/ide/depth-suppressed-close.html","https://ek9.io/ide/depth-require-exit.html","https://ek9.io/ide/depth-fatal-exit.html","https://ek9.io/ide/depth-pipeline-failures.html","https://ek9.io/ide/depth-shared-tally.html","https://ek9.io/ide/depth-worker-totals.html","https://ek9.io/ide/depth-lost-result.html","https://ek9.io/ide/depth-consistent-order.html","https://ek9.io/ide/depth-lock-order-fixed.html","https://ek9.io/ide/depth-check-then-act.html","https://ek9.io/ide/depth-di-notifiers.html","https://ek9.io/ide/depth-guess-seam.html","https://ek9.io/ide/depth-aspect-order.html","https://ek9.io/ide/depth-price-book.html","https://ek9.io/ide/depth-aspect-exception.html","https://ek9.io/ide/depth-call-counter.html","https://ek9.io/ide/depth-echo-in-process.html","https://ek9.io/ide/depth-line-echo.html","https://ek9.io/ide/depth-udp-echo.html","https://ek9.io/ide/depth-udp-pipeline.html","https://ek9.io/ide/depth-check-destinations.html","https://ek9.io/ide/depth-serve-and-call.html","https://ek9.io/ide/depth-hello-notes.html","https://ek9.io/ide/depth-json-documents.html","https://ek9.io/ide/depth-route-order.html","https://ek9.io/ide/depth-sync-key.html","https://ek9.io/ide/depth-late-status.html","https://ek9.io/ide/depth-package-greeter.html","https://ek9.io/ide/depth-package-shapes.html","https://ek9.io/ide/depth-shop-tests.html","https://ek9.io/ide/depth-postage.html","https://ek9.io/ide/depth-substitution.html","https://ek9.io/ide/depth-tri-state.html","https://ek9.io/ide/application-and-di.html","https://ek9.io/ide/aspects.html","https://ek9.io/ide/web-services.html"],"fixes":[],"example":{"scenario":"Trait rejects field","request":{"fields":[{"name":"x","type":"Integer"}],"mode":"trait","name":"Drawable","targetFile":"main.ek9"},"response":{"conflicts":[],"edits":[],"error":{"message":"trait does not support fields"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"trait does not support fields","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_organize_constants","url":"https://ek9.io/mcp/ek9_organize_constants.html","category":"editor","description":"Moves every `defines constant` declaration of one module into one block in one file (created when targetFile is new); answers status, edits[] (one INSERT + one DELETE per moved declaration) and conflicts[] (comments-in-block, module-ambiguous, target-file-ambiguous, pre-existing-duplicate-constant).","whenToUse":"'Gather this module's constants into one file' is one call with no arguments (module:'x' when several modules declare constants - the tool refuses to guess; targetFile to pick or create the file). Use it when a module's constants have fragmented across files (E11066: 3+ files; E11067: 2+ files with 10+ constants) or drifted into the wrong file.","whenNotToUse":["Creating a NEW constant from a repeated literal in source (E11065) — use ek9_extract_constant. That authors a constant; this only relocates existing ones.","Promoting a local `name <- literal` to a module constant — use ek9_promote_to_constant.","Moving a class/record/trait/component/function between files — use ek9_move_construct (it handles those five genera only, not constants).","Deleting a donor left holding only its module header — use ek9_prune_empty_sources; this tool never deletes files."],"details":"Semantics-preserving by construction: constants live in ModuleScope and codegen merges all module constants into one `_Constants` class, so no call site, `references` entry or generated byte changes. ONE module per call; a constant never crosses a module boundary; donor files are retained with their block excised and declarations keep donor source order. Comments in a block's declaration area are conflict 'comments-in-block' — mode:'hoist-comments' lifts them to the block header so consolidate then proceeds (a trailing same-line comment rides its line and never blocks); other conflict kinds are 'pre-existing-duplicate-constant', 'module-ambiguous' (several modules declare constants - supply module), 'target-file-ambiguous' (supply targetFile) and 'directive-bearing-declaration', while no-constants and already-consolidated are graceful no-ops, not errors.","arguments":[{"name":"mode","type":"string: consolidate | hoist-comments","required":false,"description":"consolidate (default) gathers every constant into one block; hoist-comments lifts comments out of each block's declaration area up to its header — the one-time mechanical repair that unblocks consolidate."},{"name":"module","type":"string","required":false,"description":"The exact module to organize. Default: the one module declaring constants; when several do, the call is conflicts[{kind:'module-ambiguous', modules:[...]}] until you name one."},{"name":"targetFile","type":"string","required":false,"description":"Workspace-relative path of the file that will hold the consolidated block. Three cases, all supported: (1) a source file of the resolved module that already has a `defines constant` block; (2) one with no such block yet — a block is created at the canonical position; (3) a path that DOES NOT EXIST — the file is created as a source file of this module (shebang + `defines module` + //EOF) with the consolidated block in it. Case (3) is the dedicated-constants-file outcome E11066's guidance recommends, so name e.g. 'myModuleConstants.ek9' and this one call does it; no separate ek9_write_file step is needed. Nothing is written on dryRun. Default: the file holding the block with the most declarations. Rejected for hoist-comments."}],"lessons":["https://ek9.io/ide/organize-constants.html"],"fixes":["E11066","E11067"],"example":{"scenario":"Organize constants noop rerun","request":{},"response":{"conflicts":[],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"All 5 constants already consolidated in rich.ek9 — nothing to move","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_organize_localized_text","url":"https://ek9.io/mcp/ek9_organize_localized_text.html","category":"editor","description":"Moves the `defines text for \"<locale>\"` blocks between files to the chosen layout - block content preserved verbatim, donors kept as residual stubs, never deleted - and answers the editor envelope: status (applied | ready | conflicts | error), written, edits[] and summary; an already-canonical layout is applied with empty edits[].","whenToUse":"'Re-lay the module's i18n files' is one call: mode split-by-locale (one file per language), split-by-text-type (one per text type) or consolidate (targetFile) - content untouched.","whenNotToUse":["Adding / removing / editing text types, methods or locale bodies - this only MOVES existing blocks; use ek9_edit_localized_text instead.","Promoting a hard-coded string literal in EK9 source into a text method (source -> i18n) — use ek9_extract_to_localized_text instead.","Feature-area or per-subdirectory layouts beyond the three fixed modes — organise by hand; the modes are deliberately limited.","Deleting a residual donor stub after relocation — this tool never deletes donors; use ek9_delete_file."],"details":"Semantics-preserving by construction: EK9 resolves text types by module-scoped class name, not file path, so no call sites break and no reference sync is needed. Every apply canonicalises ordering (locales then text types, alphabetical), so the FIRST apply on a correctly-shaped but unordered layout is a normalisation pass (non-empty edits); subsequent applies are true no-ops. Donor files are RETAINED with block ranges excised (comments, commented-out code and live constructs survive in the residual); conflict kinds are target-file-exists (mechanical: rename clash or pick different targetFile), module-name-mismatch (fix source typo or scope via `module`), discovery-spans-multiple-directories (caller picks a directory) and no-localized-text-found.","arguments":[{"name":"mode","type":"string: split-by-locale | split-by-text-type | consolidate","required":true,"description":"Layout target. split-by-locale -> <locale>.ek9 per language; split-by-text-type -> <TextTypeName>.ek9 per text type; consolidate -> the single targetFile."},{"name":"module","type":"string","required":false,"description":"The module to operate on. Default: the first module that defines any text type; supply it when several modules carry i18n."},{"name":"targetFile","type":"string","required":false,"description":"Destination: the single output file (workspace-relative), required for consolidate; REJECTED for the split modes, whose outputs are deterministically named."}],"lessons":["https://ek9.io/ide/organize-localized-text.html"],"fixes":[],"example":{"scenario":"Idempotent rerun","request":{"mode":"split-by-locale"},"response":{"conflicts":[],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Layout already organised per split-by-locale; no changes needed","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_organize_references","url":"https://ek9.io/mcp/ek9_organize_references.html","category":"editor","description":"Deletes the unused entries of one file's 'references' block (usage judged by a scratch compile, so functions, types and name-collisions are all right) and answers the editor envelope: status (applied | ready | error), written, edits[] - one delete per unused line - and summary; an already-clean file is applied with empty edits[].","whenToUse":"'Remove the references this file no longer uses' is one call: {file:'x.ek9'} - the remove-only half of ek9_sync_references (its addMissing:false).","whenNotToUse":["Adding the MISSING references too, or repairing an unresolved symbol - use ek9_sync_references (this tool is ek9_sync_references with addMissing:false).","Sorting / reordering the references block - use ek9_format (the formatter owns layout).","Renaming a referenced symbol everywhere - use ek9_rename_symbol."],"details":"Detection is compiler-driven and cascade-safe: a scratch compile with the whole block deleted pre-filters the definitely-used names, then each remaining candidate is confirmed by deleting only its line and checking the error count doesn't rise (a cascade-masked-but-used reference is kept). Immune to case conventions and name collisions; degrades to a lexer name-heuristic (over-retains, never wrongly deletes) when no scratch compile can run. Never returns status:'conflicts'; interleaved comments and kept entries are preserved exactly (targeted per-line delete).","arguments":[{"name":"file","type":"string","required":true,"description":"The .ek9 source file whose references block to trim - workspace-relative (absolute inside the workspace accepted)."}],"lessons":["https://ek9.io/ide/organize-references.html"],"fixes":[],"example":{"scenario":"No references block noop","request":{"file":"Hello.ek9"},"response":{"conflicts":[],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"No references block in Hello.ek9 — nothing to remove","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_package","url":"https://ek9.io/mcp/ek9_package.html","category":"execution","description":"Answers with bundlePath and checksumPath after assembling the publishable SOURCE bundle (.ek9 files + manifest + capabilities, not bytecode) of one package.","whenToUse":"'Build the source bundle for this package' is one call with file:'package.ek9' (the file holding the 'defines package' block). The producer step before ek9_deploy_package or ek9_install_package.","whenNotToUse":["Just checking the code compiles, no bundle wanted - use ek9_compile.","Building AND publishing in one call - use ek9_deploy_package (it packages first).","Fetching this package's declared dependencies (the consumer direction) - use ek9_resolve_dependencies."],"details":"Packaging gates on quality: a full compile, every @Test and the 80% coverage threshold must pass before the sources are zipped into <project>/.ek9/. Failures are named by stage: compile-failed (exit 8), tests-failed (11), coverage-low (12), bad-arguments (2, e.g. no 'defines package' block), timed-out after 120s. bundlePath and checksumPath are reported only when the files exist on disk after the run. The bundle is SOURCE: the consumer's compiler recompiles at install time and re-enforces the declared capabilities.","arguments":[{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size. The default answers with status, summary, bundlePath and checksumPath; 'full' adds the CLI's stdout, argv, exitCode, elapsedMs and timedOut."}],"lessons":["https://ek9.io/ide/depth-package-greeter.html","https://ek9.io/ide/depth-package-shapes.html","https://ek9.io/ide/build-and-deploy.html"],"fixes":[],"example":{"scenario":"Package shape","request":{"file":"<workspace-root>/package.ek9"},"response":{"bundlePath":".ek9/com.example.pkg-1.0.0-0.zip","checksumPath":".ek9/com.example.pkg-1.0.0-0.zip.sha256","file":"package.ek9","meta":{"serverMs":"<timing>"},"status":"ok","summary":"bundle written: com.example.pkg-1.0.0-0.zip"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_paradigm","url":"https://ek9.io/mcp/ek9_paradigm.html","category":"enquiry","description":"Returns the constant EK9 paradigm summary (syntax that is NOT C/Java/Python, first-attempt traps, concepts with no analogue elsewhere) and working rules - the smallest priming context for an AI about to write EK9 code - and with withExamples:true the compiled inline examples after it.","whenToUse":"Prime a fresh AI session before it writes or reasons about EK9 code - one call with {} (withExamples:true adds the compiled examples). The content is constant, so never re-invoke once it is in history.","whenNotToUse":["A specific keyword, type or topic page - use ek9_help.","How-to / why questions ('how do I write a switch', 'why no break') - use ek9_ask.","A specific error-code explanation (E07235, ...) - use ek9_explain_error.","The full forAI.json reference (~42K tokens) - CLI-only (ek9 -h -E5); withExamples:true here is the middle size, and ek9_help / ek9_ask give targeted depth."],"details":"Returns AiReferenceGenerator.PARADIGM_SUMMARY then WORKING_RULES (~9.7K chars / ~2.5K tokens): the NOT-C/Java/Python NO/YES syntax list (no braces, return, break, null, new; the <-/:=/:=? assignment trio), the measured first-attempt traps (precedence, literals, named arguments, invented names, override, unset fields), the concepts with no analogue elsewhere (the fixed operator set and sameness, tri-state, pure, dispatcher, closed-by-default types, constructs, stream pipelines) and the WORKING RULES for driving the tools. The footer names ek9_help / ek9_ask / ek9_explain_error as the next calls. Independent of workspace compile state; always succeeds. CLI parity: ek9 -h -E4 (withExamples adds forAI.json's inlineExamples, the harness's -E4x).","arguments":[{"name":"withExamples","type":"boolean","required":false,"description":"Append forAI.json's compiled inlineExamples after the summary (default false; ~55K chars more)"}],"lessons":["https://ek9.io/ide/help-and-docs.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_promote_to_constant","url":"https://ek9.io/mcp/ek9_promote_to_constant.html","category":"editor","description":"Moves a `name <- literal` declaration into the module's `defines constant` block (same name, original deleted); answers status, edits[] and conflicts[] (no-promotable-declaration, initialiser-not-a-literal, constant-name-collision).","whenToUse":"'Make temperature a module constant' is one call with file + symbol:'temperature' - no line needed. Use it when a whole `name <- literal` declaration (a property or a local) should become a shared module constant, keeping its name.","whenNotToUse":["Lifting a bare LITERAL and giving it a NEW name - use ek9_extract_constant (the literal-level sibling).","Wanting a different constant name (e.g. UPPER_SNAKE) — promote first, then rename with ek9_rename_symbol (there is no convention/rename parameter here).","The `<-` value is a compound expression, a call, or an interpolated backtick string — EK9 constants are literal-valued so it can never be promoted; lift a literal sub-expression with ek9_extract_constant instead."],"details":"conflicts kinds: 'no-promotable-declaration' (line is not a simple name <- value), 'initialiser-not-a-literal' (compound/call/interpolated value), 'constant-name-collision' (a module constant already has that name — rename the declaration first). Placement is shared with ek9_extract_constant via ConstantBlockPlacer: append to the module's existing `defines constant` block (even cross-file, to avoid E11066/E11067) or create one; a 'constants-scattered' advisory attaches when constants already span 2+ files. Only the `identifier <- literal` form is promoted (name AND type preserved; the `as Type:` form is deferred — constant grammar has no type annotation), and typical would-fail causes are a now-immutable value reassigned or an external member access that no longer resolves.","arguments":[{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 source file holding the `name <- literal` declaration."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"The identifier you mean (e.g. 'total'); the tool finds its declaration line in file. Pass line only to anchor one specific occurrence."}],"lessons":["https://ek9.io/ide/promote-to-constant.html"],"fixes":[],"example":{"scenario":"Interpolated value refused","request":{"file":"task.ek9","symbol":"banner"},"response":{"conflicts":[{"kind":"initialiser-not-a-literal","message":"The declaration's value is not a single literal (it is a compound expression, a call, or an interpolated string), so it cannot become a constant — EK9 constants are literal-valued."}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Initialiser is not a literal","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_prune_empty_sources","url":"https://ek9.io/mcp/ek9_prune_empty_sources.html","category":"editor","description":"Deletes every .ek9 file that is a bare zero-construct module stub (shebang + 'defines module' + //EOF, line comments allowed); answers status, edits[] (one DELETE per file) and skipped[] with a reason per retained candidate.","whenToUse":"'Delete every empty module stub left after the relocation' is one call with no arguments (narrow with roots and/or moduleFilter:['com.example.i18n']). Use it AFTER a pure-relocation tool has left donor files as bare 'defines module' shells; it needs a prior ek9_compile.","whenNotToUse":["You know the exact single file to delete - use ek9_delete_file; this tool is bulk-discovery + filter.","The stub still has block/doc comments you want pruned anyway — run ek9_remove_comments first to make it eligible, then this tool.","The empty stubs are intentional placeholders (TODO scaffolds, planned module structure) — leave them; do not run this tool."],"details":"Two-stage detection: symbol-table walk for zero-construct module scopes, then a lex-only confirmation of the bare `#!ek9 / defines module / //EOF` shape — line `//` comments count as whitespace (pruned); block (`<!- -!>`) and doc (`<?- -?>`) comments are preserving. Pure deletion (only `delete` edits, never rewrites); non-deleted candidates go in `skipped[]` (reason ∈ has-comments | has-unrecognised-content | not-a-stub | module-filter-mismatch | outside-roots) with a `retainedContent` line-slice, while status:conflicts is reserved for a locked/unreadable file (kind:file-locked-or-unreadable). `dirtyOverlay` is V1 schema-accepted but not consumed; when supplied it appears in the response's `deferredParameters[]`.","arguments":[{"name":"moduleFilter","type":"any","required":false,"description":"Restrict candidates to files declaring this exact `defines module <name>` (an array of one name, or the bare name). When omitted, every module in the scanned roots is considered."},{"name":"roots","type":"array of string","required":false,"description":"Workspace-relative directories to scan. When omitted, defaults to the watched workspace roots."}],"lessons":[],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_pull_up","url":"https://ek9.io/mcp/ek9_pull_up.html","category":"editor","description":"Moves the named methods/operators from a subclass into its superclass, dropping 'override' on the moved declarations; answers status and edits[] (one DELETE per member + one INSERT on the superclass).","whenToUse":"'Move describe() from Circle up to its superclass' is one call with symbol:'Circle', members:['describe'] - no file or line needed; the superclass comes from the 'extends' clause. Use it when a subclass member belongs on the parent (siblings duplicate it, or the abstraction was authored one level too low).","whenNotToUse":["The OPPOSITE direction - demote a member from the parent into subclasses - use ek9_push_down.","The target trait/superclass does not exist yet and you want it created + members moved in one shot — use ek9_extract_trait.","Adding an implementation for an abstract trait method onto a class (opposite direction) — use ek9_implement_methods.","Renaming a member rather than relocating it — use ek9_rename_symbol."],"details":"V1: to the superclass only, with subclass and superclass declared in the SAME file — a trait target, cross-file targets and fields are follow-ups and return status:error today. The superclass must already be 'as open' / 'as abstract'; this tool does not add it — chain ek9_make_open first. An unopened superclass (E05030), a member referencing subclass-only state, a name collision on the superclass, or a sibling now shadowing without override (E05120) are caught by the scratch-compile would-fail gate.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"members","type":"array of string","required":true,"description":"Names of methods/operators on the subclass to pull up. Operators use their symbol form (e.g. '==', '<=>')."},{"name":"superclass","type":"string","required":false,"description":"Optional — the superclass name. When omitted it is resolved from the subclass's 'extends' clause; when supplied it is validated against that superclass."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/pull-up.html"],"fixes":[],"example":{"scenario":"No superclass error","request":{"file":"solo.ek9","line":6,"members":["label"]},"response":{"conflicts":[],"edits":[],"error":{"message":"'Solo' has no superclass to pull up to — it does not 'extends' a parent class"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"'Solo' has no superclass to pull up to — it does not 'extends' a parent class","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_push_down","url":"https://ek9.io/mcp/ek9_push_down.html","category":"editor","description":"Removes the named methods/operators from a superclass and copies them into each named direct subclass; answers status, edits[] (one DELETE + one INSERT per subclass) and conflicts[] (subclass-not-direct, target-is-only-source-class).","whenToUse":"'Move fly() from Shape down into Eagle and Sparrow' is one call with symbol:'Shape', members:['fly'], subclasses:['Eagle','Sparrow'] - no file or line needed. Use it when a superclass member is only needed by some direct subclasses (the abstraction was over-promoted).","whenNotToUse":["Promoting a member UP from subclasses to the superclass (the opposite) - use ek9_pull_up.","Removing the member from the hierarchy entirely, with no subclass needing it - use ek9_safe_delete (also the fix when the source class has no subclasses).","The fix is access-level, not relocation (e.g. make it private/internal) - use ek9_change_visibility.","Traits, not classes - traits are behaviour contracts with implementors, not subclasses; edit the trait directly and use ek9_query_references to find consumers."],"details":"Class hierarchies ONLY, methods/operators ONLY (fields not yet supported); each named DIRECT subclass gets an identical copy of every member (no per-subclass body customisation). 'override' is DROPPED from copies by default (no parent left to override, else E05100); set keepAsOverride:true ONLY for multi-level hierarchies where an ancestor above the source still declares the member. status:conflicts kinds: subclass-not-direct, target-is-only-source-class; external callers reaching the member via the superclass type surface as status:would-fail from the scratch compile.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"keepAsOverride","type":"boolean","required":false,"description":"Keep the 'override' modifier on the subclass copies (only for multi-level hierarchies where an ancestor above the superclass still declares the member)."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"members","type":"array of string","required":true,"description":"Names of methods/operators on the superclass to push down. Operators use their symbol form (e.g. '==', '<=>')."},{"name":"subclasses","type":"array of string","required":true,"description":"Names of DIRECT subclasses to receive the pushed-down members. Empty errors."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/push-down.html"],"fixes":[],"example":{"scenario":"Subclass not direct conflict","request":{"file":"shapes.ek9","line":6,"members":["area"],"subclasses":["Square","NotASubclass"]},"response":{"conflicts":[{"kind":"subclass-not-direct","message":"Not direct subclasses of 'Shape': NotASubclass (direct subclasses: Circle, Square)"}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Not all subclasses are direct subclasses of Shape","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_build_status","url":"https://ek9.io/mcp/ek9_query_build_status.html","category":"enquiry","description":"Answers first: programState, queriesReliable with its reason, buildOutcome, lastPhaseReached, then sourceCount/sourcesClean/sourcesWithErrors and sources[] with per-file error and warning counts.","whenToUse":"Has the workspace compiled, and can the query tools be trusted right now - one call, no arguments (fileFilter narrows the per-source list).","whenNotToUse":["The LIST of errors/warnings rather than build-state metadata - use ek9_query_diagnostics.","You want to TRIGGER a compile, not query existing state - use ek9_compile.","You want the structural inventory (constructs, modules) - use ek9_query_workspace.","You want the compiler binary version, not workspace build state - use ek9_version."],"details":"A gate-check that always succeeds at any phase — the result IS the report. queriesReliable is true once the compile reached PRE_IR_CHECKS (the phase that builds the call graph and the metrics the symbol-anchored query tools read); reason names the phase reached. buildOutcome is success (no source has errors), partial-success (some sources clean) or failure; programState is the shared clean / partial / unavailable envelope every architecture enquiry carries.","arguments":[{"name":"fileFilter","type":"string","required":false,"description":"Optional: keep only sources whose path contains this text"}],"lessons":[],"fixes":[],"example":{"scenario":"Build status shape","request":{},"response":{"buildOutcome":"success","lastPhaseReached":"PRE_IR_CHECKS","meta":{"serverMs":"<timing>"},"phaseNumber":9,"programState":"clean","queriesReliable":true,"reason":"reached PRE_IR_CHECKS","sourceCount":1,"sources":[{"file":"MyRecord.ek9","hasErrors":false,"hasWarnings":false,"warningCount":0}],"sourcesClean":1,"sourcesWithErrors":0,"totalPhases":23}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_call_graph","url":"https://ek9.io/mcp/ek9_query_call_graph.html","category":"enquiry","description":"Answers first: callerNames / calleeNames and callerSites / calleeSites ('file.ek9:LINE') - then the chain to the requested depth.","whenToUse":"Who calls a method or function, and what does it call, to a depth - one call with symbol:'Type.member', no file needed.","whenNotToUse":["Every reference to a symbol (types, fields, not just method calls) — use ek9_query_references (symbol-level usage, not call chains).","Analysis WITHIN one body — use ek9_query_flow for control flow (branches, loops), or ek9_query_pipeline for stage-level stream-pipeline analysis.","All callable members of a TYPE, not one method's calls — use ek9_query_effective_api.","Details of one symbol at a cursor rather than call chains — use ek9_inspect_symbol_at_cursor."],"details":"direction: 'both' (default) | 'outgoing' (callees, what this depends on) | 'incoming' (callers, refactor-impact); depth 0-5 (default 1, capped at 5), with depth>1 recursing via a nested children[] per node — hop level is implicit in nesting. Response: the headline names and sites, the target's flat signature/complexity fields, then incomingCalls[]/outgoingCalls[]; each node carries caller or callee (display name), fullyQualifiedName, calledAt 'file.ek9:LINE' (the call expression; a caller calling more than once has its first here and the rest in alsoCalledAt[]), declaredAt 'file.ek9:LINE' (the callable's declaration), callKind (function-call | method-call), pure and context (the source line at the call site). The graph is built during PRE_IR_CHECKS — a workspace compiled to an earlier phase errors with the reached phase (the default ek9_compile phase suffices), and a line not on a method/function returns {callGraph:'not_found', message:...}.","arguments":[{"name":"among","type":"array of string","required":false,"description":"Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched)."},{"name":"depth","type":"integer","required":false,"description":"Maximum traversal depth (0-5, default 1)"},{"name":"direction","type":"string: both | outgoing | incoming","required":false,"description":"Direction: 'both' (default), 'outgoing', or 'incoming'"},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/call-graph.html"],"fixes":[],"example":{"scenario":"Program by symbol","request":{"direction":"outgoing","symbol":"Main"},"response":{"calleeNames":["greet"],"calleeSites":["Hello.ek9:13"],"callerNames":[],"callerSites":[],"depth":1,"direction":"outgoing","enclosingGenus":"PROGRAM","enclosingType":"Main","fullyQualifiedName":"com.example.hello::Main","meta":{"serverMs":"<timing>"},"method":"Main","outgoingCallCount":1,"outgoingCalls":[{"callKind":"function-call","calledAt":"Hello.ek9:13","callee":"greet","context":"greet(\"World\")","declaredAt":"Hello.ek9:6","fullyQualifiedName":"com.example.hello::greet","pure":false}],"parameters":[],"pure":false,"returnType":"Void","status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_capability_usage","url":"https://ek9.io/mcp/ek9_query_capability_usage.html","category":"enquiry","description":"Answers first: consistent, underDeclared, overDeclared, usedCapabilities, declaredCapabilities and findings, then actualUsage with every call site - the workspace-wide gated-type audit against the package block.","whenToUse":"Which capabilities does the code actually need versus what the package block declares - one call, no arguments; underDeclared and overDeclared answer it. Capabilities are the gated types: network, filesystem, env-var, stdio, process, clock.","whenNotToUse":["JUST the declared capabilities, not the actual-vs-declared comparison — use ek9_query_package.","Auditing secret-handling code (Sensitive.reveal callers), not capability usage — use ek9_query_sensitive_reveals. ('what env vars do I read?' is a CAPABILITY question, use THIS tool.)","You want the LIST of capability errors (use ek9_query_diagnostics) or one E12010 explained (use ek9_explain_error), not the full usage analysis.","You want method-level call relationships, not capability-level access — use ek9_query_call_graph."],"details":"Capabilities are FQ gated-type names (org.ek9.lang::TCP / Stdout / File / EnvVars / OS / Clock …), NOT abstract kinds; the audit mirrors phase-5 CapabilityTypeReferenceOrError via the shared GatedTypeMapping, so underDeclared is EXACTLY the set that fires E12010 and overDeclared is declared-but-unused (leave-one-out, so alt-coverage like NetworkProperties covered by TCP/UDP is respected). The audit verdict applies ONLY when publishable:true (publicAccess + version + license + capabilities) — otherwise usage is informational, consistent is vacuously true and a note says so — and stays workspace-wide regardless of the filters, which narrow displayed call sites only. actualUsage is an OPEN map keyed by capability → {used, callSites[{site,file,line,column,type,module,inConstruct,inConstructFqn}]}; needs a compile reaching types_resolved (unresolved types are silently not counted); remediate via ek9_add_capability / ek9_remove_capability.","arguments":[{"name":"capability","type":"string","required":false,"description":"Optional filter — restrict actualUsage to a single fully-qualified capability (e.g. \"org.ek9.lang::TCP\", \"org.ek9.lang::Stdout\"). An open string, NOT an enum — an unknown value simply matches nothing. Omit for all capabilities. Narrows the displayed call sites only; the audit remains workspace-wide."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Optional: exact module names (an entry ending in * is a prefix) whose call sites to display; a bare string is accepted as a one-element list. Omit for workspace-wide. Narrows displayed call sites only; the audit remains workspace-wide."}],"lessons":["https://ek9.io/ide/capabilities.html"],"fixes":[],"example":{"scenario":"Capability filter no match","request":{"capability":"org.ek9.lang::TCP"},"response":{"actualUsage":{"org.ek9.lang::TCP":{"callSites":[],"used":false}},"consistent":true,"declaredCapabilities":["org.ek9.lang::Stdout"],"findings":[],"meta":{"serverMs":"<timing>"},"overDeclared":[],"publishable":true,"status":"ok","underDeclared":[],"usedCapabilities":[]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_classes","url":"https://ek9.io/mcp/ek9_query_classes.html","category":"enquiry","description":"Answers first: classNames[], then classes[] (name, module, file, line, extends, traits, isOpen, isAbstract, keyMethods, methodCount) and summary counts - workspace-wide or the filtered subset.","whenToUse":"Is there already a class I can reuse, extend or compose - one call with nameFilter:'User'; no arguments lists every class. Narrow further with extendsFilter, traitFilter, methodNameFilter or moduleFilter.","whenNotToUse":["Looking for a pure data shape with no methods — use ek9_query_records.","Looking for an interface contract — use ek9_query_traits.","Looking for a DI-injectable component (a specialised class kind) — use ek9_query_components.","You already have a class name — use ek9_query_type_hierarchy (full hierarchy graph), ek9_query_effective_api (complete method API), or ek9_read_construct (source)."],"details":"EK9 classes are CLOSED by default — check isOpen before planning to extend; for a closed candidate the reuse path is composition (use as a field). status:empty means the walk succeeded but nothing matched — non-existent extends/trait/module targets surface in meta.unmatchedFilters[], NOT as an error; no compiled program is status:not-compiled (run ek9_compile first), and the only error is a traitMatch other than any/all. nameFilter/methodNameFilter are plain case-insensitive substrings, never regex; built-in org.ek9.* stdlib classes are excluded. traitFilter and extendsFilter name a trait/class EXACTLY (bare name, or module::Name for one module's) and match by symbol, transitively; traitMatch picks any-of (default) or all-of, and traitFilterResolvedTo lists the traits the filter matched. A value naming no trait/class is in meta.unmatchedFilters[], with meta.didYouMean naming those that contain it. traitFilter covers classes: records and components cannot carry traits, and the traits that extend a trait are in ek9_query_traits implementedBy.","arguments":[{"name":"among","type":"array of string","required":false,"description":"Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched)."},{"name":"extendsFilter","type":"string","required":false,"description":"Filter to classes whose extends-chain transitively includes this superclass name."},{"name":"includeAbstract","type":"boolean","required":false,"description":"Default true. When false, excludes classes marked 'as abstract'."},{"name":"includeMethodSummary","type":"boolean","required":false,"description":"Default true. When true each entry includes keyMethods[] (up to 5 public signatures). Set false for a lighter response."},{"name":"methodNameFilter","type":"string","required":false,"description":"Filter to classes declaring a method whose name matches (case-insensitive substring)."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to these exact module names. Default: workspace-wide."},{"name":"nameFilter","type":"string","required":false,"description":"Case-insensitive substring match on class names."},{"name":"traitFilter","type":"array of string","required":false,"description":"Filter to classes carrying the listed traits (transitive) - any one of them, or every one with traitMatch:'all'. Exact names, bare or module::Name."},{"name":"traitMatch","type":"string: any | all","required":false,"description":"How traitFilter combines: 'any' (default) - at least one; 'all' - every one."}],"lessons":[],"fixes":[],"example":{"scenario":"Partial trait filter","request":{"traitFilter":["Ident"]},"response":{"classNames":[],"classes":[],"meta":{"didYouMean":{"trait:Ident":["Identifiable"]},"serverMs":"<timing>","unmatchedFilters":["trait:Ident"]},"status":"empty","summary":{"abstractCount":0,"classCount":0,"moduleCount":0,"openCount":0},"traitFilterResolvedTo":[],"traitMatch":"any"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_complexity","url":"https://ek9.io/mcp/ek9_query_complexity.html","category":"enquiry","description":"Answers first: in view 'totals' the workspace-wide methodCount, averages, maxima and methodsAboveCyclomaticThreshold / methodsAboveCognitiveThreshold; in 'hotspots' hotspotNames[] then hotspots[]; in 'inputVariety' per-callable floor/ceiling (display-only).","whenToUse":"Which methods are too complex, or how complex is the workspace overall - one call with view:'hotspots' or view:'totals'; no anchor needed. Tune the hotspots view with complexityThreshold and metric.","whenNotToUse":["Analysing ONE specific method's internal control-flow structure — use ek9_query_flow (complexity FINDS complex methods; flow ANALYSES one of them).","Test coverage (line/branch/method) — use ek9_run_tests / ek9_run_quality_checks.","Per-test pass/fail outcomes — use ek9_run_tests.","Compile errors/warnings, including complexity-threshold violations as diagnostics — use ek9_query_diagnostics (this tool returns the metric VALUES, not the violations)."],"details":"Three views: totals (fixed industry thresholds 10 cyclomatic / 15 cognitive, echoed as cyclomaticThreshold / cognitiveThreshold), hotspots (methods with the chosen metric >= complexityThreshold, default cyclomatic >= 10, sorted descending) and inputVariety (per-callable floor/ceiling input-variation figures + confidence, plus per-type rollups - DISPLAY ONLY, never a gate or a target). fileFilter (a path substring) is honoured in every view; complexityThreshold < 1 is clamped to 1. Metrics are squirrelled at PRE_IR_CHECKS, so compilation must reach that phase (queriesReliable:true on ek9_query_build_status) — no test run needed; an empty or earlier-stalled workspace returns methodCount 0 / empty arrays.","arguments":[{"name":"complexityThreshold","type":"integer","required":false,"description":"Hotspots view: methods with metric >= complexityThreshold. Default 10."},{"name":"fileFilter","type":"string","required":false,"description":"Optional: keep only methods whose source path contains this text."},{"name":"metric","type":"string: cyclomatic | cognitive","required":false,"description":"Which metric to threshold on in the hotspots view."},{"name":"view","type":"string: totals | hotspots | inputVariety","required":false,"description":"Which view: totals (aggregate stats), hotspots (above-threshold methods), or inputVariety (per-construct input-variation figures, display-only)."}],"lessons":["https://ek9.io/ide/complexity-limits.html"],"fixes":[],"example":{"scenario":"Summary shape","request":{"view":"totals"},"response":{"meta":{"serverMs":"<timing>"},"totals":{"averageCognitive":0.0,"averageCyclomatic":1.0,"cognitiveThreshold":15,"cyclomaticThreshold":10,"maxCognitive":0,"maxCyclomatic":1,"methodCount":1,"methodsAboveCognitiveThreshold":0,"methodsAboveCyclomaticThreshold":0},"view":"totals"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_components","url":"https://ek9.io/mcp/ek9_query_components.html","category":"enquiry","description":"Answers first: componentNames[], then components[] (name, module, file, line, extends, isOpen, isAbstract, keyMethods, methodCount) and summary counts - the DI-injectable constructs, workspace-wide or the filtered subset.","whenToUse":"Is there already a DI component I can reuse or extend - one call with nameFilter:'Logger'; no arguments lists every component. Narrow with extendsFilter, moduleFilter or includeAbstract:false.","whenNotToUse":["The construct is a plain class, not a DI component — use ek9_query_classes instead.","You want the actual DI wiring graph (who injects what) — use ek9_query_dependency_injection instead.","You know a component's name and want its full inheritance chain — use ek9_query_type_hierarchy instead.","You know the component's name and want its full source — use ek9_read_construct instead."],"details":"status ok = one or more matched; empty = filtered set empty (incl. a moduleFilter naming non-existent modules, surfaced in meta.unmatchedFilters[] as module:<value>) and is NOT an error; error = no compiled program (run ek9_compile first). nameFilter/methodNameFilter are plain case-insensitive substrings, not regex; built-in org.ek9.* components are excluded. extends is null unless a super-component is declared (implicit Any filtered out); keyMethods are EK9-syntax signatures, constructors-first, public-only, capped at 5; unresolved types render as <unresolved> without a partial status.","arguments":[{"name":"extendsFilter","type":"string","required":false,"description":"Filter to components whose extends-chain transitively includes this super-component name."},{"name":"includeAbstract","type":"boolean","required":false,"description":"Default true. When false, excludes components marked 'as abstract'."},{"name":"includeMethodSummary","type":"boolean","required":false,"description":"Default true. When true each entry includes keyMethods[] (up to 5 public signatures). Set false for a lighter response."},{"name":"methodNameFilter","type":"string","required":false,"description":"Filter to components declaring a method whose name matches (case-insensitive substring)."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to these exact module names. Default: workspace-wide."},{"name":"nameFilter","type":"string","required":false,"description":"Case-insensitive substring match on component names."}],"lessons":[],"fixes":[],"example":{"scenario":"Partial extends unmatched","request":{"extendsFilter":"Log"},"response":{"componentNames":[],"components":[],"meta":{"didYouMean":{"extends:Log":["Logger","ConsoleLogger"]},"serverMs":"<timing>","unmatchedFilters":["extends:Log"]},"status":"empty","summary":{"abstractCount":0,"componentCount":0,"moduleCount":0,"openCount":0}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_constrained_types","url":"https://ek9.io/mcp/ek9_query_constrained_types.html","category":"enquiry","description":"Answers first: constrainedTypeNames[], then constrainedTypes[] (name, module, file, line, constrains, constraint, admissibleWindow, suffix) and summary counts.","whenToUse":"Is there already a constrained type over this base, or admitting this range - one call with baseTypeFilter:'String' or nameFilter:'Email'. Scope it with moduleFilter; no arguments lists every constrained type.","whenNotToUse":["Looking for multi-field data shapes — use ek9_query_records instead.","Looking for a class with behaviour — use ek9_query_classes instead.","You want the constrained type's full SOURCE (the declaration as written, comments and all) — use ek9_read_construct instead. This response carries the constraint predicate itself, so it answers 'what does it admit?' without reading the source."],"details":"constraint is the predicate as written ('>= 16 and <= 100'), present whenever the compiler modelled it. admissibleWindow is the inclusive interval it folds to, present only for a decidable Integer range. suffix is the shared currency or unit ('#GBP', 'mm') when the literals carry one — a Money type over GBP does not serve a USD need. constrains is the base type recovered from the synthesized base constructor (the super-aggregate is Any, not the base). nameFilter/baseTypeFilter are plain case-insensitive substrings, not regex; moduleFilter is an exact-name allow-list; built-in org.ek9.* types are excluded. status: ok (matches returned) / empty (none match, or moduleFilter named a non-existent module — meta.unmatchedFilters[] then carries module:<value>) / error (no compiled program — run ek9_compile first).","arguments":[{"name":"baseTypeFilter","type":"string","required":false,"description":"Filter to constrained types whose base type matches (case-insensitive, e.g. 'String' finds EmailAddress, PostCode, ...)."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to these exact module names. Default: workspace-wide."},{"name":"nameFilter","type":"string","required":false,"description":"Case-insensitive substring match on constrained-type names."}],"lessons":[],"fixes":[],"example":{"scenario":"List all","request":{},"response":{"constrainedTypeNames":["DrivingAge","Salary"],"constrainedTypes":[{"admissibleWindow":"[16, 100]","constrains":"Integer","constraint":">= 16 and <= 100","file":"constrained.ek9","line":6,"module":"com.example.constrained","name":"DrivingAge"},{"constrains":"Money","constraint":">= 10000#GBP and <= 120000#GBP","file":"constrained.ek9","line":9,"module":"com.example.constrained","name":"Salary","suffix":"#GBP"}],"meta":{"serverMs":"<timing>"},"status":"ok","summary":{"constrainedTypeCount":2,"moduleCount":1}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_construct","url":"https://ek9.io/mcp/ek9_query_construct.html","category":"enquiry","description":"Answers first: fieldNames, methodNames, operatorNames, defaultedOperatorNames, superName, traitNames, then construct{name, fullyQualifiedName, module, genus, isOpen, extends, traits, modifiers} and the full fields/methods/operators/constructors/metrics.","whenToUse":"Everything about one type or function in one call - fields, methods, operators, supertype, traits, metrics - with symbol:'Order', no file needed. An IDE cursor (file + line anywhere inside the construct) also works; defaulted operators are marked.","whenNotToUse":["JUST the effective member list (own + inherited + trait-provided), not the whole construct - use ek9_query_effective_api.","You want the WHOLE module, not a single construct - use ek9_query_module.","You have file + line + COLUMN and want the exact symbol at the cursor (parameter, local, …), finer than construct-level - use ek9_inspect_symbol_at_cursor.","You want one method's call relationships, not the construct's structure - use ek9_query_call_graph."],"details":"ONE uniform shape for every genus: the name lists first, then the header under 'construct{}' (name, fullyQualifiedName, module, genus, modifiers, declaration 'line', isOpen, flat 'extends' + 'traits', generic template/parameterised-type info, 'serviceUri' for services) with sibling fields/methods/operators/constructors/metrics. A FUNCTION reuses that shape — parameters appear as 'fields', the return as a single 'methods' entry, operators/constructors empty. Metrics carry complexity/cohesion/coupling/inheritanceDepth plus member counts; 'coupling' MAY be fractional (each by-trait delegation discounts 0.5).","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line anywhere inside the target construct - OMIT it and pass symbol:'<name>' instead."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/one-construct.html"],"fixes":[],"example":{"scenario":"Construct shape","request":{"file":"MyRecord.ek9","line":5},"response":{"construct":{"extends":"Any","fullyQualifiedName":"com.example::MyRecord","genus":"RECORD","isOpen":false,"line":5,"modifiers":[],"module":"com.example","name":"MyRecord"},"constructors":[{"parameters":[]}],"defaultedOperatorNames":["?","$","$$",":=:","<=>","==","<>","<","<=",">",">=","#?"],"fieldNames":["name"],"fields":[{"mutable":true,"name":"name","type":"String"}],"meta":{"serverMs":"<timing>"},"methodNames":[],"methods":[],"metrics":{"cohesion":1,"complexity":1,"coupling":0,"fieldCount":1,"inheritanceDepth":0,"methodCount":0,"operatorCount":12,"totalCyclomaticComplexity":0},"name":"MyRecord","operatorNames":["?","$","$$",":=:","<=>","==","<>","<","<=",">",">=","#?"],"operators":[{"defaulted":true,"operator":"?","parameters":[],"pure":true,"returnType":"Boolean"},{"defaulted":true,"operator":"$","parameters":[],"pure":true,"returnType":"String"},{"defaulted":true,"operator":"$$","parameters":[],"pure":true,"returnType":"JSON"},{"defaulted":true,"operator":":=:","parameters":[{"name":"param","type":"MyRecord"}],"pure":false,"returnType":"Void"},{"defaulted":true,"operator":"<=>","parameters":[{"name":"param","type":"MyRecord"}],"pure":true,"returnType":"Integer"},{"defaulted":true,"operator":"==","parameters":[{"name":"param","type":"MyRecord"}],"pure":true,"returnType":"Boolean"},{"defaulted":true,"operator":"<>","parameters":[{"name":"param","type":"MyRecord"}],"pure":true,"returnType":"Boolean"},{"defaulted":true,"operator":"<","parameters":[{"name":"param","type":"MyRecord"}],"pure":true,"returnType":"Boolean"},{"defaulted":true,"operator":"<=","parameters":[{"name":"param","type":"MyRecord"}],"pure":true,"returnType":"Boolean"},{"defaulted":true,"operator":">","parameters":[{"name":"param","type":"MyRecord"}],"pure":true,"returnType":"Boolean"},{"defaulted":true,"operator":">=","parameters":[{"name":"param","type":"MyRecord"}],"pure":true,"returnType":"Boolean"},{"defaulted":true,"operator":"#?","parameters":[],"pure":true,"returnType":"Integer"}],"status":"ok","superName":"Any","traitNames":[]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_construct_neighbourhood","url":"https://ek9.io/mcp/ek9_query_construct_neighbourhood.html","category":"enquiry","description":"Answers first: nodeCount, nodes[] (name, fullyQualifiedName, module, genus, file, line, distance), edges[] (from, to, kind) and edgesByKind - the N-hop typed ego graph merging inheritance, calls, composition, references and DI.","whenToUse":"If I change this construct, what is structurally affected - one call with symbol:'Order' and direction:'incoming' (the blast radius), no file needed.","whenNotToUse":["ONLY inheritance/trait ancestry — use ek9_query_type_hierarchy.","You want ONLY call edges — use ek9_query_call_graph.","You want the exhaustive per-site reference list (not the typed structural shape) — use ek9_query_references.","You want module-altitude coupling, not one construct's neighbourhood — use ek9_query_module_coupling."],"details":"Edge kinds: extends/implements/composes(field types)/references(param/return types)/calls(phase-5 call graph)/injects(DI fields)/dispatches(dispatcher overload group) — all types generic-unwrapped, only user-construct↔user-construct edges kept, each node carries 'distance' from the target. A virtual call THROUGH an injected abstract field is a 'calls' edge to the abstract type, which has a 'calls' edge on to each implementation that is constructed somewhere (a register in the application counts) - one hop more, never none. A function's implicit generic super ('Consumer of Address') gives 'references', not 'extends', to its type argument. Also emits 'requirements[]' (whose anchoring tests can REACH this construct) over the FULL transitive closure — never limited by 'depth', over-inclusive by construction (reach is change-impact, NOT what this construct implements); reachResolved=false means no call graph to answer from; test nodes carry isTest/requirementRef.","arguments":[{"name":"depth","type":"integer","required":false,"description":"How many edges out from the target (default 1, max 5)."},{"name":"direction","type":"string: both | incoming | outgoing","required":false,"description":"'outgoing' = what it depends on, 'incoming' = what depends on it (the blast radius), 'both' (default)."},{"name":"edgeKinds","type":"array of string: extends | implements | composes | references | calls | injects | dispatches","required":false,"description":"Restrict to these relationships. Omit for all."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"The construct: a bare name ('Order') or a qualified name ('com.acme.orders::Order') - no file needed, the tool finds it workspace-wide; 'Type.member' anchors on the member's construct."}],"lessons":["https://ek9.io/ide/call-graph.html"],"fixes":[],"example":{"scenario":"Parameterised super references its argument","request":{"direction":"incoming","symbol":"sample.arch.model::Address"},"response":{"depth":1,"direction":"incoming","edgeCount":1,"edges":[{"from":"sample.arch.model::stamp","kind":"references","to":"sample.arch.model::Address"}],"edgesByKind":{"references":1},"meta":{"serverMs":"<timing>"},"nodeCount":2,"nodes":[{"distance":0,"file":"model.ek9","fullyQualifiedName":"sample.arch.model::Address","genus":"RECORD","line":6,"module":"sample.arch.model","name":"Address"},{"distance":1,"file":"model.ek9","fullyQualifiedName":"sample.arch.model::stamp","genus":"FUNCTION","line":20,"module":"sample.arch.model","name":"stamp"}],"note":"requirements whose anchoring tests CAN REACH this construct — transitive, not limited by 'depth', and over-inclusive by construction: reach is not implementation","programState":"clean","reachResolved":true,"requirements":[],"status":"ok","target":{"distance":0,"file":"model.ek9","fullyQualifiedName":"sample.arch.model::Address","genus":"RECORD","line":6,"module":"sample.arch.model","name":"Address"}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_data_touch","url":"https://ek9.io/mcp/ek9_query_data_touch.html","category":"enquiry","description":"Answers first: anchor and verdicts (parameter → untouched | mutates | escapes | ... ), then touches[] with the mutation and escape axes and every contributing site - read-only.","whenToUse":"Does this callable (or what it calls) write through the structure I pass, or keep a reference to it - one call with symbol:'Stash.keep' and parameter:'items'. No file needed; omit parameter for a verdict per parameter.","whenNotToUse":["Whether a callable is pure (no side effects at all), not whether it touches ONE structure you pass — use ek9_query_purity_impact / the purity diagnostics.","You want raw caller/callee chains without the touch overlay — use ek9_query_call_graph.","You want to CHANGE code — data-touch is a read-only enquiry, it has no fix."],"details":"Returns status:ok with 'anchor' (the resolved callable, display form) and 'verdicts' (parameter → verdict) first, then 'touches' — one entry per tracked parameter: {parameter, mutation, escape, verdict (untouched / mutates / mutates-via / escapes / escapes-via / mutates-and-escapes / mutates-and-escapes-via / unknown), reusable, sites[], unknowns[]}. Each mutation/escape site carries file:line, kind, axis, the source 'path' touched, and — when TRANSITIVE — the 'via' callee chain plus the origin file:line where the write/store really happens. Escape currently observes user-code whole-structure store/return only; container retain-into (list += arg) reads no-escape until the retention table lands (a documented trust residual). Runs on demand over FULL_RESOLUTION (or default ek9_compile).","arguments":[{"name":"column","type":"integer","required":false,"description":"Optional 0-based IDE column. Advisory — the anchor is the enclosing callable, resolved by line, so this may be omitted."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line inside the callable whose parameter you are tracking (the enclosing method or function is resolved from it) - OMIT it and pass symbol instead."},{"name":"parameter","type":"string","required":false,"description":"The parameter name to track (the data structure). Omit to get a verdict for EVERY parameter of the callable."},{"name":"symbol","type":"string","required":false,"description":"The callable: 'Stash.keep' (Type.member) or a bare function name - no file needed, the tool finds it workspace-wide; or, with file (+ line), the name you mean there."}],"lessons":[],"fixes":[],"example":{"scenario":"Direct store","request":{"file":"locks.ek9","line":17,"parameter":"items"},"response":{"anchor":"Stash.keep(List of String)","meta":{"serverMs":"<timing>"},"status":"ok","touches":[{"escape":"may-escape","mutation":"no-mutation","parameter":"items","reusable":false,"sites":[{"axis":"escape","file":"locks.ek9","kind":"escape-store","line":17,"path":"held","transitive":false}],"unknowns":[],"verdict":"escapes"}],"verdicts":{"items":"escapes"}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_deadlock_chain","url":"https://ek9.io/mcp/ek9_query_deadlock_chain.html","category":"enquiry","description":"Answers first: chains[] - per detected lock risk its errorCode, path, outerLock/innerLock and ordered steps[] with file/line/column - chains:[] when nothing is at risk.","whenToUse":"Why does the analyser report E08252 / E08253 - the ordered, navigable steps behind every detected lock risk - one call, no arguments.","whenNotToUse":["WHETHER a deadlock exists (the count only) — use ek9_query_lock_analysis.","You want EVERY acquisition site, not just those in a detected chain — use ek9_query_enter_sites.","You want the lock catalogue (identities), not the risk chains — use ek9_query_lock_identity.","You want the raw E08252/E08253 compiler diagnostics rather than the analyser's rationale — use ek9_query_diagnostics."],"details":"status discriminates available (analysis ran; chains[] may be empty=clean) vs no-analysis (LockAnalysis absent — recompile to PRE_IR_CHECKS). Each chain: errorCode (E08252 same-thread order cycle / E08253 cross-thread same-lock hold), path (analysis-path enum), outerLock/innerLock (lock-identity descriptors; correlate stableId with ek9_query_lock_identity; an unresolvable identity degrades to {stableId,status:'unresolved'}), and steps[] (kind, description, location{1-based line,0-based column}, contextFunction, optional stepTarget). Dynamic anonymous symbols render in the friendly fn/cls form (the volatile mangled hash is suppressed) — disambiguate by location.","arguments":[],"lessons":["https://ek9.io/ide/concurrency.html"],"fixes":[],"example":{"scenario":"No locks workspace","request":{},"response":{"chains":[],"meta":{"serverMs":"<timing>"},"status":"available"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_dependency_injection","url":"https://ek9.io/mcp/ek9_query_dependency_injection.html","category":"enquiry","description":"Answers first: applicationCount and applications[] (registrations, injectionSites, boundPrograms, health incl. E11040 over-injection), programCount and programs[], then summary.","whenToUse":"How is dependency injection wired - which application registers what, where it is injected, which programs bind - one call, no arguments. Narrow to one application with applicationFilter.","whenNotToUse":["Module-level imports (references) rather than component wiring — use ek9_query_module_dependencies.","Method-level call relationships rather than component injection — use ek9_query_call_graph.","Compile errors/warnings themselves (E11040 over-injection, E08190 DI cycle) rather than the wiring graph — use ek9_query_diagnostics.","The structure of ONE specific component rather than the app-level graph — use ek9_query_construct."],"details":"Registrations report implementation/implementationFqn, kind ('component' adds interface/interfaceFqn; 'service' does not), optional aspects[] (components are always singleton-scoped — no scope field); injectionSites carry site ('Owner.field'), owner, field, type, typeFqn, satisfied. health.verdict is HEALTHY / UNSATISFIED_INJECTIONS / NO_REGISTRATIONS (satisfaction-based only); health.overInjectedComponents[] is the E11040 >4-injected-fields gate — one entry per offending component (fields[], injectionCount, limit), it does NOT flip verdict, and non-empty entries feed the split_overinjected_component workflow. Requires a prior compile; no compiled program → error.","arguments":[{"name":"applicationFilter","type":"string","required":false,"description":"Optional: keep only applications whose name contains this text"}],"lessons":["https://ek9.io/ide/services-and-di.html","https://ek9.io/ide/application-and-di.html"],"fixes":[],"example":{"scenario":"Di shape","request":{},"response":{"applicationCount":0,"applications":[],"meta":{"serverMs":"<timing>"},"programCount":0,"programs":[],"summary":{"applicationsWithIssues":0,"totalInjectionSites":0,"totalRegistrations":0}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_dependency_tree","url":"https://ek9.io/mcp/ek9_query_dependency_tree.html","category":"enquiry","description":"Answers first: direction, rootPackage, rootVersion, then tree{} (dependsOn) or deduplicated[] with broughtInBy (broughtInBy), selections[] and summary - the transitive package dependency tree across the workspace.","whenToUse":"What does this package pull in transitively, or why is module X pulled in - one call, no arguments for the whole tree. For the 'why', pass direction:'broughtInBy' and moduleFilter:'X'.","whenNotToUse":["YOUR DECLARED deps only (no transitive expansion) — use ek9_query_package.","You want module-level imports WITHIN your package, not the external dep tree — use ek9_query_module_dependencies.","You specifically want CYCLE DETECTION across the tree — use ek9_check_package_dependency_cycles.","You want to TRIGGER a resolution / fetch rather than query an existing one — use ek9_resolve_dependencies."],"details":"In-workspace scope: only packages whose source is in the compiled workspace are expanded; external deps appear as leaves with selectionNote 'external (not in workspace)'. direction:'dependsOn' is the nested DOWNWARD subtree ('what does X depend on?'), direction:'broughtInBy' the flat list with the UPWARD broughtInBy[] set ('what brings X in?'); format (nested | flat) is the same choice by shape, and giving both when they disagree is an error. moduleFilter is one exact module name (or a prefix with a trailing *): nested roots the subtree at the first match, flat keeps the matching modules; an unmatched filter still succeeds with a null/empty tree. selections[] lists each module's selected version; rejectedVersions[] is currently always empty (no remote version-conflict resolution), and revisited modules are pruned with selectionNote 'already present at shallower depth'.","arguments":[{"name":"direction","type":"string: dependsOn | broughtInBy","required":false,"description":"dependsOn (default): the downward tree from the root or the filtered module; broughtInBy: the flat list with, per module, the packages that pull it in."},{"name":"format","type":"string: nested | flat","required":false,"description":"Output shape: nested (hierarchical tree, = dependsOn) or flat (deduplicated list with broughtInBy, = broughtInBy). Optional when direction is given."},{"name":"moduleFilter","type":"string","required":false,"description":"Optional: one exact module name, or a prefix with a trailing *. dependsOn: the subtree rooted at the first match; broughtInBy: the matching modules with their broughtInBy."}],"lessons":[],"fixes":[],"example":{"scenario":"Flat filtered","request":{"direction":"broughtInBy","moduleFilter":"deptree.foundation"},"response":{"deduplicated":[{"broughtInBy":["deptree.middleware"],"module":"deptree.foundation","version":"1.0.0-0"}],"direction":"broughtInBy","meta":{"serverMs":"<timing>"},"rootPackage":"deptree.analytics","rootVersion":"3.0.0-0","summary":{"totalEdges":1,"uniqueModules":1}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_diagnostics","url":"https://ek9.io/mcp/ek9_query_diagnostics.html","category":"enquiry","description":"Answers first: diagnosticCount, errorCount, warningCount, errorCodes[] and sites[] ('file.ek9:LINE CODE message'), then diagnostics[] in full, byCode and byFile - the Problems View of the last compile.","whenToUse":"What is broken right now - every error and warning recorded by the last compile - one call, no arguments (fileFilter / severity / errorCode narrow it).","whenNotToUse":["One error code's WHY/QUICK FIX/EXAMPLE, not the current problem list — use ek9_explain_error.","You want to TRIGGER a compile rather than read already-recorded diagnostics — use ek9_compile (it produces diagnostics; this tool reads them).","You want build-state metadata (last outcome, freshness) rather than the diagnostics list — use ek9_query_build_status.","You want TEST pass/fail results rather than COMPILE diagnostics — use ek9_run_tests."],"details":"Each diagnostic carries file (workspace-relative), line, column, severity, errorCode ('SYNTAX' for a parse error, which has no E-code), message (one line, no colour codes, no embedded explanation), typeOfError and classificationDescription, plus a richExplanation when the code has one; quickFixes and offendingSymbol are on by default while there are 20 diagnostics or fewer (pass the include* flag to force either way), fuzzySuggestions and tokenLength are opt-in, and codes with a mapped fix tool gain a remediation[] list. severity is all|errors|warnings, fileFilter is a path substring, and a filter matching nothing yields diagnostics:[] with zero counts — success, not an error. byCode and byFile count diagnostics (errors+warnings combined); no workspace returns {diagnostics:'unavailable', message:...}.","arguments":[{"name":"errorCode","type":"string","required":false,"description":"Optional specific error code filter (e.g., 'E05030')"},{"name":"fileFilter","type":"string","required":false,"description":"Optional: keep only diagnostics whose file path contains this text"},{"name":"includeFuzzySuggestions","type":"boolean","required":false,"description":"Include 'Did you mean?' fuzzy match suggestions per diagnostic. Default false."},{"name":"includeOffendingSymbol","type":"boolean","required":false,"description":"Include the likely-offending symbol name per diagnostic. Default: on while there are 20 diagnostics or fewer."},{"name":"includeQuickFixes","type":"boolean","required":false,"description":"Include actionable replacement suggestions extracted from parse errors and fuzzy matches. Default: on while there are 20 diagnostics or fewer."},{"name":"includeTokenSpan","type":"boolean","required":false,"description":"Include tokenLength for highlight rendering. Default false."},{"name":"severity","type":"string: all | errors | warnings","required":false,"description":"Severity filter: 'all' (default), 'errors', or 'warnings'"}],"lessons":[],"fixes":["E11064","E11065"],"example":{"scenario":"Diagnostics shape","request":{},"response":{"byCode":{},"byFile":[],"diagnosticCount":0,"diagnostics":[],"errorCodes":[],"errorCount":0,"meta":{"serverMs":"<timing>"},"sites":[],"warningCount":0}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_dispatchers","url":"https://ek9.io/mcp/ek9_query_dispatchers.html","category":"enquiry","description":"Answers first: routing[] - per dispatcher method its dispatchOn type, typesWithOwnHandler, typesUsingInheritedHandler (served by a supertype's handler) and typesFallingBack (to the dispatchOn entry point's own body), with routingCovers when the lists are whole - then the full dispatcherMethods[] with resolutionTable; on a sealed type, allowedSubtypes[]. Do not read the class and simulate it.","whenToUse":"How does a dispatcher method route - which subtypes have their OWN handler and which fall back to the base handler - one call with symbol:'<dispatcher class>'. No file needed; on a sealed type, its allowed subtypes.","whenNotToUse":["General supertype/subtype inheritance graph (not dispatch-specific) - use ek9_query_type_hierarchy.","Caller/callee relationships of a method rather than the dispatch table - use ek9_query_call_graph.","Structural info (fields, methods, modifiers) or the callable member list of a type - use ek9_query_construct (structure) or ek9_query_effective_api (callable surface).","Which dispatchers reference a sealed type (cross-reference not yet emitted here) - use ek9_query_references on the sealed type."],"details":"Auto-detected (no 'mode' parameter): routing[] is present for a dispatcher, allowedSubtypes[] for a sealed type, and a type that is neither returns dispatcher:'not_applicable' with a message (or 'not_found' when there is no enclosing type at the anchor). Dispatcher shape: dispatcherMethods[] + dispatcherMethodCount - drawn from the FULL inheritance chain, so an entry point or handler declared in a supertype is included - each method with signature, pure, dispatchType(+Fqn), allowedSubtypes[] when the dispatch parameter type is sealed, and handlers[] (handlesType and routedTypes per handler), plus top-level sealedTypeDispatched (the FQ sealed supertype handled). ROUTING (present when the workspace is compiled): resolutionTable[] has one row per concrete type that can arrive - typeName, typeGenus, category DIRECT (handler names this exact type) / INHERITED (won via a supertype, with resolvedVia and cost) / ENTRY (the dispatch type itself, when it is concrete - served by the entry point, not a gap) / FALLBACK (no handler; the entry point's own body runs) - plus totalTypes, directCount and inheritedCount. dispatchUniverse says how far to trust the gap analysis: 'sealed' (closed by the compiler, gaps provable), 'hierarchy' (a trait / abstract class / abstract function base - gaps real but a snapshot, since another implementor may be declared later), or 'open' (an Any base). For sealed and hierarchy you also get fallbackCount, unhandledTypes[] (the FALLBACK rows - routing[].typesFallingBack is the same list) and exhaustive, and routing[].routingCovers says the lists are whole. For 'open' those are DELIBERATELY ABSENT and a note explains why: an Any base admits every type in the program and every type not yet written, so 'types you did not handle' has no fixed answer and a fallbackCount of 0 would read as a false all-clear. Sealed shape: allowedSubtypes[] (simple-name strings) + subtypeCount. Note a class is reported as a dispatcher only when it has a NON-OPERATOR entry point: argument-taking operators such as '==' are marked as dispatchers internally so they resolve on the actual type, and that is not a user-level dispatcher.","arguments":[{"name":"among","type":"array of string","required":false,"description":"Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched)."},{"name":"column","type":"integer","required":false,"description":"0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/type-hierarchy.html"],"fixes":["E05260"],"example":{"scenario":"Not a dispatcher status","request":{"symbol":"Circle"},"response":{"fullyQualifiedName":"probe.wire::Circle","genus":"CLASS","meta":{"serverMs":"<timing>"},"note":"Type is not sealed and not a dispatcher","status":"not-applicable","type":"Circle","typeLine":10,"typeSourceFile":"wire.ek9"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_effective_api","url":"https://ek9.io/mcp/ek9_query_effective_api.html","category":"enquiry","description":"Answers first: declaredMethodNames, inheritedMethodNames, overrides as 'method:Trait', operatorNames, traitNames - then every member in full with its source and file/line.","whenToUse":"What can be called on a type - declared, inherited, which methods override a trait, its operators - one call with symbol:'X', no file needed.","whenNotToUse":["ONLY the type's declared structure (own bodies/fields, no merged inherited/trait/defaulted members) - use ek9_query_construct instead.","You want the supertype/subtype graph ('what extends X?') not the member list - use ek9_query_type_hierarchy instead.","You want ONE member at a cursor - use ek9_inspect_symbol_at_cursor; everything in scope at a position - use ek9_list_visible_symbols.","You want the API of a BUILT-IN type (String, List) - use ek9_help instead."],"details":"Genus-dependent shape: a fields[] array appears only for records (record fields are public; class/component/service/application fields are private and excluded, traits have no fields), and only inherited record fields carry inheritedFrom. Per-member source is declared / inherited / trait / defaulted (compiler-synthesised operator), with the declaring site in each member's file/line; re-declared members add override:true plus overrides:{from,at:{file,line}} — follow recursively to trace override chains. Reliable merge needs FULL_RESOLUTION (Phase 7+); earlier phases mis-attribute inherited/trait/defaulted members with no PARTIAL_DATA warning to flag it.","arguments":[{"name":"column","type":"integer","required":false,"description":"0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/own-generics.html","https://ek9.io/ide/book-data-types.html","https://ek9.io/ide/book-collections.html","https://ek9.io/ide/book-integer-promotion.html","https://ek9.io/ide/book-json-taste.html","https://ek9.io/ide/book-phone.html","https://ek9.io/ide/book-optional-result.html","https://ek9.io/ide/book-generics.html","https://ek9.io/ide/one-construct.html"],"fixes":[],"example":{"scenario":"Every overload summarised","request":{"symbol":"Processor.process","verbosity":"summary"},"response":{"meta":{"serverMs":"<timing>"},"note":"'Processor.process' names 2 overloads - each is answered in overloads[], tagged with its signature; resend one signature (e.g. 'Processor.process(Integer)') for that overload alone.","overloadCount":2,"overloads":[{"constructorCount":1,"constructors":[{"name":"Processor"}],"declaredAt":"overloads.ek9:11","declaredMethodNames":["process"],"genus":"CLASS","inheritedMethodNames":[],"methodCount":2,"methods":[{"name":"process"},{"name":"process"}],"operatorCount":1,"operatorNames":["?"],"operators":[{"name":"?"}],"overrides":[],"signature":"Processor.process(Integer)","superChain":["Any"],"totalCount":4,"traitNames":[],"type":"Processor"},{"constructorCount":1,"constructors":[{"name":"Processor"}],"declaredAt":"overloads.ek9:14","declaredMethodNames":["process"],"genus":"CLASS","inheritedMethodNames":[],"methodCount":2,"methods":[{"name":"process"},{"name":"process"}],"operatorCount":1,"operatorNames":["?"],"operators":[{"name":"?"}],"overrides":[],"signature":"Processor.process(String)","superChain":["Any"],"totalCount":4,"traitNames":[],"type":"Processor"}],"status":"ok","symbol":"Processor.process"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_enter_sites","url":"https://ek9.io/mcp/ek9_query_enter_sites.html","category":"enquiry","description":"Answers first: siteCount, then sites[] (stableId, kind, receiver, lockIdentityIds, location, enclosingFunction) - every lock acquisition, workspace-wide.","whenToUse":"Where does the program acquire locks - every MutexLock.enter() / tryEnter() site - one call, no arguments. Also the route from a lock identity to the sites that acquire it (match lockIdentityIds).","whenNotToUse":["The distinct locks themselves, not the sites that acquire them - use ek9_query_lock_identity.","You want detected risk chains with rationale, not the raw acquisition inventory - use ek9_query_deadlock_chain.","You only need the count (enterSiteCount), not the full list - use ek9_query_lock_analysis.","You want general call relationships for a method, not lock-acquisition sites - use ek9_query_call_graph."],"details":"status is available (siteCount + sites[]) | no-analysis (PRE_IR_CHECKS did not run — recompile past it and retry) | not-available (compile first). Each site: stableId, kind (ENTER/TRY_ENTER), receiver display form, lockIdentityIds[] (singleton in the common case; multi-element on branch-joined/polymorphic receivers — correlate with ek9_query_lock_identity), location {file, line(1-based), column(0-based)}, and enclosingFunction {fullyQualifiedName, name, displayName, category} or null. Synthetic inline MutexKey-body functions render their mangled name in friendly 'fn' form; no filtering yet.","arguments":[],"lessons":[],"fixes":[],"example":{"scenario":"No locks workspace","request":{},"response":{"meta":{"serverMs":"<timing>"},"siteCount":0,"sites":[],"status":"available"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_enumerations","url":"https://ek9.io/mcp/ek9_query_enumerations.html","category":"enquiry","description":"Answers first: enumerationNames[], then enumerations[] (name, module, file, line, values in declaration order, valueCount) and summary counts.","whenToUse":"Is there already an enumeration for this value set - one call with nameFilter:'Status' or valueFilter:'PENDING'; no arguments lists every enumeration. Both filters are case-insensitive substrings.","whenNotToUse":["Looking for a constrained primitive (PostCode as String, DrivingAge constrain ...) — those are not enums, use ek9_query_constrained_types.","Looking for a data shape with named fields — use ek9_query_records.","Hunting a specific enum VALUE literal across raw source — use ek9_search_text.","You already know the enum name and want its full source — use ek9_read_construct."],"details":"status ∈ ok (one or more matched) / empty (walk succeeded, filters matched nothing — not an error; adds meta.unmatchedFilters[] when a moduleFilter value names no module) / error (no compiled program — compile first). Each entry carries name, module, file, line, values[] and valueCount, with values[] in declaration order (never alphabetised — ordinal order is semantically meaningful) and casing preserved verbatim. nameFilter and valueFilter are case-insensitive substrings; moduleFilter is an exact module-name allow-list.","arguments":[{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to these exact module names. Default: workspace-wide."},{"name":"nameFilter","type":"string","required":false,"description":"Case-insensitive substring match on enumeration names."},{"name":"valueFilter","type":"string","required":false,"description":"Filter to enumerations declaring a value whose name matches (case-insensitive substring). Example: \"PENDING\" finds every enum with a PENDING-like value — useful for catching duplicate value sets."}],"lessons":[],"fixes":[],"example":{"scenario":"List all","request":{},"response":{"enumerationNames":["OrderStatus","Priority"],"enumerations":[{"file":"types.ek9","line":6,"module":"com.example.types","name":"OrderStatus","valueCount":3,"values":["PENDING","CONFIRMED","SHIPPED"]},{"file":"types.ek9","line":11,"module":"com.example.types","name":"Priority","valueCount":2,"values":["LOW","HIGH"]}],"meta":{"serverMs":"<timing>"},"status":"ok","summary":{"enumerationCount":2,"moduleCount":1,"totalValues":5}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_env_vars","url":"https://ek9.io/mcp/ek9_query_env_vars.html","category":"enquiry","description":"Answers first: names[] (every env-var read), then envVars[] per call site (site, name, accessMethod, sanitization, inConstruct), dynamicAccesses[] and summary counts - type-resolved EnvVars calls, never text matches.","whenToUse":"Which environment variables does this app read, where, and how safely - one call, no arguments. Pass envVarNames for an existence check, accessMethodFilter:['unsanitizedGet'] for a security audit.","whenNotToUse":["Raw text matches of a literal name anywhere (comments, docstrings, JSON, extern files) — use ek9_search_text; this returns only RESOLVED EnvVars calls.","Auditing the broader sensitive-data surface beyond env vars (Sensitive construction / reveal points) — use ek9_query_sensitive_reveals.","You already know the variable holding a name and want its call sites — use ek9_query_references (feed a dynamic access's nameExpression there).","System properties (System.getProperty), .env files or config loaders — out of scope; this covers org.ek9.lang::EnvVars only."],"details":"Each entry carries a derived sanitization (get→sanitized, unsanitizedGet→unsanitized, sensitiveGet→sensitive-wrapped, contains→n/a) plus site ('file.ek9:LINE'), file/line/column and inConstruct/inConstructFqn — feed the FQN straight into ek9_query_call_graph to trace who reaches a secret read or where its value flows. One entry per CALL SITE, so staticAccessCount ≥ uniqueNameCount; runtime-computed names land in dynamicAccesses[]. Unmatched envVarNames/moduleFilter values are reported in meta.unmatchedFilters[] with status ok/empty, NOT errors — error only on an accessMethodFilter value outside the enum or no compiled program.","arguments":[{"name":"accessMethodFilter","type":"array of string: get | unsanitizedGet | sensitiveGet | contains","required":false,"description":"Restrict to these access methods. Example: [\"unsanitizedGet\"] for a security audit. Default: all four."},{"name":"envVarNames","type":"array of string","required":false,"description":"Restrict to specific env-var names (case-sensitive EXACT match per name, e.g. [\"DATABASE_URL\", \"AUTH_SECRET\"]). Not a substring pattern — env-var names are a set of distinct identifiers. Default: all discovered."},{"name":"includeDynamic","type":"boolean","required":false,"description":"Include the dynamicAccesses[] array flagging accesses where the env-var name is a runtime expression rather than a literal. Set false to suppress when only the statically-resolvable surface matters."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to these exact module names. Default: workspace-wide."}],"lessons":["https://ek9.io/ide/sensitive-and-environment.html"],"fixes":[],"example":{"scenario":"List all","request":{},"response":{"dynamicAccesses":[{"accessMethod":"get","column":17,"file":"config.ek9","inConstruct":"readConfig","inConstructFqn":"com.example.config::readConfig","line":15,"module":"com.example.config","nameExpression":"key","nameExpressionType":"String","note":"Name supplied as runtime expression — resolve via ek9_query_references on 'key' to trace the source value(s).","site":"config.ek9:15"}],"envVars":[{"accessMethod":"sensitiveGet","column":20,"file":"auth.ek9","inConstruct":"readSecret","inConstructFqn":"com.example.auth::readSecret","line":8,"module":"com.example.auth","name":"AUTH_SECRET","sanitization":"sensitive-wrapped","site":"auth.ek9:8"},{"accessMethod":"unsanitizedGet","column":17,"file":"config.ek9","inConstruct":"readConfig","inConstructFqn":"com.example.config::readConfig","line":10,"module":"com.example.config","name":"DEBUG_RAW","sanitization":"unsanitized","site":"config.ek9:10"},{"accessMethod":"get","column":18,"file":"config.ek9","inConstruct":"readConfig","inConstructFqn":"com.example.config::readConfig","line":8,"module":"com.example.config","name":"DOCUMENT_ROOT","sanitization":"sanitized","site":"config.ek9:8"},{"accessMethod":"contains","column":21,"file":"config.ek9","inConstruct":"readConfig","inConstructFqn":"com.example.config::readConfig","line":12,"module":"com.example.config","name":"USER","sanitization":"n/a","site":"config.ek9:12"}],"meta":{"serverMs":"<timing>"},"names":["AUTH_SECRET","DEBUG_RAW","DOCUMENT_ROOT","USER"],"status":"ok","summary":{"dynamicAccessCount":1,"moduleCount":2,"perAccessMethod":{"contains":1,"get":1,"sensitiveGet":1,"unsanitizedGet":1},"staticAccessCount":4,"uniqueNameCount":4}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_flow","url":"https://ek9.io/mcp/ek9_query_flow.html","category":"enquiry","description":"Answers first: status, branchCount, loopCount, guardCount, deadBranchCount, then method{name, fullyQualifiedName, signature, declaredAt}, isPure, metrics (cyclomatic/cognitive), flowNodes (the guard-tracked branch/loop tree) and deepAnalysis (provably dead branches, redundant tri-state checks).","whenToUse":"'How does this method or function flow inside - branches, loops, guards, dead code, complexity' is one call with symbol:'Type.method' - no file or line needed.","whenNotToUse":["method-to-method call relationships, who calls it or what it calls (use ek9_query_call_graph)","a body that is a stream pipeline and you want stage-level analysis (use ek9_query_pipeline)","just complexity numbers across MANY methods workspace-wide (use ek9_query_complexity)","the structural outline of a class/record, not the flow of a body (use ek9_query_construct)"],"details":"Uses on-demand IR generation: flow is available after PRE_IR_CHECKS (Phase 5), no full IR_GENERATION compile needed — fast and usable mid-edit. metrics{cyclomaticComplexity, cognitiveComplexity, lineCount, maxNestingDepth, branchCount, loopCount, guardCount}; flowNodes[] (the IF_ELSE_IF/WHILE_LOOP/SWITCH/TRY_CATCH_FINALLY/FOR_RANGE/… tree with depth/children/per-node guard); guards[] {introducedAt, guarantee}; deepAnalysis {deadBranches — PROVABLY unreachable, redundantChecks — tri-state checks the compiler already proved, guaranteedVariables}. Missing source, no IR construct, or failed IR generation returns status:'not-found' with a note; a line not on a specific method falls back to the construct's best default operation, so anchor precisely (symbol:'Type.method' does); cyclomatic>10, cognitive>15 or non-empty overlays flag refactor candidates for ek9_extract_method / ek9_remove_statements / ek9_apply_guard_pattern.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line anywhere inside the method/function or on its declaration - OMIT it and pass symbol:'Type.method' to let the tool find the line (a model counting lines miscounts)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/one-construct.html"],"fixes":[],"example":{"scenario":"Flow shape","request":{"file":"Hello.ek9","line":6},"response":{"branchCount":0,"deadBranchCount":0,"deepAnalysis":{"deadBranches":[],"guaranteedVariables":[],"redundantChecks":[]},"flowNodes":[],"guardCount":0,"guards":[],"inConstruct":"Main","inConstructFqn":"com.example.hello::Main","isPure":false,"loopCount":0,"meta":{"serverMs":"<timing>"},"method":{"declaredAt":{"file":"Hello.ek9","line":5},"fullyQualifiedName":"com.example.hello::Main","name":"Main","signature":"Main() <- _rtn as Void"},"metrics":{"branchCount":0,"guardCount":0,"loopCount":0},"parameters":[],"redundantCheckCount":0,"returnVariable":{"name":"_rtn","type":"Void"},"status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_functions","url":"https://ek9.io/mcp/ek9_query_functions.html","category":"enquiry","description":"Answers first: status, functionCount, functionNames - complete for the workspace or the filters given - then functions[] {name, module, file, line, signature, parameters, returnType, isPure, isAbstract}.","whenToUse":"'Which free-standing functions exist, and is there one to reuse' is one call - no arguments, or nameFilter / returnTypeFilter / moduleFilter to narrow.","whenNotToUse":["methods bound to a class or trait, not free-standing functions (use ek9_query_effective_api on the type, or ek9_query_classes)","verbatim string match inside function bodies (use ek9_search_text)","the full source of a function you already know the name of (use ek9_read_construct)"],"details":"Top-level 'defines function' constructs only — anonymous dynamic-function closures are excluded (not name-addressable), and abstract function-typedefs (FUNCTION_TRAIT, higher-order parameter types) appear only with includeAbstract:true. nameFilter/returnTypeFilter are case-insensitive substrings, not regex; built-in org.ek9.* functions are excluded. A moduleFilter naming non-existent modules yields status:empty with meta.unmatchedFilters (informational, not an error); returnType is null for Void/no returning symbol, and unresolved types render <unresolved>.","arguments":[{"name":"includeAbstract","type":"boolean","required":false,"description":"Default false. When true, also includes abstract function-typedefs (higher-order parameter signatures)."},{"name":"includePure","type":"boolean","required":false,"description":"Default true. When false, excludes functions marked 'as pure'."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to specific modules (exact names). Default: workspace-wide."},{"name":"nameFilter","type":"string","required":false,"description":"Case-insensitive substring match on function names."},{"name":"returnTypeFilter","type":"string","required":false,"description":"Filter to functions whose return type matches (case-insensitive substring, e.g. 'Boolean' finds predicates)."}],"lessons":[],"fixes":[],"example":{"scenario":"List all","request":{},"response":{"functionCount":2,"functionNames":["isPositive","greet"],"functions":[{"file":"util.ek9","isAbstract":false,"isPure":true,"line":6,"module":"com.example.util","name":"isPositive","parameters":[{"name":"number","type":"Integer"}],"returnType":"Boolean","signature":"isPositive()\n  -> number as Integer\n  <- rtn as Boolean"},{"file":"util.ek9","isAbstract":false,"isPure":false,"line":10,"module":"com.example.util","name":"greet","parameters":[{"name":"name","type":"String"}],"returnType":"String","signature":"greet()\n  -> name as String\n  <- rtn as String"}],"meta":{"serverMs":"<timing>"},"status":"ok","summary":{"moduleCount":1,"pureCount":1}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_localisations","url":"https://ek9.io/mcp/ek9_query_localisations.html","category":"enquiry","description":"Answers first: status, moduleCount, inconsistencyCount, workspaceLocales, then modules[] {name, locales, percentTranslated, methodCount} and inconsistencies[] {locale, supportedIn, missingIn}.","whenToUse":"'What languages does this app support, and which modules are missing one' is one call with no arguments - the whole i18n surface at module granularity.","whenNotToUse":["per-method translation status (translated / stubbed / missing) for ONE module (use ek9_query_translation_completeness, the deep per-module dive - call it second, after this one finds the module of interest)","finding a specific verbatim string in i18n source (use ek9_search_text)","MUTATING the i18n surface (use ek9_edit_localized_text or ek9_organize_localized_text)"],"details":"empty = zero 'defines text for' blocks anywhere (a legitimate greenfield state, not an error); an all-unmatched moduleFilter also yields empty, with meta.unmatchedFilters[] so a typo reads differently from greenfield. A module 'supports' a locale when it has at least one 'defines text for \"L\"' block; zero-block modules are auto-excluded from inconsistency analysis (excludeModules forces further exclusions). percentTranslated and methodCount (method × locale tuples) match ek9_query_translation_completeness byte-for-byte at module granularity; aggregates stop at module level (no per-method rows) to bound response size.","arguments":[{"name":"excludeModules","type":"array of string","required":false,"description":"Modules to treat as intentionally non-i18n — removed from modules[] AND from inconsistencies[].missingIn. (Modules with zero text blocks are auto-excluded already.) Default: none."},{"name":"includeFileDistribution","type":"boolean","required":false,"description":"Include i18nFiles[] (the .ek9 files holding each module's text blocks). Default off to keep responses compact; turn on when planning a ek9_organize_localized_text call."},{"name":"includeInconsistencies","type":"boolean","required":false,"description":"Include the inconsistencies[] array flagging cross-module locale support gaps. Set false to suppress."},{"name":"localeFilter","type":"array of string","required":false,"description":"Restrict per-module metrics + inconsistencies to specific locales (e.g. [\"fr_FR\", \"de\"]). workspaceLocales still lists the full discovered set. Default: all discovered locales."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict the response to specific modules (exact names). Default: all i18n modules."}],"lessons":["https://ek9.io/ide/localisations.html"],"fixes":[],"example":{"scenario":"List all","request":{},"response":{"inconsistencies":[{"locale":"fr_FR","missingIn":["com.example.billing"],"supportedIn":["com.example.auth"]}],"inconsistencyCount":1,"meta":{"serverMs":"<timing>"},"moduleCount":2,"modules":[{"locales":["de","en_GB","fr_FR"],"methodCount":6,"name":"com.example.auth","percentTranslated":100.0,"textTypeCount":1},{"locales":["de","en_GB"],"methodCount":2,"name":"com.example.billing","percentTranslated":50.0,"textTypeCount":1}],"status":"ok","summary":{"averagePercentTranslated":75.0,"fullyTranslatedLocales":["en_GB","fr_FR"],"totalTextTypes":2},"workspaceLocales":["de","en_GB","fr_FR"]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_lock_analysis","url":"https://ek9.io/mcp/ek9_query_lock_analysis.html","category":"enquiry","description":"Answers first: status, then deadlockCount, lockIdentityCount, enterSiteCount, keyBodyCount, crossThreadEdgeCount and nextStep (the one drill-down worth calling); lockIdentityCount 0 = no MutexLock anywhere, deadlock structurally impossible.","whenToUse":"'Does this workspace have any lock or deadlock risk at all' is one call with no arguments - the headline counts before any lock drill-down.","whenNotToUse":["the rationale chains behind a deadlock risk, deadlockCount > 0 (use ek9_query_deadlock_chain)","the catalogue of distinct locks (origin, display name), not just the count (use ek9_query_lock_identity)","the inventory of enter()/tryEnter() acquisition sites (use ek9_query_enter_sites)","the raw E08252/E08253 as compiler diagnostics rather than the summary (use ek9_query_diagnostics)"],"details":"Zero parameters; whole-workspace only, no module scoping. status is 'ok' (analysis ran, counts live) or 'not-compiled' (no compiled program, or compilation failed before PRE_IR_CHECKS produced a LockAnalysis — nextStep ek9_compile). nextStep on 'ok': deadlockCount>0 -> ek9_query_deadlock_chain, lockIdentityCount>0 -> ek9_query_lock_identity, otherwise none — lockIdentityCount==0 means no MutexLock use anywhere, so structural deadlock is impossible.","arguments":[],"lessons":["https://ek9.io/ide/concurrency.html"],"fixes":[],"example":{"scenario":"No compiled program","request":{},"response":{"meta":{"serverMs":"<timing>"},"nextStep":"ek9_compile","note":"No compiled program is available - nothing can be queried until the workspace compiles.","status":"not-compiled"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_lock_identity","url":"https://ek9.io/mcp/ek9_query_lock_identity.html","category":"enquiry","description":"Answers first: status, identityCount, then identities[] {stableId, origin, displayName, originSymbol, originLocation, payload}; stableId joins ek9_query_enter_sites and ek9_query_deadlock_chain.","whenToUse":"'What MutexLocks does this program have' is one call with no arguments - every distinct lock with its origin, declaration and stableId.","whenNotToUse":["the headline counts only, not the full list (use ek9_query_lock_analysis)","the acquisition SITES (where locks are entered), not the identities (use ek9_query_enter_sites)","the detected deadlock risk CHAINS, not the inventory (use ek9_query_deadlock_chain)","details of one specific symbol under a cursor (use ek9_inspect_symbol_at_cursor)"],"details":"status is ok | not-compiled (no compiled program, or PRE_IR_CHECKS did not produce a LockAnalysis — nextStep ek9_compile). On 'ok', identities[] carries per-lock {stableId, origin, displayName, originSymbol, originLocation}; origin is FIELD_ROOTED | ALLOCATION | PARAMETER | CAPTURE; stableId correlates with enter_sites.sites[].lockIdentityIds and deadlock_chain outerLock/innerLock. originSymbol and originLocation may be null; mangled _Function_/_Class_ names render friendly (fn/cls); no filtering yet. Each identity also carries payload {bodies, contained, mayEscape, unknown} — how many MutexKey bodies run under this lock and whether their lockedItem stays inside it (the same sweep as ek9_query_mutex_payload, which names the escaping bodies); absent when no enter call pairs a body with the lock.","arguments":[],"lessons":["https://ek9.io/ide/concurrency.html"],"fixes":[],"example":{"scenario":"No locks workspace","request":{},"response":{"identities":[],"identityCount":0,"meta":{"serverMs":"<timing>"},"status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_metric_limits","url":"https://ek9.io/mcp/ek9_query_metric_limits.html","category":"enquiry","description":"Returns EK9's ENFORCED quality-metric limits (coupling, cohesion, complexity, DI, size) - limitCount and limits[] with ruleCode, metricKey, limitKind, comparator, limit and usableMax - from the single source the checkers fire on.","whenToUse":"'What limit does EK9 enforce on X, and at what value' is one call with {} - every quality gate with its rule code, comparator and usableMax. Coupling, cohesion, complexity, nesting, statements, DI and size, from the single source the checkers fire on; no workspace needed.","whenNotToUse":["Where a given construct or module SITS against a limit - use ek9_query_complexity / ek9_query_module_coupling / ek9_query_module_cohesion / ek9_query_dependency_injection.","The prose MEANING of a code (E11016, ...) - use ek9_explain_error."],"details":"ENFORCED, not advisory: the compiler emits the entry's ruleCode the instant a value crosses its limit - no warning tier, no bypass. limitKind is one of scalar, per-genus, compound, ratio: scalar carries comparator/limit/usableMax ('>' means limit is the last legal value, '>=' means limit-1 is); per-genus adds a byGenus table keyed by the EK9 construct word (class, trait, record, enumeration, function, abstract-function, component, service), fallback and exempt kinds (LCOM4 exempts record/trait/function); compound fires only when disconnectedGroups>maxGroups AND ratio>maxRatio once minConstructs is reached; ratio fires when a fraction exceeds its threshold (each entry's condition says which). constructCoupling's limit is integer but its MEASURED value may be fractional (by-trait delegation discounts 0.5 each).","arguments":[],"lessons":[],"fixes":[],"example":{"scenario":"Limits shape","request":{},"response":{"limitCount":34,"limits":[{"comparator":">","limit":10,"limitKind":"scalar","metricKey":"moduleCoupling","ruleCode":"E11016","usableMax":10},{"byGenus":{"abstract-function":8,"class":12,"component":15,"enumeration":12,"function":8,"record":8,"service":15,"trait":8},"comparator":">","exempt":[],"fallback":12,"limitKind":"per-genus","metricKey":"constructCoupling","ruleCode":"E11015"},{"byGenus":{"class":8,"component":10,"enumeration":8},"comparator":">","exempt":["abstract-function","function","record","service","trait"],"fallback":8,"limitKind":"per-genus","metricKey":"lcom4","ruleCode":"E11014"},{"condition":"fires when disconnectedGroups > maxGroups AND ratio > maxRatio, only once the module has at least minConstructs constructs","limitKind":"compound","maxGroups":30,"maxRatio":0.88,"metricKey":"moduleCohesion","minConstructs":60,"ruleCode":"E11017"},{"comparator":">","limit":250,"limitKind":"scalar","metricKey":"moduleSize","ruleCode":"E11027","usableMax":250},{"comparator":">","limit":4,"limitKind":"scalar","metricKey":"injectionFields","ruleCode":"E11040","usableMax":4},{"comparator":">","limit":12,"limitKind":"scalar","metricKey":"appRegistrations","ruleCode":"E11042","usableMax":12},{"comparator":">=","limit":5,"limitKind":"scalar","metricKey":"injectedTypesPerMethod","ruleCode":"E11043","usableMax":4},{"comparator":">","limit":45,"limitKind":"scalar","metricKey":"callableComplexity","ruleCode":"E11010","usableMax":45},{"comparator":">","limit":500,"limitKind":"scalar","metricKey":"typeComplexity","ruleCode":"E11010","usableMax":500},{"comparator":">","limit":35,"limitKind":"scalar","metricKey":"cognitiveComplexity","ruleCode":"E11021","usableMax":35},{"comparator":">","limit":10,"limitKind":"scalar","metricKey":"bracketNesting","ruleCode":"E11011","usableMax":10},{"comparator":">","limit":20,"limitKind":"scalar","metricKey":"blockNesting","ruleCode":"E11011","usableMax":20},{"comparator":">","limit":6,"limitKind":"scalar","metricKey":"nestingDepth","ruleCode":"E11011","usableMax":6},{"byGenus":{"abstract-function":3,"class":4,"component":4,"enumeration":4,"function":3,"record":2,"service":4,"trait":4},"comparator":">","exempt":["any","application","constant","constrained-type","meta-data","program","text","type"],"fallback":0,"limitKind":"per-genus","metricKey":"inheritanceDepth","ruleCode":"E11019"},{"comparator":">","limit":15,"limitKind":"scalar","metricKey":"expressionComplexity","ruleCode":"E11013","usableMax":15},{"comparator":">","limit":20,"limitKind":"scalar","metricKey":"expressionOperators","ruleCode":"E11013","usableMax":20},{"comparator":">","limit":20,"limitKind":"scalar","metricKey":"memberAccesses","ruleCode":"E11013","usableMax":20},{"comparator":">","limit":50,"limitKind":"scalar","metricKey":"statementsOperator","ruleCode":"E11012","usableMax":50},{"comparator":">","limit":100,"limitKind":"scalar","metricKey":"statementsMethod","ruleCode":"E11012","usableMax":100},{"comparator":">","limit":150,"limitKind":"scalar","metricKey":"statementsFunction","ruleCode":"E11012","usableMax":150},{"comparator":">","limit":100,"limitKind":"scalar","metricKey":"statementsServiceOperation","ruleCode":"E11012","usableMax":100},{"comparator":">","limit":20,"limitKind":"scalar","metricKey":"argumentsPerCall","ruleCode":"E11010","usableMax":20},{"comparator":">","condition":"fires when the construct's complexity ratio times its statement ratio exceeds the threshold - neither operand is a gate on its own","limitKind":"ratio","metricKey":"combinedComplexitySize","ruleCode":"E11020","threshold":0.5},{"comparator":">=","limit":4,"limitKind":"scalar","metricKey":"classServiceFieldsAsComponent","ruleCode":"E11022","usableMax":3},{"comparator":">=","limit":5,"limitKind":"scalar","metricKey":"forwardedMethodsForBy","ruleCode":"E11023","usableMax":4},{"comparator":">","condition":"fires, together with forwardedMethodsForBy, when the share of a trait's methods that a class overrides by hand exceeds the threshold","limitKind":"ratio","metricKey":"forwardedMethodsShareForBy","ruleCode":"E11023","threshold":0.7},{"comparator":">=","limit":3,"limitKind":"scalar","metricKey":"hybridServiceFields","ruleCode":"E11024","usableMax":2},{"comparator":">=","limit":3,"limitKind":"scalar","metricKey":"mixedServiceFields","ruleCode":"E11025","usableMax":2},{"comparator":">=","limit":3,"limitKind":"scalar","metricKey":"mixedDataFields","ruleCode":"E11025","usableMax":2},{"comparator":">=","limit":3,"limitKind":"scalar","metricKey":"methodsSharingInjectedType","ruleCode":"E11041","usableMax":2},{"comparator":">","limit":3,"limitKind":"scalar","metricKey":"typeTransitions","ruleCode":"E11054","usableMax":3},{"comparator":">=","limit":2,"limitKind":"scalar","metricKey":"booleanLiteralArguments","ruleCode":"E11061","usableMax":1},{"comparator":">=","limit":4,"limitKind":"scalar","metricKey":"unnamedArguments","ruleCode":"E11062","usableMax":3}],"meta":{"serverMs":"<timing>"},"note":"These limits are ENFORCED — the compiler emits the listed error code when a value crosses the limit; there is no warning tier and no bypass. 'usableMax' is the largest value that still compiles (one more crosses). Comparator '>' means the limit value is the last legal one; '>=' means the last legal value is limit-1.","status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_module","url":"https://ek9.io/mcp/ek9_query_module.html","category":"enquiry","description":"Answers first: status, module, constructCount, constructNames, then constructs[] with kind, member counts and quality metrics (complexity, coupling, cohesion).","whenToUse":"'What does this module declare - classes, functions, constants, their sizes' is one call with file:'any.ek9' in it; scope:'module' unions all its files.","whenNotToUse":["the whole workspace, or a module by NAME (use ek9_query_workspace with moduleFilter)","ONE specific construct's details, not the whole module (use ek9_query_construct)","the cross-module dependency graph or fan-in/fan-out (use ek9_query_module_dependencies; fanIn/fanOut are not emitted here)","the exact symbol at a cursor (use ek9_inspect_symbol_at_cursor)"],"details":"A multi-file module has one ModuleScope per file, so the default scope:'file' can report 'no constants' when they live in a sibling file — use scope:'module' when deciding local variable vs named constant. An unknown kind is rejected, not ignored. A path in no compiled module returns status:'not-found' rather than an error; per-construct 'coupling' may be fractional (by-trait-delegation discount); per-construct sourceFile, files[] and metrics.fanIn/fanOut are deferred.","arguments":[{"name":"file","type":"string","required":true,"description":"Any .ek9 file inside the module of interest (workspace-relative; absolute inside the workspace accepted)"},{"name":"kinds","type":"array of string: application | class | component | constant | enumeration | function | program | record | service | text | trait | type","required":false,"description":"Optional filter, e.g. ['constant'] or ['class','component']. Omit for everything. EK9 has no module-scoped variables — only constants are per-module values, everything else is a type — so 'constant' is just one kind here."},{"name":"scope","type":"string: file | module","required":false,"description":"'file' (default) lists what THIS source file declares; 'module' lists what the whole module declares across ALL its files, adding a 'file' field per construct. A multi-file module has one scope per file, so the two differ: a constant declared in a sibling file is absent from the 'file' view."}],"lessons":[],"fixes":["E11064","E11065","E11066","E11067"],"example":{"scenario":"Module shape","request":{"file":"MyRecord.ek9"},"response":{"constructCount":1,"constructNames":["MyRecord"],"constructs":[{"category":"TYPE","cohesion":1,"column":4,"complexity":1,"coupling":0,"fieldCount":1,"genus":"RECORD","isOpen":false,"line":5,"memberCount":27,"methodCount":13,"modifiers":[],"name":"MyRecord","operatorCount":13}],"meta":{"serverMs":"<timing>"},"metrics":{"averageMembersPerConstruct":27.0},"module":"com.example","status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_module_cohesion","url":"https://ek9.io/mcp/ek9_query_module_cohesion.html","category":"enquiry","description":"Answers first: status, programState, moduleCount, then modules[] {name, moduleCohesion (E11017 disconnected groups), cohesionRatio, lcom4 (E11014 over-limit constructs)}; symbol:'Type' drills to one construct's LCOM4.","whenToUse":"'Should this module be split, and which constructs do too many unrelated things' is one call with no arguments, or moduleFilter:['mod'] for one module.","whenNotToUse":["how modules depend on each other, the coupling side (use ek9_query_module_coupling)","the workspace-wide module map to pick WHICH module to inspect (use ek9_query_module_landscape first, then drill here)","COMPONENT cohesion — EK9 components hold only fields/methods, not nested constructs; the cohesion unit is the MODULE, so there is no component-cohesion tool"],"details":"Per-construct LCOM4 (E11014) is a zero-recompute READ of the checker's own squirrelled COHESION value; module disconnected-groups (E11017) is RE-DERIVED (basis:'toolWalk') because the checker's value is not persisted, so it carries gate thresholds not enforced:true and can differ from the gate (this walk unwraps generics, the gate does not). E11017 fires only when groups>maxGroups AND ratio>maxRatio AND constructs>=minConstructs; band is over/approaching/ok/info. cohesionRatio (internal vs external edges) is advisory-only, never a gate; ratio:null when the module has no edges.","arguments":[{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to these modules - exact names; an entry ending in '*' is a prefix ('com.acme.*'). A single string is accepted. Omit for workspace-wide."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME ('OrderService' or 'com.acme.orders::OrderService') — drill straight to its LCOM4 (E11014) instead of the per-module view."}],"lessons":[],"fixes":[],"example":{"scenario":"Lcom4 drill","request":{"symbol":"sample.arch.orders::Order"},"response":{"construct":{"file":"orders.ek9","fullyQualifiedName":"sample.arch.orders::Order","genus":"CLASS","lcom4":{"band":"ok","comparator":">","enforced":true,"limit":8,"rule":"E11014","value":1},"line":10,"module":"sample.arch.orders","name":"Order"},"meta":{"serverMs":"<timing>"},"programState":"clean","status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_module_coupling","url":"https://ek9.io/mcp/ek9_query_module_coupling.html","category":"enquiry","description":"Answers first: status, programState, edgeCount, then edges[] {from, to, types, weight, shape, sites, inCycle, proposals} ranked worst-first, audit (adHocCoupling, overDeclaredReferences candidates) and summary.","whenToUse":"'Which types leak across which module boundaries, and how heavily' is one call with no arguments - every cross-module edge ranked worst-first, with sites.","whenNotToUse":["the per-module enforced coupling number and band, the E11016 gate (use ek9_query_module_landscape; this is the edge breakdown behind it)","confirming a declared 'references' entry is truly removable (use ek9_organize_references, a scratch compile; overDeclaredReferences here surfaces candidates only)","per-construct coupling with the 0.5-per-'by'-delegation discount, E11015 (use ek9_query_construct; module edges are whole-number binary dependencies)"],"details":"Read from RESOLVED symbol type-references (super/traits/field/param/return → edges by FQN); generics are unwrapped so List of Order couples to Order, not to org.ek9.lang. Each edge carries {from, to, types[], weight, declared, adHocFqn, shape{concentration, nearMutualityRatio, targetAbstractness}, sites[{file,line}], inCycle, proposals[]}; weight is a signature-reference count, and proposals (extract-kernel / narrow-with-trait / clarify-ownership) are advisory — pair with ek9_git_log co-change evidence before acting. audit.adHocCoupling (inline-FQN coupling with no 'references' entry) is signature-derived and safe; audit.overDeclaredReferences is candidates-only, since a body-local variable-declaration type escapes even its body-aware used-set.","arguments":[{"name":"direction","type":"string: both | outgoing | incoming","required":false,"description":"With moduleFilter: 'outgoing' = edges out of those modules, 'incoming' = edges into them, 'both' (default) = either side."},{"name":"minWeight","type":"integer","required":false,"description":"Only edges with at least this weight (signature reference count). Default 1."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to these modules - exact names; an entry ending in '*' is a prefix ('com.acme.*'). A single string is accepted. Omit for workspace-wide."},{"name":"targetAbstractness","type":"string: value | abstraction | concrete","required":false,"description":"Only edges reaching this genus class (concrete = heaviest coupling risk)."}],"lessons":[],"fixes":[],"example":{"scenario":"Coupling shape","request":{},"response":{"audit":{"adHocCoupling":[],"overDeclaredReferences":{"basis":"signature ∪ injections ∪ callGraph","candidates":[],"note":"candidates only — a body-only local-variable type declaration can still use a reference the call graph does not show; verify with ek9_organize_references (scratch compile) before removing"}},"edgeCount":2,"edges":[{"adHocFqn":false,"declared":true,"from":"sample.arch.orders","inCycle":false,"proposals":[],"shape":{"concentration":2,"nearMutualityRatio":0.0,"targetAbstractness":"value"},"sites":[{"file":"orders.ek9","line":10}],"to":"sample.arch.domain","types":["Amount","Priority"],"weight":5},{"adHocFqn":false,"declared":true,"from":"sample.arch.web","inCycle":false,"proposals":[],"shape":{"concentration":1,"nearMutualityRatio":0.0,"targetAbstractness":"concrete"},"sites":[{"file":"web.ek9","line":9}],"to":"sample.arch.orders","types":["Order"],"weight":1}],"meta":{"serverMs":"<timing>"},"programState":"clean","status":"ok","summary":{"cycleGroups":0,"worstConcentration":2}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_module_dependencies","url":"https://ek9.io/mcp/ek9_query_module_dependencies.html","category":"enquiry","description":"Answers first: status, moduleCount, edgeCount, hasCycles, then modules[] {name, files, constructCount}, dependencies[] {from, to, referenceCount, kinds} and metrics (fan-in/out, cycles).","whenToUse":"'Which modules depend on which, and are there cycles' is one call with no arguments - the whole-workspace module graph.","whenNotToUse":["the module inventory rather than the relationships (use ek9_query_workspace)","PACKAGE-level cycles between published packages, not module cycles within a package (use ek9_check_package_dependency_cycles)","the DI wiring graph (component injection), not module imports (use ek9_query_dependency_injection)","method-level call relationships, not module-level coupling (use ek9_query_call_graph)"],"details":"Empty workspace is status:ok (moduleCount:0, cycles:[]), not an error. dependencies[].kinds are STRUCTURAL (extends, implements, field_type, return_type, parameter_type), not import labels; referenceCount is coupling strength. metrics.cycles is the canonical cycle signal (empty array = none) — do NOT infer cycles from stronglyConnectedComponents, which equals moduleCount in an acyclic graph.","arguments":[{"name":"includeBuiltins","type":"boolean","required":false,"description":"Whether to include org.ek9.lang built-in module dependencies (default false)"}],"lessons":["https://ek9.io/ide/modules.html"],"fixes":[],"example":{"scenario":"Module dependencies shape","request":{},"response":{"dependencies":[],"edgeCount":0,"hasCycles":false,"meta":{"serverMs":"<timing>"},"metrics":{"averageFanIn":0.0,"averageFanOut":0.0,"cycles":[],"hasCycles":false,"maxFanIn":0,"maxFanOut":0,"stronglyConnectedComponents":1},"moduleCount":1,"modules":[{"constructCount":1,"files":["MyRecord.ek9"],"name":"com.example"}],"status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_module_landscape","url":"https://ek9.io/mcp/ek9_query_module_landscape.html","category":"enquiry","description":"Answers first: status, programState, moduleCount, moduleNames, then modules[] {name, band, types, metrics as headroom {rule, limit, value, band, enforced}, cycles} ranked worst-first and summary.","whenToUse":"'How healthy is each module - size, coupling, cohesion, cycles - against the limits the compiler enforces' is one call with no arguments.","whenNotToUse":["the specific edges coupling two modules (use ek9_query_module_coupling)","intra-module cohesion detail (use ek9_query_module_cohesion)","the dependency graph / who-imports-whom (use ek9_query_module_dependencies)","full cycle paths and how to break them (use ek9_check_module_cycles)"],"details":"Per module: 'types' (counts by genus), 'metrics' — moduleCoupling (E11016, enforced:true, basis:'trueCoupling' — the tool's own type-argument-unwrapped walk, may exceed the FQN-blind E11016 checker), constructCoupling (E11015 rollup), moduleCohesion (E11017, enforced but available:false — value not persisted by the checker), afferent/instability (advisory, enforced:false, limit:null); for applications a registrations tuple (E11042). Enforced metrics carry a real comparator + band; overall 'band' is the worst ENFORCED band (advisory never raises it). Also isApplicationOrRoot (composition roots wire everything by design), cycle membership (pointer only), file/line, and programState — architecture facts need FULL_RESOLUTION; below that, unknown.","arguments":[{"name":"band","type":"string: all | ok | approaching | at-limit | over","required":false,"description":"Restrict to modules whose overall health band is at/over this level. Default 'all'."},{"name":"metric","type":"string: efferent | afferent","required":false,"description":"Rank modules by this metric (worst first). Default 'efferent'."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to these modules - exact names; an entry ending in '*' is a prefix ('com.acme.*'). A single string is accepted. Omit for workspace-wide."}],"lessons":["https://ek9.io/ide/modules.html"],"fixes":[],"example":{"scenario":"Landscape shape","request":{},"response":{"meta":{"serverMs":"<timing>"},"moduleCount":3,"moduleNames":["sample.arch.orders","sample.arch.web","sample.arch.domain"],"modules":[{"band":"ok","cycles":[],"file":"orders.ek9","isApplicationOrRoot":false,"line":2,"metrics":{"afferent":{"band":"info","enforced":false,"excludesExternal":true,"limit":null,"rule":null,"value":1},"constructCoupling":{"band":"ok","enforced":true,"max":2,"overLimitCount":0,"rule":"E11015"},"instability":{"band":"info","enforced":false,"limit":null,"rule":null,"value":0.5},"moduleCohesion":{"available":false,"enforced":true,"note":"disconnected-groups value not persisted by the checker; pending the persist-vs-rederive decision","rule":"E11017"},"moduleCoupling":{"band":"ok","basis":"trueCoupling","comparator":">","enforced":true,"limit":10,"rule":"E11016","value":1}},"name":"sample.arch.orders","types":{"class":1}},{"band":"ok","cycles":[],"file":"web.ek9","isApplicationOrRoot":false,"line":2,"metrics":{"afferent":{"band":"info","enforced":false,"excludesExternal":true,"limit":null,"rule":null,"value":0},"constructCoupling":{"band":"ok","enforced":true,"max":1,"overLimitCount":0,"rule":"E11015"},"instability":{"band":"info","enforced":false,"limit":null,"rule":null,"value":1.0},"moduleCohesion":{"available":false,"enforced":true,"note":"disconnected-groups value not persisted by the checker; pending the persist-vs-rederive decision","rule":"E11017"},"moduleCoupling":{"band":"ok","basis":"trueCoupling","comparator":">","enforced":true,"limit":10,"rule":"E11016","value":1}},"name":"sample.arch.web","types":{"class":1}},{"band":"ok","cycles":[],"file":"domain.ek9","isApplicationOrRoot":false,"line":2,"metrics":{"afferent":{"band":"info","enforced":false,"excludesExternal":true,"limit":null,"rule":null,"value":1},"constructCoupling":{"band":"ok","enforced":true,"max":0,"overLimitCount":0,"rule":"E11015"},"instability":{"band":"info","enforced":false,"limit":null,"rule":null,"value":0.0},"moduleCohesion":{"available":false,"enforced":true,"note":"disconnected-groups value not persisted by the checker; pending the persist-vs-rederive decision","rule":"E11017"},"moduleCoupling":{"band":"ok","basis":"trueCoupling","comparator":">","enforced":true,"limit":10,"rule":"E11016","value":0}},"name":"sample.arch.domain","types":{"enumeration":1,"record":1}}],"programState":"clean","status":"ok","summary":{"atOrOverLimit":0,"inCycles":0}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_mutex_payload","url":"https://ek9.io/mcp/ek9_query_mutex_payload.html","category":"enquiry","description":"Answers first: status, summary {bodies, contained, mayEscape, unknown}, findingCount, then findings[] {file, line, inConstruct, payloadType, locks, escape, sites[] with via chain and origin}.","whenToUse":"'Does any MutexLock payload escape its critical section' is one call with no arguments - every MutexKey body, with the chain to whoever keeps the reference.","whenNotToUse":["whether ONE named structure is touched by ONE callable (use ek9_query_data_touch, which anchors on a callable and tracks a named parameter)","lock ORDER / deadlock risk rather than payload containment (that is E08252/E08255 and ek9_query_deadlock_chain)","CHANGING code — this is a read-only enquiry with no fix"],"details":"summary {bodies, contained, mayEscape, unknown} counts EVERY MutexKey body, so 'N of M contained' can be stated; findings[] is the escaping subset. Each finding carries {file, line, column (the MutexKey body, 0-based column), inConstruct / inConstructFqn (the named method/function declaring it, in callable-identity form — joins ek9_query_call_graph), payloadType (as written: 'List of String'), locks[] ({stableId, displayName} of the MutexLock it runs under — the same ids ek9_query_lock_identity lists), escape (may-escape / contained / unknown), sites[], unknowns[]}. inConstruct is absent when phase 8 lock analysis did not run (the default compile reaches it); locks[] is absent when no enter() call was paired with the body. Each site has {file, line, kind (escape-store / returns-alias), path (where the reference lands), root {name, role: this/field/parameter/capture — the root of path in the WRITER's frame}, via[] (the callee chain, by RESOLVED signature) and origin {file, line} (where it is actually stored)}. A site with NO via and NO origin IS the write, in the body itself; capture means the body captured that variable, so the object is the caller's and the fix is in the body. hints{} explains the verdicts and fields. ':=:' / ':~:' / ':^:' copy CONTENT and are not reported — they are what E08258 tells you to use. ⚠️ The copy family is SHALLOW: the container is independent but its ELEMENTS are shared, so copying a list of mutable records out of a lock still shares those records.","arguments":[{"name":"includeUnknown","type":"boolean","required":false,"description":"Also report MutexKey bodies whose escape verdict is 'unknown' — an opaque callee, or the payload handed to a function value. Off by default so the list stays actionable."}],"lessons":[],"fixes":[],"example":{"scenario":"Escaping payload","request":{},"response":{"findingCount":2,"findings":[{"column":21,"escape":"may-escape","file":"locks.ek9","inConstruct":"Box.exfiltrate(Stash)","inConstructFqn":"probe.mutex.payload::Box.exfiltrate(probe.mutex.payload::Stash)","line":26,"locks":[{"displayName":"probe.mutex.payload::lockedItems","stableId":"field:probe.mutex.payload::lockedItems@22:6"}],"payloadType":"List of String","sites":[{"file":"locks.ek9","kind":"escape-store","line":27,"origin":{"file":"locks.ek9","line":17},"path":"held","root":{"name":"held","role":"field"},"via":["probe.mutex.payload::Stash.keep(org.ek9.lang::List of String)"]}]},{"column":21,"escape":"may-escape","file":"locks.ek9","inConstruct":"Box.drainInto(Sink)","inConstructFqn":"probe.mutex.payload::Box.drainInto(probe.mutex.payload::Sink)","line":32,"locks":[{"displayName":"probe.mutex.payload::lockedItems","stableId":"field:probe.mutex.payload::lockedItems@22:6"}],"payloadType":"List of String","sites":[{"file":"locks.ek9","kind":"escape-store","line":33,"path":"sink.items","root":{"name":"sink","role":"capture"}}]}],"hints":{"copyIsShallow":"':=:' / ':~:' / ':^:' copy the container, not its elements - a list of mutable records copied out of a lock still shares those records.","may-escape":"The body hands lockedItem to something that keeps a reference, so the payload can be read and mutated with no lock held. Copy CONTENT out (rtn :=: lockedItem) or mutate lockedItem in place. A site with via[] and originLine: the named callee stores it at the origin - copy before the call, or change the callee. A site with neither: the write is in the body itself, at site.line.","root":"root.role is where the stored reference lands, in the writer's frame: this (the writer's own object), field (a field of the writer's owner), parameter (beneath a parameter, so the caller shares it), capture (a variable the MutexKey body captured from its enclosing scope - the caller's object, fix in the body).","see":"E08258 (ek9_explain_error) - the compiler rejects the direct form; this is the rest, traced through callees. Advisory: gates: false.","unknown":"The payload reached an opaque callee or a function value; retention is not statically knowable, so a human must judge it."},"meta":{"serverMs":"<timing>"},"status":"ok","summary":{"bodies":3,"contained":1,"mayEscape":2,"unknown":0}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_name_clashes","url":"https://ek9.io/mcp/ek9_query_name_clashes.html","category":"enquiry","description":"Answers first: status, name, fullyQualifiedName, clashFree, donorLocals, renames (one globally-safe fresh name per clashing local), callSiteCount, then callSites[] with per-site clashes and the summary line.","whenToUse":"'Which of this callable's locals would collide if it were inlined at its call sites' is one call with symbol:'Type.method' - no file or line needed.","whenNotToUse":["performing the inline itself (use ek9_inline_function)","applying a reported rename (use ek9_rename_symbol on each donor local's declaration, then inline)","renaming a symbol and all its references generally, not a capture pre-check (use ek9_rename_symbol)"],"details":"Reports name/kind/fullyQualifiedName, donorLocals (names the body declares), per-site clashes each with a suggestedName, an aggregated 'renames' union whose one rename per donor local is safe at every clashing site at once, and a clashFree flag. Expression-bodied operations declare no locals and are always clashFree; recursive targets report self-call sites as skipped under 'notes'. scope is inferred: callSiteFile+callSiteLine present = single-call-site, else all-call-sites (via the Phase-5 call graph, across files). Shares the NameClashDetector primitive that raises ek9_inline_function's variable-clash conflict.","arguments":[{"name":"callSiteColumn","type":"integer","required":false,"description":"single-call-site only — 1-based column on the call name (an IDE cursor); omit it and the first call on the line is taken."},{"name":"callSiteFile","type":"string","required":false,"description":"single-call-site only — workspace-relative file of the target call."},{"name":"callSiteLine","type":"integer","required":false,"description":"single-call-site only — line (1-based) of the target call."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration header - OMIT it and pass symbol:'Type.method' to let the tool find the line (a model counting lines miscounts)."},{"name":"scope","type":"string: all-call-sites | single-call-site","required":false,"description":"Optional - inferred from the arguments: callSiteFile+callSiteLine present = single-call-site (just that call, no call graph needed), else all-call-sites (every call site via the Phase-5 call graph, across files)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":[],"fixes":[],"example":{"scenario":"Uncalled no call sites","request":{"file":"main.ek9","line":13},"response":{"callSiteCount":0,"callSites":[],"clashFree":true,"donorLocals":[],"fullyQualifiedName":"test.clash::unused","kind":"function","meta":{"serverMs":"<timing>"},"name":"unused","renames":[],"scope":"all-call-sites","status":"ok","summary":"'unused' has no call sites — nothing to splice, no clashes possible."}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_package","url":"https://ek9.io/mcp/ek9_query_package.html","category":"enquiry","description":"Answers first: status, packageCount, then packages[] {name, version, description, license, tags, publishable, deps, devDeps, excludeDeps, capabilities, sourceLocation} - declared, not resolved.","whenToUse":"'What does the package directive say - name, version, deps, capabilities, publishable' is one call with no arguments.","whenNotToUse":["only the version string (use ek9_query_package_version, or ek9_version for the EK9 compiler binary's version)","the RESOLVED transitive dependency tree, not the declared list (use ek9_query_dependency_tree)","module-level (intra-package) imports, not package-level deps (use ek9_query_module_dependencies)","MODIFYING deps (use ek9_add_dependency / ek9_remove_dependency)"],"details":"Each entry carries name, version, description, license, tags, publishable, deps/devDeps/excludeDeps (declared, NOT resolved), capabilities (compare against actual use via ek9_query_capability_usage), and sourceLocation {file, line} for jump-to-edit. Works at any phase — the directive is read from source as soon as parsing completes; a module whose re-parse fails is silently skipped, not errored. The snapshot is static per session unless the directive is edited — cache and reuse.","arguments":[],"lessons":[],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_package_version","url":"https://ek9.io/mcp/ek9_query_package_version.html","category":"enquiry","description":"Answers with version (the 'defines package' literal) and the line it is on for one .ek9 file; null with an error when the file declares no package.","whenToUse":"'What is the package version' is one call with file:'package.ek9'. The lightest read of the user's version literal, and the baseline to capture before ek9_increment_version or ek9_set_version.","whenNotToUse":["The whole package directive (name, deps, capabilities, publishable) - use ek9_query_package.","The EK9 COMPILER's own version, not the user's package - use ek9_version.","Changing the version - use ek9_increment_version, ek9_set_version or ek9_set_feature_version."],"details":"Version format is major.minor.patch[-feature]-build. Read from the source as soon as it parses - no prior ek9_compile, no subprocess. version is null (never an explanation string) when the file has no package block or does not parse; the error block says which.","arguments":[{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."}],"lessons":[],"fixes":[],"example":{"scenario":"Query returns version","request":{"file":"<workspace-root>/package.ek9"},"response":{"file":"package.ek9","line":5,"meta":{"serverMs":"<timing>"},"module":"com.example.pkg","status":"ok","summary":"version 1.0.0-0","version":"1.0.0-0"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_pipeline","url":"https://ek9.io/mcp/ek9_query_pipeline.html","category":"enquiry","description":"Answers first: status, stageCount, then stages[] in order {operator, kind, consumes, produces}, sourceType, resultType and summary.transformations.","whenToUse":"'What does each stage of this stream pipeline consume and produce' is one call with symbol:'Type.method' (its first pipeline) or file+line on any line of it.","whenNotToUse":["an imperative body with branches, loops or guards, not a stream chain (use ek9_query_flow)","method-level caller/callee relationships, not stage-level pipeline analysis (use ek9_query_call_graph)","the structural outline of a class/record, not pipeline details (use ek9_query_construct)","compile errors/warnings (incl. pipeline type mismatches), not the pipeline structure (use ek9_query_diagnostics)"],"details":"stages[] is ordered, each carrying operator, kind, context, consumes, produces (consumes omitted on source stages). kind enum: source (cat/for), filter (filter/reject/uniq), map (map/flatten/group/join/split), limit (head/tail/skipping), sort, tee, async, call, reduce, terminal (collect/`>`/`>>`), with kind-specific arg fields predicate/function/limit/collector (limit numeric for a plain int literal, else raw text). Flat sourceType/resultType and nested summary{stageCount, sourceType, terminalType, transformations[]} give the whole-pipeline type-evolution story. Where pipelines nest, the innermost chain spanning the line wins; a body holding several pipelines needs file+line for any but the first.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line the pipeline spans - any line of the chain; OMIT it and pass symbol:'Type.method' for the first pipeline in that body, or use ek9_read_file(lineNumbers:true) rather than counting."},{"name":"symbol","type":"string","required":false,"description":"The method or function whose body holds the pipeline - 'Type.method' or a function name - no file or line needed; the FIRST pipeline in that body is decomposed."}],"lessons":["https://ek9.io/ide/book-streams.html","https://ek9.io/ide/one-construct.html"],"fixes":[],"example":{"scenario":"Pipeline shape","request":{"file":"Hello.ek9","line":6},"response":{"meta":{"serverMs":"<timing>"},"nextStep":"anchor on a line of the cat | ... | collect chain, or pass symbol:'Type.method' for the first pipeline in that body","note":"No stream pipeline found at line 6","status":"not-found"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_programs","url":"https://ek9.io/mcp/ek9_query_programs.html","category":"enquiry","description":"Answers first: status, programCount, programNames - complete for the workspace or the filters given - then programs[] {name, module, file, line, signature, parameters}.","whenToUse":"'What programs (entry points) does this app expose, with what arguments' is one call with no arguments, or nameFilter / argTypeFilter / moduleFilter to narrow.","whenNotToUse":["running a program you already know the name of (use ek9_run_program; this tool only DISCOVERS - query first, then run the chosen one)","callable functions rather than executable entry points (use ek9_query_functions)","the full source of a program you already know the name of (use ek9_read_construct)"],"details":"status is ok (>=1 program) / empty (filtered set empty — NOT an error; carries meta.unmatchedFilters[] when a moduleFilter names no module) / not-compiled (nothing compiled yet — compile first). Each program projects name, module, file, line, a ready-to-read signature string, and parameters[] as {name,type} pairs read off the program's single entry method. argTypeFilter is a leading-prefix, in-order, case-insensitive exact-type match; unresolved arg types render as <unresolved> without degrading status.","arguments":[{"name":"argTypeFilter","type":"array of string","required":false,"description":"Filter to programs whose argument list STARTS WITH these types, in order (case-insensitive, exact type-name match). Example: [\"Date\"] matches programs whose first argument is a Date."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to specific modules (exact names). Default: workspace-wide."},{"name":"nameFilter","type":"string","required":false,"description":"Case-insensitive substring match on program names."}],"lessons":[],"fixes":[],"example":{"scenario":"List all","request":{},"response":{"meta":{"serverMs":"<timing>"},"programCount":2,"programNames":["Main","DailyBatch"],"programs":[{"file":"app.ek9","line":6,"module":"com.example.app","name":"Main","parameters":[],"signature":"Main()"},{"file":"app.ek9","line":10,"module":"com.example.app","name":"DailyBatch","parameters":[{"name":"runDate","type":"Date"}],"signature":"DailyBatch()\n  -> runDate as Date"}],"status":"ok","summary":{"moduleCount":1,"withArgsCount":1}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_purity_impact","url":"https://ek9.io/mcp/ek9_query_purity_impact.html","category":"enquiry","description":"Answers first: status, change, availableChanges, verdict (ready / would-fail / cascade-too-large / blocked-refuse-to-root), callerNames, calleeNames, then anchor, contract, afferent, efferent axes - the same closure ek9_fix_purity_contract applies.","whenToUse":"'Who breaks if this stops being pure, or what must become pure if it does' is one call with symbol:'Type.method' - on a callable flagged E08130/E05150/E05160 the change the compiler asks for, on any other the what-if (changeKind:'purity-what-if', nothing to apply).","whenNotToUse":["applying the purity fix, not previewing it (use ek9_fix_purity_contract)","previewing a signature change (add/remove/reorder params, return type), not a purity change (use ek9_query_signature_impact)","raw caller/callee chains without the purity verdict overlay (use ek9_query_call_graph)","the list of purity errors first, to find a callable to anchor on (use ek9_query_diagnostics)"],"details":"Returns a BlastRadius (BlastRadiusJson): anchor callable + three axes — 'contract' (the override group; root is the ONLY legal edit anchor), 'afferent' (transitive pure-caller closure that breaks if pure is removed), 'efferent' (non-pure-callee closure that must become pure if pure is added) — each node with a verdict (root / fixable / breaks) and file:line. Overall verdict (ready / would-fail / cascade-too-large / blocked-refuse-to-root) is computed by the SAME rule ek9_fix_purity_contract applies, so picture and fix agree. change: 'remove-pure' = which CALLERS break if this stops being pure (the afferent axis); 'add-pure' = which CALLEES must become pure (the efferent axis); E08130 offers both, E05150 only add-pure, E05160 only remove-pure. Works under compile errors via an on-demand call graph; FULL_RESOLUTION (or default ek9_compile) suffices. The add-pure what-if (no purity error at the callable) also compiles the change in memory - the body's own rules (E08100 / E08120 / E08140) are no call graph's - and a change that adds errors is would-fail with them as wouldBeDiagnostics. A program named by symbol is its body; a type is refused with its members.","arguments":[{"name":"change","type":"string: add-pure | remove-pure","required":false,"description":"'remove-pure' = which CALLERS break if this stops being pure; 'add-pure' = which CALLEES must become pure. Omit to take the natural direction for the diagnosed code (E08130 offers both - see availableChanges)."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line where the purity error (E08130 / E05150 / E05160) fires - OMIT it and pass symbol:'Type.method' to let the tool find the flagged line."},{"name":"symbol","type":"string","required":false,"description":"The flagged method or function - 'Type.method' or a function name - no file or line needed; the tool finds its first purity error."}],"lessons":["https://ek9.io/ide/blast-radius.html"],"fixes":[],"example":{"scenario":"E05150 contract axis","request":{"file":"a.ek9","line":10},"response":{"afferent":[],"anchor":{"detail":"E05150","file":"a.ek9","fullyQualifiedName":"purity.probe.a::Derived.calc()","label":"Derived.calc()","line":10,"verdict":"fixable"},"availableChanges":["add-pure"],"calleeNames":[],"callerNames":[],"change":"add-pure","changeKind":"purity","contract":[{"detail":"contract root","file":"a.ek9","fullyQualifiedName":"purity.probe.a::Base.calc()","label":"Base.calc()","line":6,"verdict":"root"},{"detail":"override — aligns to root","file":"a.ek9","fullyQualifiedName":"purity.probe.a::Derived.calc()","label":"Derived.calc()","line":10,"verdict":"fixable"}],"efferent":[],"meta":{"serverMs":"<timing>"},"note":"Read-only preview. 'verdict' and the closures are the SAME the fix tool applies; drive the change with ek9_fix_purity_contract using the matching mode.","status":"ok","summary":{"afferent":0,"cascadeThreshold":25,"contract":2,"efferent":0},"verdict":"ready"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_records","url":"https://ek9.io/mcp/ek9_query_records.html","category":"enquiry","description":"Answers first: status, recordCount, recordNames - complete for the workspace or the filters given - then records[] {name, module, file, line, fields, extends, traits, isOpen}.","whenToUse":"'Which records exist, and is there a data shape to reuse' is one call - no arguments, or nameFilter / fieldNameFilter / moduleFilter to narrow.","whenNotToUse":["constructs with methods/behaviour, not just data (use ek9_query_classes)","interface contracts (use ek9_query_traits)","constrained primitive types, EmailAddress as String (use ek9_query_constrained_types)","a record you already know the name of (ek9_query_references for its usage sites, ek9_read_construct for its full source)"],"details":"Each record carries name, module, file (workspace-relative), line, fields[] (name+type; unresolved types render <unresolved>), extends (null unless a super declared; implicit Any filtered), traits[], isOpen. Only directly-declared fields — supers not flattened; nameFilter and fieldNameFilter are plain case-insensitive substrings, never regex. status:empty (not an error) when nothing matched or moduleFilter named non-existent modules — then meta.unmatchedFilters[] carries module:<value>.","arguments":[{"name":"fieldNameFilter","type":"string","required":false,"description":"Filter to records declaring a field whose name matches (case-insensitive substring)."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to specific modules (exact names). Default: workspace-wide."},{"name":"nameFilter","type":"string","required":false,"description":"Case-insensitive substring match on record names."}],"lessons":[],"fixes":[],"example":{"scenario":"List all","request":{},"response":{"meta":{"serverMs":"<timing>"},"recordCount":2,"recordNames":["PostalAddress","Amount"],"records":[{"extends":null,"fields":[{"name":"line1","type":"String"},{"name":"city","type":"String"},{"name":"postCode","type":"String"}],"file":"shapes.ek9","isOpen":false,"line":6,"module":"com.example.shapes","name":"PostalAddress","traits":[]},{"extends":null,"fields":[{"name":"amount","type":"Integer"},{"name":"currency","type":"String"}],"file":"shapes.ek9","isOpen":false,"line":13,"module":"com.example.shapes","name":"Amount","traits":[]}],"status":"ok","summary":{"moduleCount":1}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_references","url":"https://ek9.io/mcp/ek9_query_references.html","category":"enquiry","description":"Answers first: useSiteCount, usedByConstructs, useSites as file.ek9:LINE - then each reference with its source line (omitted above 50 sites unless verbosity:'full').","whenToUse":"'Who uses X, and from which constructs' is one call with symbol:'Type.member' - no file needed; the pre-flight for rename, safe-delete and change-signature.","whenNotToUse":["a method's incoming AND outgoing call structure in one query (use ek9_query_call_graph)","what a type EXPOSES or how it RELATES (supertypes/subtypes/traits), not where it is used (use ek9_query_effective_api or ek9_query_type_hierarchy)","raw text occurrences (comments, string literals) (use ek9_search_text; this tool resolves structural references via the type system)"],"details":"Anchor symbol may be any kind the compiler tracks: types, methods, functions, fields, constants, and locals / parameters / returning params inside a body. Two distinct enums on the response: top-level 'kind' is uppercase (METHOD, FIELD, TYPE…); per-reference 'kind' is lowercase snake_case — declaration (always first), structural (extends, trait_implementation, field_type, parameter_type, return_type…), calls (method_call, function_call, constructor_call) and identity-match body usages (variable_usage, parameter_usage, field_access, constant_usage…). A use of a VARIABLE (field, parameter, local, returning variable, constant) carries access:'read' or access:'write' (with writeOperator), and the headline gives writeSiteCount and writeSites - who CHANGES it. A write is an assignment (':', ':=', '=', ':=?') or a mutating operator ('+=', ':=:', ':~:', ':^:', '++', ...), so 'order.total += 5' is a write though it stores nothing to the field; a mutating METHOD call ('items.add(x)') is not. For a PROPERTY the writeSites are every line that can change its value on any instance (THE property write-site query): direct, through an alias ('t <- order.total; t += 5'), a view ('t <- order.getTotal()'), a method that is not pure on its object, or a user callee data touch says writes its parameter - writeSitesByRoute counts them and writes[] gives each with foundBy, operation, certain (false for view/method/callee: they MAY change it), through, fedBy and, for a callee, origin (where inside it the write is). A reference whose type was INFERRED (no text names the symbol: 'if product <- store.findProduct(id)' for Product) carries explicit:false - one per name that received the type - as does a method call on an instance for its type ('$product.getPriority()' does not spell Product); a site whose text names the symbol is explicit:true. When any are inferred the headline gives explicitUseSiteCount and inferredUseSiteCount; include:'explicit' keeps only the sites that name it. An overloaded 'Type.member' with no signature (a constructor 'Type.Type' included) answers for EVERY overload: useSites is their union and overloads[] holds each one's answer tagged with its signature, resendable as 'Type.m(P)'; when they form a dispatcher the name means its entry point. summary.productionVsTest is a PATH HEURISTIC (test = path contains a 'test' segment), not authoritative; a cursor on whitespace/comment/unresolvable returns status:'not-found', not an error.","arguments":[{"name":"among","type":"array of string","required":false,"description":"Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched)."},{"name":"column","type":"integer","required":false,"description":"0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"include","type":"string: all | explicit | inferred","required":false,"description":"Which use sites: 'all' (default), 'explicit' (only sites whose text names the symbol) or 'inferred' (only names whose type was INFERRED as it, e.g. 'p <- find(id)' for Product - one per name). The headline counts both either way."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":[],"fixes":[],"example":{"scenario":"References shape","request":{"file":"MyRecord.ek9","line":5},"response":{"declaredAt":{"column":4,"file":"MyRecord.ek9","line":5},"fullyQualifiedName":"com.example::MyRecord","kind":"TYPE","meta":{"serverMs":"<timing>"},"name":"MyRecord","referenceCount":1,"references":[{"column":4,"context":"MyRecord","explicit":true,"file":"MyRecord.ek9","kind":"declaration","line":5,"symbol":"MyRecord"}],"status":"ok","summary":{"byFile":[{"count":1,"file":"MyRecord.ek9"}],"byKind":{"declaration":1},"productionVsTest":{"heuristic":"test when the file path contains a 'test' segment (case-insensitive), else production","production":1,"test":0}},"useSiteCount":0,"useSites":[],"useSitesExclude":"the declaration"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_requirement","url":"https://ek9.io/mcp/ek9_query_requirement.html","category":"enquiry","description":"Answers status (ok | not-found) and requirementId first, then the node(s): each carries authored{title, body, retired, meta} and derived{developed, anchoringTests, parentChain, children} so a computed rollup is never mistaken for a person's assertion; list and outstanding return requirementCount + requirements[], footprint the anchoringTests and reachedSymbols.","whenToUse":"'What does requirement X say, and what is under it?' is one call: {mode:'detail', requirementId:'REQ:fraud-screening'}; mode 'outstanding' with no id is the backlog.","whenNotToUse":["Mutating a requirement (title/body/retired) — use ek9_update_requirement (writes are bottom-up; you never set derived children/rollups).","Creating new requirements — use ek9_create_requirement.","Blast radius (which requirements reach a given SYMBOL) — starts from a symbol, so use ek9_query_construct_neighbourhood, whose requirements[] axis answers exactly that.","Checking that requirement references resolve at compile time — that is ek9_check_requirements."],"details":"Modes: detail (one node), hierarchy (subtree, optional depth), list (filter by developed/retired/prefix/assignee/titleLike), outstanding (live, not yet developed — the backlog), footprint (call-graph reach of the requirementId's anchoring tests - over-inclusive by construction, reachResolved:false when the call graph is unavailable). 'developed' is always derived and read-only - anchored by a @Test directly or via children, NOT that it is correct or adequately tested. Every response opens with status: 'ok', or 'not-found' from detail/hierarchy for an unknown requirementId; footprint just reports empty anchoringTests.","arguments":[{"name":"assignee","type":"string","required":false,"description":"For list: match nodes whose meta.assignee equals this."},{"name":"depth","type":"integer","required":false,"description":"For hierarchy: how far down to walk. Omit for the whole subtree; 1 gives the node and its direct children."},{"name":"developed","type":"boolean","required":false,"description":"For list: match only developed (true) or only outstanding (false). Omit to match either."},{"name":"mode","type":"string: detail | hierarchy | list | outstanding | footprint","required":true,"description":"Which read to perform."},{"name":"prefix","type":"string: REQ | CTRL | CAP | CON","required":false,"description":"For list: match one node kind."},{"name":"requirementId","type":"string","required":false,"description":"Required for detail, hierarchy and footprint, e.g. REQ:fraud-screening."},{"name":"retired","type":"boolean","required":false,"description":"For list: match only retired (true) or only live (false). Omit to match either."},{"name":"titleLike","type":"string","required":false,"description":"For list: case-insensitive substring of the title or body."}],"lessons":[],"fixes":[],"example":{"scenario":"Query requirement not found","request":{"mode":"detail","requirementId":"REQ:never-created"},"response":{"detail":"no requirement with this id exists in .ek9-ai/requirements/","meta":{"serverMs":"<timing>"},"nextStep":"ek9_query_requirement {mode:'list'} to see the ids that do exist","requirementId":"REQ:never-created","status":"not-found"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_sensitive_reveals","url":"https://ek9.io/mcp/ek9_query_sensitive_reveals.html","category":"enquiry","description":"Answers first: status, revealCount, violationCount, privilegedCount, violationSites as file.ek9:LINE, then reveals[] {file, line, column, module, inConstruct, inConstructFqn, privilege}.","whenToUse":"'Where are secrets revealed, and which reveals are illegal (E11090)' is one call with no arguments - every Sensitive.reveal() site with its privilege verdict.","whenNotToUse":["env-var, network or filesystem capability audits, not the Sensitive type (use ek9_query_capability_usage)","just the LIST of E11090 errors, not the full reveal-site audit (use ek9_query_diagnostics)","E11090 explained rather than checked across the workspace (use ek9_explain_error)","references to some arbitrary symbol (use ek9_query_references; this tool is specific to Sensitive.reveal())"],"details":"Type-resolution-driven (mirrors the compiler's PrivilegedRevealOrError check): only calls that RESOLVE to Sensitive.reveal are counted, so a workspace compiled below FULL_RESOLUTION silently under-reports — run ek9_compile first for an audit-grade result. Per-reveal privilege: privileged (legal) / unprivileged (caller class lacks Privileged, E11090) / in-function (reveal in a free function, which can never be Privileged, E11090); inConstruct is 'Class.method' or the function name, inConstructFqn its qualified identity. Revealing secrets into log strings is almost always a bug even when it passes the Privileged check.","arguments":[{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to these modules - exact names; an entry ending in '*' is a prefix ('com.acme.*'). A single string is accepted. Omit for workspace-wide."}],"lessons":["https://ek9.io/ide/sensitive-and-environment.html"],"fixes":[],"example":{"scenario":"Audit","request":{},"response":{"meta":{"serverMs":"<timing>"},"moduleCount":1,"privilegedCount":1,"revealCount":3,"reveals":[{"column":22,"file":"audit.ek9","inConstruct":"SecureVault.consume","inConstructFqn":"demo.sensitive.audit::consume","line":14,"module":"demo.sensitive.audit","privilege":"privileged"},{"column":22,"file":"audit.ek9","inConstruct":"LeakyService.consume","inConstructFqn":"demo.sensitive.audit::consume","line":22,"module":"demo.sensitive.audit","privilege":"unprivileged"},{"column":20,"file":"audit.ek9","inConstruct":"leakInFunction","inConstructFqn":"demo.sensitive.audit::leakInFunction","line":31,"module":"demo.sensitive.audit","privilege":"in-function"}],"status":"ok","violationCount":2,"violationSites":["audit.ek9:22","audit.ek9:31"]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_service_routes","url":"https://ek9.io/mcp/ek9_query_service_routes.html","category":"enquiry","description":"Answers first: status, programState, routeCount, byService, then routes[] {verb, uri, fullPath, parameters with binding + sanitized, securityGate, cors, auditWarnings} and summary counts.","whenToUse":"'What is the HTTP attack surface - every route, its inputs, which are unsanitized or unguarded' is one call, no arguments; verb/service/uri/audit narrow it.","whenNotToUse":["how services get their components wired, DI, not the route list (use ek9_query_dependency_injection)","whether services declare/require the network capability, not HTTP routes (use ek9_query_capability_usage)","whether routes ever surface secrets, the secret-handling audit (use ek9_query_sensitive_reveals)","the full structure of one specific service class, not the route catalogue (use ek9_query_construct)"],"details":"status ok | empty (empty = no 'defines service' blocks, or filters matched nothing); needs a prior ek9_compile. parameters[].binding is UPPERCASE (PATH/QUERY/HEADER/CONTENT/REQUEST/CONTEXT); securityGate/cors are the declaring FUNCTION reference {name,fqn,file,line} (usually another file) — the compiler stores only the reference, null = unguarded / no CORS. auditWarnings flags unsanitized-{query,header,content} (PATH excluded, template-constrained) and unguarded-route; reuses the compiler's own ServiceMetadataExtractor, so the inventory never diverges from generated routing.","arguments":[{"name":"audit","type":"string: all | unsanitized | unguarded","required":false,"description":"Audit-level filter: all (default), unsanitized (routes with >=1 un-sanitized input parameter), unguarded (routes without a security gate)."},{"name":"service","type":"string","required":false,"description":"Optional service-name SUBSTRING filter ('Order' matches OrderService)."},{"name":"uri","type":"string","required":false,"description":"Optional fullPath SUBSTRING filter ('/addresses' matches every route under it)."},{"name":"verb","type":"string: all | GET | POST | PUT | DELETE | PATCH | HEAD | OPTIONS","required":false,"description":"Filter by HTTP verb (default all)."}],"lessons":["https://ek9.io/ide/services-and-di.html","https://ek9.io/ide/web-services.html"],"fixes":[],"example":{"scenario":"Inventory","request":{},"response":{"byService":{"CachedService":1,"ClockService":1,"CorsService":1,"LookupService":2,"OrderService":4,"PublicService":1,"ReportService":6},"meta":{"serverMs":"<timing>"},"programState":"clean","routeCount":16,"routes":[{"anySanitized":false,"auditCompliant":true,"auth":{"explicitlyOpen":false,"guarded":true,"source":"service"},"baseUri":"/api/cached","caching":{"directive":"public,max-age=600,s-maxage=30","directives":["public"],"maxAgeSeconds":600,"sMaxAgeSeconds":30,"source":"override"},"cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"none"},"file":"routes.ek9","fullPath":"/api/cached/fresh/{tag}","line":119,"method":"fresh","module":"demo.routes","parameters":[{"binding":"PATH","line":120,"name":"tag","sanitized":false,"source":"tag","type":"org.ek9.lang::String"}],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":{"file":"routes.ek9","fullyQualifiedName":"demo.routes::MyGate","line":17,"name":"MyGate"},"service":"CachedService","serviceFQN":"demo.routes::CachedService","uri":"/fresh/{tag}","verb":"GET"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Attach a security gate with `constrain by <Gate>` on the route or service","kind":"unguarded-route"}],"auth":{"explicitlyOpen":true,"guarded":false},"baseUri":"/api/clock","caching":{"directive":"public,max-age=3600,must-revalidate","directives":["public","must-revalidate"],"maxAgeSeconds":3600,"source":"default"},"cors":null,"domainFootprint":{"injectedComponentCount":1,"status":"opaque"},"file":"routes.ek9","fullPath":"/api/clock/time","line":183,"method":"time","module":"demo.routes","parameters":[],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":null,"service":"ClockService","serviceFQN":"demo.routes::ClockService","uri":"/time","verb":"GET"},{"anySanitized":false,"auditCompliant":true,"auth":{"explicitlyOpen":false,"guarded":true,"source":"service"},"baseUri":"/api/cors","cors":{"file":"routes.ek9","fullyQualifiedName":"demo.routes::MyCors","line":21,"name":"MyCors"},"domainFootprint":{"injectedComponentCount":0,"status":"unknown"},"file":"routes.ek9","fullPath":"/api/cors","line":114,"method":"ping","module":"demo.routes","parameters":[],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":{"file":"routes.ek9","fullyQualifiedName":"demo.routes::MyGate","line":17,"name":"MyGate"},"service":"CorsService","serviceFQN":"demo.routes::CorsService","uri":"/","verb":"GET"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Attach a security gate with `constrain by <Gate>` on the route or service","kind":"unguarded-route"}],"auth":{"explicitlyOpen":true,"guarded":false},"baseUri":"/api/lookup","cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"unknown"},"file":"routes.ek9","fullPath":"/api/lookup/all","line":172,"method":"lookup","module":"demo.routes","parameters":[],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":null,"service":"LookupService","serviceFQN":"demo.routes::LookupService","uri":"/all","verb":"GET"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Attach a security gate with `constrain by <Gate>` on the route or service","kind":"unguarded-route"}],"auth":{"explicitlyOpen":true,"guarded":false},"baseUri":"/api/lookup","cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"unknown"},"file":"routes.ek9","fullPath":"/api/lookup/one/{id}","line":175,"method":"lookup","module":"demo.routes","parameters":[{"binding":"PATH","line":176,"name":"id","sanitized":false,"source":"id","type":"org.ek9.lang::String"}],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":null,"service":"LookupService","serviceFQN":"demo.routes::LookupService","uri":"/one/{id}","verb":"GET"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Mark parameter 'content' as `sanitized` (or validate it) before use","kind":"unsanitized-content","param":"content"}],"auth":{"explicitlyOpen":false,"guarded":true,"source":"service"},"baseUri":"/api/orders","cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"unknown"},"file":"routes.ek9","fullPath":"/api/orders","line":96,"method":"create","module":"demo.routes","parameters":[{"binding":"CONTENT","line":97,"name":"content","sanitized":false,"type":"org.ek9.lang::String"}],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":{"file":"routes.ek9","fullyQualifiedName":"demo.routes::MyGate","line":17,"name":"MyGate"},"service":"OrderService","serviceFQN":"demo.routes::OrderService","uri":"/","verb":"POST"},{"anySanitized":true,"auditCompliant":true,"auth":{"explicitlyOpen":false,"guarded":true,"source":"service"},"baseUri":"/api/orders","cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"unknown"},"file":"routes.ek9","fullPath":"/api/orders/find","line":100,"method":"search","module":"demo.routes","parameters":[{"binding":"QUERY","line":101,"name":"term","sanitized":true,"source":"q","type":"org.ek9.lang::String"}],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":{"file":"routes.ek9","fullyQualifiedName":"demo.routes::MyGate","line":17,"name":"MyGate"},"service":"OrderService","serviceFQN":"demo.routes::OrderService","uri":"/find","verb":"GET"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Attach a security gate with `constrain by <Gate>` on the route or service","kind":"unguarded-route"}],"auth":{"explicitlyOpen":true,"guarded":false},"baseUri":"/api/orders","cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"unknown"},"file":"routes.ek9","fullPath":"/api/orders/status","line":104,"method":"status","module":"demo.routes","parameters":[],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":null,"service":"OrderService","serviceFQN":"demo.routes::OrderService","uri":"/status","verb":"GET"},{"anySanitized":false,"auditCompliant":true,"auth":{"explicitlyOpen":false,"guarded":true,"source":"service"},"baseUri":"/api/orders","cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"unknown"},"file":"routes.ek9","fullPath":"/api/orders/{id}","line":92,"method":"byId","module":"demo.routes","parameters":[{"binding":"PATH","line":93,"name":"id","sanitized":false,"source":"id","type":"org.ek9.lang::String"}],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":{"file":"routes.ek9","fullyQualifiedName":"demo.routes::MyGate","line":17,"name":"MyGate"},"service":"OrderService","serviceFQN":"demo.routes::OrderService","uri":"/{id}","verb":"GET"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Attach a security gate with `constrain by <Gate>` on the route or service","kind":"unguarded-route"}],"auth":{"explicitlyOpen":true,"guarded":false},"baseUri":"/api/public","cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"unknown"},"file":"routes.ek9","fullPath":"/api/public/status","line":109,"method":"health","module":"demo.routes","parameters":[],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":null,"service":"PublicService","serviceFQN":"demo.routes::PublicService","uri":"/status","verb":"GET"},{"anySanitized":false,"auditCompliant":true,"auth":{"explicitlyOpen":false,"guarded":true,"source":"route"},"baseUri":"/api/reports","cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"unknown"},"file":"routes.ek9","fullPath":"/api/reports/admin","line":147,"method":"admin","module":"demo.routes","parameters":[],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":{"file":"routes.ek9","fullyQualifiedName":"demo.routes::MyGate","line":17,"name":"MyGate"},"service":"ReportService","serviceFQN":"demo.routes::ReportService","uri":"/admin","verb":"DELETE"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Attach a security gate with `constrain by <Gate>` on the route or service","kind":"unguarded-route"}],"auth":{"explicitlyOpen":true,"guarded":false},"baseUri":"/api/reports","caching":{"source":"dynamic"},"cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"none"},"file":"routes.ek9","fullPath":"/api/reports/detail/{ref}","line":138,"method":"detail","module":"demo.routes","parameters":[{"binding":"PATH","line":139,"name":"ref","sanitized":false,"source":"ref","type":"org.ek9.lang::String"}],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":null,"service":"ReportService","serviceFQN":"demo.routes::ReportService","uri":"/detail/{ref}","verb":"GET"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Attach a security gate with `constrain by <Gate>` on the route or service","kind":"unguarded-route"}],"auth":{"explicitlyOpen":true,"guarded":false},"baseUri":"/api/reports","caching":{"directive":"public,max-age=3600,must-revalidate","directives":["public","must-revalidate"],"maxAgeSeconds":3600,"source":"default"},"cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"none"},"file":"routes.ek9","fullPath":"/api/reports/summary","line":132,"method":"summary","module":"demo.routes","parameters":[],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":null,"service":"ReportService","serviceFQN":"demo.routes::ReportService","uri":"/summary","verb":"GET"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Attach a security gate with `constrain by <Gate>` on the route or service","kind":"unguarded-route"}],"auth":{"explicitlyOpen":true,"guarded":false},"baseUri":"/api/reports","caching":{"directive":"public,max-age=3600,must-revalidate","directives":["public","must-revalidate"],"maxAgeSeconds":3600,"source":"default"},"cors":null,"domainFootprint":{"elements":[{"depth":1,"file":"routes.ek9","fullyQualifiedName":"demo.routes::Thing","genus":"CLASS","kind":"resolved","line":50,"type":"Thing","via":"ThingRepo"},{"depth":2,"file":"routes.ek9","fullyQualifiedName":"demo.routes::Deep","genus":"RECORD","kind":"recursed","line":38,"type":"Deep","via":"ThingRepo"}],"injectedComponentCount":1,"status":"derived"},"file":"routes.ek9","fullPath":"/api/reports/things","line":163,"method":"things","module":"demo.routes","parameters":[],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":null,"service":"ReportService","serviceFQN":"demo.routes::ReportService","uri":"/things","verb":"GET"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Attach a security gate with `constrain by <Gate>` on the route or service","kind":"unguarded-route"}],"auth":{"explicitlyOpen":true,"guarded":false},"baseUri":"/api/reports","caching":{"directive":"public,max-age=3600,must-revalidate","directives":["public","must-revalidate"],"maxAgeSeconds":3600,"source":"default"},"cors":null,"domainFootprint":{"elements":[{"depth":1,"file":"routes.ek9","fullyQualifiedName":"demo.routes::Ticket","genus":"RECORD","kind":"resolved","line":34,"type":"Ticket","via":"Repo"}],"injectedComponentCount":1,"status":"derived"},"file":"routes.ek9","fullPath":"/api/reports/tickets","line":156,"method":"tickets","module":"demo.routes","parameters":[],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":null,"service":"ReportService","serviceFQN":"demo.routes::ReportService","uri":"/tickets","verb":"GET"},{"anySanitized":false,"auditCompliant":false,"auditWarnings":[{"fix":"Attach a security gate with `constrain by <Gate>` on the route or service","kind":"unguarded-route"}],"auth":{"explicitlyOpen":true,"guarded":false},"baseUri":"/api/reports","caching":{"directive":"private,max-age=42","directives":["private"],"maxAgeSeconds":42,"source":"override"},"cors":null,"domainFootprint":{"injectedComponentCount":0,"status":"none"},"file":"routes.ek9","fullPath":"/api/reports/traited","line":150,"method":"traited","module":"demo.routes","parameters":[],"returns":{"type":"HTTPResponse","typeFqn":"org.ek9.lang::HTTPResponse"},"securityGate":null,"service":"ReportService","serviceFQN":"demo.routes::ReportService","uri":"/traited","verb":"GET"}],"status":"ok","summary":{"corsConfiguredRoutes":1,"guardedRoutes":6,"sanitizedCount":1,"totalParams":6,"unguardedRoutes":10,"unsanitizedCount":5}}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_signature_impact","url":"https://ek9.io/mcp/ek9_query_signature_impact.html","category":"enquiry","description":"Answers first: status, direction (the mutation kind), verdict (ready / would-fail), callerSites, then anchor, contract (root + overrides the change cascades to) and afferent (the call sites ek9_change_signature would rewrite, each fixable or breaks).","whenToUse":"'What breaks if I add, remove or reorder a parameter, or change the return type' is one call with symbol:'Type.method' plus the mutations - no file needed.","whenNotToUse":["applying the change, not previewing it (use ek9_change_signature with the same mutations)","previewing a PURITY change derived from an existing diagnostic, not a signature edit (use ek9_query_purity_impact)","raw caller/callee chains without the per-site update verdict (use ek9_query_call_graph)","EVERY reference to a symbol (any kind), not the call sites a specific mutation would rewrite (use ek9_query_references)"],"details":"Overall verdict is would-fail if ANY afferent site is breaks, else ready. Axes: 'contract' (⬆ override group — root has verdict 'root', overrides 'fixable'); 'afferent' (▲ one-hop call sites — each fqn a call-site file:line:col; 'fixable' rewritten mechanically, 'breaks' for an added param with no valueForExistingCalls and no unset instance, or a removed param without dropCallSiteArguments, 'consistent' when the argument list is unchanged (a return-type or purity change rewrites no site)); 'efferent' (▼ always empty — a signature change does not alter what the anchor calls). direction/availableDirections carry the mutation kind verbatim (add-parameter / remove-parameter / reorder-parameters / change-return-type / change-purity), not an axis; needs a FULL_RESOLUTION workspace (default ek9_compile suffices).","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the method or function declaration - OMIT it and pass symbol:'Type.method' to let the tool find the line (a model counting lines miscounts)."},{"name":"mutations","type":"array of any","required":true,"description":"The proposed signature change (same shape as ek9_change_signature): one or more {kind: 'add-parameter' (+ parameter:{name,type,position?,valueForExistingCalls?}), 'remove-parameter' (+ removeParameterName, + optional dropCallSiteArguments:true), 'reorder-parameters' (+ newParameterOrder:[names]), 'change-return-type' (+ newReturnType), 'change-purity' (+ purityChange)}. Drives the direction and the per-site verdict."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/blast-radius.html"],"fixes":[],"example":{"scenario":"Add parameter","request":{"file":"r.ek9","line":6,"mutations":[{"kind":"add-parameter","parameter":{"name":"scale","type":"Integer","valueForExistingCalls":"1"}}]},"response":{"afferent":[{"detail":"argument list rewritten mechanically","file":"r.ek9","fullyQualifiedName":"<workspace-root>/r.ek9:20:26","label":"r.ek9:20","line":20,"verdict":"fixable"},{"detail":"argument list rewritten mechanically","file":"r.ek9","fullyQualifiedName":"<workspace-root>/r.ek9:21:26","label":"r.ek9:21","line":21,"verdict":"fixable"}],"anchor":{"detail":"add scale as Integer","file":"r.ek9","fullyQualifiedName":"sig.probe::Renderer.render(org.ek9.lang::Integer)","label":"Renderer.render()","line":6,"verdict":"root"},"availableDirections":["add-parameter"],"callerSites":["r.ek9:20","r.ek9:21"],"changeKind":"signature","contract":[{"detail":"contract root","file":"r.ek9","fullyQualifiedName":"sig.probe::Renderer.render(org.ek9.lang::Integer)","label":"Renderer.render()","line":6,"verdict":"root"},{"detail":"override — signature cascades with the root","file":"r.ek9","fullyQualifiedName":"sig.probe::FancyRenderer.render(org.ek9.lang::Integer)","label":"FancyRenderer.render()","line":11,"verdict":"fixable"}],"direction":"add-parameter","efferent":[],"meta":{"serverMs":"<timing>"},"note":"Read-only preview of a proposed signature change. The 'afferent' sites are exactly the call sites ek9_change_signature would rewrite; apply with ek9_change_signature using the same mutations.","status":"ok","summary":{"afferent":2,"contract":2,"efferent":0},"verdict":"ready"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_tool_catalogue","url":"https://ek9.io/mcp/ek9_query_tool_catalogue.html","category":"enquiry","description":"Returns the whole EK9 tool inventory grouped by category - toolCount and toolNames per category plus workflowNames by default; verbosity:'summary' adds each tool's description, rules and IDE precedent, 'full' the JSON schemas.","whenToUse":"'What tools are there' is one call with {} at session start - every tool's name by category (enquiry/editor/execution) and the workflow names in ~4K. Use verbosity:'summary' for descriptions, rules and IDE precedents; cache it, the catalogue is static within a session.","whenNotToUse":["ONE tool's parameters and schema - use ek9_query_tool_detail (cheaper; takes a name or an intent phrase).","One named workflow's step sequence - use ek9_query_workflow.","Re-fetching mid-session - it does not change; reuse the cached response."],"details":"Pure static read of the in-process McpToolRegistry - no workspace coupling. verbosity: 'none' (default) = names + counts; 'summary' = the slim catalogue (first-sentence descriptions, categoryRules, idePrecedent / rules / workflows when present - OMITTED when absent, so use property-presence); 'full' = with inputSchema. includeSchemas:true lifts any level to 'full'. category narrows to one of enquiry / editor / execution - the only way schemas fit under the 128 KB ceiling. The JSON field is 'rules'; toolCount is emitted at the top and per category. CLI parity: ek9 -h -E8 (slim) / ek9 -h -E7 (full).","arguments":[{"name":"category","type":"string: enquiry | editor | execution","required":false,"description":"Only this category's section"},{"name":"includeSchemas","type":"boolean","required":false,"description":"Include the JSON Schema for every tool (lifts verbosity to 'full'). Default false."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size: 'none' (default) = names + counts (~4K); 'summary' = the slim catalogue with descriptions, rules and workflows; 'full' = with every tool's JSON schema."}],"lessons":["https://ek9.io/ide/asking-the-ide.html"],"fixes":[],"example":{"scenario":"Catalogue names default","request":{},"response":{"categories":{"editor":{"toolCount":75,"toolNames":["ek9_write_file","ek9_delete_file","ek9_delete_directory","ek9_move_file","ek9_rename_file","ek9_edit_file","ek9_new_construct","ek9_remove_statements","ek9_remove_comments","ek9_insert_statements","ek9_create_dynamic_function","ek9_create_dynamic_class","ek9_add_field","ek9_rename_field","ek9_remove_field","ek9_introduce_field","ek9_introduce_parameter","ek9_safe_delete","ek9_extract_method","ek9_extract_variable","ek9_extract_constant","ek9_promote_to_constant","ek9_organize_constants","ek9_create_requirement","ek9_update_requirement","ek9_inline_variable","ek9_inline_function","ek9_rename_symbol","ek9_change_signature","ek9_fix_purity_contract","ek9_change_visibility","ek9_make_open","ek9_make_closed","ek9_make_abstract","ek9_make_concrete","ek9_seal_type","ek9_unseal_type","ek9_add_to_sealed_allowlist","ek9_add_method","ek9_add_route","ek9_add_application","ek9_add_program","ek9_anchor_test","ek9_apply_symbolic_fix","ek9_apply_guard_pattern","ek9_add_constructor","ek9_convert_constructor","ek9_add_operator","ek9_collapse_to_default_operator","ek9_expand_default_operator","ek9_adopt_trait","ek9_implement_methods","ek9_generate_delegation","ek9_generate_dispatcher","ek9_prune_empty_sources","ek9_rewrite_string_concat","ek9_insert_coalescing","ek9_surround_with","ek9_move_construct","ek9_pull_up","ek9_push_down","ek9_extract_trait","ek9_toggle_block_comment","ek9_format","ek9_edit_localized_text","ek9_extract_to_localized_text","ek9_organize_localized_text","ek9_organize_references","ek9_sync_references","ek9_add_dependency","ek9_remove_dependency","ek9_exclude_transitive_dependency","ek9_remove_transitive_exclusion","ek9_add_capability","ek9_remove_capability"]},"enquiry":{"toolCount":77,"toolNames":["ek9_version","ek9_help","ek9_explain_error","ek9_paradigm","ek9_ask","ek9_query_tool_catalogue","ek9_query_tool_detail","ek9_query_workflow","ek9_list_workflows","ek9_query_metric_limits","ek9_read_construct","ek9_read_file","ek9_search_text","ek9_list_files","ek9_check_requirements","ek9_query_requirement","ek9_render_specification","ek9_find_unused_code","ek9_find_inline_candidates","ek9_query_translation_completeness","ek9_git_status","ek9_git_diff","ek9_git_log","ek9_git_blame","ek9_git_branch","ek9_check_package_dependency_cycles","ek9_query_package_version","ek9_query_package","ek9_query_name_clashes","ek9_inspect_symbol_at_cursor","ek9_list_visible_symbols","ek9_query_complexity","ek9_query_construct","ek9_query_flow","ek9_advise_loop","ek9_verify_method","ek9_query_module","ek9_query_pipeline","ek9_query_workspace","ek9_query_classes","ek9_query_records","ek9_query_traits","ek9_query_components","ek9_query_constrained_types","ek9_query_functions","ek9_query_programs","ek9_query_enumerations","ek9_query_localisations","ek9_query_env_vars","ek9_query_capability_usage","ek9_query_sensitive_reveals","ek9_query_service_routes","ek9_query_diagnostics","ek9_query_effective_api","ek9_query_type_hierarchy","ek9_query_references","ek9_query_dispatchers","ek9_query_build_status","ek9_query_call_graph","ek9_find_constructs_by_name","ek9_find_symbols","ek9_query_dependency_injection","ek9_query_module_dependencies","ek9_query_module_landscape","ek9_query_module_coupling","ek9_query_module_cohesion","ek9_query_construct_neighbourhood","ek9_query_purity_impact","ek9_query_data_touch","ek9_query_mutex_payload","ek9_query_signature_impact","ek9_check_module_cycles","ek9_query_dependency_tree","ek9_query_lock_analysis","ek9_query_deadlock_chain","ek9_query_enter_sites","ek9_query_lock_identity"]},"execution":{"toolCount":29,"toolNames":["ek9_compile","ek9_clean","ek9_run_tests","ek9_run_quality_checks","ek9_generate_edge_case_tests","ek9_git_init","ek9_git_add","ek9_git_commit","ek9_git_push","ek9_git_switch","ek9_git_merge","ek9_git_restore","ek9_git_revert","ek9_git_fetch","ek9_git_pull","ek9_git_stash","ek9_package","ek9_install_package","ek9_deploy_package","ek9_generate_signing_keys","ek9_set_version","ek9_set_feature_version","ek9_increment_version","ek9_resolve_dependencies","ek9_run_program","ek9_debug_session","ek9_debug_control","ek9_debug_inspect","ek9_debug_observe"]}},"meta":{"serverMs":"<timing>"},"nextStep":"ek9_query_tool_detail tool:'<name>' for one tool's parameters; verbosity:'summary' here for every tool's description, rules and IDE precedent; ek9_query_workflow name:'<workflow>' for a step sequence.","status":"ok","toolCount":181,"workflowCount":4,"workflowNames":["release","feature_branch_start","investigate_build_failure","investigate_runtime_defect"]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_tool_detail","url":"https://ek9.io/mcp/ek9_query_tool_detail.html","category":"enquiry","description":"Returns one tool's entry - status, match (exact|single|ambiguous|none), then whenToUse, whenNotToUse, description, examples and inputSchema - by name, intent phrase or the error code it remediates.","whenToUse":"'How do I call ek9_x / which tool does Y' is one call with tool:'ek9_x' or an intent phrase ('find a class by name'). Pass errorCode:'E11066' instead for the tool that remediates a diagnostic; the answer is its when-to-use, parameters and schema before you invoke it.","whenNotToUse":["The whole tool inventory - use ek9_query_tool_catalogue.","A named tool SEQUENCE (release, feature_branch_start) - use ek9_query_workflow.","An error code's diagnosis rather than its remediating tool - use ek9_explain_error."],"details":"Branch on match: 'exact' (a registered name, before or after normalisation - lower case, 'ek9 '/'ek9_' stripped, spaces to '_') and 'single' (fuzzy winner: top score >= 1.5x the runner-up, the sole candidate, or the one tool whose name tokens all appear in the phrase) carry the full tool object; 'ambiguous' carries ranked candidates[] without schemas; 'none' is status:not-found with nextStep. verbosity: 'full' (default) = the JSON schema; 'summary' = parameters[] (name, type, required, enum); 'none' = name, whenToUse, description only. idePrecedent / rules / workflows are omitted when empty. Static read of the in-process registry + BM25F index - works before any user code is parsed.","arguments":[{"name":"errorCode","type":"string","required":false,"description":"An EK9 error code (E11066): answers with the tool mapped to remediate it, never a fuzzy guess"},{"name":"tool","type":"string","required":false,"description":"Tool name ('ek9_query_construct', 'query construct') or an intent phrase ('find a class by name')"},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size: 'full' (default) = the JSON schema; 'summary' = parameters[] with name/type/required/enum; 'none' = name, whenToUse, description."}],"lessons":[],"fixes":[],"example":{"scenario":"Phrase with repeated word","request":{"tool":"extract a statement range into a new pure function with explicit parameters and return, then replace the block with a call"},"response":{"candidates":[{"description":"Inserts the new method (parameters and return inferred from variable data-flow) and replaces the block with a call to it; answers status, edits[] and summary, an ambiguous or boundary-crossing block as conflicts[].","name":"ek9_extract_method","score":17.852444444012846},{"description":"Rewrites the declaration and EVERY call site atomically (add / remove / reorder parameters, change the return type, toggle 'as pure'); answers status, edits[] and summary with the call-site count, a blocking call site as conflicts[] (callsite-incompatible-with-new-signature).","name":"ek9_change_signature","score":12.916106476475791},{"description":"Folds a contiguous line range under an if / if-else / try-catch / try-catch-finally / for-range / while / switch head, re-indenting the block per EK9's brace-free rules; answers status and edits[] (one REPLACE carrying the head + the re-indented lines, one DELETE per absorbed line).","name":"ek9_surround_with","score":9.436655014487078},{"description":"Appends a new parameter to the enclosing method/function, replaces the selected in-body expression with it and passes the ORIGINAL expression at every call site (Fowler \"Introduce Parameter\"); answers status, edits[] and conflicts[] (value-expression-not-a-single-expression, type-not-inferable, ...).","name":"ek9_introduce_parameter","score":7.640907449210905},{"description":"Splices EK9 statement(s) into a named method/function/operator body at anchor top, bottom, replace or a body line, re-indented by the tool; answers status, edits[] (one INSERT), insertedLineRange and resultingBodySnippet, or error.problems[] naming the entry that does not parse.","name":"ek9_insert_statements","score":7.536982906982008}],"match":"ambiguous","meta":{"serverMs":"<timing>"},"note":"Several tools fit 'extract a statement range into a new pure function with explicit parameters and return, then replace the block with a call' - re-query with tool:'<one of candidates[].name>'.","status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_traits","url":"https://ek9.io/mcp/ek9_query_traits.html","category":"enquiry","description":"Answers first: status, implementedByAll (when asked), traitCount, traitNames - complete for the workspace or the filters given - then traits[] {name, module, file, line, traitOf, implementedBy, implementedByCount, methods, methodCount}.","whenToUse":"'Which traits exist, and is there a contract I can adopt' is one call - no arguments for the workspace, nameFilter / methodNameFilter / moduleFilter to narrow.","whenNotToUse":["concrete classes (use ek9_query_classes)","data shapes (use ek9_query_records)","a trait's depth-by-depth implementer graph (ek9_query_type_hierarchy with symbol:'TraitName'); the implementers themselves come back here as implementedBy","a trait's full source (use ek9_read_construct)"],"details":"nameFilter/methodNameFilter are plain case-insensitive substrings (not regex), moduleFilter an exact module-name allow-list; built-in org.ek9.* traits are excluded. status is ok (traits returned) / empty (no match — meta.unmatchedFilters[] lists any moduleFilter values naming non-existent modules as module:<value>) / not-compiled (no compiled program — run ek9_compile first). traitOf lists only directly-declared super-traits (with trait of ...); methods[] are EK9-syntax signatures capped at 8, including the synthesized operator ?; unresolved types render as <unresolved>. implementedBy is every construct carrying the trait workspace-wide - classes, traits that extend it, and types that get it through a sub-trait or a superclass - nothing to verify; records and components cannot carry traits, and a dynamic class inside a function body is not listed. implementedByAll names traits exactly (bare or module::Name) and intersects their implementedBy; a name that names no trait is in meta.unmatchedFilters[] as trait:<value>, with meta.didYouMean naming the traits that contain it.","arguments":[{"name":"implementedByAll","type":"array of string","required":false,"description":"Trait names (exact, bare or module::Name). Answers implementedByAll: the constructs that carry EVERY one of them, transitively."},{"name":"includeMethodSummary","type":"boolean","required":false,"description":"Default true. When true each entry includes methods[] (the contract signatures). Set false for a lighter response."},{"name":"methodNameFilter","type":"string","required":false,"description":"Filter to traits declaring a method whose name matches (case-insensitive substring)."},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to specific modules (exact names). Default: workspace-wide."},{"name":"nameFilter","type":"string","required":false,"description":"Case-insensitive substring match on trait names."}],"lessons":[],"fixes":[],"example":{"scenario":"List all","request":{},"response":{"meta":{"serverMs":"<timing>"},"status":"ok","summary":{"moduleCount":1},"traitCount":2,"traitNames":["Identifiable","Describable"],"traits":[{"file":"contracts.ek9","implementedBy":[],"implementedByCount":0,"line":6,"methodCount":2,"methods":["identity()\n  <- rtn as String","operator ?\n  <- rtn as Boolean"],"module":"com.example.contracts","name":"Identifiable","traitOf":[]},{"file":"contracts.ek9","implementedBy":[],"implementedByCount":0,"line":10,"methodCount":2,"methods":["describe()\n  <- rtn as String","operator ?\n  <- rtn as Boolean"],"module":"com.example.contracts","name":"Describable","traitOf":[]}]}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_translation_completeness","url":"https://ek9.io/mcp/ek9_query_translation_completeness.html","category":"enquiry","description":"Answers status, translationDebtCount and translationDebt[] (every {textType, locale, method} still needing translation) first, then the per-(text type, locale, method) status grid (translated | stubbed | missing-error) and summary totals - the whole module, nothing to verify.","whenToUse":"'What still needs translating?' is one call: {} lists every {textType, locale, method} still placeholder-stubbed in the module's i18n text, no file needed.","whenNotToUse":["You just wrote via ek9_edit_localized_text and its response already carries translationDebt[] - re-querying is redundant.","You want full method bodies, not just status — use ek9_query_construct on the text type.","You want to grep the literal placeholder marker text — use ek9_search_text; this tool returns structured status, not raw matches.","You need to CLEAR an orphaned //AI: marker whose body is already translated — feed the method's placeholderMarker line to ek9_remove_comments."],"details":"Method status: `translated`, `stubbed` (the marker comment above the body matches placeholderPattern — the body literal is NOT the discriminator, an empty \"\" body alone is not stubbed), or `missing-error` (E07150: method exists in other locales but not this one — transient mid-edit, 0 in a clean workspace). Text-type-per-locale status: complete / partial / stubbed / missing-incomplete / absent-by-design (a text type validly living in only some locales — excluded from percent denominators). translationDebt[] is {textType, locale, method, params} in that field order, LOCKED identical to ek9_edit_localized_text; unknown filter names surface in warnings[] and are skipped, not errored.","arguments":[{"name":"includeMethodBodies","type":"boolean","required":false,"description":"When true, each method entry includes its current body (truncated to 200 chars)."},{"name":"localeFilter","type":"array of string","required":false,"description":"Limit results to specific locales. Default: all locales discovered in the module."},{"name":"module","type":"string","required":false,"description":"The module to operate on. Default: the first module that defines any text type; supply it when several modules carry i18n."},{"name":"placeholderPattern","type":"string","required":false,"description":"Marker-detection regex applied to trimmed source lines. Default: literal match for `//AI: translate the message` (the marker emitted by LocalizedTextWriter)."},{"name":"textTypeFilter","type":"array of string","required":false,"description":"Limit results to specific text type names. Default: all text types in the module."}],"lessons":["https://ek9.io/ide/localisations.html"],"fixes":[],"example":{"scenario":"Completeness shape","request":{},"response":{"locales":["de","en_GB"],"meta":{"serverMs":"<timing>"},"module":"com.example.i18n","status":"ok","summary":{"localeCount":2,"methodPairCount":2,"missingMethodCount":0,"perLocale":{"de":{"missingMethod":0,"percentTranslated":100.0,"stubbed":0,"translated":1},"en_GB":{"missingMethod":0,"percentTranslated":100.0,"stubbed":0,"translated":1}},"percentTranslated":100.0,"stubbedCount":0,"textTypeCount":1,"translatedCount":2},"textTypes":[{"locales":{"de":{"methods":[{"location":{"file":"text.ek9","line":11},"name":"mainWelcome","params":[],"status":"translated"}],"status":"complete"},"en_GB":{"methods":[{"location":{"file":"text.ek9","line":6},"name":"mainWelcome","params":[],"status":"translated"}],"status":"complete"}},"name":"WelcomePageText"}],"translationDebt":[],"translationDebtCount":0}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_type_hierarchy","url":"https://ek9.io/mcp/ek9_query_type_hierarchy.html","category":"enquiry","description":"Answers first: subtypeNames (implementedBy on a trait), superNames, traitNames, allowedSubtypes for a sealed trait - complete workspace-wide - then the full graph.","whenToUse":"'Who extends or implements X, and what does X extend' is one call with symbol:'X' - no file needed; file + line only from an IDE cursor.","whenNotToUse":["the methods/operators callable on the type, not its ancestry (use ek9_query_effective_api)","the structure (own fields/methods) of ONE construct, not the inheritance chain (use ek9_query_construct)","details of a single symbol under the cursor, not the whole tree (use ek9_inspect_symbol_at_cursor)","the API of a BUILT-IN language type (String, List, …) (use ek9_help; this tool only walks workspace types)"],"details":"Hierarchy queries are meaningful only for CLASS, TRAIT, RECORD, COMPONENT; SERVICE/APPLICATION/PROGRAM/ENUMERATION return basic info with empty superChain/subtypes, and a location resolving to no aggregate type returns status:'not-found'. Two depth metrics: root-level `depth` is distance from the inheritance root DOWN to the queried type; each subtype's `depth` is distance FROM the queried type (1=direct child). `subtypes` holds ALL transitive descendants (counted by subtypeCount/summary.totalDescendants; summary.directSubtypes counts depth 1 only), plus isOpen (always) and, when applicable, transitive allTraits, sealed/allowedSubtypes/exhaustive, and generic markers.","arguments":[{"name":"among","type":"array of string","required":false,"description":"Names to answer FOR: 'which of these ...' - the name lists shrink to these and amongUnmatched names the ones that are not in the answer. Bare names, 'mod::Type' or 'Type.member'; a MODULE name stands for every construct in it ('which in scale.m07 do not ...' = amongUnmatched)."},{"name":"column","type":"integer","required":false,"description":"0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/own-generics.html","https://ek9.io/ide/book-generics.html","https://ek9.io/ide/type-hierarchy.html"],"fixes":["E05030","E05240","E05250"],"example":{"scenario":"Type hierarchy shape","request":{"file":"MyRecord.ek9","line":5},"response":{"declaredAt":{"file":"MyRecord.ek9","line":5},"depth":1,"fullyQualifiedName":"com.example::MyRecord","genus":"RECORD","isOpen":false,"meta":{"serverMs":"<timing>"},"name":"MyRecord","status":"ok","subtypeCount":0,"subtypeNames":[],"subtypeNamesCover":"every descendant workspace-wide, direct and indirect - nothing to verify","subtypes":[],"summary":{"directSubtypes":0,"superDepth":1,"totalDescendants":0,"traitCount":0},"superChain":[{"declaredAt":{"file":"org-ek9-lang.ek9","line":6},"fullyQualifiedName":"org.ek9.lang::Any","genus":"ANY","isOpen":true,"name":"Any"}],"superNames":["Any"],"traitNames":[],"traits":[],"type":"MyRecord"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_workflow","url":"https://ek9.io/mcp/ek9_query_workflow.html","category":"enquiry","description":"Returns one named multi-tool workflow's ordered steps (tool + one-line reason each), or with no name every workflow with workflowNames first.","whenToUse":"'What are the steps of the release workflow' is one call with name:'release' - the ordered tool sequence with a reason per step. Omit name for every workflow (workflowNames first).","whenNotToUse":["The tool inventory rather than the named sequences - use ek9_query_tool_catalogue.","ONE tool's parameters - use ek9_query_tool_detail."],"details":"Reads the in-process static workflow registry - no coupling to workspace compile state, works from any phase. Exact name match only (the names are in workflowNames). A workflow is a recipe, not an executable: walk sequence[] in order, calling each step's tool and handling its failure before the next; every step names a registered tool.","arguments":[{"name":"name","type":"string","required":false,"description":"Workflow name (e.g. 'release'); omit for every workflow"}],"lessons":[],"fixes":[],"example":{"scenario":"Release workflow shape","request":{"name":"release"},"response":{"match":"exact","meta":{"serverMs":"<timing>"},"name":"release","sequence":[{"reason":"Bump the appropriate version part (typically patch after a fix).","tool":"ek9_increment_version"},{"reason":"Verify nothing regressed; produces the coverage report as a side effect.","tool":"ek9_run_tests"},{"reason":"Run full quality checks — coverage, complexity, readability, DI — to confirm nothing has degraded since the last release.","tool":"ek9_run_quality_checks"},{"reason":"Build the deployable artefact at the new version.","tool":"ek9_package"},{"reason":"Install into ~/.ek9/lib so sibling workspaces can pick it up.","tool":"ek9_install_package"},{"reason":"Verify the installed version matches what was bumped.","tool":"ek9_query_package_version"}],"status":"ok","summary":"Bump version + run tests with coverage + build artefact + install locally + verify."}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_query_workspace","url":"https://ek9.io/mcp/ek9_query_workspace.html","category":"enquiry","description":"Answers first: status, moduleCount, moduleNames, constructCount, then modules[] {name, constructCount, constructs[] {name, category, genus}}; verbosity:'none' lists modules only, 'full' adds per-construct detail.","whenToUse":"'What is in this workspace - every module and what each declares' is one call with no arguments; moduleFilter:['com.acme.*'] narrows it.","whenNotToUse":["one module's contents anchored by a file (use ek9_query_module)","locating a single named construct, not enumerating the workspace (use ek9_find_constructs_by_name)","the module dependency graph rather than the inventory (use ek9_query_module_dependencies)","a built-in type's API (use ek9_help; includeBuiltins only lists org.ek9.lang constructs, it does not document them)"],"details":"verbosity selects the shape: none = module names + sourceCount only; summary (default) = adds each module's public constructs as {name, category, genus} plus constructCount; full = further adds line, memberCount and a modifiers array (open/abstract/extern) on aggregate constructs. moduleFilter is exact names, '*' suffix for a prefix; includeBuiltins defaults false (user code only).","arguments":[{"name":"includeBuiltins","type":"boolean","required":false,"description":"Whether to include org.ek9.lang built-in modules (default false)"},{"name":"moduleFilter","type":"array of string","required":false,"description":"Restrict to these modules - exact names; an entry ending in '*' is a prefix ('com.acme.*'). A single string is accepted. Omit for workspace-wide."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"none = module names + sourceCount; summary (default) = each module's constructs as {name, category, genus}; full = adds line, memberCount and modifiers per construct."}],"lessons":[],"fixes":[],"example":{"scenario":"Workspace shape","request":{},"response":{"constructCount":1,"meta":{"serverMs":"<timing>"},"moduleCount":1,"moduleNames":["com.example"],"modules":[{"constructCount":1,"constructs":[{"category":"TYPE","genus":"RECORD","name":"MyRecord"}],"name":"com.example"}],"status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_read_construct","url":"https://ek9.io/mcp/ek9_read_construct.html","category":"enquiry","description":"Answers first: source.text with source.file/startLine/endLine from the compiled symbol-table boundaries (no line guessing), construct {name, fullyQualifiedName, kind}, members[{name, kind, signature, startLine, endLine, compilerMade?}] (a program has none) and source.contentHash.","whenToUse":"You want the source text of one construct or member - one call with symbol:'Shape', 'mod::Shape', 'Shape.computeTotal' or 'Shape.?'; no file or line needed. Anchor file + line only from an IDE cursor.","whenNotToUse":["The WHOLE file, not one construct - use ek9_read_file (path).","Structure only, no bodies — use ek9_query_construct (declared members/signatures; cheaper) or ek9_query_effective_api (full visible set incl. inherited/trait/defaulted).","Semantic info (type, set/unset state, mutability) at a cursor, not source text — use ek9_inspect_symbol_at_cursor.","Keyword search across the workspace — use ek9_search_text."],"details":"Ambiguity is keyed on the DEFINING module only — a construct reachable via a references block is not a second definition; when a name is declared in several modules the refusal lists them and the qualified form ('mod::Name') picks one. An overloaded member name returns EVERY overload (scope:'overloads', each with its signature and source); a dispatcher's name returns its entry point; 'Shape.render(Circle)' returns that overload alone. source.contentHash is the whole file's hash for expectedContentHash on ek9_edit_file. Requires the workspace compiled (ek9_compile) at least to symbols_defined; types_resolved gives reliable signatures.","arguments":[{"name":"file","type":"string","required":false,"description":"IDE cursor form: the .ek9 file (workspace-relative or absolute inside the workspace). OPTIONAL - a symbol alone finds its file."},{"name":"includeBody","type":"boolean","required":false,"description":"When false, returns signatures only: each declaration's line and its '->' / '<-' lines (a typed return up to its initialiser), no bodies."},{"name":"line","type":"integer","required":false,"description":"1-based line anywhere inside the target with file - OMIT it and pass symbol:'<name>' instead (a model counting lines miscounts)."},{"name":"lineNumbers","type":"boolean","required":false,"description":"When true, each line of source.text is prefixed 'N| ' (the ek9_read_file form). Default false - source.startLine/endLine already anchor the slice."},{"name":"memberName","type":"string","required":false,"description":"Narrows a bare construct symbol to ONE member (method / operator / constructor / field name; operators by symbol: ?, <=>, $). 'Shape.member' says the same in one key."},{"name":"module","type":"string","required":false,"description":"Exact module name that picks one declaration when symbol is a bare name declared in several modules; 'mod::Shape' says the same in one key."},{"name":"symbol","type":"string","required":false,"description":"The construct or member: 'Shape' | 'mod::Shape' (when the name is declared in several modules) | 'Shape.computeTotal' | 'Shape.?' (an operator by its EK9 symbol). No file or line needed. With file, the identifier to anchor on there."}],"lessons":[],"fixes":[],"example":{"scenario":"Built in type member","request":{"symbol":"String.first"},"response":{"error":{"kind":"built-in-type","message":"'String' is a built-in EK9 type - it has no source to read"},"meta":{"serverMs":"<timing>"},"nextStep":"ek9_help 'String' lists its constructors, methods and operators - including first; ek9_query_effective_api does the same for a type in this workspace.","status":"not-found"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_read_file","url":"https://ek9.io/mcp/ek9_read_file.html","category":"enquiry","description":"Answers first: content (numbered 'N| ' when lineNumbers:true), contentHash for expectedContentHash, and for .ek9 the structure outline {module, constructs[{kind,name,startLine,endLine,signature}]} - whole file up to 2,000 lines, truncated:true first when cut.","whenToUse":"You know the file path and want its text - one call with path:'orders.ek9'; add lineNumbers:true before any line-anchored edit, startLine/endLine for a slice. The .ek9 structure outline comes free, so you can plan navigation without reading the body.","whenNotToUse":["A SEMANTIC change - go straight to the editor with symbol:'<name>' (ek9_add_method, ek9_change_signature, ek9_rename_symbol, ...), no read first; a TEXT edit anchored on lines - read WITH lineNumbers:true first and quote those numbers into ek9_edit_file.","You know the construct name but NOT the file path — use ek9_read_construct (symbol:'Name').","You want a focused single-construct slice, not the whole file — use ek9_read_construct.","Searching or browsing rather than reading a known file — ek9_search_text (keyword search), ek9_list_files (directory listing), ek9_query_workspace (structure overview without file content)."],"details":"structure.constructs[].kind is the EK9 word for the construct (class/trait/record/enumeration/constrained-type/function/abstract-function/program/component/service/application/constant/text; dispatchers are just class); non-.ek9 files report the detected language (markdown/json/java/yaml/xml/properties/plaintext) with no structure. The raw read ignores compile success, but the workspace must be initialized via ek9_compile, and the .ek9 overlay needs a compiled workspace (else a degraded-provider warning; raw content still returned). contentHash is the value to pass as expectedContentHash to ek9_write_file / ek9_edit_file. A file over 2,000 lines is cut at 2,000 with truncated:true first and the startLine/endLine call that restores the rest. Hard errors: no workspace roots, path outside workspace (security), not found, directory (use ek9_list_files), binary, invalid range (start>end).","arguments":[{"name":"endLine","type":"integer","required":false,"description":"1-based last line of a slice (inclusive); clamped to the file's lineCount with a range-clamped warning."},{"name":"includeStructure","type":"boolean","required":false,"description":"When true (default), .ek9 files include the structure outline {module, constructs[{kind,name,startLine,endLine,signature}]}. Ignored for non-EK9 files."},{"name":"lineNumbers","type":"boolean","required":false,"description":"When true, 'content' is returned with each line prefixed by its 1-based number ('15| sayHello() as pure'). Use it before ANY line-anchored call (edit_file line-replace, remove_statements, a 'line' argument) - counting lines in raw text miscounts. For the symbol tools prefer symbol:'<name>' and no line at all."},{"name":"path","type":"string","required":true,"description":"File path: workspace-relative (preferred) or absolute inside the workspace. Must exist and be a text file."},{"name":"range","type":"object","required":false,"description":"IDE alias for the flat startLine/endLine pair: {\"startLine\": 100, \"endLine\": 200}."},{"name":"startLine","type":"integer","required":false,"description":"1-based first line of a slice (inclusive). With endLine; omit both for the whole file (capped at 2,000 lines)."}],"lessons":[],"fixes":[],"example":{"scenario":"Read with line numbers","request":{"includeStructure":false,"lineNumbers":true,"path":"MyRecord.ek9"},"response":{"byteCount":125,"content":"1| #!ek9\n2| defines module com.example\n3| \n4|   defines record\n5|     MyRecord\n6|       name as String: String()\n7|       default operator\n8| \n9| //EOF\n10| ","contentHash":"sha256:7f5d05c57b329129ca15e7987b5459766b0b8be769d09ca971ed9e360e492d29","encoding":"UTF-8","language":"ek9","lastModified":"<timing>","lineCount":9,"lineNumbers":true,"meta":{"serverMs":"<timing>"},"path":"MyRecord.ek9","status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_remove_capability","url":"https://ek9.io/mcp/ek9_remove_capability.html","category":"editor","description":"Answers with the edit that revokes one gated-type capability from the 'capabilities <- [...]' List of a 'defines package' block, plus the resolved capability name.","whenToUse":"'This package no longer needs TCP' is one call with file:'package.ek9' and capability:'TCP'. The full 'org.ek9.lang::TCP' is accepted too; revoke a declared capability the code stopped using.","whenNotToUse":["Declaring a capability - use ek9_add_capability.","Checking whether the gated type is still referenced before revoking - use ek9_query_capability_usage (this tool performs no usage scan).","Removing a library dependency - use ek9_remove_dependency."],"details":"Preserves the List's single-/multi-line form. Removing the LAST entry is a real decision: an empty List literal is a parse error, so the whole declaration must go, and without a capabilities declaration the package is no longer publishable-enforced - hence the removeListIfEmpty gate (default false -> conflict 'would-empty-capabilities-list'). conflicts[].kind 'capability-not-declared' lists the existing entries. If the gated type is still used the next compile fires E12010 (no usage scan here); enforcement applies only to publishable packages (publicAccess + version + license + capabilities all declared).","arguments":[{"name":"capability","type":"string","required":true,"description":"The gated type to revoke: a bare name such as 'TCP' (resolved to org.ek9.lang::TCP) or the fully-qualified name - matched against the capabilities List entries."},{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"removeListIfEmpty","type":"boolean","required":false,"description":"True allows removing the LAST entry, which drops the whole 'capabilities <- [...]' declaration (an empty List literal is a parse error) and switches capability enforcement off for the package. False (default) refuses that case with conflict 'would-empty-capabilities-list'."}],"lessons":["https://ek9.io/ide/capabilities.html"],"fixes":[],"example":{"scenario":"Remove capability empties with flag","request":{"capability":"org.ek9.lang::Stdout","file":"package.ek9","removeListIfEmpty":true},"response":{"capability":"org.ek9.lang::Stdout","conflicts":[],"edits":[{"before":"    capabilities <- [\"org.ek9.lang::Stdout\"]","endLine":9,"file":"package.ek9","startLine":9,"type":"delete"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Removed org.ek9.lang::Stdout; removed now-empty capabilities declaration","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_remove_comments","url":"https://ek9.io/mcp/ek9_remove_comments.html","category":"editor","description":"Deletes one whole-line comment block (//, <!- -!>, <!-- --> or <?- -?>) in full; answers status and edits[] (one DELETE per line), or conflicts[] (kind 'comment-shares-line-with-code') when a boundary line also carries code.","whenToUse":"'Drop the //AI: comment in orders.ek9' is one call with file + symbol:'AI' (a word from the comment) or line (any line inside it) - the tool expands to the whole block. Use it on a stale whole-line comment: an acted-on instruction, or a <?- -?>/<!- -!> block whose target was removed.","whenNotToUse":["Removing CODE statements, not comments - use ek9_remove_statements (comments live on the HIDDEN ANTLR channel that remove_statements does not touch).","Stripping a TRAILING comment from a code-bearing line (e.g. `x <- 10 //note`) — V1 refuses with comment-shares-line-with-code; use ek9_edit_file line-replace.","Removing many comments at once or reshaping the file beyond comment removal — use ek9_write_file (overwrite) as the read+rewrite escape hatch."],"details":"summary names the comment form removed: line-comment / block-comment / block-comment-html / doc-comment; edits are one DELETE per resolved line. A comment whose first or last line also carries code outside the delimiters returns status:'conflicts' (kind comment-shares-line-with-code).","arguments":[{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 source file containing the comment."},{"name":"line","type":"integer","required":false,"description":"Any 1-based line inside the comment - the tool expands to the full extent of the block via the ANTLR token stream. OMIT it and pass symbol:'<word>' to let the tool find the line."},{"name":"symbol","type":"string","required":false,"description":"A word from the comment's text (e.g. 'AI' from '//AI: ...'); the first line carrying it as a whole word anchors the call. Pass line instead when the word also occurs in code."}],"lessons":["https://ek9.io/ide/comments-and-format.html"],"fixes":[],"example":{"scenario":"Remove line comment apply","request":{"file":"Hello.ek9","line":6},"response":{"conflicts":[],"edits":[{"before":"      // drop me","endLine":6,"file":"Hello.ek9","startLine":6,"type":"delete"}],"meta":{"serverMs":"<timing>"},"resolvedPath":"<workspace-root>/Hello.ek9","risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Removed line-comment on line 6","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_remove_dependency","url":"https://ek9.io/mcp/ek9_remove_dependency.html","category":"editor","description":"Answers with the edit that deletes one entry from the deps or devDeps Dict of a 'defines package' block (the whole Dict when it was the last entry).","whenToUse":"'Drop the dependency on ek9open.net.handy.tools' is one call with file:'package.ek9', bucket:'deps' (or 'devDeps') and module:'ek9open.net.handy.tools'.","whenNotToUse":["Adding a dependency - use ek9_add_dependency.","Lifting a transitive EXCLUSION - use ek9_remove_transitive_exclusion.","Removing a capability declaration - use ek9_remove_capability.","The module is a transitive, not a direct deps/devDeps entry - use ek9_exclude_transitive_dependency to stop the pull-in."],"details":"An emptied bucket's whole 'bucket <- { ... }' declaration is removed (EK9 forbids an empty Dict) and the summary says so - there is no flag either way. Only the multi-line Dict form is edited (a single-line bucket is error 'single-line-bucket-unsupported'); an unknown module conflicts with 'dependency-not-declared' listing the bucket's keys. Edits the source only - chain ek9_resolve_dependencies to clean the local cache; the dry run performs no scratch compile, so a reference-breaking removal is caught by the post-apply verify.","arguments":[{"name":"bucket","type":"string: deps | devDeps","required":true,"description":"Which Dict to remove from: 'deps' (runtime, deployed) or 'devDeps' (dev/test only, not deployed)."},{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"module","type":"string","required":true,"description":"The dependency's module name to remove, e.g. 'ek9open.network.support.utils' - matched against the Dict key."}],"lessons":["https://ek9.io/ide/package-block.html"],"fixes":[],"example":{"scenario":"Remove dependency not declared","request":{"bucket":"deps","file":"package.ek9","module":"ek9open.never.declared.here"},"response":{"conflicts":[{"description":"ek9open.never.declared.here is not declared in deps; existing keys: [ek9open.network.support.utils, ek9open.net.handy.tools]","file":"package.ek9","kind":"dependency-not-declared"}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"ek9open.never.declared.here is not declared in deps; existing keys: [ek9open.network.support.utils, ek9open.net.handy.tools]","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_remove_field","url":"https://ek9.io/mcp/ek9_remove_field.html","category":"editor","description":"Deletes a field from a class/record/component; answers status and edits[] (one DELETE), or conflicts[] with every in-body reference classified by 'kind' and a suggestedRepair for the mechanical ones.","whenToUse":"'Remove the field spare from Greeter' is one call with symbol:'Greeter.spare' - no file or line needed. Use it when a class/record/component field is dead, redundant or being collapsed; the tool walks the owning construct's body and deletes it or reports the blocking reference sites.","whenNotToUse":["Deleting a method, type, function or any symbol whose uses cross files - use ek9_safe_delete (the workspace-wide superset; it deletes fields too).","Keeping the field but changing its name — use ek9_rename_field instead."],"details":"Each conflict carries a 'kind': boolean-chain-term / format-string-interpolation / constructor-param are mechanically repairable (constructor-param repairs cascade to callers in other files); expression-operand is the ESCALATION kind — semantics change, ask the human. The server re-walks the construct body on every call, so re-call after repairs rather than self-judging completion; there is no force flag — the conflicts list dominates. Default operators on the construct (<=>, ?, $, #?, ...) never block removal but surface a wouldAutoDerive[] note — derived identity/equality/string form shifts silently, so warn the human.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"memberName","type":"string","required":false,"description":"Field to remove. Must exist on the construct (omit when symbol is 'Type.field')."},{"name":"symbol","type":"string","required":true,"description":"The construct that owns the field ('Greeter'), or the field itself as 'Greeter.spare' (then memberName may be omitted) - found workspace-wide, no file needed."}],"lessons":["https://ek9.io/ide/remove-field.html"],"fixes":[],"example":{"scenario":"Remove unreferenced field apply","request":{"constructName":"Greeter","fieldName":"spare","file":"Greeter.ek9"},"response":{"conflicts":[],"edits":[{"before":"      spare as Integer: 0","endLine":7,"file":"Greeter.ek9","startLine":7,"type":"delete"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Removed spare from Greeter (1 edit)","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_remove_statements","url":"https://ek9.io/mcp/ek9_remove_statements.html","category":"editor","description":"Deletes a contiguous statement range from one method/function/operator body; answers status and edits[] (one DELETE per line), or conflicts[] (range-straddles-method-boundary, range-not-on-statement-boundary, removed-statement-declares-used-local, removal-is-a-replacement, range-empties-body).","whenToUse":"'Delete these two statements inside the body' is one call with file, fromText and toText (the first and last line as written), or startLine:36, endLine:37 - the range must sit inside ONE method/function/operator body on statement boundaries. Use it to drop specific statements without a read + full-text rewrite (the second tool in a force-delete cleanup loop).","whenNotToUse":["Removing an unused entry from the references block (not body statements) - use ek9_organize_references (often run AFTER this tool).","Removing the `<- rtn` return-value declaration (a signature change) - use ek9_change_signature; removing a class/record FIELD - use ek9_remove_field.","Moving a block to a new method rather than dropping it - use ek9_extract_method; removing a whole function/method by inlining it at call sites - use ek9_inline_function.","The range is NOT inside a body - use ek9_edit_file line-replace with empty replacement (references block, package metadata) or ek9_remove_comments (whole-line comment blocks); deleting the entire file - use ek9_delete_file."],"details":"Range MUST stay within one body and align with statement boundaries. Conflict kinds: range-straddles-method-boundary (mechanical - narrow to one body; a WHOLE member goes through ek9_safe_delete), range-not-on-statement-boundary (mechanical - response carries the boundary-snapped range to re-issue), range-includes-return-value-declaration (use ek9_change_signature). Before any compile the removal CLOSURE is computed by symbol (a kept statement using a removed local goes too; so does a kept local whose every read is removed): one range that compiles is removed-statement-declares-used-local / removal-leaves-unread-local with that exact range in details; gaps or the whole body is removal-is-a-replacement (no widening compiles - the new statements go in with ek9_edit_file line-replace or ek9_insert_statements anchor:'replace'); range-empties-body when every statement goes and the return is not initialised. Statement extents are ANTLR-derived so comments and string literals never false-match; indentation and unrelated statements are preserved.","arguments":[{"name":"endLine","type":"integer","required":false,"description":"Or the last line to remove (1-based, inclusive). Must be inside the SAME body as startLine, must align with a statement boundary, must be >= startLine."},{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 source file containing the target body."},{"name":"fromText","type":"string","required":false,"description":"The block's FIRST line exactly as written (indentation ignored) - instead of counting startLine. Must name one line; add more of it when it occurs twice."},{"name":"startLine","type":"integer","required":false,"description":"Or the first line to remove (1-based, inclusive) - an IDE selection. Must be inside a method/function/operator body and must align with a statement boundary."},{"name":"toText","type":"string","required":false,"description":"The block's LAST line as written - the first line matching it at or after fromText. Omit it for a one-line block."}],"lessons":[],"fixes":[],"example":{"scenario":"Remove single statement apply","request":{"endLine":8,"file":"Hello.ek9","startLine":8},"response":{"conflicts":[],"edits":[{"before":"      stdout.println(\"Removable\")","endLine":8,"file":"Hello.ek9","startLine":8,"type":"delete"}],"meta":{"serverMs":"<timing>"},"resolvedPath":"<workspace-root>/Hello.ek9","risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Removed statements 8-8 from com.example.hello::_main","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_remove_transitive_exclusion","url":"https://ek9.io/mcp/ek9_remove_transitive_exclusion.html","category":"editor","description":"Answers with the edit that deletes one excludeDeps entry from a 'defines package' block, re-allowing a previously-blocked transitive dependency.","whenToUse":"'Stop excluding ek9open.some.bad.pack' is one call with file:'package.ek9' and module:'ek9open.some.bad.pack'. For when the parent upgraded, or the transitive is wanted again.","whenNotToUse":["Adding an exclusion - use ek9_exclude_transitive_dependency.","Removing a direct dependency from deps/devDeps - use ek9_remove_dependency."],"details":"conflicts[].kind: 'exclusion-not-declared' (the description lists the existing keys) and 'dependency-is-direct-not-transitive' (use ek9_remove_dependency). error.message: 'package-block-not-found', 'excludeDeps-not-found' or 'single-line-bucket-unsupported' (only the multi-line Dict form is edited). An emptied Dict's whole declaration is removed and the summary says so. Removal affects future resolutions only - pair with ek9_resolve_dependencies.","arguments":[{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"module","type":"string","required":true,"description":"The previously-excluded transitive module, e.g. 'ek9open.some.bad.dependency.pack' - matched against the excludeDeps Dict key."}],"lessons":["https://ek9.io/ide/package-block.html"],"fixes":[],"example":{"scenario":"Remove transitive exclusion apply","request":{"file":"package.ek9","module":"ek9open.some.bad.dependency.pack"},"response":{"conflicts":[],"edits":[{"before":"      \"ek9open.some.bad.dependency.pack\": \"ek9open.org.supertools.util\",","endLine":15,"file":"package.ek9","startLine":15,"type":"delete"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":1,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Removed ek9open.some.bad.dependency.pack from excludeDeps","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_rename_field","url":"https://ek9.io/mcp/ek9_rename_field.html","category":"editor","description":"Renames a private field and every use inside its owning construct body in one atomic edit; answers status and edits[] (one REPLACE per rewritten line).","whenToUse":"'Rename the field farewell on Greeter to signoff' is one call with symbol:'Greeter.farewell', newName:'signoff' - no file or line needed. Use it for a class/record/component FIELD: the declaration plus every use inside the construct body, in one atomic edit.","whenNotToUse":["Renaming a method, type, function, local or any symbol whose uses cross files - use ek9_rename_symbol (the workspace-wide superset; it renames fields too).","The field doesn't exist yet — use ek9_add_field, don't rename what isn't there.","You want to DELETE the field, not rename it — use ek9_remove_field.","The user supplied the exact modified source text — use ek9_edit_file; this tool is a semantic construct-scoped rename, not a raw edit."],"details":"Every blocking case is an error, never conflicts[]: construct/field not found, name collision on the same construct, newName equals oldName, invalid/reserved identifier, or a synthesised member with no source occurrence. V1 find-references is a word-boundary textual scan over the construct's body byte range, so a same-named local that shadows the field is also renamed.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"newName","type":"string","required":true,"description":"New field name. Must be a valid EK9 identifier and not collide with an existing field on the same construct."},{"name":"oldName","type":"string","required":false,"description":"Current field name. Must exist on the construct (omit when symbol is 'Type.field')."},{"name":"symbol","type":"string","required":true,"description":"The construct that owns the field ('Greeter'), or the field itself as 'Greeter.farewell' (then oldName may be omitted) - found workspace-wide, no file needed."}],"lessons":["https://ek9.io/ide/rename-field.html"],"fixes":[],"example":{"scenario":"Rename field same name disambiguation","request":{"constructName":"Greeter","file":"GreeterB.ek9","newName":"signoff","oldName":"farewell"},"response":{"conflicts":[],"edits":[{"after":"      signoff as String: \"Bye\"","before":"      farewell as String: \"Bye\"","endLine":6,"file":"GreeterB.ek9","startLine":6,"type":"replace"},{"after":"        <- result as String: signoff","before":"        <- result as String: farewell","endLine":9,"file":"GreeterB.ek9","startLine":9,"type":"replace"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":2,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Renamed field farewell → signoff on Greeter","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_rename_file","url":"https://ek9.io/mcp/ek9_rename_file.html","category":"editor","description":"Answers first: status (applied | ready | conflicts), written and edits[{file, newFile, type:move}] - a pure file-system rename of a .ek9 source, contents and module identity untouched.","whenToUse":"You want a .ek9 file under another name or path, contents untouched - one call with oldPath + newPath (both .ek9). The directory does not affect module membership.","whenNotToUse":["Renaming a non-.ek9 file, or moving any file - use ek9_move_file (the same move without the .ek9 extension check).","Changing the MODULE of the contained constructs — use ek9_move_construct(mode=cross-module) per construct; that edits the 'defines module' line and rewrites references.","Renaming a CONSTRUCT (identifier) inside the file rather than the file — use ek9_rename_symbol.","Relocating a construct between files — use ek9_move_construct."],"details":"The only structural refusal is the HARD dev/ exit guard (no override flag): a dev/ file containing @Test or assert* cannot be renamed into a production directory (conflict kind dev-exit-contains-tests) — strip the markers first or keep it in dev/; a markerless dev→production rename is permitted (dev-exit-promotion advisory). A destination collision is an error (no overwrite flag) — pick another name or ek9_delete_file first. Crossing a sourceRoot boundary is a source-root-crossed warning, not a failure; edits[] carries a single rename entry with no before/after content since nothing in the file changed.","arguments":[{"name":"newPath","type":"string","required":true,"description":"Destination: must end in .ek9; may be in a different directory (the directory does NOT affect module membership). Workspace-relative (preferred) or absolute inside the workspace."},{"name":"oldPath","type":"string","required":true,"description":"File path: workspace-relative (preferred) or absolute inside the workspace. The .ek9 file as it is now; must exist."}],"lessons":["https://ek9.io/ide/rename-and-move-file.html"],"fixes":[],"example":{"scenario":"Rename ek9 file apply","request":{"newPath":"helpers.ek9","oldPath":"helper.ek9"},"response":{"advisories":[{"kind":"module-identity-unchanged","message":"EK9 module identity is set by the file's 'defines module' line, not its directory — every construct's fully-qualified name is unchanged by this move and workspace references continue to resolve."}],"conflicts":[],"edits":[{"file":"helper.ek9","newFile":"helpers.ek9","type":"move"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"moderate","fileCount":2,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Moved helper.ek9 → helpers.ek9","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_rename_symbol","url":"https://ek9.io/mcp/ek9_rename_symbol.html","category":"editor","description":"Renames a symbol and every workspace reference to it atomically across all files (references blocks and `${...}` holes included); answers status, edits[] per site and conflicts[] (name-collision-in-target-scope, convention-mismatch, symbol-not-renameable).","whenToUse":"'Rename Shape to Polygon everywhere' is one call with symbol:'Shape', newName:'Polygon' - no file or line needed (a member is 'Shape.area'; a local or parameter needs the file). Use it for a top-level construct, a member, a parameter or a local plus EVERY workspace reference, atomically.","whenNotToUse":["Operators (==, <=>, $, ...) - fixed contracts, cannot be renamed; use ek9_safe_delete + ek9_add_operator.","Changing a construct's MODULE rather than its name — use ek9_move_construct (mode=cross-module).","Renaming the .ek9 FILE, not a symbol — use ek9_rename_file (module identity is the 'defines module' line, not the path).","Renaming a record/component FIELD specifically — ek9_rename_field is the field-scoped anchor; this tool handles fields too, but rename_field is the precise path."],"details":"Collision, casing-convention and banned-identifier checks run before any rewrite; a colliding newName returns status:'conflicts' (kind 'name-collision-in-target-scope') — inspect, don't silently retry. The dry-run runs a scratch-workspace compile, so a semantically unsafe rename surfaces as status:'would-fail' before any disk write. Casing convention is enforced per symbol kind: PascalCase for types, camelCase for members/locals. alsoRename renames further symbols in the SAME changeset (the IDE's Find and Replace in symbols mode): any conflict refuses them all, and two on one line are rewritten together.","arguments":[{"name":"alsoRename","type":"array of object","required":false,"description":"OPTIONAL further symbols renamed in the same changeset, each {file, line, column, newName}: a place the symbol is written (its declaration or a reference; column 0-based) and its new name. Any conflict refuses them all."},{"name":"column","type":"integer","required":false,"description":"0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim."},{"name":"file","type":"string","required":false,"description":"The .ek9 file containing the symbol's declaration (or a reference to it) - OPTIONAL when symbol is a construct name or 'Type.member'; required for a local or a parameter."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"newName","type":"string","required":true,"description":"The new name. Must be a valid EK9 identifier honouring the symbol kind's casing convention (PascalCase for types, camelCase for members/locals) and not in EK9's banned non-descriptive set (temp/flag/data/value/...)."},{"name":"symbol","type":"string","required":true,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/replace-symbols.html","https://ek9.io/ide/rename-symbol.html"],"fixes":[],"example":{"scenario":"Rename symbol operator error","request":{"column":7,"file":"main.ek9","line":13,"newName":"isReady"},"response":{"conflicts":[],"edits":[],"error":{"message":"Operators cannot be renamed — their identity IS the operator symbol. Use ek9_safe_delete + ek9_add_operator to replace"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"Operators cannot be renamed — their identity IS the operator symbol. Use ek9_safe_delete + ek9_add_operator to replace","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_render_specification","url":"https://ek9.io/mcp/ek9_render_specification.html","category":"enquiry","description":"Answers status (ok | not-found), requirementId and markdown - the specification document generated from the requirement graph with every section marked authored or derived - plus anchorsResolved saying whether a compile backed the derived sections.","whenToUse":"'Write me the specification for X' is one call: {requirementId:'CAP:payments'} renders the subtree as markdown from the graph - a root for the exec summary, a leaf for acceptance criteria.","whenNotToUse":["You want the requirement graph structure / traceability, not a rendered doc — use ek9_query_requirement.","Checking that requirement references resolve — use ek9_check_requirements.","Authoring or confirming intent (the 'why' bodies this render displays) — use ek9_update_requirement (its confirm-intent mode stamps the 'last confirmed' date).","PDF / Word / slides — this emits markdown only; pipe the output through pandoc / the docx/pptx/pdf conversion downstream."],"details":"A view, never a stored source: the requirement nodes are the truth, the markdown is disposable and must not be persisted as source. Every render visibly separates derived (what the code provably does, always fresh) from authored (recorded intent) — that separation is the anti-staleness guarantee. Top-level anchorsResolved is true only when a compiled program was available; when false, derived sections are absent (not wrong) so 'nothing anchors this' is distinguishable from 'nothing compiled'.","arguments":[{"name":"depth","type":"integer","required":false,"description":"How far down to disclose. Omit for the whole subtree; 1 gives the node and its direct children."},{"name":"profile","type":"string: technical | summary","required":false,"description":"technical names the anchoring tests; summary gives intent and status only."},{"name":"requirementId","type":"string","required":true,"description":"Where to cut the tree, e.g. CAP:payments. Render from a root for the whole picture."}],"lessons":[],"fixes":[],"example":{"scenario":"Render specification not found","request":{"requirementId":"REQ:never-created"},"response":{"detail":"no requirement with this id exists in .ek9-ai/requirements/","meta":{"serverMs":"<timing>"},"nextStep":"ek9_query_requirement {mode:'list'} to see the ids that do exist","requirementId":"REQ:never-created","status":"not-found"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_resolve_dependencies","url":"https://ek9.io/mcp/ek9_resolve_dependencies.html","category":"execution","description":"Answers with status after resolving one package's declared dependency tree (ek9 -Dp), which cleans all build artefacts and the project's dependency copy (.ek9/deps/) first, then rewrites ek9.lock.","whenToUse":"'Re-resolve the dependencies after I changed the package block' is one call with file:'package.ek9' and confirm:true. It cleans every build artefact and the project's dependency copy (.ek9/deps/) first, then resolves the declared tree from the packages installed locally (there is no remote repository to fetch from yet) and rewrites ek9.lock.","whenNotToUse":["Compiling without cleaning first - use ek9_compile (this reads a current ek9.lock, or resolves only when it is missing or stale).","Cleaning build artefacts WITHOUT re-resolving - use ek9_clean.","Installing THIS package's own bundle (the producer direction) - use ek9_install_package.","Editing the dependency DECLARATION - ek9_add_dependency / ek9_remove_dependency / ek9_exclude_transitive_dependency, then this to apply it."],"details":"No mode parameter and no source mutation - the package block is unchanged. ek9 -Dp runs a -Cl clean-all FIRST, deleting every build artefact AND the project's dependency copy (.ek9/deps/) before re-resolving; confirm is checked before any fork. It is the only command that accepts a dependency's library content that no longer matches a committed ek9.lock (every other build refuses, exit 17, until this runs). Version conflicts and unresolved dependencies surface in stderr (pin the version with ek9_add_dependency on a conflict). Fixed 120s timeout -> status:timed-out.","arguments":[{"name":"confirm","type":"boolean","required":true,"description":"Must be true: acknowledges that every build artefact and the project's dependency copy (.ek9/deps/) are deleted before re-resolving."},{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size. The default answers with status and summary; 'full' adds the CLI's stdout, argv, exitCode, elapsedMs and timedOut."}],"lessons":["https://ek9.io/ide/build-and-deploy.html"],"fixes":[],"example":{"scenario":"Resolve shape","request":{"confirm":true,"file":"<workspace-root>/package.ek9"},"response":{"file":"package.ek9","meta":{"serverMs":"<timing>"},"status":"ok","summary":"dependencies resolved"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_rewrite_string_concat","url":"https://ek9.io/mcp/ek9_rewrite_string_concat.html","category":"editor","description":"Replaces a selected `\"a\" + var + \"b\"` concat with the equivalent backtick interpolation, escaping backtick and `$` in literal segments; answers status and edits[] (one REPLACE), conflicts[] (selection-not-a-string-expression, operand-has-no-string-operator with a suggestedRepair), or status:unchanged when the selection is already a backtick literal.","whenToUse":"'Turn this \"a\" + var + \"b\" concat into a backtick literal' is one call with file and selection:{startLine, startColumn, endLine, endColumn} (1-based, inclusive) covering exactly the concat expression. Use it when a concat reads better interpolated, or before ek9_extract_to_localized_text.","whenNotToUse":["The goal is to move the string into the i18n surface, not just modernise syntax - use ek9_extract_to_localized_text (it runs this first when the source is a concat).","An operand is a conditional/lambda/collection/side-effecting/non-stringable expression - the tool refuses with an escalation conflict; extract that operand to a local via ek9_extract_variable first, then re-run.","The `+` on the selection is not string concat (e.g. numeric 1 + 2) - not a string expression; there is nothing to interpolate."],"details":"Transformation is syntactic; the admission gate is semantic - a compiled program is required and every operand's type must define `_string()`, else a conflict carrying a suggestedRepair. A selection already in target form is status:unchanged (nothing written). Escaping: backtick and `$` in literal segments are escaped; redundant \\\" is reduced to \"; \\n \\t \\r \\\\ preserved verbatim.","arguments":[{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 source file containing the selection."},{"name":"selection","type":"object","required":true,"description":"The IDE selection covering exactly the concat expression (or one string literal): startLine/endLine and startColumn/endColumn, all 1-based, end INCLUSIVE - read them off ek9_read_file(lineNumbers:true). startCol/endCol are accepted."}],"lessons":["https://ek9.io/ide/rewrite-string-concat.html"],"fixes":[],"example":{"scenario":"Already in target form","request":{"selection":{"endCol":33,"endLine":8,"startCol":19,"startLine":8},"targetFile":"Hello.ek9"},"response":{"conflicts":[],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"unchanged","summary":"Selection is already a backtick literal - nothing to rewrite","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_run_program","url":"https://ek9.io/mcp/ek9_run_program.html","category":"execution","description":"Answers with programStdout, programStderr and programExitCode after compiling one .ek9 file and running the program it declares, with string args auto-parsed into the program's typed parameters; exitedBy says whether an exit code is the program's own or the EK9 CLI's.","whenToUse":"'Run this program and show me its output' is one call with file:'hello.ek9' (plus programName when the file declares several programs). Pass args as strings; each is auto-parsed into the program's typed parameter.","whenNotToUse":["Running @Test programs through the test runner - use ek9_run_tests.","Compiling only, with no run - use ek9_compile.","Reading the last compile's diagnostics without running - use ek9_query_diagnostics."],"details":"Stage 1 always compiles (incremental - near no-op when the cache is warm), stage 2 runs the emitted java command in its OWN process, so exitedBy says whose exit code it is: 'ek9-cli' (stage 1) or 'program' (stage 2). A program's code is its own - a returned Integer, an uncaught Exception's exitCode, a Panic's - and never means a CLI status, even when it is 3, 8 or 11. status: ok (program exited 0) / program-exited (the program exited non-zero - programExitCode, programStderr says why) / program-timed-out (killed at timeoutSeconds, exitedBy:'timeout') / compile-failed (the CLI's exit 8, compileExitCode, stage 2 skipped) / argument-mismatch (EK9's entry point refused args that do not fit the program's parameters, exit 9 or 10, exitedBy:'ek9-cli') / program-not-specified (several programs, none named - programs[] lists them) / no-programs (the file declares none - answered from the source before any compile, with the ek9_add_program route) / bad-command-combination (programName not in the file - programs[] lists what is) / no-run-command-emitted. env and workingDir apply ONLY to the program, never the compiler; there is NO sandbox - file writes, network calls and OS exits are real.","arguments":[{"name":"args","type":"array of string","required":false,"description":"Positional arguments passed to the running program, as strings; the runtime parses each into the declared parameter type."},{"name":"env","type":"object","required":false,"description":"Environment variables for the program's process (stage 2), merged onto the inherited shell environment; a null value unsets the variable. Pass resolved values - no ${VAR} expansion is done. Never applied to the compiler (stage 1)."},{"name":"file","type":"string","required":true,"description":"The .ek9 file declaring the program, workspace-relative (an absolute path inside the workspace is accepted)."},{"name":"programName","type":"string","required":false,"description":"Which program to run when the file declares several (the CLI's -r); a file with one program needs none."},{"name":"timeoutSeconds","type":"integer","required":false,"description":"Wall-clock limit before the program is killed. Default 120."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size. The default answers with status, summary, exitedBy, programStdout, programStderr and programExitCode (compileExitCode when the compile stage fails); 'full' adds the compile stage's stdout and both stages' argv, exit codes and elapsed times."},{"name":"withDebug","type":"boolean","required":false,"description":"Default false. True runs the program with the JDWP debug agent attached (the CLI's -dr) so a debugger can connect."},{"name":"workingDir","type":"string","required":false,"description":"Working directory for the program's process (stage 2). Default: the server's own cwd."}],"lessons":["https://ek9.io/ide/first-project.html","https://ek9.io/ide/book-notes.html","https://ek9.io/ide/book-programs.html","https://ek9.io/ide/depth-echo-in-process.html","https://ek9.io/ide/depth-check-destinations.html","https://ek9.io/ide/depth-note-links.html","https://ek9.io/ide/depth-serve-and-call.html","https://ek9.io/ide/depth-json-documents.html","https://ek9.io/ide/depth-sync-key.html","https://ek9.io/ide/run-configurations.html","https://ek9.io/ide/networking.html","https://ek9.io/ide/the-terminal.html"],"fixes":[],"example":{"scenario":"Run program shape","request":{"file":"<workspace-root>/Hello.ek9","timeoutSeconds":30},"response":{"exitedBy":"program","file":"Hello.ek9","meta":{"serverMs":"<timing>"},"programExitCode":0,"programStderr":"","programStdout":"Hello\n","programTimedOut":false,"status":"ok","summary":"program exited 0"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_run_quality_checks","url":"https://ek9.io/mcp/ek9_run_quality_checks.html","category":"execution","description":"Compiles, runs the tests and answers status (ok | compile-failed | no-tests-found | tests-failed | coverage-low) with tests:{passed, failed}, coverage (overall, methods, lines, branches, byModule), complexity.hotspots[], readability, injections, uncoveredMethods[] and the advisory lockPayloads - every quality metric in one call, extracted in-process.","whenToUse":"'Is the project's quality posture OK?' is one call: {} compiles, runs the tests and reports coverage, complexity hotspots, readability, DI and uncovered methods together.","whenNotToUse":["Per-test pass/fail detail, test filtering, or an HTML report - use ek9_run_tests.","Complexity from an already-compiled workspace with no re-compile - use ek9_query_complexity.","Compile error/warning detail, not metrics - use ek9_query_diagnostics.","Compiling without running tests - use ek9_compile."],"details":"status is one of: ok (tests pass + coverage meets threshold) / tests-failed / coverage-low (tests pass but coverage below threshold) / compile-failed / no-tests-found - the same words ek9_run_tests uses. lockPayloads reports MutexKey bodies whose protected payload may leave the lock — each naming the enclosing method, the MutexLock it runs under and the via chain to the callee that keeps the reference — beside a census {bodies, contained, mayEscape, unknown} of EVERY body; it carries gates:false and is NOT part of status — advisory until it proves reliable enough to stop a publish (ek9_query_mutex_payload is the same sweep, workspace-scoped). All metrics are extracted in-process from CoverageRuntime after execution (no disk reads/writes for metrics); complexityThreshold (default 10) gates the cyclomatic hotspots list, uncoveredMethods is capped at 50 entries sorted by file then start line, and the entry-point file auto-detects when omitted. RELEASE chain: ek9_increment_version -> ek9_run_tests -> ek9_run_quality_checks -> ek9_package.","arguments":[{"name":"complexityThreshold","type":"integer","required":false,"description":"Methods with cyclomatic complexity >= this appear in complexity.hotspots."},{"name":"file","type":"string","required":false,"description":"The entry-point .ek9 source file (absolute, or relative to projectDir). Omit to auto-detect the shallowest non-dev .ek9 file."},{"name":"projectDir","type":"string","required":false,"description":"Project root holding the .ek9 sources - absolute, or relative to the workspace root. Omit to use the workspace root itself (the first root ek9_compile was given)."}],"lessons":["https://ek9.io/ide/depth-postage.html","https://ek9.io/ide/quality-report.html","https://ek9.io/ide/contracts-and-risk.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_run_tests","url":"https://ek9.io/mcp/ek9_run_tests.html","category":"execution","description":"Compiles and runs the project's @Test programs (auto-forcing -Cd -O0 so coverage probes map to source) and answers status (ok | compile-failed | no-tests-found | tests-failed | coverage-low), tests:{passed, failed}, overallCoverage, results[] per test, plus the inputVariety and hex change-risk blocks.","whenToUse":"'Do the tests pass?' is one call: {} runs every @Test program in the workspace; testNameFilter:'SmokeTest' (bare or qualified) runs one.","whenNotToUse":["Running a NORMAL entry-point program (no @Test directive) - use ek9_run_program.","Compiling tests WITHOUT running them - use ek9_compile with includeDev:true.","Wanting the full quality snapshot (coverage + complexity + readability + DI) in one call - use ek9_run_quality_checks.","Authoring a @Test program rather than running one - use ek9_add_program with isTest:true."],"details":"In-process CompilationPipeline (bootstrap → discover → compile → runTests), the tests themselves in a fresh child JVM per run, killed at the test time limit (E82001); no pre-compiled workspace needed. status ∈ {ok, compile-failed, no-tests-found, tests-failed, coverage-low}; 'ok' requires all tests green AND coverage at or above the 80% threshold (coverageSufficient). Every run with results carries 'inputVariety' and a 'hex' change-risk block (hazard x exposure, worst construct named, caMax blast radius) - read hex before editing; verbosity:'full' adds per-method/branch/statement uncovered items with file+line (CLI -t4/-t5 data) and the full ranked hex construct list; the invariant interpretation prose only with notes:true.","arguments":[{"name":"coverageDetail","type":"boolean","required":false,"description":"Retained boolean alias for verbosity:'full'."},{"name":"file","type":"string","required":false,"description":"The entry-point .ek9 source file (absolute, or relative to projectDir). Omit to auto-detect the shallowest non-dev .ek9 file."},{"name":"generateReport","type":"boolean","required":false,"description":"Default false. When true, additionally produces an HTML coverage report at .ek9/coverage/index.html."},{"name":"notes","type":"boolean","required":false,"description":"Default false. When true, include the full interpretation prose beside the metric blocks (how to read hex/hexMax/bands/cohorts, why Ca and purity sit outside the score, what asserted variety means). It is invariant text and ~1,300 tokens, so it is omitted by default and every block instead carries a one-line pointer. The same guidance is permanently available via ek9_help with keyword 'hex' - prefer that once, over paying for it on every run."},{"name":"projectDir","type":"string","required":false,"description":"Project root holding the .ek9 sources - absolute, or relative to the workspace root. Omit to use the workspace root itself (the first root ek9_compile was given)."},{"name":"testGroupFilter","type":"string","required":false,"description":"Run only tests in the named group. Tests without the group are skipped."},{"name":"testNameFilter","type":"string","required":false,"description":"Run only this test: a fully qualified name (com.acme::SmokeTest) or a bare program name (SmokeTest) when it is unique across the workspace - an ambiguous bare name is refused naming the candidates."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size. summary (default): counts, per-test results, the hex and inputVariety headlines. full: also a 'coverage' block of every UNCOVERED method / branch / statement with file + line (the CLI -t4/-t5 data) and hex.constructs[], the full ranked per-construct list with raw signals. none: status and counts only."}],"lessons":["https://ek9.io/ide/book-testing.html","https://ek9.io/ide/book-shop.html","https://ek9.io/ide/book-game-journal.html","https://ek9.io/ide/depth-inventory.html","https://ek9.io/ide/depth-guess-seam.html","https://ek9.io/ide/depth-shop-tests.html","https://ek9.io/ide/application-and-di.html","https://ek9.io/ide/tests.html"],"fixes":[],"example":{"scenario":"Run tests shape","request":{"projectDir":"<workspace-root>"},"response":{"buildLog":"Bootstrap: Initialising compiler\nBootstrap: Compiler ready\nDiscovery: Scanning for .ek9 files\nDiscovery: 1 source file(s)\nCompile: Compiling 1 source file(s)\nCompile: Compilation succeeded\nTest: Discovering tests\nTest: No tests found\n","compileSucceeded":true,"coverageSufficient":true,"hex":{"available":false,"reason":"no per-construct metrics were registered - typically no tests ran; caMax may still be present (notes:true for the full reason)."},"inputVariety":{"assertedPercent":0.0,"assertionValidatedTests":0,"constructCount":0,"constructs":[],"drivenPercent":0.0,"interactionNote":"no target, deliberately - compare a callable against ITSELF over time; notes:true for why.","note":"omitted (invariant, ~1,300 tokens): pass notes:true, or ek9_help keyword 'hex' once.","outputValidatedTests":0,"totalAsserted":0,"totalDriven":0,"totalDrivenPairs":0,"totalFloor":0,"totalPairCeiling":0},"mainSource":"seed.ek9","meta":{"serverMs":"<timing>"},"overallCoverage":0.0,"projectDir":"<workspace-root>","resultCount":0,"results":[],"status":"no-tests-found","summary":"No @Test programs found - nothing ran","testRunOutput":"","tests":{"allTestsPassed":false,"failed":0,"passed":0},"totalDurationMs":"<timing>"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_safe_delete","url":"https://ek9.io/mcp/ek9_safe_delete.html","category":"editor","description":"Deletes a top-level construct or a class/record/component member - or several as one change - after a workspace-wide reference check; answers status and edits[] (one DELETE per line), or conflicts[] with one 'construct-still-referenced' entry per citing site.","whenToUse":"'Delete OrderProcessor if nothing uses it' is one call with symbol:'OrderProcessor' - no file or line needed (a member is 'Type.member'). Use it to DELETE a top-level construct or a class/record/component member with a workspace-wide reference check blocking it while anything still uses the target.","whenNotToUse":["You only want to KNOW the reference count, not delete - use ek9_query_references.","You want to DISCOVER deletion candidates across the workspace — use ek9_find_unused_code.","The construct should be RENAMED, not deleted — use ek9_rename_symbol.","A method should keep existing but shed parameters — use ek9_change_signature."],"details":"Live references yield status:'conflicts', NOT an error — one conflicts[] entry per citing site (kind 'construct-still-referenced'; only the declaration site is excluded from the count); references are intentional, so surface them rather than silently retrying. Single-file V1: anchoring on a usage of a symbol declared elsewhere (or an external/built-in symbol) errors and names the declaring file; non-deletable kinds (enum values, individual references-block entries, statements) also error. A top-level deletion that empties its file attaches a 'file-emptied' advisory pointing at ek9_delete_file; override/sealed coupling is not pre-checked in V1 and surfaces as a post-apply compile failure.","arguments":[{"name":"column","type":"integer","required":false,"description":"0-based char offset of the target identifier on 'line' (an IDE cursor). OMIT it and pass symbol:'<name>' instead, or omit both and the first identifier on the line is taken (right for a declaration line). Reuse a column from ek9_inspect_symbol_at_cursor verbatim."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."},{"name":"symbols","type":"array of string","required":false,"description":"Several to delete as ONE change - all or none (e.g. a dead method and its dead callers: ['reportTitles','Product.getTitle'], in any order). Instead of symbol."}],"lessons":["https://ek9.io/ide/safe-delete.html","https://ek9.io/ide/unused-code.html"],"fixes":[],"example":{"scenario":"Safe delete same basename other directory","request":{"file":"app/rates.ek9","line":5,"symbol":"discount"},"response":{"conflicts":[],"edits":[],"error":{"message":"Target 'discount' is declared in file://<workspace-root>/other/rates.ek9 — open that file and place the cursor on its declaration to delete it"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"Target 'discount' is declared in file://<workspace-root>/other/rates.ek9 — open that file and place the cursor on its declaration to delete it","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_seal_type","url":"https://ek9.io/mcp/ek9_seal_type.html","category":"editor","description":"Adds 'allow only A, B, C' to a class or trait declaration (plus 'as open' on a class that has no extensibility modifier); answers status, edits[] and conflicts[] naming any entry that does not extend the target or any existing subtype left off the list.","whenToUse":"'Seal Shape to Circle and Square' is one call with symbol:'Shape', allowOnly:['Circle','Square'] - no file or line needed. Use it to INITIALLY seal a class or trait to a known, fixed subtype list for exhaustive dispatch or API lock-down.","whenNotToUse":["The type is ALREADY sealed and you just want to add entries - use ek9_add_to_sealed_allowlist.","You want the OPPOSITE, removing an existing 'allow only' clause — use ek9_unseal_type.","You want extensibility WITHOUT a fixed subtype list (just 'as open') — use ek9_make_open.","You want forced subclassing WITHOUT a fixed list — use ek9_make_abstract."],"details":"Class/trait targets only — records/components/functions error. Every allowOnly entry must ALREADY extend/implement the target (conflicts: entry-does-not-extend-target), and the language requires concrete entries — an abstract entry fails the dry-run compile per E05250. Sealed CLASSES need 'as open' or 'as abstract' per E05270 (existing modifier kept, else 'as open' auto-emitted; traits need none); an already-sealed target returns conflicts (target-already-sealed).","arguments":[{"name":"allowOnly","type":"array of string","required":true,"description":"The 'allow only' list: every concrete class that may extend/implement the target, at any depth."},{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/book-allow-only.html","https://ek9.io/ide/seal-type.html"],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_search_text","url":"https://ek9.io/mcp/ek9_search_text.html","category":"enquiry","description":"Answers first: matchCount, files[], sites['file.ek9:LINE'] (truncated:true first when cut), then matches[{file,line,column,snippet}] - a literal or regex grep across the workspace with EK9-aware exclusions (build outputs, .ek9-cache/, dot-directories).","whenToUse":"You want every place a piece of TEXT or a regex appears across workspace files - one call with query:'TODO'; add pathPattern:'**/*.ek9' or path to bound it. Comments, strings, README mentions, config keys - when no symbol name or file path is known.","whenNotToUse":["Uses of a NAMED construct or member - use ek9_query_references (symbol:'Type.member', semantic, exact); to find a construct by name use ek9_find_constructs_by_name.","Searching for a FILE NAME rather than content — use ek9_list_files.","Searching for compiler errors / warnings — use ek9_query_diagnostics.","As a 'locate first' pre-step before mutating — editors (e.g. ek9_edit_localized_text, ek9_organize_localized_text) do their own discovery; dispatch straight to them."],"details":"Pure lexical grep — never consults symbol tables or the AST, so identical results regardless of compile state; requires watched roots (run ek9_compile first). Literal mode matches EK9 operators (<=> ? :=?) verbatim with no escaping; regex mode needs a valid java.util.regex.Pattern. caseSensitive defaults to true when the query is an identifier containing an uppercase letter (a symbol name) and false otherwise; pass it explicitly to override. path bounds the root (a directory, or a single file to search only it), pathPattern filters within it (intersection, cannot un-exclude); maxResults default 100 max 1000 - a cut result opens with truncated:true and matchTotal. column is 0-based, the base every EK9 tool uses.","arguments":[{"name":"caseSensitive","type":"boolean","required":false,"description":"Omit it: an identifier with an uppercase letter (a symbol name) is searched case-sensitively, anything else case-insensitively. Set it to override."},{"name":"includeHidden","type":"boolean","required":false,"description":"When true, includes dot-files and otherwise-excluded build directories in the scan."},{"name":"isRegex","type":"boolean","required":false,"description":"When true, query is parsed as a java.util.regex.Pattern."},{"name":"maxResults","type":"integer","required":false,"description":"Cap on matches[] (default 100, max 1000). A cut result opens with truncated:true and matchTotal (the true count)."},{"name":"path","type":"string","required":false,"description":"Bounds the search: a workspace-relative directory, or ONE file to search just that file ('m04.ek9'). Defaults to the workspace root."},{"name":"pathPattern","type":"string","required":false,"description":"Optional glob restricting which files are searched, applied relative to path (e.g. \"**/*.ek9\", \"src/main/**\"). Intersects with default exclusions — cannot bring back excluded paths."},{"name":"query","type":"string","required":true,"description":"Literal text (default) or regex pattern (when isRegex:true). Literal mode matches special characters verbatim — no escaping needed for operators like <=> ? :=? * ( ) [ ] \\."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"full (default) returns matches[] records; summary keeps the headline only (files, sites, counts); none collapses the lists to counts."}],"lessons":[],"fixes":[],"example":{"scenario":"Search bounded to one file","request":{"path":"MyRecord.ek9","query":"MyRecord"},"response":{"caseSensitive":true,"fileCount":1,"files":["MyRecord.ek9"],"isRegex":false,"matchCount":1,"matches":[{"column":4,"file":"MyRecord.ek9","line":5,"snippet":"    MyRecord"}],"meta":{"serverMs":"<timing>"},"query":"MyRecord","sites":["MyRecord.ek9:5"],"status":"ok"}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_set_feature_version","url":"https://ek9.io/mcp/ek9_set_feature_version.html","category":"execution","description":"Answers with the new version and previousVersion after setting the 'defines package' version literal to MAJOR.MINOR.PATCH-feature (build restarts at 0), plus written and line.","whenToUse":"'Publish under a feature-tagged version' is one call with file:'package.ek9' and version:'1.0.0-hotfix' (or just 'hotfix'). A bare tag is prefixed with the file's current MAJOR.MINOR.PATCH. Hotfix and release branches, vendor- or customer-specific variants.","whenNotToUse":["A plain version with no feature tag - use ek9_set_version.","Bumping the current version by one component (feature-tagged or not) - use ek9_increment_version.","Reading the current version without changing it - use ek9_query_package_version."],"details":"Wraps ek9 -SF. A feature tag is letters then letters/digits (no '-' inside it: 'rc1' and 'customerA' are tags, 'feature-branch' is not). The build component restarts at 0 and later CI snapshots bump it with ek9_increment_version component:'build'. Switches the version FORMAT from plain to feature-tagged; ek9_set_version switches it back. The literal is validated before the fork; the file's version line is read before and after so version, previousVersion, written and line are facts from the file.","arguments":[{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size. The default answers with status, summary, version, previousVersion, written and line; 'full' adds the CLI's argv, exitCode, elapsedMs and timedOut."},{"name":"version","type":"string","required":true,"description":"The MAJOR.MINOR.PATCH-FEATURE literal, e.g. '1.0.0-alpha' or '2.1.0-rc1'; a bare tag such as 'alpha' is prefixed with the file's current MAJOR.MINOR.PATCH. The tag is letters then letters/digits."}],"lessons":["https://ek9.io/ide/package-block.html"],"fixes":[],"example":{"scenario":"Set feature version apply","request":{"file":"<workspace-root>/package.ek9","version":"1.0.0-alpha"},"response":{"file":"package.ek9","line":5,"meta":{"serverMs":"<timing>"},"previousVersion":"1.0.0-0","status":"ok","summary":"version 1.0.0-0 -> 1.0.0-alpha-0","version":"1.0.0-alpha-0","written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_set_version","url":"https://ek9.io/mcp/ek9_set_version.html","category":"execution","description":"Answers with the new version and previousVersion after setting the 'defines package' version literal to an explicit MAJOR.MINOR.PATCH (build restarts at 0), plus written and line.","whenToUse":"'Set the package version to 2.0.0' is one call with file:'package.ek9' and version:'2.0.0'. An explicit base version rather than a bump: first GA, a breaking release, a mis-bump reset.","whenNotToUse":["Bumping the current version by one component - use ek9_increment_version.","A feature-tagged version (X.Y.Z-feature) - use ek9_set_feature_version.","Reading the current version without changing it - use ek9_query_package_version."],"details":"Wraps ek9 -SV. The build component restarts at 0 (2.0.0 becomes 'version <- 2.0.0-0') and an existing feature tag is replaced by whatever the literal carries. There is deliberately no 'must be greater than current' guard - setting an older version is how a mis-bump is corrected. The literal is validated before the fork; the file's version line is read before and after the rewrite so version, previousVersion, written and line are facts from the file.","arguments":[{"name":"file","type":"string","required":true,"description":"The .ek9 file holding the 'defines package' block, workspace-relative (typically 'package.ek9'); an absolute path inside the workspace is accepted."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size. The default answers with status, summary, version, previousVersion, written and line; 'full' adds the CLI's argv, exitCode, elapsedMs and timedOut."},{"name":"version","type":"string","required":true,"description":"The new MAJOR.MINOR.PATCH literal, e.g. '1.2.3' - no build suffix (the build restarts at 0)."}],"lessons":["https://ek9.io/ide/package-block.html"],"fixes":[],"example":{"scenario":"Set version apply","request":{"file":"<workspace-root>/package.ek9","version":"2.5.7"},"response":{"file":"package.ek9","line":5,"meta":{"serverMs":"<timing>"},"previousVersion":"1.0.0-0","status":"ok","summary":"version 1.0.0-0 -> 2.5.7-0","version":"2.5.7-0","written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_surround_with","url":"https://ek9.io/mcp/ek9_surround_with.html","category":"editor","description":"Folds a contiguous line range under an if / if-else / try-catch / try-catch-finally / for-range / while / switch head, re-indenting the block per EK9's brace-free rules; answers status and edits[] (one REPLACE carrying the head + the re-indented lines, one DELETE per absorbed line).","whenToUse":"'Wrap those lines in an if on count > 0' is one call with file, fromText (the block's first line as written), toText (its last), surroundType:'if', condition:'count > 0' - the tool owns the re-indent. Use it on a contiguous range of WHOLE statements at one indent level that should run conditionally, loop, or be exception-handled.","whenNotToUse":["You want EK9's idiomatic guard form (<-, :=?) for a null/unset check, not a generic if wrap — use ek9_apply_guard_pattern.","You want to factor the block into a named method rather than wrap it — use ek9_extract_method.","You want to convert an imperative loop into a stream pipeline — use ek9_advise_loop.","You want to wrap a single expression in a coalescing/elvis operator — use ek9_insert_coalescing."],"details":"Head text you pass (condition for if/if-else/while, rangeExpression for for-range, exceptionType/exceptionVariable for try-catch) is parsed alone first - a text that does not parse is status:error with nothing written - then emitted verbatim. An omitted head is an opaque placeholder for the caller to edit: `if` inserts `surroundGuard <- Boolean(true)` then `if surroundGuard? //AI:`, `while` inserts `loopGuard <- Boolean(false)` then `while loopGuard //AI:`, `for-range` inserts `for i in 1 ... 10 //AI:`, `switch` inserts `switchSubject <- Integer(0)`, `switch switchSubject //AI:`, `case 1 //AI:` over the wrapped lines and a `default` holding a compiling placeholder (a bare `true` would trip E07390 pointless-condition). Wrapped lines are re-indented +2 spaces; the head line(s) sit at the block's current indent; a line range outside the file or endLine < startLine is a hard error.","arguments":[{"name":"caseValues","type":"string","required":false,"description":"switch: the text after 'case' for the selected code (e.g. '1, 2, 3, 4, 5', '< passMark'), emitted verbatim. Omitted: 'case 1 //AI: Replace with the case values'."},{"name":"condition","type":"string","required":false,"description":"if / if-else / while: the condition source text (e.g. 'count > 0', 'name?'), emitted verbatim; switch: the value switched on (e.g. 'day'). Omitted: an opaque placeholder with an //AI: marker to replace."},{"name":"endLine","type":"integer","required":false,"description":"Or the last line of the selection (1-based, inclusive)."},{"name":"exceptionType","type":"string","required":false,"description":"try-catch / try-catch-finally: the caught type (default Exception)."},{"name":"exceptionVariable","type":"string","required":false,"description":"try-catch / try-catch-finally: the handler's variable name (default ex)."},{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 source file containing the lines to wrap."},{"name":"fromText","type":"string","required":false,"description":"The block's FIRST line exactly as written (indentation ignored) - instead of counting startLine. Must name one line; add more of it when it occurs twice."},{"name":"rangeExpression","type":"string","required":false,"description":"for-range: the text after 'for i in' (e.g. '1 ... 10', 'items'), or a whole 'item in items' clause. Omitted: 'for i in 1 ... 10 //AI: Replace range'."},{"name":"startLine","type":"integer","required":false,"description":"Or the first line of the selection (1-based) - an IDE selection."},{"name":"surroundType","type":"string: if | if-else | try-catch | try-catch-finally | for-range | while | switch","required":true,"description":"The wrapper: if, if-else, try-catch, try-catch-finally, for-range, while or switch (the selection becomes the first case, with a default)."},{"name":"toText","type":"string","required":false,"description":"The block's LAST line as written - the first line matching it at or after fromText. Omit it for a one-line block."}],"lessons":["https://ek9.io/ide/book-weather.html","https://ek9.io/ide/book-switch.html","https://ek9.io/ide/book-grade.html","https://ek9.io/ide/book-counting.html","https://ek9.io/ide/book-decisions.html","https://ek9.io/ide/book-describe.html","https://ek9.io/ide/book-phone.html","https://ek9.io/ide/book-optional-result.html","https://ek9.io/ide/surround-with.html"],"fixes":[],"example":{"scenario":"Surround with condition does not parse","request":{"condition":"count >","endLine":8,"file":"Hello.ek9","startLine":8,"surroundType":"if"},"response":{"conflicts":[],"edits":[],"error":{"message":"condition does not parse as EK9: extraneous indentation expecting valid statement or expression near 'indentation' - fix the text, or omit it for a placeholder head"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"condition does not parse as EK9: extraneous indentation expecting valid statement or expression near 'indentation' - fix the text, or omit it for a placeholder head","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_sync_references","url":"https://ek9.io/mcp/ek9_sync_references.html","category":"editor","description":"Rewrites one file's 'references' block - adding the module::Name entry for each cross-module symbol the file uses but has not declared (E50001/E50010) and deleting each entry nothing uses - and answers the editor envelope: status (applied | ready | conflicts | error), written, edits[] and summary ('Added N and removed M reference(s)').","whenToUse":"'Fix this file's references block' (the EK9 Organize Imports) is one call: {file:'x.ek9'} adds every missing cross-module reference and removes every unused one.","whenNotToUse":["You only want to KNOW which symbols are unresolved without rewriting - use ek9_query_diagnostics.","You want to just reformat whitespace/indent, not change references semantics — use ek9_format.","You're moving a construct between modules (it rewrites references as part of the move) — use ek9_move_construct (mode=cross-module).","You want to consolidate a shared reference set across many files into one shared file — that is workspace-wide, not this single-file tool."],"details":"Entries are symbol-level (module.path::Identifier) — no module wildcards; disable addMissing or removeUnused for a surgical one-sided sync. Add-detection is compiler-driven (file-scoped scratch compile, iterated to a fixpoint since EK9 surfaces unresolved names across several phases). A name resolving to more than one module is surfaced as status:conflicts (kind auto-added-reference-creates-ambiguity — fully-qualify the use site, then retry) rather than guessed; a stale entry whose symbol no longer exists is simply removed as unused.","arguments":[{"name":"addMissing","type":"boolean","required":false,"description":"Add references for cross-module symbols the file uses but doesn't declare. Default true."},{"name":"file","type":"string","required":true,"description":"The .ek9 source file whose references block to sync - workspace-relative (absolute inside the workspace accepted). The file must have compiled to FULL_RESOLUTION or beyond."},{"name":"removeUnused","type":"boolean","required":false,"description":"Remove references nothing in the file uses. Default true."}],"lessons":["https://ek9.io/ide/sync-references.html"],"fixes":[],"example":{"scenario":"Both toggles false error","request":{"addMissing":false,"file":"uses.ek9","removeUnused":false},"response":{"conflicts":[],"edits":[],"error":{"message":"addMissing and removeUnused cannot both be false — nothing to sync"},"meta":{"serverMs":"<timing>"},"status":"error","summary":"addMissing and removeUnused cannot both be false — nothing to sync","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_toggle_block_comment","url":"https://ek9.io/mcp/ek9_toggle_block_comment.html","category":"editor","description":"Wraps a whole-line range in EK9 block-comment markers (<!- ... -!>) or removes them when the range already carries them, never nesting; answers status and edits[] (two INSERTs or two DELETEs).","whenToUse":"'Comment out lines 42-50 of orders.ek9' is one call with file, startLine:42, endLine:50; re-select INCLUDING the marker lines to uncomment. Use it to TEMPORARILY exclude whole lines from compilation - debug bisection, staged rollout, scratch code.","whenNotToUse":["PERMANENTLY removing a construct - use ek9_safe_delete (commenting-out is wrong unless truly temporary).","Commenting a single line or a partial line — use a // line comment via ek9_edit_file; this tool wraps WHOLE lines only."],"details":"Wraps whole lines startLine..endLine in the EK9-distinctive <!- … -!> form (not the HTML <!-- … --> nor the reserved documentation <?- … -?>), each marker on its own line indented to match the first line of the range. Refuses to nest: if any line in the range begins with a marker from any of the three block-comment forms it returns status:error ('Cannot comment: line N contains a block comment marker'); // line comments inside the range are fine. Invalid range (endLine<startLine, startLine<1, or endLine past EOF) returns status:error 'Invalid line range: S-E'.","arguments":[{"name":"endLine","type":"integer","required":true,"description":"Last line of the range to toggle (1-based, inclusive). Must be >= startLine."},{"name":"file","type":"string","required":true,"description":"Workspace-relative path to the .ek9 source file."},{"name":"startLine","type":"integer","required":true,"description":"First line of the range to toggle (1-based, inclusive)."}],"lessons":["https://ek9.io/ide/comments-and-format.html"],"fixes":[],"example":{"scenario":"Toggle on apply","request":{"endLine":8,"file":"Hello.ek9","startLine":8},"response":{"conflicts":[],"edits":[{"after":"      -!>","endLine":9,"file":"Hello.ek9","startLine":9,"type":"insert"},{"after":"      <!-","endLine":8,"file":"Hello.ek9","startLine":8,"type":"insert"}],"meta":{"serverMs":"<timing>"},"resolvedPath":"<workspace-root>/Hello.ek9","risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":2,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Added block comment around lines 8-8","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_unseal_type","url":"https://ek9.io/mcp/ek9_unseal_type.html","category":"editor","description":"Removes the 'allow only A, B, C' clause from a sealed class or trait, keeping its 'as open' / 'as abstract'; answers status and edits[] (one REPLACE on the declaration line), or conflicts[] (kind 'already-unsealed') when there is no clause.","whenToUse":"'Unseal Shape' is one call with symbol:'Shape' - no file or line needed. Use it when a sealed class or trait's `allow only ...` subtype set is no longer warranted and the type should be openly extensible again.","whenNotToUse":["ADDING an `allow only` clause (the opposite direction) - use ek9_seal_type.","The type stays sealed but you want MORE subtypes in the existing allowlist — use ek9_add_to_sealed_allowlist.","After unsealing, locking the (now-extensible) class down entirely — chain ek9_make_closed (as open → closed) or ek9_make_concrete (as abstract → concrete)."],"details":"Class or trait targets only (a record/component/function target errors); a target that is not sealed is status:conflicts with kind 'already-unsealed'. The extensibility modifier is always preserved (sealed classes require `as open` OR `as abstract` per E05270; traits carry none). Unsealing is a WIDENING change — existing subtypes were all in the removed allowlist so they keep compiling, and prior E05240 blocks on new extensions are resolved. The design cost is that dispatchers over the target silently lose compile-time exhaustiveness per E05260 (new subtypes then hit the default fallback) — check ek9_query_dispatchers before committing.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line of the declaration or a reference - OMIT it and pass symbol:'<name>' to let the tool find the line (a model counting lines in a file miscounts); if you do count, use ek9_read_file(lineNumbers:true)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/unseal-type.html"],"fixes":["E05240"],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_update_requirement","url":"https://ek9.io/mcp/ek9_update_requirement.html","category":"editor","description":"Rewrites one existing requirement node's markdown file (body, title, meta, position, retirement) or deletes it, and answers the editor envelope: status (applied | ready | conflicts), written, edits[] and summary naming the mode applied.","whenToUse":"'Change requirement X' is one call: {mode:'edit-body-text', requirementId:'REQ:x', text, authorKind, authorName}; modes cover title, meta, reparent, retire and delete.","whenNotToUse":["Adding a NEW requirement node - use ek9_create_requirement.","Anchoring or retargeting which @Test proves a requirement - use ek9_anchor_test (there is no set-status here: 'developed' is derived from anchors).","Reading a requirement or the graph - use ek9_query_requirement."],"details":"Modes: edit-body-text (authored why; a vertical-drift trigger — clears intent confirmation on confirmed descendants, advisory only, nothing becomes undeveloped), edit-title, edit-meta (empty value removes the key; unnamed attrs left alone), retire / un-retire (retire in place, optional supersededBy successor that must already exist), reparent (own parentId + optional rankKey; refused with kind would-create-cycle if it would make the node its own ancestor), confirm-intent (re-stamp confirmed_at), delete (the only gated mode — kind still-referenced while children/anchors remain). Other conflict kinds: target-not-found, target-retired (un-retire first), missing-value, parent-not-found, parent-retired. rename-slug is refused (a partial rename leaves dangling @Test anchors) - create the replacement and retire this node with supersededBy instead; each edit is a whole-file rewrite (no line range).","arguments":[{"name":"authorKind","type":"string: human | persona","required":true,"description":"Who is making the change - recorded in the changelog, the same attribution ek9_create_requirement records. Required here: an edit is never attributed by inheritance (only a created child inherits its parent's author)."},{"name":"authorName","type":"string","required":true,"description":"The changing identity's name; paired with authorKind."},{"name":"dryRun","type":"boolean","required":false,"description":"When true nothing is written; the response shows the would-be edits with status:'ready'."},{"name":"meta","type":"object","required":false,"description":"For edit-meta: attributes to set. An empty value removes the key. Attributes not named are left alone."},{"name":"mode","type":"string: edit-body-text | edit-title | edit-meta | retire | un-retire | reparent | confirm-intent | delete","required":true,"description":"What to change."},{"name":"parentId","type":"string","required":false,"description":"For reparent: the new parent's requirement id. Omit to promote the requirement to a root."},{"name":"rankKey","type":"string","required":false,"description":"For reparent: position among the new siblings."},{"name":"requirementId","type":"string","required":true,"description":"The requirement to change, e.g. REQ:fraud-screening."},{"name":"supersededBy","type":"string","required":false,"description":"For retire: the successor requirement that replaces this one. It must already exist."},{"name":"terse","type":"boolean","required":false,"description":"Retained boolean alias for verbosity:'summary'."},{"name":"text","type":"string","required":false,"description":"The new body (edit-body-text) or the new title (edit-title)."},{"name":"verbosity","type":"string: full | summary | none","required":false,"description":"Response size: full (default) carries each edit's full content; summary drops the edit bodies; none collapses edits[] to a count."}],"lessons":[],"fixes":[],"example":{"scenario":"Update requirement delete refused","request":{"authorKind":"human","authorName":"Steve Limb","mode":"delete","requirementId":"REQ:payments"},"response":{"conflicts":[{"detail":"1 thing(s) still reference this - reparent or remove them first: REQ:fraud","kind":"still-referenced","subject":"REQ:payments"}],"edits":[],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":0,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"conflicts","summary":"Would change nothing — 1 conflict(s)","wouldBeDiagnostics":[],"written":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_verify_method","url":"https://ek9.io/mcp/ek9_verify_method.html","category":"enquiry","description":"Answers first: status, name, verified, then counterexampleCount, counterexamples[] {obligation, witness, suggestedTest, suggestedFix}, provedSafe, deadBranches and nextStep.","whenToUse":"'Can any input break this function's contract - a panic or an unset result' is one call with symbol:'name' - no file needed; the breaking input is returned.","whenNotToUse":["internal control flow or complexity of a body, not contract safety (use ek9_query_flow)","materialising a returned counterexample as an actual failing test (use ek9_generate_edge_case_tests)","discharging a returned counterexample by inserting the suggested require (use ek9_apply_symbolic_fix)","the every-build census rollup across the whole workspace (use ek9_run_tests with generateReport:true - the quality report's Contract roundel)"],"details":"Runs the SymbolicEngine on demand against the already-resolved program (after PRE_IR_CHECKS — no -Xverify flag, no IR), resolving the ENCLOSING FUNCTION from the anchor; a type/record/bare-expression target returns status:'not-found' (re-anchor on the function) and a dynamic function returns status:'not-applicable' (no verification claim either way - its captures are constructor-injected fields, not free inputs). verified means verified TO A BOUND (finite value-class enumeration + affine boundaries from requires) — advisory, never fails a build. counterexamples[] carry {obligation, witness as name=value, line}, enriched with suggestedTest, suggestedFix (the discharging require — its presence gates ek9_apply_symbolic_fix) and alreadyTested/testProgram when an existing @Test already pins that boundary; obligation kinds today are DIV_BY_ZERO (silently-unset result), CALLEE_REQUIRE (a callee's require violated across a call) and CONSTRAINED_CONSTRUCTION (constructed value can leave the constrained type's window); provedSafe[] lists obligations proven unbreakable and deadBranches[] {reason} branches unreachable for every input.","arguments":[{"name":"file","type":"string","required":false,"description":"The EK9 source file - OPTIONAL when symbol is a construct name; required to anchor on a member or a use site."},{"name":"line","type":"integer","required":false,"description":"1-based line inside the function's body or on its declaration - OMIT it and pass symbol:'name' to let the tool find the line (a model counting lines miscounts)."},{"name":"symbol","type":"string","required":false,"description":"A construct NAME alone ('Shape', 'sample.deps.core::Validator') - no file needed, the tool finds it workspace-wide; or, with file (+ line), the identifier you mean there."}],"lessons":["https://ek9.io/ide/contracts-and-risk.html"],"fixes":[],"example":{"scenario":"Verify dynamic not analysable","request":{"file":"Dynamic.ek9","line":12},"response":{"declaredAt":{"file":"Dynamic.ek9","line":11},"fullyQualifiedName":"com.example.dynamic::fn","meta":{"serverMs":"<timing>"},"name":"fn","note":"a dynamic function has no named declaration to analyse, and its captured variables are constructor-injected fields rather than free inputs — the bounded model does not cover it","status":"not-applicable","summary":"Not analysable — no verification claim is made either way: a dynamic function has no named declaration to analyse, and its captured variables are constructor-injected fields rather than free inputs — the bounded model does not cover it.","verified":false}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_version","url":"https://ek9.io/mcp/ek9_version.html","category":"enquiry","description":"Returns the EK9 compiler toolchain version string, e.g. '0.0.1-0'.","whenToUse":"'Which EK9 compiler version is this' is one call with {} - the toolchain version string for a bug report, diagnostic bundle or compatibility check.","whenNotToUse":["The project's OWN package version (from the package directive) - use ek9_query_package_version.","The full package directive (name, version, deps) - use ek9_query_package.","Build state (last outcome, freshness) rather than a version string - use ek9_query_build_status."],"details":"Pure static read of the compiler-binary version baked in at build time — no workspace, compile phase or symbol tables involved, so no trustLevel is emitted. The value is constant for the lifetime of the binary: call once per session and reuse from conversation history rather than re-invoking. Same value as the CLI 'ek9 -V'.","arguments":[],"lessons":[],"fixes":[],"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
{"name":"ek9_write_file","url":"https://ek9.io/mcp/ek9_write_file.html","category":"editor","description":"Answers first: status (applied | ready | would-fail | conflicts), written, edits[{file, type:create|overwrite, bytesWritten}] and contentHash; a .ek9 write carries wouldBeDiagnostics from the verifying compile, any other file is written as-is.","whenToUse":"You are creating a file or replacing one whole - one call with path + content; a .ek9 path is compile-verified, any other file is written as-is. On create a .ek9 path gets the shebang / defines module / //EOF boilerplate when missing; a verified apply is rolled back on new errors.","whenNotToUse":["A few text-level changes inside an EXISTING file - use ek9_edit_file (find/replace, line-replace, regex) rather than rewriting the whole file.","Reading existing file content — use ek9_read_file (the read counterpart).","Reformatting or semantically mutating existing .ek9 source — use ek9_format, or the semantic editors (ek9_add_field, ek9_add_method, ek9_move_construct); don't read-modify-write through this tool.","Renaming or deleting a file — use ek9_move_file / ek9_delete_file (metadata ops, not content writes)."],"details":"fileKind is inferred from the extension (.ek9 → ek9-source); pass it only to override. Boilerplate handling is create-only and idempotent on all three markers; on overwrite of ek9-source, missing markers attach warnings rather than mutating edited content. A .ek9 dry run scratch-compiles the would-be file (ready / would-fail); a .ek9 apply is verified by the post-write compile and rolled back on new diagnostics (would-fail + apply-rolled-back advisory, written:false) - wouldBeDiagnostics is present only on a verified write. Non-.ek9 targets are written without compile checking (non-ek9-file-not-compile-checked advisory). Writes are workspace-bounded and UTF-8; expectedContentHash (the contentHash ek9_read_file returned) guards overwrites against lost-update races; every applied write returns the new contentHash. An explicit module that diverges from the path-derived one attaches a module-name-mismatches-path warning — the write still succeeds.","arguments":[{"name":"content","type":"string","required":true,"description":"Content to write. For a .ek9 path on create, may be body-only — the writer prepends shebang + defines module and appends //EOF when missing."},{"name":"createIntermediateDirs","type":"boolean","required":false,"description":"When true (default), missing parent directories are created automatically."},{"name":"expectedContentHash","type":"string","required":false,"description":"The contentHash ek9_read_file (or a prior write) returned for the file's CURRENT content; the write is refused when the file changed since (lost-update protection)."},{"name":"fileKind","type":"string: text | ek9-source | env | config","required":false,"description":"Inferred from the extension (.ek9 → ek9-source, else text); pass it only to override. ek9-source: boilerplate injection on create + compile verification; env: KEY=VALUE; config: reserved."},{"name":"mode","type":"string: auto | create-only | overwrite-only","required":false,"description":"auto (default): create or overwrite; create-only: conflict if the file exists; overwrite-only: error if it doesn't."},{"name":"module","type":"string","required":false,"description":"Fully-qualified EK9 module name for a .ek9 create. Optional — defaults to the path-derived module under the workspace source root; an explicit value that differs emits a 'module-name-mismatches-path' warning."},{"name":"path","type":"string","required":true,"description":"File path: workspace-relative (preferred) or absolute inside the workspace. Created when absent (mode auto)."}],"lessons":["https://ek9.io/ide/project-files.html"],"fixes":[],"example":{"scenario":"Write negated membership as sent","request":{"content":"#!ek9\ndefines module com.example.names\n\n  defines function\n\n    isNew() as pure\n      ->\n        name as String\n        names as List of String\n      <- rtn as Boolean: not name in names\n\n//EOF\n","mode":"create-only","path":"Names.ek9"},"response":{"conflicts":[],"contentHash":"sha256:109c174f2975113c5d175a4ad480666eecec1141e785453f2eda39fdc0dcbd7f","edits":[{"boilerplateInjection":{"eof":"preserved","module":"preserved","shebang":"preserved"},"bytesWritten":194,"file":"Names.ek9","type":"create"}],"meta":{"serverMs":"<timing>"},"risk":{"crossesModuleBoundary":false,"estimatedSeverity":"trivial","fileCount":1,"lineCount":0,"touchesPublicApi":false,"touchesTests":false},"status":"applied","summary":"Created Names.ek9 (194 bytes)","workspaceHash":"<workspace-hash>","wouldBeDiagnostics":[],"written":true}},"validation":"from the MCP server's own registry; the example is a recorded call (an MCP probe) that the full-build gate replays, failing on any change"}
