Agent Installation Contract

This is the normative, host-neutral installation procedure for the public BJD CMS Content distribution. Complete it in order. Do not weaken a failed check.

1. Establish the local target

Detect Windows, macOS, Linux, or WSL.
Identify the current Agent host and its supported local stdio MCP and skill registration mechanisms. Do not assume Codex.
Require Python 3.10 or newer. No third-party Python dependency is needed.
Preserve all unrelated existing Agent/MCP configuration. Before editing a shared configuration file, use the host's supported update mechanism or create a recoverable backup.

Stop and report if the host cannot run a local stdio MCP process or if its configuration location cannot be determined safely.

2. Select and verify an immutable release

Repository:

https://git.justconn.top/gitea-admin/bjd-cms-content

Resolve the latest stable, non-draft, non-prerelease Gitea Release.
Download SHA256SUMS and exactly one platform-appropriate archive: .tar.gz for POSIX systems or .zip for Windows.
Verify the archive byte-for-byte against its entry in SHA256SUMS before extraction.
Extract into a newly created temporary directory. Reject archive traversal, absolute members, symlinks, or a checksum mismatch.
Read RELEASE.json and require transport=stdio, skill_required=true, python_requires compatible with the installed Python, and positive server/client versions and tool count.

Never install from the floating main branch. Never continue after a missing asset, ambiguous latest release, or failed checksum.

3. Install side by side

From the extracted release root, run the bundled installer:

POSIX:   sh install/install.sh
Windows: powershell -ExecutionPolicy RemoteSigned -File install/install.ps1

Use the default per-user prefix unless the user or an existing managed setup provides a different absolute prefix. The installer creates a versioned directory and a current pointer; it must not overwrite an already installed directory of the same version.

Record the exact plugin and skill paths printed by the installer.

4. Register the host-neutral runtime

Read install/generic-mcp.md and the matching host adapter when present. Add or update only the bjd-cms-content registration with:

transport: stdio
command: the platform's Python 3 launcher
args: <absolute-plugin-path>/scripts/server.py
cwd: <absolute-plugin-path>
env.BJD_CMS_SKILL_ROOT: <absolute-skill-path>

Do not put a bearer Token in MCP configuration. If the host supports local skills, register the complete skill directory, not only SKILL.md. If it does not, retain the directory and ensure the Agent reads its README.md and SKILL.md before CMS work.

Restart or reload the Agent host using its supported lifecycle.

5. Verify the installed pair without credentials

Run the client.py adjacent to the installed server.py:

python3 <absolute-plugin-path>/scripts/client.py native-smoke

Require all of the following:

the reported server version equals RELEASE.json.server_version;
the reported client version equals RELEASE.json.client_version;
the reported tool count equals RELEASE.json.tool_count;
bundled_pair_verified=true;
initialization, ping, and tool listing succeed.

Stop on a mismatch. Do not substitute a global or cached client/server.

6. Configure credentials without exposing them

From the complete installed skill directory run:

python3 scripts/cms_api.py configure
python3 scripts/cms_api.py doctor

doctor is redacted and makes no network request. Do not read, print, or copy the configuration file. If token_configured=false, report the exact path printed by the helper and pause. Tell the user to fill only AI_CONTENT_API_TOKEN= locally with the independently issued credential. Never ask for the Token in chat and never put it in a command, prompt, source repository, MCP configuration, or log.

After a new explicit user message confirms the Token was saved, run only the read-only connection check:

python3 scripts/cms_api.py GET /api/ai/content/schema/news

Require a successful top-level envelope with no errors. A 401, 403, or 429 is an authoritative server boundary; stop and report it. Do not try a different credential or site.

7. Completion report

Report only:

installed release version and immutable release URL;
plugin and skill paths;
Agent host registration result;
redacted native-smoke identity and tool count;
whether the private Token is configured, without reading or displaying it;
read-only schema-check result, if the user had already saved a Token.

Do not exercise production write tools as an installation test. The first production mutation must be a reviewed real business draft following the skill's schema, validation, version, confirmation, verification, and audit rules.

4.9 KiB Raw Blame History