gh api repos/spranab/truenas-mcp/actions/runs reports a total_count of 0. The repo has two workflows, and one of them exists to publish the npm package. I wrote it on August 5th, the day after telling a user his fix was going out as v1.0.1. Today is 2026-11-12 and npm still serves 1.0.0.
truenas-mcp is an MCP server for the TrueNAS SCALE REST API. It exposes one hierarchical tool instead of one tool per operation. The README's case for that: covering TrueNAS properly the naive way takes 50-80 tool schemas, "around 28,000 tokens of your context window spent before the model has read a single word of your question, on every request, whether or not you touch storage." truenas-mcp puts 278 actions across 18 categories behind a single tool at roughly 200 tokens. Version 1.0.0 went to npm on 2026-03-31. It is the only version npm has ever had.
Issue #1
On 2026-06-23 a user called jsapede reported that the app lifecycle tools (start, stop, redeploy) were returning 404 on TrueNAS SCALE 25.10. His report had a table of the old endpoints next to the ones that worked on 25.10, a list of which tools worked and which didn't, and the request-body format he'd worked out. I didn't answer for five and a half weeks.
When I did, on 08-02, I'd read through truenas/middleware at tag TS-25.10.2.1 to find out why. TrueNAS's REST layer only generates the /{namespace}/id/{id}/{method} route for methods marked @item_method (the rule is at restful.py#L236). The app lifecycle methods live in plain Service classes in plugins/apps/app_scale.py, so they're only reachable at /app/{method}. The URL my tools were calling, /app/id/{name}/start, never existed. That's also true on 25.04, which means those tools were broken in 1.0.0 from the first day. 25.10 is just when someone noticed.
The body format comes from restful.py#L807-853, and it's mechanical once you've seen it. If the method takes one positional argument, the request body is that argument. So app.start wants a bare JSON string:
POST /app/start
"dozzle"
With two or more arguments, the body has to be an object keyed by argument name, and any key the method doesn't expect is a hard 400. Upgrade and rollback both take (app_name, options), so the version goes inside options and the app name moves out of the URL into the body:
// POST /app/upgrade
{ "app_name": "dozzle", "options": { "app_version": "1.2.3" } }
The bodies jsapede had suggested for those two would still have hit that 400. I disagreed with him in two other places as well. He'd proposed PUT /app/update as the replacement for app_update, but CRUD update is explicitly excluded from the collection resource, so that route isn't registered; the existing PUT /app/id/{name} was correct and I left it alone, asking him to paste the exact request if he still saw a 404. He'd also listed app_outdated_images as confirmed working. I didn't think it could be. app.outdated_docker_images requires an app name, which makes it POST-only, and the tool was sending a bare GET. The fix touched seven tools. Start, stop and redeploy were one routing mistake repeated three times. Upgrade and rollback were the body-shape rule. Outdated-images was the GET. The seventh was app_get, which I moved to GET /app?id={name} even though my own comment says the old route "should also be valid," so call that one a preference. I also rechecked the VM tools, which use the same /vm/id/{id}/{action} shape. Those really are item methods and didn't need changing.
The comment ended: "Going out as v1.0.1."
On 08-04 jsapede asked, "is there any 1.0.1 release?" Later that day I committed 5feda9b, "Fix app lifecycle endpoints (#1)", with Reported-by: jsapede and Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> in the trailer, and tagged it v1.0.1.
The promise
My reply on 08-05 said the fix was "merged and tagged, but the publish itself is still pending on my side." Since dist/ isn't committed, I gave him a build-from-source route: clone the v1.0.1 tag, npm install && npm run build, point the MCP client at dist/cli.js. Then I wrote this:
I'll comment here the moment 1.0.1 is live on npm, which should be shortly. I've also added a release workflow to the repo so this gap doesn't happen again; tags will publish themselves from here on.
The workflow is bd96c35, .github/workflows/release.yml, committed the same day. Its commit message is mostly about auth. The job requests an OIDC id-token, "so once the repo is registered as a trusted publisher for the package on npmjs.com there is no credential to store or rotate, and releases carry a provenance attestation." An NPM_TOKEN secret works as a fallback. Before publishing, it checks the tag against package.json, so a mismatched tag fails the job.
It has two triggers. Pushing a new v* tag runs it automatically. There's also a manual workflow_dispatch path, and the comment at the top of the file explains why: it publishes "manually against a tag that already exists (useful when a tag was pushed before this workflow was in place)." The input's description is "Existing tag to publish (e.g. v1.0.1)". When I typed that example I knew which tag was stranded.
After
I kept working on the repo. Eight more commits went in:
-
b84468b, 08-18: README rewrite leading with the context-window numbers -
5afb887andd955553, 08-28: Dockerfile and MCP registry scaffolding (the second one added.github/workflows/mcp-registry.yml) -
27e3005, 09-02: license badge -
9d59296, 09-08:llms-install.mdfor a Cline marketplace submission -
4f978ad, 09-19: install-doc fix -
5d49cc1, 10-17:server.jsondescription sync -
753f714, 10-21: a Related Projects link, plus one more thing
The commit message for that last one says I ran npm install "to sync package-lock.json's self-referential version field (1.0.0 -> 1.0.1) with package.json, which was bumped in a prior commit without updating the lockfile."
Eleven weeks after tagging 1.0.1, I was keeping the lockfile consistent with a version npm had never seen.
The day before, 10-20, the repo picked up its eighth star. The first two arrived on 03-31, then one each on 04-07, 04-11, 04-23, 06-20 and 08-24. Anyone who found the project on 10-20 and installed it from npm got 1.0.0.
Issue #1 is still open. Putting "(#1)" in a commit subject links the issue without closing it; GitHub only auto-closes on keywords like "Fixes #1." I could have closed it by hand, but the comment I promised jsapede was supposed to come first, and there's been nothing to announce.
What I got wrong
For new releases, the workflow does take the decision out of my hands: push a tag and it publishes. But v1.0.1 already existed when the workflow landed, so it could only go out through the manual path, and I never used it. I also never pushed a second tag across those eight commits. In three months the automatic path hasn't had a single chance to fire, and nobody has tried the manual one. So I can't tell you whether it works. gh secret list --repo spranab/truenas-mcp comes back empty, which means there's no NPM_TOKEN. The only way the publish step can authenticate is npm trusted publishing over OIDC, and that depends on the repo being registered as a trusted publisher on npmjs.com. Nothing in the repo tells me whether I did that. If I didn't, pressing the button in August would have failed at npm publish, and "tags will publish themselves from here on" would have been false from the day I wrote it, with no one, me included, any the wiser.
What I'd built was a YAML file I believed was a release process. npm publish from my own machine was one command and was available the whole time. The workflow gave me a second way to make the same decision, and I made it through neither. Having written it, I felt like the problem was handled, and I think that feeling is a big part of why the tag stayed stranded.
The next step on this repo doesn't involve writing anything. It's running the workflow once against v1.0.1 and reading the log. If it publishes, I close #1 and post the comment I owe. If it fails on auth, I find out my release automation was never connected to anything, which I'd rather learn from one log than from another three months of silence. The rule I'm keeping: a release mechanism counts as finished after it has shipped one real version.
For the record, monthly npm downloads from my metrics log: 262 on 2026-10-12, 249 on 10-26, 147 on 11-02, 113 on 11-09. I can't tie that drop to the unpublished fix. Monthly numbers on a package this small move around for their own reasons, and I have no idea how many of those installs ever touched an app lifecycle tool. Every one of them got 1.0.0.
Pranab Sarkar, Independent Researcher
Top comments (1)
total_count: 0is the most useful number in this post, because it narrows the cause to four things and each one has a different check. Either the workflow file is not on the ref the event resolves from (GitHub reads the workflow from the default branch for release events, so a file that only ever lived on your working branch has correctly never run), or the event never fired, or anon:filter cannot match what you pushed (tags: ['v*']against a tag named1.0.1,types: [published]against a draft), or the actor wasGITHUB_TOKEN— events created with that token do not start new workflow runs, so a release cut by one workflow will not trigger the publish workflow that waits for it.gh workflow list --allseparates the last two from the first two in one command: a workflow disabled for inactivity shows up there, and a workflow that has never been dispatched does not.The check I would add is not on the workflow, it is on the artifact.
npm view truenas-mcp dist-tags.latestnext to theversioninpackage.jsonat HEAD, compared on a schedule, and paged when they disagree for more than an hour. The publish workflow being green is not evidence that npm serves your fix; the only ground truth is what the registry resolves, which is exactly the same reason the endpoint in issue #1 looked fine while returning 404 — the tool reported its own view of the call, not the server's.