Containerising inspector

[aaronpowell]

Fixes #237

Motivation and Context

I want to be able to use a container version of the inspector rather than via npx.

How Has This Been Tested?

I merged the branch into main on my fork and created a tag so I could publish a release. Here's the workflow run (ignore the failing package job, I can't publish to npm) and here's the published image

Note: since the workflow is configured to publish to GitHub Packages not Docker Hub the GITHUB_TOKEN needs to be able to write packages. This is configured in the workflow, but you also need to update the repo settings to allow the workflow to request a token with write permissions:

Breaking Changes

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Currently, the image only has the nodejs runtime in it, so it doesn't support running stdio servers with python/.NET/Java/etc. Instead, they would probably be handled as different tags. My primary focus is on supporthing servers that are SSE (and streamable http in the future)

[cliffhall]

We really need something in the "how has this been tested" section of these PRs, particularly if it hooks into CI.

[aaronpowell]

We really need something in the "how has this been tested" section of these PRs, particularly if it hooks into CI.

I'll update that section, but it's mainly running a docker build and starting a container.

Testing the CI pipeline is a bit harder, since it's artifact publishing, so I'm just using the instructions from the GitHub docs.

[cliffhall]

We really need something in the "how has this been tested" section of these PRs, particularly if it hooks into CI.

I'll update that section, but it's mainly running a docker build and starting a container.

Testing the CI pipeline is a bit harder, since it's artifact publishing, so I'm just using the instructions from the GitHub docs.

Got it. But I don't want to break the inspector with an untested workflow. Can you please test it in your fork and take screenshots of every step?

[aaronpowell]

@cliffhall I've updated the issue description with how I've tests it and links to the Actions run on my fork that I used.

Here's some screenshot of the image on my fork:

And the workflow run (sorry, it's pretty long, so I'll break it a bit 🤣):

[cliffhall]

@aaronpowell thanks for doing that testing, I really appreciate it. Will give it closer eyes soon.

[aaronpowell]

@aaronpowell thanks for doing that testing, I really appreciate it. Will give it closer eyes soon.

Let me know if you need any more details on the workflow or the life cycle.

[olaservo]

Dropping a note here too - looking into how we might get this pushed as an official image on Docker hub. (There appears to be an old version published there that is about ~4 months old.)

[cliffhall]

@aaronpowell This is what I get when I try to pull your container image with:

docker pull ghcr.io/aaronpowell/inspector:sha256-8fe64aece8867d5c619e6910f1aa7f7c3c4267bb7374a42ec44bc6ab028f4ea5

[dahlsailrunner]

I got the same error as above when pulling the container with the :sha... tag, but when I did this everything worked fine, including running the container.

docker pull ghcr.io/aaronpowell/inspector

[cliffhall]

I got the same error as above when pulling the container with the :sha... tag, but when I did this everything worked fine, including running the container.

docker pull ghcr.io/aaronpowell/inspector

Yep, this works. I was able to run the container but of course the host's ports are not accessable, out of box, so the link doesn't work. You have to connect the ports in Docker Desktop's Optional Settings on the run dialog, or with docker run -p 6277:6277 -p 6274:6274

Then you're good to go.

[cliffhall]

@aaronpowell this is looking good. There is some setup outside the files in this repo though. Will look into it.

[jpmcb]

It's likely advantageous to have separate build and runtime stages:

# layer 1 - build stage
FROM node:22-slim AS build

# copies all the files over and installs dependencies

# actually compile the typescript which emits the "server/build/" and "client/dist/"
RUN npm run build

# layer 2 - runtime stage with the compiled /bundled javascript
FROM node:22-slim
WORKDIR /app

# copy over all build / dist files (including node_module dependencies)
COPY --from=build /app/client/dist ./client/dist
COPY --from=build /app/server/build ./server/build
COPY --from=build /app/node_modules ./node_modules

# etc. etc. rest of dockerfile

[jpmcb]

Why this workaround? Are there platform specific optional dependencies in the inspector that need to be pulled into the image for running?

[cliffhall]

Should probably be npm ci instead.

[olaservo]

cc @slimslenderslacks

[Stefano-Pedretti]

Hi, we may need to change also the listening host, now it's hardcoded as 127.0.0.1 that is not exposed in the docker network.

a new env variable like CLIENT_HOST and SERVER_HOST should be added.

[cliffhall]

Hey @slimslenderslacks and @aaronpowell! Can we determine what the exact gap is with this? There is already another PR #471 looking to add this. We have at least been able to test this on Aaron's deployment, so I'm inclined to want this one to make it in.

In addition to addressing the comments above by @jpmcb I think we need to set up some Github secrets that @dsp-ant, @ihrpr, @jspahrsummers or other core team members could wrangle for us.

[aaronpowell]

@cliffhall I've updated the Dockerfile based on the last round of feedback, but I will admit that it is a little clunky to use the container due to the use of environment variables. What I was intending to do was to have it so you could just run docker run --rm -p 8080:6274 -p 8081:6277 inspect but that has a problem because the server is exposed via the host on 8081 but the client app doesn't know that, it thinks it's on 6277 (which it is, but only inside the container). The resulting is that you would have to go into the inspector UI and configure the endpoint which the server is running on so that it uses the port it exposes to the host via.

The result of this is that you run docker run --rm -p 8080:8080 -p 8081:8081 -e CLIENT_PORT=8080 -e SERVER_PORT=8081 inspector, specifying the environment variables and then overriding the port in the container for the client and server.

Admittedly, this is only a problem if you're mapping a non-default port, as docker run --rm -p 6274:6274 -p 6277:6277 inspector is fine as the ports are matching each other (and the defaults).

[Stefano-Pedretti]

@cliffhall I've updated the Dockerfile ...
Admittedly, this is only a problem if you're mapping a non-default port, as docker run --rm -p 6274:6274 -p 6277:6277 inspector is fine as the ports are matching each other (and the defaults).

Thanks, please consider a reverse proxy scenario (i.e. traefik) where a path prefix may be added. I can provide a docker compose example if needed.

[cliffhall]

@aaronpowell Is there an updated image I can pull? I see the SHA digest still matches what was there before.

[aaronpowell]

New tagged image up:

docker pull ghcr.io/aaronpowell/inspector:docker-test-2

Here's it running under WSL on my machine:

[cliffhall]

OK, success. I was testing against a streamableHttp server running on localhost (outside the container) and so had to turn on host networking so it could see localhost:3001 and connect to it.

docker run --rm --network host -p 6274:6274 -p 6277:6277 ghcr.io/aaronpowell/inspector:docker-test-2

[aaronpowell]

That secret is provided by GitHub as part of Actions, it doesn't need to be setup

[cliffhall]

That secret is provided by GitHub as part of Actions, it doesn't need to be setup

@aaronpowell Nice, thanks.

I'm trying to determine what the gap is so we can commit and try this.

• Any other special settings to allow publishing to ghcr.io (that we might need a someone with admin rights to do first)?
• If we try to run this workflow what will the final name be?
  • Your last one was ghcr.io/aaronpowell/inspector:docker-test-2
  • I see that was a release tag in your repo
  • If this runs on every release (0.15.0, 0.16.0, 0.16.1 etc.), I'm guessing the list of images would end up being:
    • ghcr.io/modelcontextprotocol/inspector:0.15.0
    • ghcr.io/modelcontextprotocol/inspector:0.16.0
    • ghcr.io/modelcontextprotocol/inspector:0.16.1

[aaronpowell]

@cliffhall here's the docs that describe how to publish to GitHub Container Registry (there is also a section there on publishing to Docker Hub).

From an auth perspective, it uses the GITHUB_TOKEN secret that Actions includes, and the Action requests some additional permissions, which I already have in the workflow file.

If we try to run this workflow what will the final name be?

The name of the image will be ghcr.io/modelcontextprotocol/inspector, which is defined in this line. The reason mine is aaronpowell/inspector is because I use the variable github.repository. If you want to push to Docker Hub then you'd remove the ghcr.io part.

The action only runs on the creation of a release (per this condition) and for my testing I was just creating tags/releases with random names, but using your release structure you'd end up with 0.15.0, etc. as a tag on the image.

[aaronpowell]

The workflow step I added here is pretty simplistic in terms of what it generates and publishes, but you can add more registries, tags and metadata if you desire. This is an example of a more complex image build that I use on another project that generates a lot more tags and supports multiple container registries (GitHub Container Registry and Azure Container Registry).

[cliffhall]

The workflow step I added here is pretty simplistic in terms of what it generates and publishes, but you can add more registries, tags and metadata if you desire. This is an example of a more complex image build that I use on another project that generates a lot more tags and supports multiple container registries (GitHub Container Registry and Azure Container Registry).

Right. I think we might want to publish to Docker Hub as well, but we'll need to set up a namespace and login info that goes into secrets, etc. For the first go, since this should work with an admin's approval and no further changes, I think this looks pretty good.