Package com.ssgllc.fish.config.mcp

Class McpDeveloperToolsConfig.DeveloperTools

java.lang.Object

com.ssgllc.fish.config.mcp.McpDeveloperToolsConfig.DeveloperTools

Enclosing class:

McpDeveloperToolsConfig

public static class McpDeveloperToolsConfig.DeveloperTools
extends Object

Tool implementations for developer productivity.

Backed by ReportService, SqlValidator, CalculatedFieldService, ConfigTestService, BpmProcessInstanceService, ApplicationService, PerRequestDebugService, and DebugLogCaptureService.

Field Summary

Fields

Modifier and Type	Field	Description
protected final com.fasterxml.jackson.databind.ObjectMapper	mapper

Method Summary

Modifier and Type	Method	Description
protected String	bytesToString(byte[] bytes)	Decodes a byte array to a UTF-8 string.
String	checkReportSql(String name, String definition, String config, String summaryDefinition, String reportDefinitionId, String personalizedReportId)
String	describeClass(String className)
String	describeFunction(String functionName, String className)
protected String	errorJson(Exception e)	Produces a standard {"error":"<message>"} JSON response from an exception.
String	executeGroovyScript(String script, Map<String,Object> variables, String scriptLabel)
String	executeTextTemplate(String textTemplateName, Map<String,Object> variables)
protected String	flaggingErrors(Callable<String> action)	Invokes action and returns its JSON text.
String	getDebugLogs(String debugToken)
protected String	handleTool(Callable<Object> action)	Invokes action, serializes the result with toJson(java.lang.Object), and returns it.
String	listGroovyClasses()
String	listGroovyFunctions(String className, String filterText)
String	listSpelClasses()
String	listSpelFunctions(String className, String filterText)
String	setDebugLogging(Map<String,String> packageLevels)
String	testAttributeExpression(String entityType, String entityId, String expression, String runAsUserLogin)
String	testEntityLifecycleScript(String entityType, String entityId, String script, String lifecycleEvent, String scriptLabel)
String	testFullReport(String name, String definition, String config, String runAsUserLogin, String summaryDefinition, String reportDefinitionId, String personalizedReportId)
String	testMatchExpression(String entityType, String entityId, String potentialId, String matchExp, Double matchThreshold, Double notMatchThreshold)
String	testMergeExpression(String entityType, String bestRecordId, String supplementalId, String mergeExpression, boolean evaluateAsBoolean)
String	testProcessScript(String processInstanceId, String script, String scriptLabel)
String	testReportOutput(String name, String definition, Map<String,Object> parameters, String config, String runAsUserLogin, String summaryDefinition, String reportDefinitionId, String fileType, String inspection, String personalizedReportId)
String	testSpelExpression(String entityType, String entityId, String calcExpression, String runAsUserLogin)
protected String	toJson(Object value)	Serializes value to a compact JSON string (no indent).
String	validateReport(String name, String definition, String config, String runAsUserLogin, String reportDefinitionId)
String	validateSql(String sql)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

mapper

protected final com.fasterxml.jackson.databind.ObjectMapper mapper

Method Details

validateReport

@Tool(name="validate-report",
      description="Parse a report SQL template to extract parameters and output columns without executing. Adds a warnings list when a token looks like a mistyped input widget.")
public String validateReport(@ToolParam(required=false,description="Report name")
 String name,
 @ToolParam(required=false,description="Report SQL; user inputs are {TYPE|Label} widgets, e.g. {DATE|Start Date} (see report-development-guide)")
 String definition,
 @ToolParam(required=false,description="JSON config string")
 String config,
 @ToolParam(required=false,description="User login to impersonate")
 String runAsUserLogin,
 @ToolParam(required=false,description="Id of a saved report definition to test; a name, SQL or config passed with it replaces the saved value for this run only")
 String reportDefinitionId)

testReportOutput

@Tool(name="test-report-output",
      description="Execute a report SQL template with parameter values, returning up to 25 rows. With fileType (xlsx, pdf, csv, txt or xml) it renders that file in test mode, with the same row cap, and returns a description of the file instead of rows: sheets, column titles, cell types, number formats and widths for xlsx; page count, size and orientation for pdf; line counts and the header for csv and txt; the element structure for xml. For pdf and txt, cutOffText lists text the file cuts short to fit its box or column. Cell values and text are left out unless inspection=sample.")
public String testReportOutput(@ToolParam(required=false,description="Report name")
 String name,
 @ToolParam(required=false,description="Report SQL; user inputs are {TYPE|Label} widgets, e.g. {DATE|Start Date} (see report-development-guide)")
 String definition,
 @ToolParam(required=false,description="Parameter names to values")
 Map<String,Object> parameters,
 @ToolParam(required=false,description="JSON config string")
 String config,
 @ToolParam(required=false,description="User login to impersonate")
 String runAsUserLogin,
 @ToolParam(required=false,description="Summary SQL; may reference ${DETAIL_QUERY}")
 String summaryDefinition,
 @ToolParam(required=false,description="Id of a saved report definition to test; a name, SQL or config passed with it replaces the saved value for this run only")
 String reportDefinitionId,
 @ToolParam(required=false,description="xlsx, pdf, csv, txt or xml to render and describe that file; omit for the JSON rows")
 String fileType,
 @ToolParam(required=false,description="With fileType: shape (default) describes structure only; sample also returns the first rows or text and a failed Summary\'s database message, which can contain PHI")
 String inspection,
 @ToolParam(required=false,description="Id of a personalized report to test, in place of reportDefinitionId: its parent report runs with the saved columns and sort, but not the saved input defaults")
 String personalizedReportId)

testFullReport

@Tool(name="test-full-report",
      description="Smoke-test a report with auto-generated dummy parameter values.")
public String testFullReport(@ToolParam(required=false,description="Report name")
 String name,
 @ToolParam(required=false,description="Report SQL; user inputs are {TYPE|Label} widgets, e.g. {DATE|Start Date} (see report-development-guide)")
 String definition,
 @ToolParam(required=false,description="JSON config string")
 String config,
 @ToolParam(required=false,description="User login to impersonate")
 String runAsUserLogin,
 @ToolParam(required=false,description="Summary SQL; may reference ${DETAIL_QUERY}")
 String summaryDefinition,
 @ToolParam(required=false,description="Id of a saved report definition to test; a name, SQL or config passed with it replaces the saved value for this run only")
 String reportDefinitionId,
 @ToolParam(required=false,description="Id of a personalized report to test, in place of reportDefinitionId: its parent report runs with the saved columns and sort, but not the saved input defaults")
 String personalizedReportId)

checkReportSql

@Tool(name="check-report-sql",
      description="Run the report against the database at zero rows and return {\"ok\":true} or an error. The detail and summary SQL are parsed, planned and bound, but no rows come back, so the result never carries data. Every input is left unselected, so each widget comparison becomes 1 = 1 and is not checked, and a failure that happens only while rows are read (division by zero, a failed cast of a stored value) is not detected.")
public String checkReportSql(@ToolParam(required=false,description="Report name")
 String name,
 @ToolParam(required=false,description="Report SQL; user inputs are {TYPE|Label} widgets, e.g. {DATE|Start Date} (see report-development-guide)")
 String definition,
 @ToolParam(required=false,description="JSON config string")
 String config,
 @ToolParam(required=false,description="Summary SQL; may reference ${DETAIL_QUERY}")
 String summaryDefinition,
 @ToolParam(required=false,description="Id of a saved report definition to test; a name, SQL or config passed with it replaces the saved value for this run only")
 String reportDefinitionId,
 @ToolParam(required=false,description="Id of a personalized report to test, in place of reportDefinitionId: its parent report runs with the saved columns and sort, but not the saved input defaults")
 String personalizedReportId)

validateSql

@Tool(name="validate-sql",
      description="Validate SQL table and column references against the data model.")
public String validateSql(@ToolParam(description="SQL SELECT statement")
 String sql)

testSpelExpression

@Tool(name="test-spel-expression",
      description="Evaluate a SpEL expression against an entity instance.")
public String testSpelExpression(@ToolParam(description="Entity type name")
 String entityType,
 @ToolParam(description="Entity UUID")
 String entityId,
 @ToolParam(description="SpEL expression to evaluate")
 String calcExpression,
 @ToolParam(required=false,description="User login to impersonate")
 String runAsUserLogin)

testMatchExpression

@Tool(name="test-match-expression",
      description="Score a dedup match expression between two entities of the same type.")
public String testMatchExpression(@ToolParam(description="Entity type name")
 String entityType,
 @ToolParam(description="Primary entity UUID (.e)")
 String entityId,
 @ToolParam(description="Potential match UUID (.p)")
 String potentialId,
 @ToolParam(description="Match scoring expression")
 String matchExp,
 @ToolParam(description="MATCH threshold (0-100)")
 Double matchThreshold,
 @ToolParam(description="NOT_MATCH threshold (0-100)")
 Double notMatchThreshold)

testMergeExpression

@Tool(name="test-merge-expression",
      description="Evaluate a merge survivorship expression between two entities (.b=best, .s=supplemental).")
public String testMergeExpression(@ToolParam(description="Entity type name")
 String entityType,
 @ToolParam(description="Best/surviving record UUID (.b)")
 String bestRecordId,
 @ToolParam(description="Supplemental record UUID (.s)")
 String supplementalId,
 @ToolParam(description="Merge survivorship expression")
 String mergeExpression,
 @ToolParam(required=false,description="If true, returns boolean shouldKeepEntity")
 boolean evaluateAsBoolean)

testAttributeExpression

@Tool(name="test-attribute-expression",
      description="Test a boolean attribute security expression against an entity instance.")
public String testAttributeExpression(@ToolParam(description="Entity type name")
 String entityType,
 @ToolParam(description="Entity UUID")
 String entityId,
 @ToolParam(description="Boolean SpEL expression")
 String expression,
 @ToolParam(required=false,description="User login to impersonate")
 String runAsUserLogin)

listSpelClasses

@Tool(name="list-spel-classes",
      description="List the classes callable from a SpEL expression, with a one-line summary each. Follow up with list-spel-functions for one class\'s functions.")
public String listSpelClasses()

listGroovyClasses

@Tool(name="list-groovy-classes",
      description="List the classes callable from a Groovy script, with a one-line summary each. Wider than the SpEL set: adds the published utilities and bean instance methods (see boundAs). Follow up with list-groovy-functions for one class\'s functions.")
public String listGroovyClasses()

listSpelFunctions

@Tool(name="list-spel-functions",
      description="List SpEL-callable functions with a one-line summary each. Requires className (from list-spel-classes) or filterText - the whole surface is several hundred functions. filterText matches a function\'s name or its summary. Call describe-function for one function\'s full documentation and usage examples.")
public String listSpelFunctions(@ToolParam(required=false,description="Class simple or qualified name to scope to, e.g. DateUtil or f()")
 String className,
 @ToolParam(required=false,description="Substring matched against each function\'s name and its summary, e.g. \"email\"")
 String filterText)

listGroovyFunctions

@Tool(name="list-groovy-functions",
      description="List Groovy-callable functions with a one-line summary each. Requires className (from list-groovy-classes) or filterText - the whole surface is several hundred functions. filterText matches a function\'s name or its summary. Call describe-function for one function\'s full documentation and usage examples.")
public String listGroovyFunctions(@ToolParam(required=false,description="Class simple or qualified name to scope to, e.g. DateUtil or f()")
 String className,
 @ToolParam(required=false,description="Substring matched against each function\'s name and its summary, e.g. \"email\"")
 String filterText)

describeClass

@Tool(name="describe-class",
      description="Full documentation for one callable class: both javadoc paragraphs, the Spring bean name Groovy reaches it through, and its public fields. Use when a class summary from a list call is not enough - several classes put a usage warning in the second paragraph, which the listings do not carry.")
public String describeClass(@ToolParam(description="Class simple or qualified name, or f() for the builder root")
 String className)

describeFunction

@Tool(name="describe-function",
      description="Full documentation for one SpEL or Groovy function: description, usage examples, parameters, return value and deprecation. Returns every match, since a bare name can be ambiguous across overloads and classes - narrow with className, and compare the signature on each result to pick an overload.")
public String describeFunction(@ToolParam(description="Function name, e.g. getConceptFromCode")
 String functionName,
 @ToolParam(required=false,description="Class simple or qualified name to disambiguate")
 String className)

executeGroovyScript

@Tool(name="execute-groovy-script",
      description="Execute a Groovy script with optional bound variables; Spring beans available implicitly.")
public String executeGroovyScript(@ToolParam(description="Groovy script source code")
 String script,
 @ToolParam(required=false,description="Bound variable names to values")
 Map<String,Object> variables,
 @ToolParam(required=false,description="Free-form label for logs, stack traces and the script audit event. NOT a TextTemplate name - use execute-text-template to run a registered template by name.")
 String scriptLabel)

executeTextTemplate

@Tool(name="execute-text-template",
      description="Execute a named TextTemplate Groovy script with optional bound variables.")
public String executeTextTemplate(@ToolParam(description="TextTemplate name")
 String textTemplateName,
 @ToolParam(required=false,description="Bound variable names to values")
 Map<String,Object> variables)

testEntityLifecycleScript

@Tool(name="test-entity-lifecycle-script",
      description="Test a Groovy script with lifecycle-event-bound variables for a real entity.")
public String testEntityLifecycleScript(@ToolParam(description="Entity type name")
 String entityType,
 @ToolParam(description="Entity UUID for context")
 String entityId,
 @ToolParam(description="Groovy script source code")
 String script,
 @ToolParam(description="Lifecycle event name")
 String lifecycleEvent,
 @ToolParam(required=false,description="Free-form label for logs, stack traces and the script audit event. NOT a TextTemplate name - use execute-text-template to run a registered template by name.")
 String scriptLabel)

testProcessScript

@Tool(name="test-process-script",
      description="Execute a Groovy script in a running process instance context (requires ROLE_SUPER).")
public String testProcessScript(@ToolParam(description="Running process instance UUID")
 String processInstanceId,
 @ToolParam(description="Groovy script source code")
 String script,
 @ToolParam(required=false,description="Free-form label for logs, stack traces and the script audit event. NOT a TextTemplate name - use execute-text-template to run a registered template by name.")
 String scriptLabel)

setDebugLogging

@Tool(name="set-debug-logging",
      description="Create a per-request debug token for specified package log levels.")
public String setDebugLogging(@ToolParam(description="Package name to log level map")
 Map<String,String> packageLevels)

getDebugLogs

@Tool(name="get-debug-logs",
      description="Retrieve captured debug log entries by token.")
public String getDebugLogs(@ToolParam(description="Debug token from set-debug-logging")
 String debugToken)

toJson

protected String toJson(Object value)

Serializes value to a compact JSON string (no indent). Returns {"error":"serialization failed"} if serialization throws.

Parameters:

value - the object to serialize; may be null

Returns:

compact JSON string

bytesToString

protected String bytesToString(byte[] bytes)

Decodes a byte array to a UTF-8 string. Used to convert binary report output to a returnable string.

Parameters:

bytes - raw bytes

Returns:

decoded string

handleTool

protected String handleTool(Callable<Object> action)

Invokes action, serializes the result with toJson(java.lang.Object), and returns it. Any exception thrown by the action is caught and converted to a standard {"error":"<message>"} response via errorJson(java.lang.Exception). Use this in every @Tool method to eliminate identical try/catch boilerplate.

Parameters:

action - the tool logic to invoke; may throw any exception

Returns:

compact JSON string — the serialized result on success, or an error object on failure

flaggingErrors

protected String flaggingErrors(Callable<String> action)

Invokes action and returns its JSON text. A failure is thrown as a McpToolsSupport.McpToolFailure carrying the same {"error":"<message>"} text errorJson(java.lang.Exception) produces, so the MCP layer marks the result isError while the client still reads the familiar error object.

Parameters:

action - the tool logic, returning the tool's JSON text; may throw any exception

Returns:

the JSON text the action produced

errorJson

protected String errorJson(Exception e)

Produces a standard {"error":"<message>"} JSON response from an exception. Falls back to the simple class name when Throwable.getMessage() is null.

Parameters:

e - the exception to convert

Returns:

JSON error string