Merge pull request #163 from WolframResearch/feature/docker-docs-update

Docs: Overhaul Docker usage guide

Author: rhennigan

Dockerfile

@@ -12,7 +12,7 @@
 #
 # For node-locked licensing (free but requires persistent storage):
 #   docker run -i --rm \
-#     -v ./Licensing:/root/.WolframEngine/Licensing \
+#     -v ./Licensing:/home/wolframengine/.WolframEngine/Licensing \
 #     -e MCP_SERVER_NAME=Wolfram \
 #     ghcr.io/wolframresearch/mcpserver:latest
 

README.md

@@ -31,6 +31,7 @@ A Wolfram Language toolkit for integrating with AI agents and LLMs — providing
 - **MCP Apps** for interactive UI resources in supported clients (e.g., embedded notebook viewers, Wolfram\|Alpha result displays)
 - **Agent Skills** for distributing Wolfram tools as portable skills to AI coding agents (Claude Code, Cursor, Gemini CLI, VS Code, and [more](https://agentskills.io/))
 - **Paclet extensions** allowing third-party paclets to contribute MCP tools, prompts, and servers via the `"AgentTools"` extension
+- **Docker image** for running the MCP server in a container without a local Wolfram Engine installation
 
 ## Requirements
 
@@ -52,6 +53,14 @@ PacletInstall["Wolfram/AgentTools"]
 Needs["Wolfram`AgentTools`"]
 ```
 
+### Docker Image
+
+A prebuilt Docker image is available as an alternative to a local Wolfram Engine installation. See [Docker documentation](docs/docker.md) for setup and MCP client configuration examples.
+
+```bash
+docker pull ghcr.io/wolframresearch/mcpserver:latest
+```
+
 ## Quick Start
 
 Install a Wolfram MCP server for Claude Desktop:

docs/docker.md

@@ -2,54 +2,74 @@
 
 This guide explains how to run the Wolfram MCP Server using Docker containers.
 
-## Quick Start
+## Initial Setup
 
-Pull and run the image:
+Pull the image to your local machine:
 
 ```bash
-docker run -i --rm \
-  -e WOLFRAMSCRIPT_ENTITLEMENTID=your-entitlement-id \
-  ghcr.io/wolframresearch/mcpserver:latest
+docker pull ghcr.io/wolframresearch/mcpserver:latest
 ```
 
-## Prerequisites
-
-### Wolfram Engine License
+**Note:** On Windows, you'll need to ensure that [Docker Desktop](https://www.docker.com/products/docker-desktop/) is running before using `docker` commands.
 
-The MCP server requires a valid Wolfram Engine license. You have two options:
+### Configure Licensing
 
-#### Option 1: Entitlement ID (Recommended for Containers)
+#### Option 1: Entitlement ID
 
 Use a Wolfram Service Credits entitlement ID. This is ideal for ephemeral containers since no persistent storage is needed.
 
-1. Obtain an entitlement ID from [Wolfram Service Credits](https://www.wolfram.com/service-credits/)
-2. Pass it via environment variable:
-   ```bash
-   -e WOLFRAMSCRIPT_ENTITLEMENTID=O-XXXX-XXXXXXXXXXXXX
+1. Obtain an entitlement ID by evaluating the following in Wolfram Language (adjust the settings as desired):
+   ```wl
+   entitlement = CreateLicenseEntitlement @ <|
+      (* Number of kernels to allow simultaneously: *)
+      "StandardKernelLimit" -> 4,
+      (* Time limit for a kernel activated using this entitlement: *)
+      "LicenseExpiration" -> Quantity[ 30, "Minutes" ],
+      (* Time for which the entitlement is valid: *)
+      "EntitlementExpiration" -> Quantity[ 1, "Months" ]
+   |>
+   ```
+
+2. Copy the entitlement ID to the clipboard:
+   ```wl
+   CopyToClipboard[entitlement["EntitlementID"]]
+   ```
+
+3. Pass it via environment variable in your MCP client configuration (see below for examples):
+   ```json
+   "-e", "WOLFRAMSCRIPT_ENTITLEMENTID=<entitlement-id>"
    ```
 
-**Note:** Service credits are consumed while the kernel is running.
+**Note:** Service credits are consumed while the kernel is running, so this method is best for short-lived containers.
 
 #### Option 2: Node-Locked License (Free)
 
-Use a free [Wolfram Engine Developer License](https://www.wolfram.com/developer-license/). This requires persistent storage for the license file.
+Use an existing license associated with your Wolfram ID or get a free [Wolfram Engine Developer License](https://www.wolfram.com/developer-license/). This requires persistent storage for the license file.
+
+1. If needed, get a free license at https://www.wolfram.com/developer-license/
 
-1. Get a free license at https://www.wolfram.com/developer-license/
 2. Activate once interactively:
    ```bash
-   docker run -it --entrypoint wolframscript \
-     -v ./Licensing:/root/.WolframEngine/Licensing \
+   docker run -it --rm --entrypoint wolframscript \
+     -v ./Licensing:/home/wolframengine/.WolframEngine/Licensing \
      ghcr.io/wolframresearch/mcpserver:latest
    ```
+
 3. Enter your Wolfram ID credentials when prompted
-4. For subsequent runs, mount the same licensing directory:
+
+4. Verify the license is activated (it should not prompt for credentials):
    ```bash
-   docker run -i --rm \
-     -v ./Licensing:/root/.WolframEngine/Licensing \
+   docker run -it --rm --entrypoint wolframscript \
+     -v ./Licensing:/home/wolframengine/.WolframEngine/Licensing \
      ghcr.io/wolframresearch/mcpserver:latest
    ```
 
-**Note:** The license expires periodically and will auto-renew automatically when the Wolfram kernel starts and the container has internet connectivity. Ensure that the `./Licensing` directory is kept persistent and mounted on every run so that the renewed license is preserved across container restarts.
+5. Ensure the volume is mounted in your MCP client configuration (see below for examples):
+   ```json
+   "-v", "/path/to/Licensing:/home/wolframengine/.WolframEngine/Licensing"
+   ```
+
+**Note:** In MCP client configurations, use an absolute host path rather than `./Licensing`, since many clients launch `docker` with a working directory that is not the project directory. Change `/path/to/Licensing` to wherever you want to store the license information. Ensure that the licensing directory is kept persistent and mounted on every run so that the renewed license is preserved across container restarts.
 
 ## Server Configurations
 
@@ -72,7 +92,7 @@ docker run -i --rm \
 
 ## Mounting a Workspace Directory
 
-The container starts in an empty `/workspace` directory. You can mount a host directory here to give the MCP server access to your files:
+The container starts in an empty `/workspace` directory. You can mount a host directory here to give the MCP server access to your project files:
 
 ```bash
 docker run -i --rm \
@@ -85,31 +105,25 @@ This allows the server to read and write files in your project directory. For ex
 
 ```bash
 docker run -i --rm \
-  -v $(pwd):/workspace \
+  -v .:/workspace \
   -e WOLFRAMSCRIPT_ENTITLEMENTID=your-id \
   ghcr.io/wolframresearch/mcpserver:latest
 ```
 
-On Windows (PowerShell):
-```powershell
-docker run -i --rm `
-  -v ${PWD}:/workspace `
-  -e WOLFRAMSCRIPT_ENTITLEMENTID=your-id `
-  ghcr.io/wolframresearch/mcpserver:latest
-```
+Mounting a directory is necessary if you want to use tools that need to read or write files, e.g., `ReadNotebook`, `WriteNotebook`, `TestReport`, `CodeInspector`, etc.
 
 **Security Note:** The container will have full read/write access to the mounted directory. Only mount directories you trust the MCP server to access.
 
-## MCP Client Configuration
+## Example MCP Client Configurations
 
 ### Claude Desktop
 
-Add to `~/.config/claude/claude_desktop_config.json` (Linux) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
   "mcpServers": {
-    "wolfram": {
+    "Wolfram": {
       "command": "docker",
       "args": [
         "run", "-i", "--rm",
@@ -129,33 +143,13 @@ Add to your project's `.mcp.json` or global `~/.claude.json`:
 ```json
 {
   "mcpServers": {
-    "wolfram": {
-      "command": "docker",
-      "args": [
-        "run", "-i", "--rm",
-        "-e", "WOLFRAMSCRIPT_ENTITLEMENTID=your-entitlement-id",
-        "-e", "MCP_SERVER_NAME=WolframLanguage",
-        "ghcr.io/wolframresearch/mcpserver:latest"
-      ]
-    }
-  }
-}
-```
-
-### With Workspace Mount
-
-To give the MCP server access to your project files, mount a directory to `/workspace`:
-
-```json
-{
-  "mcpServers": {
-    "wolfram": {
+    "Wolfram": {
       "command": "docker",
       "args": [
         "run", "-i", "--rm",
         "-v", "/path/to/your/project:/workspace",
         "-e", "WOLFRAMSCRIPT_ENTITLEMENTID=your-entitlement-id",
-        "-e", "MCP_SERVER_NAME=Wolfram",
+        "-e", "MCP_SERVER_NAME=WolframLanguage",
         "ghcr.io/wolframresearch/mcpserver:latest"
       ]
     }
@@ -170,11 +164,11 @@ For clients using node-locked licensing, include the licensing volume mount:
 ```json
 {
   "mcpServers": {
-    "wolfram": {
+    "Wolfram": {
       "command": "docker",
       "args": [
         "run", "-i", "--rm",
-        "-v", "/path/to/Licensing:/root/.WolframEngine/Licensing",
+        "-v", "/path/to/Licensing:/home/wolframengine/.WolframEngine/Licensing",
         "-e", "MCP_SERVER_NAME=Wolfram",
         "ghcr.io/wolframresearch/mcpserver:latest"
       ]
@@ -188,11 +182,11 @@ You can combine multiple volume mounts (licensing + workspace):
 ```json
 {
   "mcpServers": {
-    "wolfram": {
+    "Wolfram": {
       "command": "docker",
       "args": [
         "run", "-i", "--rm",
-        "-v", "/path/to/Licensing:/root/.WolframEngine/Licensing",
+        "-v", "/path/to/Licensing:/home/wolframengine/.WolframEngine/Licensing",
         "-v", "/path/to/your/project:/workspace",
         "-e", "MCP_SERVER_NAME=Wolfram",
         "ghcr.io/wolframresearch/mcpserver:latest"
@@ -244,15 +238,22 @@ This allows you to test changes without rebuilding the image.
 
 ## Troubleshooting
 
-### "Kernel initialization failed"
+### MCP server fails to start on Windows
+
+On Windows, you'll need to ensure that [Docker Desktop](https://www.docker.com/products/docker-desktop/) is running before starting the MCP server.
 
-This usually indicates a licensing issue. Verify:
+### "Your Wolfram Engine installation is not activated"
+
+This usually indicates a licensing issue. Verify that:
 - Your entitlement ID is valid and has available credits
 - Or your node-locked license directory is mounted correctly
 
-### Slow startup
+### MCP server startup times out
 
-The first kernel startup takes several seconds. This is normal for Wolfram Engine. Pre-building MX files can improve this.
+Pulling the Docker image the first time can take a while. Before running the MCP server, try pulling the image manually to ensure it is ready for fast startup:
+```bash
+docker pull ghcr.io/wolframresearch/mcpserver:latest
+```
 
 ### Container exits immediately
 
@@ -272,8 +273,10 @@ docker run -i --rm \
 | Tag | Description |
 |-----|-------------|
 | `latest` | Most recent release |
-| `x.y.z` | Specific version (e.g., `1.6.25`) |
-| `sha-xxxxx` | Specific commit |
+| `x.y.z` | Specific version (e.g., `2.0.13`) |
+| `xxxxxxx` | Specific commit (e.g., `27f0c1f`) |
+
+All available tags can be found [here](https://github.com/WolframResearch/AgentTools/pkgs/container/mcpserver/versions).
 
 ## Architecture