Conversation
* Add MIT license and bump version to 17.0.0-beta.1 - Add MIT LICENSE file - Update monorepo version to align with Umbraco 17 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Standardise version to 17.0.0-beta.1 and update repository URLs - Bump SDK version from 1.0.0-beta.1 to 17.0.0-beta.1 - Update all repository URLs to github.com/umbraco/Umbraco-MCP-Base - Add junit.xml to .gitignore 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: Phil Whittaker <pjw@umbraco.dk> Co-authored-by: Claude <noreply@anthropic.com>
- Bump PSW_VERSION from 1.2.0-alpha01 to 1.2.0-alpha03 - Replace --no-run with --build-only (renamed upstream in PR #195) - Remove -u flag (sets SQLite defaults, conflicts with --database-type) - Add --run-dir to explicitly set script execution directory - Use dotnet tool update instead of install to handle upgrades - Auto-update PSW when installed version doesn't match expected - Remove .gitkeep from demo-site/ before PSW runs to avoid empty dir issues Co-authored-by: Phil Whittaker <pjw@umbraco.dk> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Simplify createToolResult() to a single `data` parameter and add a compatibility mode that controls whether tool results include both `structuredContent` and a JSON-stringified `content` fallback. By default, both fields are populated for maximum MCP client compatibility. Set `DISABLE_OUTPUT_COMPATIBILITY_MODE=true` to return `structuredContent` only, reducing token duplication for clients that support it (e.g. Claude Code, Claude Desktop). - Simplify createToolResult(data?) — replaces the 3-parameter overload - Add configureToolResultMode() for server startup configuration - Fall back to env var for hosted Workers where config isn't available - Preserve empty text content for void (no-data) tool results - Update test environment to set mode via env var
Simplify tool result API and add output compatibility mode
Add hosted MCP package and multi-transport chaining
- Add @umbraco-cms/mcp-hosted package for Cloudflare Worker-hosted MCP
servers with OAuth authorization, consent screens, multi-site support,
and KV-based token storage
- Add registerChainedTools helper supporting stdio and in-process
transports to proxy tools from other MCP servers
- Migrate SDK HTTP client from axios to native fetch
- Add readOnlyHint annotation filtering and in-process MCP connections
- Add worker entry point, tunnel support, and get-server-info tool to
template
- Add integration and E2E test infrastructure for hosted and chained MCP
- Add add-tool, add-test, and add-eval Claude Code skills
- Fix scaffold to rewrite @umbraco-cms/mcp-hosted file: refs and exclude
test-results/ from template copy
Resolves conflicts to bring release changes (version bumps, hosted-mcp CI pipeline, jest-junit, CLAUDE.md release docs) into dev. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Merge main back into dev after beta.5 release
loadServerConfig is async but tests were calling it synchronously with mockReturnValue instead of mockResolvedValue. This caused TypeScript errors when scaffolding new projects via create-mcp-server. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Without this, Jest globals (describe, it, expect) don't resolve in the IDE when the types array is explicitly set. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ents Comprehensive E2E testing for the create-mcp-server CLI, bug fixes found during manual testing, a new container mode for wrapping MCP servers, and template/skill improvements from real-world usage feedback. CLI Bug Fixes - McpOAuthComposer.cs: Try-catch resilience so Umbraco starts before DB is ready (unattended install) - setup-instance.ts: Write connection string to appsettings.local.json, unattended install config to appsettings.Development.json, patch Program.cs to load appsettings.local.json - Template TS errors: Fix createToolResult signature, jest.fn typing in server-config.test.ts - collections.ts cleanup: removeExamples() now cleans up collections.ts imports E2E Tests CLI E2E (19 deterministic steps, cli-e2e.test.ts): - Scaffold → init (Forms + SQL Server) → start Umbraco → API user creation → token verification → swagger discovery → .discover.json → generate client → TypeScript compile → unit tests → integration test against real Umbraco → real API calls → hosted worker Container Mode E2E (5 steps): - Scaffold → remove API tools → compile → build → worker starts Skill E2E (3 steps, skill-e2e.test.ts, opt-in via RUN_SKILL_TESTS=true): - /build-tools creates Language collection that compiles - /build-tools-tests creates integration tests - Integration tests pass against real Umbraco Infrastructure: Random SQL Server database per run, KEEP_E2E_ASSETS=true for preserving project between runs, test:e2e:revert for resetting skill output, test:e2e:cleanup for teardown. Container Mode New init prompt choice: "Container mode — wrap other MCP servers via chaining, no direct API tools" - removeApiTools() strips orval, generated client, example tools while keeping chaining infrastructure - Tool mode question comes after Umbraco instance setup (instance always needed for OAuth) Template Improvements - Self-signed certs in Jest: Override globalThis.fetch with undici's fetch (Node 22's built-in fetch ignores NODE_TLS_REJECT_UNAUTHORIZED in Jest VM sandbox) - MSW conditional: Gate setupMswServer() behind USE_MOCK_API=true (was blocking real API calls in integration tests) - .gitignore: Added to template (demo-site/, .env, appsettings.local.json, .discover.json) Skill Improvements - build-tools: Compile after EACH tool file, not batch - build-tools-tests: Complete working builder example with delete/cleanup, anti-pattern warning for result.content[0].text (must use createSnapshotResult), initializeUmbracoFetch in setup.ts template, read-only collection guidance - count-tools: Replace glob npm package with Node 22 built-in fs.globSync - Plugin install: Correct commands in discover output (/plugin marketplace add + /plugin install)
Release 17.0.0-beta.6 (#25) - Add CLI E2E tests, container mode, temp…
… trimming (#23) - Add handleCliCommands() SDK helper for --list-tools, --describe-tool, --generate-context flags - Add input sanitization (length limits, key count, depth) with dry-run mode (--dry-run) - Add response trimming to keep tool output within configurable token limits - Add --debug-config flag with secret stripping for safe config inspection - Add test catalogue to CLAUDE.md and consolidate CLI docs into docs/cli.md
…#27) - Add onElicitation callback to eval runner for handling elicitation prompts - Add outputSchema to ProxiedTool type for structured content support - Bump @modelcontextprotocol/sdk to ^1.28.0 for structuredContent support - Fix ToolCallback type mismatch with new registerTool signature - Relax rejectPathTraversal to allow /-prefixed paths (Umbraco uses these as identifiers for stylesheets, scripts, partial views) - Add Symbol.asyncDispose polyfill for Jest VM context (fixes eval tests with upgraded Claude Agent SDK) - Add @anthropic-ai/claude-agent-sdk dependency to tests/cli - Update template OAuth client ID to umbraco-back-office-hosted-mcp
…31) - Add --call <tool-name> and --call-args <json> CLI flags for direct tool invocation without MCP protocol — prints JSON result to stdout, exits - Remove --umbraco-client-id and --umbraco-client-secret CLI flags to prevent secret leakage in terminal output, shell history, and AI conversation context - Make cliFlag optional on ConfigFieldDefinition for env-only fields - Move mcp-cli skill to template/.claude/skills/ so it ships with every scaffolded project - Remove plugins-server/ — replaced by per-project skill in template and --call in SDK - Make handleCliCommands async to support awaiting tool handlers - Refactor CLI evals to load skill from template instead of removed plugins-server - Update docs to recommend .env / MCP config env block for credentials
# Conflicts: # CLAUDE.md # docs/cli.md # packages/create-mcp-server/src/init/__tests__/__snapshots__/removal-functions.test.ts.snap # packages/mcp-server-sdk/src/cli/__tests__/handle-cli-commands.test.ts # packages/mcp-server-sdk/src/cli/handle-cli-commands.ts # packages/mcp-server-sdk/src/config/config.ts # template/src/index.ts # tests/cli/evals/mcp-cli-knowledge.test.ts # tests/cli/evals/mcp-cli-tool-calling.test.ts # tests/cli/evals/setup.ts
Merge main into dev after beta.7 release
## CI/CD — GitHub Actions test workflow
- 3 jobs: Test Suite, CLI Scaffolding E2E, LLM Eval Tests
- Test Suite (every PR): unit tests (449 SDK + 191 hosted + 121 CLI + 24 template), integration tests (21 CLI + 20 Wrangler + 18 chained), Playwright E2E (15 hosted + 12 chained) — 891 tests
- CLI Scaffolding E2E (every PR): scaffold → init → Umbraco start → discover → generate → compile → unit tests → hosted worker — 19 tests with SQL Server in Docker
- Skill E2E (release PRs): build tools + integration tests via Claude Agent SDK against real Umbraco — 2 tests
- LLM Eval Tests (release PRs): CLI knowledge + tool-calling evals — 20 tests
## SDK Helpers
- server-ref: module-scoped Server reference for elicitation in stdio and hosted modes
- confirmAction(extra, message): one-liner for elicitation confirmation pattern
- extractChainedResult(result): normalise chained MCP tool call results
- setupElicitationMock test helper from @umbraco-cms/mcp-server-sdk/testing
- CfWorkerJsonSchemaValidator in createPerRequestServer (Ajv blocked in Workers)
## CLI Improvements
- Umbraco version picker in init flow — fetches stable + RC versions from NuGet
- --template-version passthrough to PSW CLI
- Version derived from package.json (auto-updates on major bumps)
- Shared nuget-versions.ts module
- Restart hint in discover when API user creation fails on fresh install
## Security
- Consent form CSRF: validate state token on POST
- Separate OAuth client IDs: umbraco-back-office-hosted-mcp (authorization_code) vs umbraco-back-office-mcp (client_credentials)
…ev-beta8 # Conflicts: # tests/cli/evals/mcp-cli-knowledge.test.ts
Merge main into dev after beta.8 release
* feat: add cursor-based pagination decorator for MCP tools
Replaces skip/take with opaque cursor parameter on paginated tools.
Applied at registration time — zero changes to individual tool files.
- withCursorPagination() decorator auto-detects skip/take in inputSchema
- Encodes cursor as base64url JSON { s: skip, t: take }
- Adds nextCursor to response when more pages exist
- Default page size 50, overridable per-tool via pageSize property
- Preserves all non-pagination params (filter, orderBy, etc.)
- 29 unit tests covering encode/decode, schema transform, handler, response
* docs: update test skills and agents for cursor-based pagination
Add cursor pagination guidance to:
- build-tools-tests SKILL.md — full examples of withCursorPagination in tests
- add-test SKILL.md — reference to cursor pagination for paginated tools
- integration-test-creator agent — paginated tool testing section
page.getByText(toolName) matched tool descriptions containing the tool
name as a substring, causing strict mode violations with many tools.
Adding { exact: true } and .first() prevents ambiguous matches.
Co-authored-by: Claude <noreply@anthropic.com>
* Release 17.0.0-beta.9 (#37)
Moves cursor pagination into the standard decorator chain so all hosts
(stdio, hosted, any future) get it automatically without each registrar
needing to apply it separately.
- Adds CursorPaginatedArgs<Args> conditional type that correctly reflects
the schema transformation (skip/take → optional cursor) at the TypeScript level
- Exports CursorPaginatedArgs from the SDK public API
- Updates template tests to use cursor-based pagination
- Re-enables Skill E2E and LLM Eval CI jobs
- Adds PR CI monitoring guidance to CLAUDE.md
…ev-beta12 # Conflicts: # .claude-plugin/marketplace.json # package-lock.json # package.json # packages/create-mcp-server/package.json # packages/hosted-mcp/package.json # packages/mcp-server-sdk/package.json # plugins/.claude-plugin/plugin.json # plugins/package.json # template/package.json
Merge main into dev after 17.0.0-beta.12 release
The CLI read its own version with `createRequire(import.meta.url)` +
`require("../../package.json")`. The path was correct from source
(`src/init/nuget-versions.ts`), but after tsup bundles everything into
`dist/index.js`, `import.meta.url` points at `dist/`, so the relative path
no longer finds package.json — npx-installed CLIs crashed with
"Cannot find module '../../package.json'" at module load. The bug shipped
undetected through beta.9, beta.10, and beta.11 because every existing
E2E imports source (`../../src/...`) and never executes the bundled
output.
Fixes and guardrails:
- Resolve package.json via `import pkg from "../package.json" with { type: "json" }`
so tsup inlines the version at build time — no runtime path resolution.
- Add `--version` / `-v` to the CLI so the bundled entry point is
smoke-testable without going through interactive prompts.
- PR suite: new "CLI bundle smoke test" step (`node dist/index.js --version`)
runs after the CLI build. Takes seconds and fails immediately on any
module-load error in the bundled output. Would have caught this bug on
the PR that introduced it.
- Scheduled daily workflow (`scheduled-daily.yml`, 06:00 UTC):
* `published-cli-smoke` — runs `npx @umbraco-cms/create-umbraco-mcp-server@latest`
(and `@beta`) against a clean runner, scaffolds, installs, and typechecks.
Catches regressions in the currently-published artifact (bundle bugs,
missing `files` entries, broken deps).
* `cli-e2e` — full 19-step deterministic E2E, same as the PR job but
scheduled so tooling drift (Umbraco updates, PSW updates, .NET SDK
changes) surfaces without waiting for a PR.
* Failure notifications rely on GitHub's built-in scheduled-workflow
emails to the workflow file's last committer.
Also, in `check-api-user.ts`:
- Support `UMBRACO_ADMIN_EMAIL` / `UMBRACO_ADMIN_PASSWORD` env var overrides
so `discover` can auto-create the API user against an existing Umbraco
whose admin credentials differ from the PSW unattended-install defaults.
- Discriminate admin-login failures from bearer-token failures via an
`AutoCreateFailure` type. Only the bearer-token case surfaces the
"restart Umbraco (17.3 regression)" advice; admin-login failures now say
what actually went wrong and point at the env vars.
Follow-up: #52 proposes restructuring init around `{url, username, password}`
so the existing-instance flow never exposes swagger URLs or surfaces the
env-var workaround.
Merge main into dev after 17.0.0-beta.13 release
Registers WorktreeCreate and WorktreeRemove hooks in .claude/settings.json that shell out to scripts/worktree-create.sh and scripts/worktree-remove.sh. New worktrees branch off origin/dev (falling back to main/master), copy .env, and — when a demo-site/ is present — provision an isolated SQL Server database and rewrite launchSettings.json to use dynamic ports. Remove tears the database and worktree down. Adds .claude/worktrees/ to .gitignore and ships a .worktreeinclude stub listing files the create script copies in.
Add a committed .mcp.json to the template so every scaffolded project
is immediately callable in Claude Code after `init` + `/build-tools`
+ `npm run build`, with no manual `claude mcp add` step.
Uses `node --env-file=.env ./dist/index.js` so credentials stay in
`.env` (gitignored) and `.mcp.json` itself is always safe to commit.
Works because the template's `engines.node` is already >= 22 where the
`--env-file` flag is stable, and because Claude Code launches project-
scoped MCP servers with the project directory as cwd, so both
`./dist/index.js` and `.env` resolve correctly.
- Add template/.mcp.json using `--env-file=.env`.
- Update template/README.md with a "Testing with Claude Code" section.
- Update template/CLAUDE.md to reference .mcp.json in the testing flow.
- Update root CLAUDE.md to note scaffolded projects ship with .mcp.json.
- Extend discover's next-steps to include `npm run build` after
/build-tools + /build-tools-tests.
- Add a scaffolding unit test asserting .mcp.json is emitted into a
fresh project; refresh the template-structure snapshot.
Replaces the swagger-URL prompt in init's "Use existing instance" branch
with a three-field flow (base URL, admin email, admin password). init
now drives the full pipeline for that branch — health check, API user
creation with the supplied admin credentials, swagger discovery, orval
config, .env writes — so the user never types a swagger URL and never
has to match hardcoded admin credentials.
- checkApiUser accepts an explicit admin override so init threads prompted
credentials through without relying on UMBRACO_ADMIN_EMAIL /
UMBRACO_ADMIN_PASSWORD env vars. Env-var fallback preserved.
- promptExistingInstance validates the three inputs and strips trailing
slashes from the base URL.
- runInit handles single-swagger auto-select, multi-swagger picker, and
unreachable-instance gracefully (warns and moves on rather than dying).
- Unit tests cover happy path, multi-swagger picker, and unreachable cases.
New self-contained E2E (existing-instance-e2e.test.ts) copies
tests/umbraco-instance/ to a temp dir, spawns it on a random port with
--no-launch-profile + ASPNETCORE_URLS=http://127.0.0.1:0, and overrides
its connection string to a per-test SQL Server database. Shares the
cli-e2e SQL Server infrastructure so the two suites run in the same CI
job without conflict. Runs scaffold + init pipeline + real management-
API call, tears the instance and DB down cleanly in afterAll.
Renamed cli-e2e → new-instance-e2e to make the pairing with the new
existing-instance E2E obvious:
- tests/e2e/cli-e2e.test.ts → tests/e2e/new-instance-e2e.test.ts
- describe("CLI full E2E") → describe("new-instance E2E")
- [E2E] log prefix → [new-instance-e2e]
- test:e2e script, both CLAUDE.md files, and both workflow display names
updated. Job IDs left as cli-e2e to avoid churning external status-
check configs.
CI: added a "Run existing-instance E2E tests" step to the PR and
scheduled-daily workflows so the new suite runs alongside the renamed
new-instance suite.
Closes #58.
Main to dev update
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
hifi-phil
added a commit
that referenced
this pull request
Apr 22, 2026
Release 17.0.0-beta.14 (#61)
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.
Summary
Release
17.0.0-beta.14.Included since beta.13
f1b8ed5Existing-instance init:{url, user, password}prompts + E2E (Existing-instance path: rewrite init prompts around {url, username, password} and add E2E coverage #58) (Existing-instance init: {url, user, password} prompts + E2E (#58) #59)0f63a08feat: ship.mcp.jsonwith scaffolded projects (Template: add .mcp.json so scaffolded projects are testable in Claude Code out of the box #55) (feat: ship .mcp.json with scaffolded projects (#55) #56)3a166a8Add worktree create/remove hook scripts (Add worktree create/remove hook scripts #57)Version bump
All version-carrying files bumped to
17.0.0-beta.14:package.json(root)packages/mcp-server-sdk/package.jsonpackages/hosted-mcp/package.jsonpackages/create-mcp-server/package.jsontemplate/package.jsonplugins/package.jsonplugins/.claude-plugin/plugin.json.claude-plugin/marketplace.json(metadata + both plugin entries)package-lock.jsonVerified no stale
beta.13references remain.Test plan
betadist-tag on mergev17.0.0-beta.14created from merge commitmainback intodev🤖 Generated with Claude Code