@mokoconsulting/mcp-mokosuite 1.0.0 → 1.1.0-dev.372

package/.mokogit/workflows/pre-release.yml

@@ -7,8 +7,8 @@
 # INGROUP: MokoCLI.Release
 # REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Generic
 # PATH: /.mokogit/workflows/pre-release.yml
-# VERSION: 06.00.00
-# BRIEF: Batched pre-release on nightly schedule + manual dispatch (rolling dev/rc asset, build-metadata version — #404)
+# VERSION: 06.01.00
+# BRIEF: Batched pre-release on nightly schedule + manual dispatch (rolling dev/rc asset, build-metadata version — #404); non-Joomla MokoGIT release + cosmetic release-notes are best-effort. npm publishing moved OUT of this universal workflow into Template-NPM's dedicated npm-publish.yml so it can't leak into non-npm repos via sync.
 
 name: "Universal: Pre-Release"
 
@@ -19,8 +19,32 @@ name: "Universal: Pre-Release"
 # as BUILD METADATA (version_build_metadata.php) instead of a committed bump, and
 # the asset is published under a FIXED rolling name replaced in place.
 on:
+  # Dev-channel release on every merge to dev. Uses build-metadata versioning
+  # (version_build_metadata.php) so nothing is committed back to dev — the #404
+  # manifest <version> merge-conflict problem does NOT return. paths-ignore is a
+  # non-code denylist: a push touching only docs / CI config / repo metadata does
+  # not build. The concurrency guard below collapses a burst of merges into one.
+  push:
+    branches:
+      - dev
+    paths-ignore:
+      - '.mokogit/**'
+      - '.gitea/**'
+      - '.github/**'
+      - '.vscode/**'
+      - '.idea/**'
+      - 'docs/**'
+      - 'wiki/**'
+      - '**/*.md'
+      - '.editorconfig'
+      - '.gitignore'
+      - '.gitattributes'
+      - '.gitmodules'
+      - '.gitmessage'
+      - 'phpstan.neon'
+      - 'LICENSE'
   schedule:
-    # Nightly at 07:00 UTC — batches the day's dev merges into one dev build.
+    # Nightly at 07:00 UTC — safety-net batch for any dev merge a push build missed.
     - cron: '0 7 * * *'
   workflow_dispatch:
     inputs:
@@ -40,6 +64,14 @@ on:
         default: dev
         type: string
 
+concurrency:
+  # Per channel + ref: a burst of dev merges collapses to the latest build. A
+  # manual alpha/beta/rc dispatch has its own group, so it is never cancelled by
+  # a dev push (and vice versa); the nightly runs on the default-branch ref, a
+  # different group again.
+  group: pre-release-${{ github.ref }}-${{ inputs.stability || 'development' }}
+  cancel-in-progress: true
+
 permissions:
   contents: write
 
@@ -53,14 +85,15 @@ jobs:
     name: "Build Pre-Release (${{ inputs.stability || 'development' }})"
     runs-on: release
     # Skip on template repos (Template-*) — they scaffold other repos and do not release.
-    # Trigger-loop guard (#404 follow-up): this workflow already runs ONLY on `schedule` +
-    # `workflow_dispatch` (the every-push trigger that caused the ~150x pre-release storm on
-    # chore/mokoonyx-template-sync-* branches was removed in #404) — so a template-sync push
-    # can no longer reach it. As defence-in-depth we also refuse a manual dispatch aimed at a
-    # bot/sync ref, so provisioning tooling cannot fan out dispatches against those branches.
+    # Triggers: push to dev (per-merge dev-channel build), the nightly schedule
+    # (safety-net batch), and manual workflow_dispatch. The push trigger is scoped
+    # to `dev` + a non-code paths-ignore, so a template-sync/doc-only push can't
+    # reach it (the ~150x storm on chore/mokoonyx-template-sync-* stays prevented).
+    # As defence-in-depth we also refuse a manual dispatch aimed at a bot/sync ref.
     if: >-
       !startsWith(github.event.repository.name, 'Template-') &&
       (
+        github.event_name == 'push' ||
         github.event_name == 'schedule' ||
         (
           github.event_name == 'workflow_dispatch' &&
@@ -73,9 +106,9 @@ jobs:
       )
 
     steps:
-      # #404 — no push event any more. The build ref is the dispatch input (default
-      # dev) or, for the nightly schedule, dev. On schedule github.ref_name is the
-      # default branch (main), so we resolve the pre-release branch explicitly here.
+      # Build ref: the dispatch input if given, else `dev` — which is correct for
+      # both a push (only `dev` triggers it) and the nightly schedule (where
+      # github.ref_name would otherwise be the default branch, main).
       - name: Resolve build ref
         id: ref
         run: echo "ref=${{ inputs.ref || 'dev' }}" >> "$GITHUB_OUTPUT"
@@ -88,9 +121,32 @@ jobs:
           ref: ${{ steps.ref.outputs.ref }}
           submodules: recursive
 
-      - name: Update submodules to main
+      - name: Update submodules to latest
+        # Skip cleanly on submodule-less repos. The old step was a silent no-op:
+        # `2>/dev/null || true` swallowed every error and the in-step `git pull`
+        # used an UN-credentialed remote, so private submodules never actually
+        # updated. Credential the private remote, then update each submodule to its
+        # tracked branch (default: the submodule's default branch) so the built
+        # package contains the latest submodule content. Per #404 this is
+        # working-tree only (no commit) — the package is built from the working tree.
+        run: |
+          if [ -f .gitmodules ]; then
+            git config --global url."https://x-access-token:${{ secrets.MOKOGIT_TOKEN }}@git.mokoconsulting.tech/".insteadOf "https://git.mokoconsulting.tech/"
+            git submodule sync --recursive
+            git submodule update --init --remote --recursive
+          else
+            echo "No .gitmodules — skipping submodule update."
+          fi
+
+      - name: Isolate workspace (remove foreign/stale checkouts)
         run: |
-          git submodule foreach --quiet 'git checkout main && git pull --quiet origin main' 2>/dev/null || true
+          find . -name .git -not -path './.git' -prune -print | while read nested; do
+            dir=$(dirname "$nested")
+            [ "$dir" = "." ] && continue
+            git ls-files --error-unmatch "$dir" >/dev/null 2>&1 && continue
+            echo "::warning::Removing untracked nested checkout: $dir"
+            rm -rf "$dir"
+          done
 
       - name: Setup MokoCLI tools
         env:
@@ -100,19 +156,39 @@ jobs:
           # Use pre-installed /opt/mokocli if available (updated by cron every 6h)
           if [ -f /opt/mokocli/cli/version_bump.php ] && [ -f /opt/mokocli/cli/manifest_element.php ] && [ -f /opt/mokocli/vendor/autoload.php ]; then
             echo Using pre-installed /opt/mokocli
+            # Keep the pre-installed copy current with mokocli main (auto-refresh; soft — never fails the run).
+            if git -C /opt/mokocli rev-parse --git-dir >/dev/null 2>&1; then
+              git -C /opt/mokocli pull --ff-only --quiet 2>/dev/null || echo "  (mokocli git refresh skipped)"
+              REFRESH_TOK="$(printf '%s' "${MOKO_CLONE_TOKEN}" | tr -d '[:space:]')"
+              if [ -n "${REFRESH_TOK}" ] && command -v composer >/dev/null 2>&1; then
+                composer config -g http-basic.git.mokoconsulting.tech x-access-token "${REFRESH_TOK}" 2>/dev/null || true
+                ( cd /opt/mokocli && composer install --no-dev --no-interaction --no-progress --optimize-autoloader --quiet ) 2>/dev/null || echo "  (mokocli composer refresh skipped)"
+              fi
+            fi
             echo MOKO_CLI=/opt/mokocli/cli >> $GITHUB_ENV
           else
             echo Falling back to fresh clone
+            # Strip any stray whitespace/newline a pasted secret may carry, and mask
+            # it in the logs. Without the trim + quoted URL below, a trailing newline
+            # in MOKOGIT_TOKEN word-splits CLONE_URL so git clone sees extra
+            # positionals and dies with "fatal: Too many arguments".
+            MOKO_CLONE_TOKEN="$(printf '%s' "${MOKO_CLONE_TOKEN}" | tr -d '[:space:]')"
+            echo "::add-mask::${MOKO_CLONE_TOKEN}"
+            if [ -z "${MOKO_CLONE_TOKEN}" ]; then
+              echo "::error::MOKOGIT_TOKEN secret is empty — cannot clone mokocli fallback." >&2
+              exit 1
+            fi
             if ! command -v composer > /dev/null 2>&1; then
               sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer > /dev/null 2>&1
             fi
             rm -rf /tmp/mokocli
-            CLONE_URL=https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/mokocli.git
-            git clone --depth 1 --branch main --quiet $CLONE_URL /tmp/mokocli
+            CLONE_URL="https://x-access-token:${MOKO_CLONE_TOKEN}@${MOKO_CLONE_HOST}/mokocli.git"
+            git clone --depth 1 --branch main --quiet "${CLONE_URL}" /tmp/mokocli
             cd /tmp/mokocli
             # Authenticate to the MokoGIT private Composer registry (git.mokoconsulting.tech)
             # declared in mokocli composer.json (preferred-install=dist) before installing deps.
             composer config -g http-basic.git.mokoconsulting.tech x-access-token "${MOKO_CLONE_TOKEN}"
+            export COMPOSER_AUTH="{\"http-basic\":{\"git.mokoconsulting.tech\":{\"username\":\"x-access-token\",\"password\":\"${MOKO_CLONE_TOKEN}\"}}}"
             composer install --no-dev --no-interaction --no-progress --optimize-autoloader --quiet
             echo MOKO_CLI=/tmp/mokocli/cli >> $GITHUB_ENV
           fi
@@ -266,6 +342,11 @@ jobs:
             --path . --version "$VERSION" --branch "${{ steps.ref.outputs.ref }}" --stability "$STABILITY" 2>/dev/null || true
           php ${MOKO_CLI}/version_check.php --path . --fix 2>/dev/null || true
 
+          # Emit a Joomla schema-update stub for each shipped extension's own
+          # version so #__schemas tracks the manifest (fixes "database out of date").
+          # No-op (|| true) on non-Joomla repos, which have no sql/updates dirs.
+          php ${MOKO_CLI}/schema_stub.php --path . || true
+
           # Ensure licensing tags (updateservers, dlid) if enabled in manifest.xml
           php ${MOKO_CLI}/manifest_licensing.php --path . --fix 2>/dev/null || true
 
@@ -302,20 +383,61 @@ jobs:
 
           echo "=== Pre-Release: ${EXT_ELEMENT} ${VERSION}${SUFFIX} ==="
 
+      # npm publishing is NOT part of this universal workflow — it lives only in
+      # Template-NPM (.mokogit/workflows/npm-publish.yml) so it cannot leak into
+      # Joomla / non-npm repos via template sync. Joomla-family repos attach a zip
+      # below; npm repos publish from their own dedicated workflow.
+      # Release API operations (create / notes / upload / cascade delete) run
+      # against THIS repo, so they authenticate with the built-in per-run
+      # github.token (contents: write) — NOT the org MOKOGIT_TOKEN. That keeps
+      # MOKOGIT_TOKEN least-privilege (read-only, used only for the cross-repo
+      # mokocli / submodule clones above) while same-repo release writes stay
+      # scoped to the run — matching auto-release.yml (Template-Generic #188).
+      # github.token carries no trailing newline, but trim + mask anyway for
+      # Authorization-header hygiene.
+      - name: Sanitize release API token
+        if: steps.eligibility.outputs.proceed == 'true'
+        run: |
+          T="$(printf '%s' "${{ github.token }}" | tr -d '[:space:]')"
+          echo "::add-mask::${T}"
+          echo "MOKO_TOKEN=${T}" >> "$GITHUB_ENV"
+
       - name: Create release
         id: release
         if: steps.eligibility.outputs.proceed == 'true'
+        # The MokoGIT release is the deliverable ONLY for the Joomla family. npm/mcp/
+        # client publish their real artifact upstream (npm) and merely mirror a
+        # release here, so a MokoGIT release failure must not fail those runs.
+        # release_create.php can fail its delete-then-recreate of the rolling dev/rc
+        # release (DELETE returns HTTP 200 but the release lingers), which turns an
+        # already-successful npm publish red. We branch on family INSIDE the run
+        # script (this act runner rejects `continue-on-error: ${{ ... }}` — it only
+        # accepts a literal bool): Joomla stays fatal; non-Joomla swallows a release
+        # failure so a green npm publish stays green.
         run: |
           TAG="${{ steps.meta.outputs.tag }}"
           VERSION="${{ steps.meta.outputs.version }}"
           API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
-          php ${MOKO_CLI}/release_create.php \
-            --path . --version "$VERSION" --tag "$TAG" \
-            --token "${{ secrets.MOKOGIT_TOKEN }}" --api-base "$API_BASE" \
-            --repo "${GIT_REPO}" --branch "${{ steps.ref.outputs.ref }}" --prerelease
+          if [ "${{ steps.eligibility.outputs.is_joomla_family }}" = "true" ]; then
+            php ${MOKO_CLI}/release_create.php \
+              --path . --version "$VERSION" --tag "$TAG" \
+              --token "${MOKO_TOKEN}" --api-base "$API_BASE" \
+              --repo "${GIT_REPO}" --branch "${{ steps.ref.outputs.ref }}" --prerelease
+          else
+            php ${MOKO_CLI}/release_create.php \
+              --path . --version "$VERSION" --tag "$TAG" \
+              --token "${MOKO_TOKEN}" --api-base "$API_BASE" \
+              --repo "${GIT_REPO}" --branch "${{ steps.ref.outputs.ref }}" --prerelease \
+              || echo "::warning::MokoGIT release failed — non-fatal for npm/mcp/client (npm is the real artifact)"
+          fi
 
       - name: Update release notes from CHANGELOG.md
         if: steps.eligibility.outputs.proceed == 'true'
+        # Release notes are cosmetic. The release-body PATCH can 403 on this MokoGIT
+        # instance (the per-run github.token lacks release-write), and for npm/mcp/
+        # client the published package is the real artifact — never let this fail
+        # the run. (Matches the cascade step's best-effort contract.)
+        continue-on-error: true
         run: |
           TAG="${{ steps.meta.outputs.tag }}"
           VERSION="${{ steps.meta.outputs.version }}"
@@ -332,7 +454,7 @@ jobs:
           fi
 
           # Update release body via API
-          RELEASE_ID=$(curl -sf -H "Authorization: token ${{ secrets.MOKOGIT_TOKEN }}" \
+          RELEASE_ID=$(curl -sf -H "Authorization: token ${MOKO_TOKEN}" \
             "${API_BASE}/releases/tags/${TAG}" | python3 -c "import json,sys; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
 
           if [ -n "$RELEASE_ID" ]; then
@@ -344,7 +466,7 @@ jobs:
               '${API_BASE}/releases/${RELEASE_ID}',
               data=payload, method='PATCH',
               headers={
-                  'Authorization': 'token ${{ secrets.MOKOGIT_TOKEN }}',
+                  'Authorization': 'token ${MOKO_TOKEN}',
                   'Content-Type': 'application/json'
               })
           urllib.request.urlopen(req)
@@ -352,6 +474,25 @@ jobs:
             echo "Release notes updated from CHANGELOG.md"
           fi
 
+      # Build-time PHP dependency vendoring (universal, guarded). If a package ships a
+      # composer.json, fetch its runtime deps into that package's vendor dir BEFORE
+      # release_package.php zips the working tree — so a component can declare a PHP
+      # library (e.g. dompdf) via composer.json + composer.lock instead of committing
+      # vendor/. No-op for any repo without a package composer.json; non-fatal so a
+      # composer failure can never block a release (it packages whatever vendor exists).
+      - name: Vendor PHP dependencies (build-time)
+        if: steps.eligibility.outputs.proceed == 'true'
+        continue-on-error: true
+        run: |
+          command -v composer >/dev/null 2>&1 || { sudo apt-get update -qq && sudo apt-get install -y -qq composer >/dev/null 2>&1 || true; }
+          for cj in $(find source/packages -maxdepth 2 -name composer.json 2>/dev/null); do
+            dir="$(dirname "$cj")"
+            echo "::notice::composer install (no-dev) in ${dir}"
+            composer install --no-dev --no-interaction --no-progress --optimize-autoloader --working-dir="$dir" \
+              || echo "::warning::composer install failed in ${dir} — packaging existing vendor"
+          done
+          true
+
       # Joomla-family only: mokocli release_package.php builds the extension zip
       # (+ sha256, attach). npm/mcp/client package/publish in their platform shim
       # (trust boundary, ADR #124), so this PHP zip step is skipped for them.
@@ -365,31 +506,29 @@ jobs:
           TAG="${{ steps.meta.outputs.tag }}"
           STABILITY="${{ steps.meta.outputs.stability }}"
           API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
-          # #404 — publish the pre-release asset under a FIXED rolling name
-          # (pkg_<ext>-dev.zip / -rc.zip) replaced in place, instead of a new
-          # versioned file each build. --stability drives the channel slug; the
-          # in-package manifest <version> still advances (build metadata) so the
-          # updater keeps detecting new builds.
+          # Publish the pre-release asset under a VERSIONED rolling name
+          # (pkg_<ext>-<version>-dev.zip / -rc.zip) replaced in place each build. The
+          # release version is stable within a base version, so the asset URL stays
+          # stable while the version is visible in the filename. The in-package
+          # manifest <version> still advances (build metadata) so the updater keeps
+          # detecting new builds.
           php ${MOKO_CLI}/release_package.php \
             --path . --version "$VERSION" --tag "$TAG" \
-            --token "${{ secrets.MOKOGIT_TOKEN }}" --api-base "$API_BASE" \
+            --token "${MOKO_TOKEN}" --api-base "$API_BASE" \
             --repo "${GIT_REPO}" --output /tmp \
             --stability "$STABILITY" --rolling || true
 
-      # updates.xml is generated dynamically by MokoGIT license server.
-      # #404 — the dynamic feed must point <downloadurl> at the FIXED rolling asset
-      # name for dev/rc (pkg_<ext>-dev.zip), matching what release_package.php now
-      # publishes. mokocli's updates_xml_build.php grew a --rolling flag for this;
-      # the server-side generator (MokoGIT license server) needs the equivalent
-      # change so the served updates.xml references the fixed filename, not the old
-      # versioned one. See #404 report — flagged for human/server-side follow-up.
+      # updates.xml <downloadurl> is generated server-side by MokoGIT (the license
+      # server; being moved to MokoSuiteLicensing). It must reference the VERSIONED
+      # rolling asset (pkg_<ext>-<version>-dev.zip) that release_package.php now
+      # publishes — keep the server-side generator in sync with that filename.
 
       - name: "Delete lesser pre-release channels (cascade)"
         if: steps.eligibility.outputs.proceed == 'true'
         continue-on-error: true
         run: |
           API_BASE="${GIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
-          TOKEN="${{ secrets.MOKOGIT_TOKEN }}"
+          TOKEN="${MOKO_TOKEN}"
 
           php ${MOKO_CLI}/release_cascade.php \
             --stability "${{ steps.meta.outputs.stability }}" \

package/.mokogit/workflows/rc-revert.yml

@@ -34,7 +34,7 @@ jobs:
           BRANCH: ${{ github.event.pull_request.head.ref }}
           REPO: ${{ github.repository }}
           GIT_URL: ${{ vars.MOKOGIT_URL || 'https://git.mokoconsulting.tech' }}
-          TOKEN: ${{ secrets.MOKOGIT_TOKEN }}
+          TOKEN: ${{ secrets.MOKOGIT_TOKEN || github.token }}
         run: |
           set -euo pipefail
           # BRANCH is attacker-controlled (PR head ref). Strict allowlist before ANY use.

package/.mokogit/workflows/version-set.yml

@@ -5,12 +5,12 @@
 # FILE INFORMATION
 # DEFGROUP: MokoGIT.Workflow.Template
 # INGROUP: MokoCLI.CI
-# REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Joomla
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Generic
 # PATH: /.mokogit/workflows/version-set.yml
-# VERSION: 01.00.00
-# BRIEF: Set or reset the extension version across all version-bearing files
+# VERSION: 01.01.00
+# BRIEF: Set or reset the project version across all version-bearing files (README / CHANGELOG / file-header blocks universal; the Joomla manifest step is guarded and no-ops on non-Joomla repos)
 
-name: "Joomla: Set Version"
+name: "Universal: Set Version"
 
 on:
   workflow_dispatch:

package/AGENTS.md

@@ -0,0 +1,39 @@
+<!--
+  Copyright 2026 Moko Consulting
+  SPDX-License-Identifier: GPL-3.0-or-later
+  BRIEF: Shared AI-agent instruction source of truth for this repository.
+  This file is the single point of truth; CLAUDE.md / GEMINI.md / MOKOAI.md point here.
+-->
+
+# mcp-mokosuite — Agent Instructions
+
+`mcp-mokosuite` is an MCP (Model Context Protocol) server for MokoSuite. It
+exposes MokoSuite operations to AI agents over the Model Context Protocol.
+
+> Read by every AI agent (Claude Code, Gemini CLI, MokoAI). CLAUDE.md / GEMINI.md / MOKOAI.md point here.
+
+## Platform & Layout
+
+- Platform: MCP server (Node.js).
+- Language: TypeScript.
+- Source dir: `src/`.
+- TypeScript config: `tsconfig.json`.
+- Example runtime config: `config.example.json`.
+- Docs: `docs/`.
+- Notable files: `package.json`, `Makefile`, `CODE_OF_CONDUCT.md`.
+
+## Commands
+
+- `npm install` — install dependencies.
+- `npm run build` — compile TypeScript (see `package.json` scripts).
+- `make` — see `Makefile` for the repo's build/lint targets.
+
+## Rules
+
+- Never commit `.claude/`, `.gemini/`, `.mokoai/`, `.mcp.json`, `TODO.md`, or
+  minified/compiled assets.
+- Workflow / automation config lives under `.mokogit/`.
+- Attribute all machine-authored commits with `Authored-by: Moko Consulting`.
+- Do not commit real credentials; copy `config.example.json` to a local,
+  ignored config.
+- Standards: MokoCLI — https://git.mokoconsulting.tech/MokoConsulting/mokocli/wiki/Home

package/CHANGELOG.md

@@ -1,18 +1,54 @@
+# Changelog
 
+All notable changes to this project are documented here, following [Keep a Changelog](https://keepachangelog.com/) and MokoStandards `XX.YY.ZZ` versioning.
 
 ## [Unreleased]
 
-### Changed
-- Branding: Git -> MokoGIT in workflow DEFGROUP tags, committer identity (git-actions[bot] -> mokogit-actions[bot]), and platform prose. Functional tokens (GIT_TOKEN/GITHUB_TOKEN, GIT_ACTIONS_*, vars.GITEA_*, git.mokoconsulting.tech) preserved.
+## [01.01.00] - 2026-08-15
 
-### Removed
-- CI: stripped GitHub-only workflows (DEFGROUP GitHub.Workflow), which do not run on MokoGIT Actions: auto-dev-issue.yml changelog-validation.yml standards-compliance.yml sync-version-on-merge.yml.
+### Added
+- **Layer 1 (Extensions Store / MokoSuiteExtensions)** — 5 MCP tools against the
+  `/v1/mokosuiteextensions` base path:
+  - Reads: `store_catalog_list` (`GET /catalog`), `store_catalog_get`
+    (`GET /catalog/{id}`).
+  - Writes: `store_install` (`POST /catalog/{id}/install`), `store_update`
+    (`POST /catalog/{id}/update`), `store_uninstall`
+    (`POST /catalog/{id}/uninstall`, `confirm: true` guard — destructive).
+- Bumped the MCP server advertised version to `1.1.0`.
+
+### Note
+- The store write routes (`/install`, `/update`, `/uninstall`) are being added to
+  the store REST API in parallel and may not be live on a site until that ships and
+  deploys. The read routes exist. The tools are defined now regardless.
 
-### Changed
-- Migrated all workflow and template paths from `.github/` to `.mokogit/`
-- Template source paths updated: `templates/git/` to `templates/mokogit/`
-- HCL definition files removed -- Template repos are now the canonical source
+## [01.00.00] - 2026-07-26
 
 ### Added
-- CI: gate build/CI/release/version workflows so they skip template repos; smart-gate the sync workflows to run only on Template-* repos; normalize mokocli/MokoCLI refs and drop the stale mokoconsulting-tech org slug.
-- `branch-cleanup.yml`: auto-delete merged feature branches after PR merge
+- **Foundation** — the real MokoSuite MCP server (de-templated from Template-NPM):
+  - Multi-site connection model with two credential tiers per site — a Joomla Web
+    Services Bearer token for read/CRUD, plus an optional `health_api_token` + HQ
+    RSA private key for the remote-control tier (`src/types.ts`).
+  - RSA remote-control request signing reproducing HQ's
+    `X-MokoSuite-Signature` / `-Timestamp` / `-Key-Version` scheme (RSA-2048 over
+    `domain|timestamp|token`, SHA-256, 300 s window) (`src/signing.ts`).
+  - Joomla Web Services HTTP client with a signed `remoteControl()` path alongside
+    the token-auth methods (`src/client.ts`).
+- **Layer 0 (Platform / MokoSuiteClient)** — 24 MCP tools:
+  - Foundation: `mokosuite_ping`, `list_connections`, `api_request`.
+  - Reads: `client_get_health`, `client_get_dashboard`, `client_list_extensions`,
+    `client_list_plugins`, `client_list_snapshots`, `client_list_users`,
+    `client_export_users`.
+  - Actions: `client_clear_cache`, `client_check_updates`, `client_install_extension`,
+    `client_toggle_plugin`, `client_create_snapshot`, `client_reset_snapshot`,
+    `client_sync_push`.
+  - Remote-control (RSA-signed; `confirm: true` guard on destructive fleet-wide ops):
+    `client_provision_reset`, `client_remote_login`, `client_users_reset_passwords`,
+    `client_users_reset_2fa`, `client_users_disable_all`, `client_users_enable_all`,
+    `client_users_force_logout`.
+- Published `@mokoconsulting/mcp-mokosuite@1.0.0` to npmjs.org and the internal
+  git.mokoconsulting.tech registry.
+
+### Verified
+- The read tier (`get_health`, `get_dashboard`, `list_extensions`, `list_plugins`,
+  `list_snapshots`) returns live data from `suite.dev.mokoconsulting.tech`
+  (`/api/index.php/v1/mokosuiteclient/*`).

package/dist/index.js

@@ -21,6 +21,8 @@ import { ApiClient } from './client.js';
 import { hasRemoteControl } from './signing.js';
 /** Base path for MokoSuiteClient Web Services (appended after /api/index.php). */
 const MSC = '/v1/mokosuiteclient';
+/** Base path for MokoSuiteExtensions (store) Web Services (appended after /api/index.php). */
+const MSE = '/v1/mokosuiteextensions';
 let config;
 function clientFor(connection) {
     return new ApiClient(getConnection(config, connection));
@@ -51,7 +53,7 @@ function requireConfirm(confirm) {
 // ── Server ──────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'mcp-mokosuite',
-    version: '1.0.0',
+    version: '1.1.0',
 });
 // ════════════════════════════════════════════════════════════════════════
 // FOUNDATION — connectivity & generic access
@@ -168,6 +170,31 @@ server.tool('client_users_force_logout', 'Terminate ALL user sessions on a MokoS
         return guard;
     return formatResponse(await clientFor(connection).remoteControl('POST', `${MSC}/users/force-logout`));
 });
+// ════════════════════════════════════════════════════════════════════════
+// LAYER 1 — Extensions Store (MokoSuiteExtensions)
+// ════════════════════════════════════════════════════════════════════════
+server.tool('store_catalog_list', 'List the products available in the MokoSuite Extensions store catalog for a site.', { ...ConnectionParam }, async ({ connection }) => formatResponse(await clientFor(connection).get(`${MSE}/catalog`)));
+server.tool('store_catalog_get', 'Get a single MokoSuite Extensions store product by its catalog id.', {
+    id: z.number().describe('Catalog product id'),
+    ...ConnectionParam,
+}, async ({ id, connection }) => formatResponse(await clientFor(connection).get(`${MSE}/catalog/${id}`)));
+server.tool('store_install', 'Install a MokoSuite Extensions store product on a site by its catalog id.', {
+    id: z.number().describe('Catalog product id to install'),
+    ...ConnectionParam,
+}, async ({ id, connection }) => formatResponse(await clientFor(connection).post(`${MSE}/catalog/${id}/install`)));
+server.tool('store_update', 'Update an installed MokoSuite Extensions store product on a site by its catalog id.', {
+    id: z.number().describe('Catalog product id to update'),
+    ...ConnectionParam,
+}, async ({ id, connection }) => formatResponse(await clientFor(connection).post(`${MSE}/catalog/${id}/update`)));
+server.tool('store_uninstall', 'Uninstall a MokoSuite Extensions store product from a site by its catalog id. Destructive — requires `confirm: true`.', {
+    id: z.number().describe('Catalog product id to uninstall'),
+    confirm: z.boolean().describe('Must be true — uninstalling removes the product from the target site'),
+    ...ConnectionParam,
+}, async ({ id, confirm, connection }) => {
+    if (!confirm)
+        return text('Refused: set `confirm: true` to uninstall this store product.');
+    return formatResponse(await clientFor(connection).post(`${MSE}/catalog/${id}/uninstall`));
+});
 // ── Start Server ────────────────────────────────────────────────────────
 async function main() {
     config = await loadConfig();

package/docs/API.md

@@ -11,53 +11,62 @@ BRIEF: MCP tool reference documentation
 
 # API Reference
 
-All tools accept an optional `connection` parameter to target a specific named connection. If omitted, the default connection is used.
-
-## Example Resources
-
-> Replace these example tools with your actual API tools.
-
-### `example_resources_list`
-List resources with optional search.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `search` | string | No | Search query |
-| `limit` | number | No | Max results |
-| `page` | number | No | Page number (0-based) |
-
-### `example_resource_get`
-Get a single resource by ID.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `id` | number | Yes | Resource ID |
-
-### `example_resource_create`
-Create a new resource.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `name` | string | Yes | Resource name |
-| `description` | string | No | Resource description |
-
-## Generic
-
-### `api_request`
-Make a raw API request to any endpoint.
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `method` | `"GET"` / `"POST"` / `"PUT"` / `"PATCH"` / `"DELETE"` | Yes | HTTP method |
-| `endpoint` | string | Yes | API path |
-| `body` | object | No | Request body |
-| `params` | object | No | Query parameters |
-
-### `list_connections`
-List all configured connections. No parameters.
+Every tool accepts an optional `connection` parameter naming a MokoSuite site/connection from your config (`~/.mcp_mokosuite.json`); omit it to use the default. Tool endpoints target the MokoSuiteClient Web Services under `/api/index.php/v1/mokosuiteclient/`.
+
+Two credential tiers apply per connection:
+- **Read / CRUD** — the site's Joomla Web Services Bearer token (`apiToken`).
+- **Remote-control** (RSA-signed) — the site's `healthApiToken` + HQ's `rsaPrivateKeyPath`. Tools in that tier fail with a clear message if those aren't configured.
+
+## Foundation
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `mokosuite_ping` | `connection?` | Check a site's reachability (calls its dashboard endpoint, reports HTTP status). |
+| `list_connections` | — | List configured sites, their role, and which credential tiers are available. |
+| `api_request` | `method`, `endpoint`, `body?`, `params?`, `connection?` | Raw request to any endpoint relative to `/api/index.php` (escape hatch). |
+
+## Layer 0 — Platform (MokoSuiteClient)
+
+### Reads (Joomla API token)
+
+| Tool | Parameters | Endpoint |
+|------|------------|----------|
+| `client_get_health` | `connection?` | `GET /v1/mokosuiteclient/health` — full 16-check diagnostics |
+| `client_get_dashboard` | `connection?` | `GET .../dashboard` — health summary, versions, plugin states |
+| `client_list_extensions` | `connection?` | `GET .../extensions` — installed + update info |
+| `client_list_plugins` | `connection?` | `GET .../plugins` — Moko feature plugins + state |
+| `client_list_snapshots` | `connection?` | `GET .../snapshot` |
+| `client_list_users` | `connection?` | `GET .../users` |
+| `client_export_users` | `connection?` | `GET .../users/export` |
+
+### Actions (Joomla API token, `core.manage`)
+
+| Tool | Parameters | Endpoint |
+|------|------------|----------|
+| `client_clear_cache` | `connection?` | `POST .../cache` |
+| `client_check_updates` | `connection?` | `POST .../update` |
+| `client_install_extension` | `url`, `connection?` | `POST .../install` — install from remote ZIP (64 MB cap) |
+| `client_toggle_plugin` | `extension_id`, `connection?` | `POST .../plugins` (`task=toggle`) |
+| `client_create_snapshot` | `label?`, `connection?` | `POST .../snapshot` |
+| `client_reset_snapshot` | `name`, `connection?` | `POST .../reset` — restore a baseline |
+| `client_sync_push` | `target?`, `connection?` | `POST .../sync` |
+
+### Remote-control (RSA-signed; requires HQ credentials)
+
+Destructive fleet-wide tools require `confirm: true`.
+
+| Tool | Parameters | Endpoint |
+|------|------------|----------|
+| `client_provision_reset` | `confirm`, `connection?` | `POST .../provision-reset` |
+| `client_remote_login` | `connection?` | `POST .../remote-login` — one-time login URL (60 s TTL) |
+| `client_users_reset_passwords` | `confirm`, `connection?` | `POST .../users/reset-passwords` |
+| `client_users_reset_2fa` | `confirm`, `connection?` | `POST .../users/reset-2fa` |
+| `client_users_disable_all` | `confirm`, `connection?` | `POST .../users/disable-all` |
+| `client_users_enable_all` | `confirm`, `connection?` | `POST .../users/enable-all` |
+| `client_users_force_logout` | `confirm`, `connection?` | `POST .../users/force-logout` |
 
 ## Revision History
 
 | Date | Version | Author | Notes |
 | --- | --- | --- | --- |
-| 2026-05-07 | 0.0.1 | jmiller | Initial template API reference |
+| 2026-07-26 | 01.00.00 | Moko Consulting | Foundation + Layer 0 tool reference (24 tools) |