getappmap · kgilpin · Jun 22, 2026
diff --git a/docs/appmap-docs.md b/docs/appmap-docs.md
@@ -18,7 +18,7 @@ By using AppMap data, Navie is the first AI code architect with the context to u
 
 Over 90,000 software developers are using the [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap) and the [AppMap plugin for JetBrains](https://plugins.jetbrains.com/plugin/16701-appmap).
 
-<a class="btn btn-primary btn-lg" href="/docs/get-started-with-appmap/">Get Started</a>
+<a class="btn btn-primary btn-lg" href="/docs/get-started-with-appmap/">Get Started</a> <a class="btn btn-secondary btn-lg" href="/docs/troubleshooting/">Troubleshooting</a>
 
 ![AppMap Navie with Sequence diagram in Visual Studio Code](/assets/img/docs/vscode-with-navie-prompt.webp)
 _AppMap Navie with Sequence diagram in Visual Studio Code_

diff --git a/docs/get-started-with-appmap/navie-ai-quickstart.md b/docs/get-started-with-appmap/navie-ai-quickstart.md
@@ -29,7 +29,7 @@ After you complete the installation of AppMap for your code editor. Open the Nav
 
 To open the Navie Chat, open the AppMap plugin in the sidebar menu for your code editor, and select the `New Navie Chat` option.
 
-![Open Navie](/assets/img/open-navie.webp)
+![Open Navie](/assets/img/open-navie.png)
 
 ## Ask Navie about your App
 
@@ -65,6 +65,24 @@ The Navie UI includes a standard chat window, and a context panel which will inc
 
 ![Navie Context Window](/assets/img/navie-context-window.webp)
 
+## Review Your Code
+
+You can also use Navie to review your code. This is a great way to get an overview of your codebase, identify potential issues, and improve the quality of your code.
+Navie uses the same types of data to perform code review as it does for answering questions, including code snippets, sequence diagrams, traces, and other I/O data.
+
+To start a code review, click the `Review Your Code` button in the Navie sidebar. This will generate a list of suggested improvements for your codebase, including:
+
+![Review Your Code](/assets/img/review_your_code_button.png)
+
+- Potential bugs
+- SQL query optimizations
+- HTTP request optimizations
+- Security vulnerabilities
+- Performance improvements
+- Code design improvements and anti-patterns
+
+... and more. Because Navie uses AppMap Data, it can provide more accurate and relevant suggestions than other code review tools.
+
 ## Improve Navie AI Responses with AppMap Data
 
 Generate AppMap Data and you will greatly improve the quality of your Navie AI responses. With AppMap Data for your project, you can now ask much deeper architectural questions about your application. This is possible because of the additional context from AppMap Data and the higher accuracy and relevance of the code snippets which are relevant to your question.

diff --git a/docs/reference/appmap-airgapped-install.md b/docs/reference/appmap-airgapped-install.md
@@ -345,6 +345,13 @@ To open the Output window, on the menu bar, choose View > Output, or in Windows
 
 ![Open View in VS Code](/assets/img/docs/vscode-output-1.webp)
 
+When reviewing logs, pay attention to startup errors that might indicate:
+- System compatibility issues (e.g., GLIBC version requirements on Linux)
+- Permission problems (especially on Windows)
+- Temporary directory access restrictions
+
+For detailed information about common error patterns and their solutions, see our [VS Code troubleshooting guide](/docs/troubleshooting/vscode).
+
 Click on the output log dropdown in the right corner to view a list of all the available output logs.
 
 ![Open Output logs list](/assets/img/docs/vscode-output-2.webp)
@@ -369,10 +376,18 @@ Next, open `Help` > `Show Log...` will open the IDE log file.
 
 ## Support
 
-For help with your offline install of AppMap Navie, please open a new support request by emailing [support@appmap.io](mailto:support@appmap.io)
+If you encounter startup issues with the VS Code extension, first check our [troubleshooting guide](/docs/troubleshooting/vscode) for solutions to common problems like:
+- Linux GLIBC version compatibility requirements
+- Windows temporary directory permissions
+- Extension startup failures
 
-Include the following information in your support request.
+If you're still experiencing issues with your offline installation of AppMap Navie, please open a new support request by emailing [support@appmap.io](mailto:support@appmap.io)
 
+Include the following information in your support request:
+- Any error messages from the VS Code Output panel (AppMap: Services channel)
+- Your operating system version and details:
+  - For Linux: output of `ldd --version`
+  - For Windows: OS build number and whether VS Code is running as administrator
 - Company Name
 - Code editor name and version (e.g. VS Code or JetBrains)
 - AppMap binary version

diff --git a/docs/reference/appmap-mcp.md b/docs/reference/appmap-mcp.md
@@ -0,0 +1,158 @@
+---
+layout: docs
+title: Docs - Reference
+description: "Reference for the AppMap MCP server, which exposes recorded AppMap Data to AI assistants as read-only query tools over the Model Context Protocol."
+toc: true
+reference: true
+step: 12
+name: AppMap MCP Server
+---
+
+# AppMap MCP Server
+
+- [AppMap MCP Server](#appmap-mcp-server)
+  - [Overview](#overview)
+  - [Prerequisites](#prerequisites)
+    - [Install the AppMap CLI](#install-the-appmap-cli)
+    - [Build the query index](#build-the-query-index)
+  - [Starting the server](#starting-the-server)
+    - [Options](#options)
+  - [Configuring an MCP client](#configuring-an-mcp-client)
+  - [Tools](#tools)
+    - [Common filters](#common-filters)
+    - [Orientation and ranking](#orientation-and-ranking)
+    - [Finding records](#finding-records)
+    - [Analyzing recordings](#analyzing-recordings)
+  - [Resources](#resources)
+  - [GitHub repository](#github-repository)
+
+## Overview
+
+The AppMap MCP server exposes recorded [AppMap Data](/docs/reference) to AI assistants as a set of read-only query tools over the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP-capable client &mdash; for example an AI coding assistant or chat client &mdash; can connect to the server and ask questions about how your application actually ran: which endpoints are slow, where time is spent, what SQL was issued, what exceptions occurred, and how a single request executed end to end.
+
+The server reads from a pre-built query database that AppMap maintains from your recorded AppMap Data. It never modifies your AppMap Data or your application &mdash; it only answers queries.
+
+The MCP server is part of the [AppMap CLI](/docs/reference/appmap-client-cli) and is started with the `appmap query mcp` command. It communicates over standard input and output (stdio) using newline-delimited [JSON-RPC 2.0](https://www.jsonrpc.org/specification) messages, which is the standard MCP stdio transport.
+
+## Prerequisites
+
+### Install the AppMap CLI
+
+The MCP server ships with the AppMap CLI. Install the `appmap` binary by following the instructions in the [AppMap CLI reference](/docs/reference/appmap-client-cli#prerequisites).
+
+### Build the query index
+
+The MCP server reads from a query database (`query.db`) that is derived from your recorded AppMap Data. Build or refresh this index by running the `index` command in your project:
+
+```console
+$ appmap index
+```
+{: .example-code}
+
+If the query database has not been built, the MCP server reports that the query DB was not found and instructs you to run `appmap index` first. Re-run `appmap index` after recording new AppMap Data so the server queries the latest results.
+
+<div class="alert alert-info">
+If you use the AppMap plugin for <a href="/docs/reference/vscode">Visual Studio Code</a> or <a href="/docs/reference/jetbrains">JetBrains</a>, you do not need to run <code>appmap index</code> yourself. The plugin runs the index command automatically in <code>--watch</code> mode for every <code>appmap.yml</code> file it finds in your project, keeping the query database up to date as you record new AppMap Data.
+</div>
+
+## Starting the server
+
+Run the MCP server from the root of your project:
+
+```console
+$ appmap query mcp
+```
+{: .example-code}
+
+The server reads JSON-RPC requests from standard input and writes responses to standard output, one JSON object per line. All logging is written to standard error so that it does not corrupt the protocol stream &mdash; on startup the server prints `appmap mcp listening on stdio` to standard error.
+
+In normal use you do not run this command by hand. Instead, you configure your MCP client to launch it (see [Configuring an MCP client](#configuring-an-mcp-client)).
+
+### Options
+
+| Option | Description |
+| ------ | ----------- |
+| `-d`, `--directory` | Program working directory. |
+| `--appmap-dir` | Directory containing AppMap Data. |
+| `--query-db` | Path to the `query.db` file, overriding the default location. |
+
+## Configuring an MCP client
+
+MCP clients launch the server as a stdio subprocess. Most clients accept a JSON configuration that names the command to run and the directory to run it in. The exact file and field names vary by client, but the configuration follows this shape:
+
+```json
+{
+  "mcpServers": {
+    "appmap": {
+      "command": "appmap",
+      "args": ["query", "mcp"]
+    }
+  }
+}
+```
+
+By default the server queries the project in the client's working directory. To query a different project, pass `--directory` in `args`. Use the `--appmap-dir` or `--query-db` options if your AppMap Data or query database lives in a non-default location. Make sure the `appmap` binary is on the `PATH` available to the client, or use an absolute path for `command`.
+
+<div class="alert alert-info">
+The query database must already exist before the client connects. Run <code>appmap index</code> in the project first, and re-run it whenever you record new AppMap Data.
+</div>
+
+## Tools
+
+The server exposes the following tools. Every list tool returns a paged result of the form `{ rows, total, limit, offset }`, and every tool returns its result as JSON. When orienting against an unfamiliar project, start with `list_endpoints` to see the available routes and where time and errors are concentrated.
+
+### Common filters
+
+Most tools accept a shared set of optional filters to narrow results:
+
+| Filter | Description |
+| ------ | ----------- |
+| `route` | Limit to a specific HTTP route (for example `GET /users/:id`). |
+| `status` | Limit to a specific HTTP status code. |
+| `duration` | Limit to records at or above a minimum elapsed time. |
+| `branch` | Limit to recordings captured on a git branch. |
+| `commit` | Limit to recordings captured at a git commit. |
+| `since`, `until` | Limit to a time range. |
+| `appmap` | Limit to a single recording, identified by its canonical path. |
+| `limit`, `offset` | Page through results. |
+
+### Orientation and ranking
+
+| Tool | Description |
+| ---- | ----------- |
+| `list_endpoints` | Per-route summary table with request count, average and p95 latency, and error rate. The recommended first call when exploring a project. Sort by `count`, `avg`, `p95`, or `err`. |
+| `function_hotspots` | Functions ranked by total elapsed time across recordings, with a representative source path, line number, and fully-qualified id. Filter by `route` or `class`. |
+| `sql_hotspots` | SQL queries ranked by total elapsed time, deduplicated by query text, with call count and average latency. |
+| `list_labels` | AppMap [labels](/docs/reference/analysis-labels) ranked by usage, with a sample function id for each label. |
+
+### Finding records
+
+| Tool | Description |
+| ---- | ----------- |
+| `find_recordings` | Recording-level rows (one per AppMap recording), with a canonical `path` and a `kind` of `junit`, `request`, or `other`. Use the returned `path` as the `appmap` argument to other tools. |
+| `find_requests` | Individual HTTP server requests, with method, route, status code, elapsed time, and branch. |
+| `find_queries` | Individual SQL queries, with query text, elapsed time, and the calling class and method. Filter by `table`, `class`, or `method`. |
+| `find_calls` | Individual function calls, including captured parameters and return values. Filter by `class`, `method`, `label`, or exact `event_id`s. When a class or method matches nothing, the result includes a "did you mean" suggestion. |
+| `find_logs` | Application log lines captured during recordings. Filter by `message` or `logger`. |
+| `find_exceptions` | Exceptions raised during recordings. Use `with_logs` to attach the most recent preceding log lines to each exception. |
+
+### Analyzing recordings
+
+| Tool | Description |
+| ---- | ----------- |
+| `get_call_tree` | The call tree of a single recording (identified by its `appmap` path). Focus on a function, SQL query, or HTTP request with `focus_type` and `focus_value`; control breadth with `parent_depth`, `child_depth`, and `min_elapsed_ms`. Returns a byte-budgeted text tree by default, or full JSON nodes with `format: json`. |
+| `find_related` | Recordings ranked by similarity to a source recording, scoring shared routes, SQL tables, and classes. Useful for finding other recordings that exercise the same code. |
+| `compare_branches` | Per-route p95 latency for two branches (`branch_a` and `branch_b`) with the delta between them. Sort by `delta`, `p95-a`, or `p95-b`. |
+
+## Resources
+
+In addition to tools, the server exposes the following MCP resources:
+
+| Resource | Description |
+| -------- | ----------- |
+| `appmap://endpoints` | All HTTP endpoints with request count, average latency, p95 latency, and error rate, as JSON. |
+| `appmap://recording/{ref}/logs` | All log lines for a single recording, where `{ref}` is the URL-encoded canonical path of the recording. |
+
+## GitHub repository
+
+[https://github.com/getappmap/appmap-js/tree/main/packages/cli](https://github.com/getappmap/appmap-js/tree/main/packages/cli)
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -19,6 +19,7 @@ redirect_from: [/docs/reference/browser-extension]
   - [AppMap for Java – Gradle Plugin](/docs/reference/appmap-gradle-plugin)
 - [AppMap Command line interface (CLI)](/docs/reference/appmap-client-cli.html)
 - [Remote recording API](/docs/reference/remote-recording-api)
+- [AppMap MCP Server](/docs/reference/appmap-mcp)
 - [Analysis Rules](/docs/reference/analysis-rules)
 - [Analysis Labels](/docs/reference/analysis-labels)
 - [License Key Installation](/docs/reference/license-key-install)

diff --git a/docs/reference/jetbrains.md b/docs/reference/jetbrains.md
@@ -120,6 +120,8 @@ When you run a Java application with the AppMap agent, [remote recording](/docs/
 
 You can make a [remote recording](../recording-methods#remote-recording) from within the JetBrains IDE.
 
+**Security Warning**: Remote recording should only be enabled in non-production environments. Enabling it in other environments is a security risk as the recording endpoints may be accessible to anyone who can reach the application server. You can ensure that remote recording is not enabled by ensuring that the `appmap` Java agent is not loaded by the JVM.
+
 1. [Install the JetBrains plugin](https://plugins.jetbrains.com/plugin/16701-appmap) if you haven't already.
 2. Start your application with remote recording enabled. For Java, [run your Java application with AppMap](#running-a-java-application-with-appmap). For other languages, consult the [agent reference](/docs/reference) for details.
 3. To start a recording, click the remote recording button, or use the command **Start AppMap recording**.
@@ -133,9 +135,22 @@ You can make a [remote recording](../recording-methods#remote-recording) from wi
 
 For more details about remote recording, see:
 
-- [Recording methods > Remote recording](/docs/recording-methods)
+- [Recording methods > Remote recording](/docs/get-started-with-appmap/making-appmap-data#with-remote-application-recording)
 - [Remote recording API](../reference/remote-recording-api)
 
+## Requests recording
+
+You can configure AppMap to record HTTP requests and responses in your Java application. This is useful for understanding how your application interacts with external services.
+
+1. [Install the JetBrains plugin](https://plugins.jetbrains.com/plugin/16701-appmap) if you haven't already.
+2. Start your application with the `appmap` Java agent enabled. For Java, [run your Java application with AppMap](#running-a-java-application-with-appmap). For other languages, consult the [agent reference](/docs/reference) for details.
+3. Interact with your application through its UI or API.
+4. AppMap will automatically record HTTP requests and responses. The recorded requests will be saved as AppMap data files in the project AppMap directory (`tmp/appmap` by default).
+
+For more details about requests recording, see:
+
+- [Recording methods > Requests recording](/docs/get-started-with-appmap/making-appmap-data#with-api-request-recording)
+
 ## AppMap Plugin actions
 
 To open the list of AppMap plugin actions, press `CTRL+SHIFT+A` on Windows and Linux, or `COMMAND+SHIFT+A` on macOS, and type `AppMap`. You can also find these actions at `Tools > AppMap` of the main menu.

diff --git a/docs/reference/vscode.md b/docs/reference/vscode.md
@@ -131,6 +131,7 @@ To open the list of AppMap extension actions, press `CTRL+SHIFT+P` or `COMMAND+S
 
 Most of the command names should be self-explanatory. Here are a few commands which are a bit more complicated:
 
+- **AppMap: Review Your Code** Starts a code review using AppMap Navie. This command analyzes your code changes and provides a comprehensive report to help you improve code quality, security, and performance by providing specific, actionable suggestions.
 - **AppMap: Filter/Find AppMap by name** Opens the AppMap side bar view and the filter/find text field
 - **AppMap: Login**, **AppMap: Logout** Some extension functionality requires you to login to the AppMap Server. You'll be prompted to do this when you setup AppMap for the first time. You can also login and logout using the built-in `Accounts` feature of VSCode.
 - **AppMap: Touch Out-of-Date Test Files** If you have AppMap Diagrams generated from test cases, this command will determine which tests need to be re-run in order to bring the AppMap Data up-to-date. It will then "touch" (update the modified date) of each out-of-date test case. You can use a file watching trigger program like `Guard` (Ruby), `grunt` or `gulp` (JS) to re-run the test cases as they are touched.
@@ -175,3 +176,9 @@ After [recording AppMap Data](/docs/recording-methods.html) for your project, op
 ## GitHub repository
 
 [https://github.com/getappmap/vscode-appland](https://github.com/getappmap/vscode-appland)
+
+## Troubleshooting
+
+If you encounter issues with the AppMap VS Code extension, particularly during startup, please check the Output panel
+(`View -> Output`, select "AppMap: Services") for error messages. Common startup issues and their solutions are documented
+in our [troubleshooting guide](/docs/troubleshooting/vscode).
diff --git a/docs/troubleshooting/index.md b/docs/troubleshooting/index.md
@@ -0,0 +1,53 @@
+---
+layout: docs
+title: Troubleshooting AppMap
+description: "Find solutions to common AppMap issues and get help with installation, configuration, and usage problems"
+toc: true
+name: Troubleshooting
+step: 1
+---
+
+# Troubleshooting AppMap
+
+This guide helps you find solutions to common AppMap issues. Select the appropriate section based on your problem area:
+
+## IDE Integration Issues
+
+### VS Code Extension
+
+Having problems with the AppMap VS Code extension? Check our detailed [VS Code troubleshooting guide](/docs/troubleshooting/vscode) for solutions to common issues like:
+
+- GLIBC version compatibility on Linux
+- Windows permission and temporary file errors
+- Extension startup problems
+
+### JetBrains Plugin
+
+For JetBrains IDE plugin issues, refer to our [air-gapped installation guide](/docs/reference/appmap-airgapped-install#jetbrains) which covers:
+
+- Plugin installation problems
+- Binary compatibility issues
+- Installation in restricted environments
+
+## Environment-Specific Issues
+
+### Docker Integration
+
+If you're using AppMap with Docker, see our [Docker troubleshooting guide](/docs/reference/integrations/docker#troubleshooting-appmap-and-docker) for help with:
+
+- Container configuration
+- Volume mounting
+- Performance optimization
+
+## Getting Help
+
+If you can't find a solution to your problem:
+
+1. Check the logs:
+
+   - [VS Code logs](/docs/troubleshooting/vscode#accessing-error-logs)
+   - [JetBrains logs](/docs/reference/appmap-airgapped-install#accessing-navie-logs)
+
+2. Contact Support:
+   - Email: [support@appmap.io](mailto:support@appmap.io)
+   - GitHub Issues: [AppMap VS Code Extension](https://github.com/getappmap/vscode-appland/issues)