Prepare the MCP server for npm - #147
Merged
Merged
Conversation
Publishing is irreversible - npm versions cannot be replaced, only superseded - so this is what a dry run of the package turned up. Each was found by installing the packed tarball into an empty directory and running it as a consumer would, not by reading the manifest. **Chaining off by default.** The scaffold enables it, which spawns `npx -y @umbraco-cms/mcp-dev` at startup and proxies ~350 tools. On a fresh install the first run hangs, silently, while npx downloads it - locally it looks instant only because the package is cached. It also duplicates every Umbraco tool for anyone already running Umbraco's own server, which was reported from Tailored Travel. UpDoc's tools call UpDoc's endpoints and never delegate, so the chain earned nothing. UMBRACO_MCP_CHAIN=true restores it. **yargs is a runtime dependency.** It was moved to devDependencies on the evidence that nothing in the bundle imports it. That evidence was wrong: the SDK loads it dynamically to parse --call and --list-tools. Without it both flags are silently ignored and the server just starts, which is a confusing way to fail. **Four dependencies moved to devDependencies** - the Cloudflare Worker and eval test packages, none of which ship in dist/. A clean install is now 40 packages. **README rewritten.** It was the scaffold's, titled "mcp", explaining how to build a template. It is the npm front page, so it now covers what the server is, what it needs (Umbraco 17, UpDoc 17.5.3.6+, an API user), how to register it, and what the two tools do. **Metadata added** - author, repository, homepage, bugs. Without repository there is no link from npm back to the source. Verified from a clean install in an empty directory: 40 packages, 0 vulnerabilities, both tools listed, list-workflows returns the expected shape. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@umbraco-cms/mcp-server-sdk is at 1.0.0-beta.35, which is the latest and is tagged both latest and beta. Pinned exactly rather than with a caret, so a new beta cannot change behaviour between releases. Anyone installing this inherits that beta dependency, so the README says so and suggests pinning. Normal for this ecosystem today - Umbraco's own MCP packages are all beta - but not something to discover afterwards. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Everything the package needed before a first publish. npm versions cannot be replaced, only superseded, so this was worth doing carefully.
Each problem was found by installing the packed tarball into an empty directory and running it as a consumer would — not by reading the manifest. None of them were visible from the source tree.
Chaining off by default
The scaffold enables it, which spawns
npx -y @umbraco-cms/mcp-devat startup and proxies ~350 tools through this server.UpDoc's tools call UpDoc's endpoints and never delegate, so the chain earned nothing.
UMBRACO_MCP_CHAIN=truerestores it.yargs is a runtime dependency
It was moved to devDependencies on the evidence that nothing in the bundle imports it. That evidence was wrong: the SDK loads it dynamically to parse
--calland--list-tools.Without it, both flags are silently ignored and the server just starts — no error, no output. A static grep could not have caught this; only running the installed package did.
Four dependencies moved to devDependencies
The Cloudflare Worker and eval-test packages, none of which ship in
dist/. A clean install is now 40 packages, 0 vulnerabilities.README rewritten
It was the scaffold's, titled
# mcp, explaining how to build a template. It is the npm front page, so it now covers what the server is, what it needs (Umbraco 17, UpDoc 17.5.3.6+, an API user), how to register it, and what the two tools do — including that documents are created as drafts.Metadata
author,repository,homepage,bugs. Withoutrepositorythere is no link from npm back to the source.Also notes the beta SDK dependency, since consumers inherit it.
Verified
Clean install in an empty directory: 40 packages, 0 vulnerabilities, both tools listed,
list-workflowsreturns the expected{ items: [...] }shape.🤖 Generated with Claude Code