refactor(tools)!: name every tool for its server and its result - #116
Merged
Conversation
Record the rules the v2 rename follows: the apexlog_ prefix, a verb that states the shape of the result, banned verbs, and eight field rules. Add "don't state what the caller can derive" to the shaping conventions. Refs #107
Every failure to open the log reported "Log file not found", so a permission error, a directory in place of a file, or an exhausted descriptor table all sent the caller to look for a file that was there. Report ENOENT as missing, name the code otherwise, and keep the original error as `cause`. Refs #109
All three analysis tools documented an absolute path and accepted any string. A relative one resolved against the server's working directory, which is where the client spawned the server and not where the caller is, so it read a different file or none and reported neither. Declare the path once in apexLogSource, the module the three tools already share for loading a log, and refine it to absolute. Refinements do not reach the JSON schema, so the tool definitions are unchanged at ~1,053 tokens. Resolve execute_anonymous's outputDir to absolute too, so the filePath it returns stays one the analysis tools accept. A relative outputDir now anchors to the project root, the base the default already used. Refs #109
Only SIGINT was trapped, so a supervised restart, a container stop, or a client that ends a stdio server hit Node's default and exited without the clean close. Refs #109
execute_anonymous created directories anywhere the process could write, from an agent-supplied path. The MCP spec expects a server to work inside the roots the client declares, so report rather than refuse: the log is still written, and both the response and stderr name where it went. Silent for the default outputDir, for one inside a root, and for a client that declares no roots. Symlinks are followed on both sides. Refs #109
isMethodNode kept EXECUTION_STARTED and ENTERING_MANAGED_PKG, which own no time, and dropped every query, DML, flow and workflow node, which do. This is the one classification the tools will share, with grouping so a query repeated in a loop is one row carrying its call count. Nothing calls it yet. Refs #108
find_performance_bottlenecks returned four hand-built sections that
covered six of the thirteen limits, repeated the CPU figure as prose,
and ranked methods by namespace — a second, disagreeing answer to the
question analyze_apex_log_performance already answers.
It now returns one table: the limits at or above a threshold, worst
first, as {limit, used, max, usedPercentage} rows. All thirteen are
covered. The table is reported even when empty, beside the threshold
that selected it, so "nothing is at risk" is an answer rather than a
gap.
BREAKING CHANGE: the analysisType parameter is removed and replaced by
threshold. The cpuBottlenecks, databaseBottlenecks, methodBottlenecks
and governorLimitWarnings sections and the note field are gone.
Refs #108
analyze_apex_log_performance ranked methods, so the time a transaction spent in queries, DML, flows and managed packages was invisible. It now ranks every timed operation by self time in one table, with kind, namespace, limit, minSelfMs and groupBy to select and fold the rows. The prose summary and the recommendations are gone: the table says what they said. returnedSelfPercentage carries the one fact the rows cannot — what share of the transaction they account for between them. The definition costs 32% more, for the five selection parameters. The response costs 33% less on the governor-heavy log and 54% less on the minimal one. Closes #108
get_apex_log_summary reported five hand-picked totals and only the limits something was spent against. It now reports where the time went, one row per kind of operation, and what each namespace consumed. timeByKind names the trace category that decides whether a kind reaches the log, so a zero can be read: soql 0 beside DB NONE means the queries were not logged, and beside DB FINEST means none ran. limitsByNamespace shows a managed package spending your CPU time, which no tool could show before. truncated reads the top-level lines. The parser marks the line that lost its exit event, not the log, so the root flag is always false. The response costs 16% more on a log that uses its limits, for the two tables. No fact was dropped to pay for them. Closes #62
The response carried a sentence telling the caller to write a .gitignore entry, on the runs where the output directory was new. That is a rule applied to a fact the caller could not see. It now states the fact, outputDirCreated, and lets the agent apply its own rule. Four tokens where the sentence was fifteen. It is reported either way, not only when true. An absent field cannot be told apart from one the server never worked out. success is now succeeded, which is how every other boolean in the server reads. Closes #109
An unprefixed name collides between servers: get_issue and list_issues ship in both the GitHub and the Sentry server. A verb that names the work rather than the result cannot be told apart from another tool's, and analyze, find and detect all name work. get_apex_log_summary -> apexlog_get_summary analyze_apex_log_performance -> apexlog_list_slow_operations find_performance_bottlenecks -> apexlog_list_limit_risks execute_anonymous -> apexlog_execute_anonymous The modules and their exports follow the tool they serve. The 1.0.0 changelog section keeps the names that shipped. Closes #107
lcottercertinia
approved these changes
Aug 12, 2026
lcottercertinia
added this pull request to the merge queue
Aug 12, 2026
lukecotter
added a commit
to lukecotter/debug-log-analyzer-mcp
that referenced
this pull request
Aug 12, 2026
Stacked on certinia#116. "Migrating from 1.x" covered the org flags alone, so a reader upgrading had nothing that named the tools. It now maps every 1.x name to its 2.0 one, and says what needs updating by hand. Client allow and deny lists are the part that breaks quietly. Claude Code writes them as `mcp__<server>__<tool>`, so a stale `mcp__apex-log-mcp__execute_anonymous` stops permitting the tool without saying so. The flag content is unchanged, under an "Org access" heading so the two subsections read apart. Closes certinia#107
This was referenced Aug 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #115.
An unprefixed name collides between servers:
get_issueandlist_issuesship in both the GitHub and the Sentry server. A verb that names the work rather than the result cannot be told apart from another tool's — andanalyze,findanddetectall name work.get_apex_log_summaryapexlog_get_summaryanalyze_apex_log_performanceapexlog_list_slow_operationsfind_performance_bottlenecksapexlog_list_limit_risksexecute_anonymousapexlog_execute_anonymousThe modules and their exported symbols follow the tool they serve:
analyzeLogPerformance.tsislistSlowOperations.ts,findPerformanceBottlenecks.tsislistLimitRisks.ts, and the golden files are named for their tool.The 1.0.0 changelog section keeps the names that shipped.
The definitions now cost ~1,128 tokens, one more than before — the longer names.
Closes #107