@certinia/apex-log-mcp 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.txt +28 -0
- package/README.md +216 -0
- package/dist/ApexLogParser.js +2788 -0
- package/dist/index.js +77 -0
- package/dist/salesforce/connection.js +15 -0
- package/dist/salesforce/debugLevels.js +125 -0
- package/dist/salesforce/traceFlags.js +43 -0
- package/dist/salesforce/users.js +13 -0
- package/dist/tools/analyzeLogPerformance.js +150 -0
- package/dist/tools/executeAnonymous.js +182 -0
- package/dist/tools/findPerformanceBottlenecks.js +165 -0
- package/dist/tools/getLogSummary.js +88 -0
- package/package.json +73 -0
package/LICENSE.txt
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Certinia Inc. All rights reserved.
|
|
4
|
+
|
|
5
|
+
Redistribution and use in source and binary forms, with or without
|
|
6
|
+
modification, are permitted provided that the following conditions are met:
|
|
7
|
+
|
|
8
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
9
|
+
list of conditions and the following disclaimer.
|
|
10
|
+
|
|
11
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
12
|
+
this list of conditions and the following disclaimer in the documentation
|
|
13
|
+
and/or other materials provided with the distribution.
|
|
14
|
+
|
|
15
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
16
|
+
contributors may be used to endorse or promote products derived from
|
|
17
|
+
this software without specific prior written permission.
|
|
18
|
+
|
|
19
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
20
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
21
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
22
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
23
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
24
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
25
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
26
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
27
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
28
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
package/README.md
ADDED
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
# Apex Log MCP Server
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@certinia/apex-log-mcp)
|
|
4
|
+
[](https://github.com/certinia/debug-log-analyzer-mcp/actions/workflows/ci.yml)
|
|
5
|
+
[](https://opensource.org/licenses/BSD-3-Clause)
|
|
6
|
+
[](https://nodejs.org/)
|
|
7
|
+
[](https://www.typescriptlang.org/)
|
|
8
|
+
|
|
9
|
+
**An MCP server that gives AI assistants tools to analyze Salesforce Apex debug logs for performance bottlenecks, slow methods, and governor limit usage.**
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<img src="https://raw.githubusercontent.com/certinia/debug-log-analyzer-mcp/main/docs/images/apex-log-mcp.png" alt="Claude analyzing an Apex debug log for performance bottlenecks and governor limit concerns" width="800" />
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
Give your AI assistant — Claude, Copilot, or any MCP-compatible client — the ability to parse Apex debug logs and surface the performance insights that matter. Instead of scrolling through thousands of log lines, ask your assistant to find what's slow and why.
|
|
16
|
+
|
|
17
|
+
[Quick Start](#quick-start) |
|
|
18
|
+
[What You Can Do](#what-you-can-do) |
|
|
19
|
+
[Tools Reference](#tools-reference) |
|
|
20
|
+
[Configuration](#configuration) |
|
|
21
|
+
[How It Works](#how-it-works) |
|
|
22
|
+
[Documentation](#documentation) |
|
|
23
|
+
[Contributing](#contributing) |
|
|
24
|
+
[Contributors](#contributors) |
|
|
25
|
+
[License](#license)
|
|
26
|
+
|
|
27
|
+
## Quick Start
|
|
28
|
+
|
|
29
|
+
Add to your MCP client configuration (`claude_desktop_config.json`, VS Code `mcp.json`, etc.):
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"mcpServers": {
|
|
34
|
+
"apex-log-mcp": {
|
|
35
|
+
"command": "npx",
|
|
36
|
+
"args": ["-y", "@certinia/apex-log-mcp"]
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
That's it. Open a conversation and ask your AI assistant to analyze an Apex debug log.
|
|
43
|
+
|
|
44
|
+
## What You Can Do
|
|
45
|
+
|
|
46
|
+
Ask your AI assistant to work with Apex debug logs using natural language:
|
|
47
|
+
|
|
48
|
+
- "Give me a summary of this debug log"
|
|
49
|
+
- "Show me the 5 slowest methods in the default namespace"
|
|
50
|
+
- "Are we approaching any governor limits in this transaction?"
|
|
51
|
+
- "Run this Apex against my scratch org and analyze the performance"
|
|
52
|
+
|
|
53
|
+
## Tools Reference
|
|
54
|
+
|
|
55
|
+
### analyze_apex_log_performance
|
|
56
|
+
|
|
57
|
+
Rank methods in an Apex debug log by self-execution time. Returns method names, durations (in ms), SOQL/DML counts, and optimization recommendations. Best for finding which specific methods to optimize.
|
|
58
|
+
|
|
59
|
+
| Parameter | Type | Required | Description |
|
|
60
|
+
| ------------- | ------ | -------- | ----------------------------------------------------------------- |
|
|
61
|
+
| `logFilePath` | string | Yes | Absolute path to the Apex debug log file (.log) |
|
|
62
|
+
| `topMethods` | number | No | Number of slowest methods to return (default: 10) |
|
|
63
|
+
| `minDuration` | number | No | Minimum duration in milliseconds to include a method (default: 0) |
|
|
64
|
+
| `namespace` | string | No | Filter methods by namespace |
|
|
65
|
+
|
|
66
|
+
### get_apex_log_summary
|
|
67
|
+
|
|
68
|
+
Get a high-level summary of an Apex debug log including total execution time (in ms), method count, SOQL/DML totals, governor limits, and active namespaces. Best for a quick overview before deeper analysis.
|
|
69
|
+
|
|
70
|
+
| Parameter | Type | Required | Description |
|
|
71
|
+
| ------------- | ------ | -------- | ----------------------------------------------- |
|
|
72
|
+
| `logFilePath` | string | Yes | Absolute path to the Apex debug log file (.log) |
|
|
73
|
+
|
|
74
|
+
### find_performance_bottlenecks
|
|
75
|
+
|
|
76
|
+
Check whether an Apex log transaction is approaching governor limits (flags usage above 80%). Analyzes CPU time, SOQL/DML limits, query rows, and method execution patterns by namespace. Best for checking if a transaction is at risk of hitting governor limits.
|
|
77
|
+
|
|
78
|
+
| Parameter | Type | Required | Description |
|
|
79
|
+
| -------------- | ------ | -------- | ---------------------------------------------------- |
|
|
80
|
+
| `logFilePath` | string | Yes | Absolute path to the Apex debug log file (.log) |
|
|
81
|
+
| `analysisType` | string | No | Type of analysis (default: `all`). See values below. |
|
|
82
|
+
|
|
83
|
+
**`analysisType` values:**
|
|
84
|
+
|
|
85
|
+
| Value | Description |
|
|
86
|
+
| ---------- | ------------------------------------------------------ |
|
|
87
|
+
| `cpu` | Checks CPU time governor limit |
|
|
88
|
+
| `database` | Checks SOQL query, DML statement, and query row limits |
|
|
89
|
+
| `methods` | Groups methods by namespace with duration totals |
|
|
90
|
+
| `all` | Runs all three analysis types (default) |
|
|
91
|
+
|
|
92
|
+
### execute_anonymous
|
|
93
|
+
|
|
94
|
+
Executes anonymous Apex code against any authenticated Salesforce org. Saves the resulting debug log to a local file and returns a summary with the file path. Use the file path with `get_apex_log_summary`, `analyze_apex_log_performance`, or `find_performance_bottlenecks` for deeper analysis.
|
|
95
|
+
|
|
96
|
+
| Parameter | Type | Required | Description |
|
|
97
|
+
| ------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
98
|
+
| `apex` | string | Yes | The anonymous Apex to be executed |
|
|
99
|
+
| `targetOrg` | string | No | Alias or username of the target Salesforce org. Uses the project default if not specified. |
|
|
100
|
+
| `outputDir` | string | No | Directory to save the debug log file. Defaults to `.apex-log-mcp/` in the project root. |
|
|
101
|
+
| `debugLevel` | string \| object | No | Controls the trace flag debug levels. Use `"default"` to reset all categories to defaults, a log level string (e.g. `"FINEST"`) to set all categories to that level, or an object to override specific categories. Omit to keep existing config. |
|
|
102
|
+
|
|
103
|
+
**`debugLevel` as an object** — override specific categories, the rest keep their defaults:
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{ "database": "FINEST", "apexCode": "FINE" }
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Each category accepts a log level: `NONE`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `FINE`, `FINER`, `FINEST`
|
|
110
|
+
|
|
111
|
+
**Default debug levels** (used when `debugLevel` is omitted):
|
|
112
|
+
|
|
113
|
+
| Category | Default Level |
|
|
114
|
+
| --------------- | ------------- |
|
|
115
|
+
| `apexCode` | FINE |
|
|
116
|
+
| `apexProfiling` | FINE |
|
|
117
|
+
| `callout` | DEBUG |
|
|
118
|
+
| `database` | FINEST |
|
|
119
|
+
| `nba` | INFO |
|
|
120
|
+
| `system` | DEBUG |
|
|
121
|
+
| `validation` | DEBUG |
|
|
122
|
+
| `visualforce` | FINE |
|
|
123
|
+
| `wave` | INFO |
|
|
124
|
+
| `workflow` | FINE |
|
|
125
|
+
|
|
126
|
+
**Example prompts:**
|
|
127
|
+
|
|
128
|
+
- "Execute this Apex and show me the log: `System.debug('Hello');`"
|
|
129
|
+
- "Run a query for all Accounts and analyze the performance"
|
|
130
|
+
- "Execute this Apex with all debug levels set to FINEST"
|
|
131
|
+
- "Run this Apex against my QA org with database logging set to FINEST"
|
|
132
|
+
|
|
133
|
+
> **Note:** Requires `--allowed-orgs` to be [configured](#enabling-execute_anonymous). Uses the project's default org unless `targetOrg` is specified. The debug log is saved to a local file (default: `.apex-log-mcp/`) and the response includes the file path, org username (and alias, if set), and execution summary. Add `.apex-log-mcp/` to your `.gitignore` to avoid committing debug logs.
|
|
134
|
+
|
|
135
|
+
## Configuration
|
|
136
|
+
|
|
137
|
+
The [Quick Start](#quick-start) configuration is all you need for log analysis tools. The sections below cover enabling `execute_anonymous`.
|
|
138
|
+
|
|
139
|
+
### Enabling `execute_anonymous`
|
|
140
|
+
|
|
141
|
+
The `execute_anonymous` tool is **disabled by default**. To enable it, pass `--allowed-orgs` with a comma-separated list of allowed orgs:
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"mcpServers": {
|
|
146
|
+
"apex-log-mcp": {
|
|
147
|
+
"command": "npx",
|
|
148
|
+
"args": [
|
|
149
|
+
"-y",
|
|
150
|
+
"@certinia/apex-log-mcp",
|
|
151
|
+
"--allowed-orgs",
|
|
152
|
+
"ALLOW_ALL_ORGS"
|
|
153
|
+
]
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### Allowed org tokens
|
|
160
|
+
|
|
161
|
+
| Token | Description |
|
|
162
|
+
| ------------------------ | ------------------------------------------------------------------------ |
|
|
163
|
+
| `ALLOW_ALL_ORGS` | Permits execution against any authenticated org |
|
|
164
|
+
| `DEFAULT_TARGET_ORG` | Resolves the project/global default `target-org` from Salesforce CLI |
|
|
165
|
+
| `DEFAULT_TARGET_DEV_HUB` | Resolves the project/global default `target-dev-hub` from Salesforce CLI |
|
|
166
|
+
|
|
167
|
+
You can also pass org usernames or aliases directly:
|
|
168
|
+
|
|
169
|
+
```json
|
|
170
|
+
"args": ["-y", "@certinia/apex-log-mcp", "--allowed-orgs", "dev@example.com,my-scratch-org"]
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## How It Works
|
|
174
|
+
|
|
175
|
+
This server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to expose Apex log analysis as tools that any MCP-compatible AI client can call.
|
|
176
|
+
|
|
177
|
+
- **Runs as a local process** — your AI client spawns the server and communicates locally. No network requests, no API keys.
|
|
178
|
+
- **Uses the same parser as the [Apex Log Analyzer VS Code extension](https://github.com/certinia/debug-log-analyzer)** — battle-tested parsing of the Apex debug log format.
|
|
179
|
+
- **Returns structured data** — all durations in milliseconds, governor limits as used/limit pairs, methods with SOQL/DML counts — so your AI assistant can reason about the results.
|
|
180
|
+
|
|
181
|
+
## Documentation
|
|
182
|
+
|
|
183
|
+
- [User Guide & Docs](https://certinia.github.io/debug-log-analyzer/)
|
|
184
|
+
- [MCP Specification](https://modelcontextprotocol.io/)
|
|
185
|
+
|
|
186
|
+
### Related Projects
|
|
187
|
+
|
|
188
|
+
- [Apex Log Analyzer VS Code Extension](https://github.com/certinia/debug-log-analyzer) — Full-featured Apex log analyzer for VS Code
|
|
189
|
+
|
|
190
|
+
## Contributing
|
|
191
|
+
|
|
192
|
+
We welcome contributions! Please see our [Contributing Guide](https://github.com/certinia/debug-log-analyzer-mcp/blob/main/CONTRIBUTING.md) for details.
|
|
193
|
+
|
|
194
|
+
- [Developing](https://github.com/certinia/debug-log-analyzer-mcp/blob/main/DEVELOPING.md) — Set up your development environment
|
|
195
|
+
- [Code of Conduct](https://github.com/certinia/debug-log-analyzer-mcp/blob/main/CODE_OF_CONDUCT.md) — Community guidelines
|
|
196
|
+
|
|
197
|
+
## Contributors
|
|
198
|
+
|
|
199
|
+
Thanks to our amazing contributors!
|
|
200
|
+
|
|
201
|
+
<p align="center">
|
|
202
|
+
<a href="https://github.com/certinia/debug-log-analyzer-mcp/graphs/contributors">
|
|
203
|
+
<img src="https://contrib.rocks/image?repo=certinia/debug-log-analyzer-mcp&max=25" />
|
|
204
|
+
</a>
|
|
205
|
+
</p>
|
|
206
|
+
|
|
207
|
+
## License
|
|
208
|
+
|
|
209
|
+
<p align="center">
|
|
210
|
+
Copyright © Certinia Inc. All rights reserved.
|
|
211
|
+
</p>
|
|
212
|
+
<p align="center">
|
|
213
|
+
<a href="https://opensource.org/licenses/BSD-3-Clause">
|
|
214
|
+
<img src="https://img.shields.io/badge/License-BSD_3--Clause-blue.svg?style=flat-square"/>
|
|
215
|
+
</a>
|
|
216
|
+
</p>
|