Publish the documented plexosdb-mcp distribution in release automation

[pesap]

Publish the documented plexosdb-mcp distribution in release automation

Executor instructions: Follow this issue step by step. Run every
verification command and confirm the expected result before moving on. If any
STOP condition is true, stop and report instead of improvising.

Drift check (run first): git diff --stat a11b6a3..HEAD -- .github/workflows/release.yaml .release-please-config.json .release-please-manifest.json src/plexosdb-mcp/pyproject.toml src/plexosdb-mcp/uv.lock src/plexosdb-mcp/README.md docs/source/howtos/mcp_server.md src/plexosdb-mcp/CHANGELOG.md
If any in-scope file changed since this issue was written, compare the
Current behavior excerpts against live code before proceeding. If they do not
match, stop and ask for /plan to refresh this issue.

Status

• Priority: P2
• Effort: M
• Risk: HIGH
• Depends on: Run the nested plexosdb-mcp package in CI and pre-push checks #155
• Category: dx
• Planned at: commit a11b6a3, 2026-07-08

Current behavior

The branch documents plexosdb-mcp as an installable package, but release
automation still builds and publishes only the root plexosdb distribution.

• src/plexosdb-mcp/README.md:9-23 — package README tells users to install and run plexosdb-mcp.

# src/plexosdb-mcp/README.md:9-23
uv add plexosdb-mcp
...
uvx plexosdb-mcp
...
uvx plexosdb-mcp --read-only

• docs/source/howtos/mcp_server.md:38-58 — user docs describe uv add plexosdb-mcp and uvx plexosdb-mcp.

# docs/source/howtos/mcp_server.md:38-58
uv add plexosdb-mcp
...
uvx plexosdb-mcp
...
uvx plexosdb-mcp --read-only

• src/plexosdb-mcp/pyproject.toml:2-17 — nested package metadata and script exist.

# src/plexosdb-mcp/pyproject.toml:2-17
name = "plexosdb-mcp"
version = "0.1.0"
...
[project.scripts]
plexosdb-mcp = "plexosdb_mcp.__main__:main"

• .github/workflows/release.yaml:65 — release build runs only the root build command.

# .github/workflows/release.yaml:65
run: uv build

• .release-please-config.json:63 — release-please is configured for the root package name only.

// .release-please-config.json:63
"package-name": "plexosdb"

Desired behavior or Goal

A release that documents uvx plexosdb-mcp must also build, version, smoke-test,
and publish the plexosdb-mcp distribution. The release workflow should produce
both root plexosdb artifacts and nested plexosdb-mcp artifacts intentionally,
with release-please tracking both package versions.

Acceptance criteria

• Release automation builds the root plexosdb distribution and the nested plexosdb-mcp distribution into the release artifact set.
• Release-please manifest/config tracks src/plexosdb-mcp as a separate Python package named plexosdb-mcp.
• A package smoke test installs the built plexosdb-mcp wheel and runs plexosdb-mcp health, expecting JSON with "ok": true.
• Public docs and the nested package README match the chosen publishing strategy.
• TestPyPI/PyPI publication is not enabled for plexosdb-mcp until Trusted Publishing or an equivalent approved publishing path exists for the plexosdb-mcp package name.

Non-goals

• Do not rename the root package or change the root plexosdb release behavior except where required to build both packages.
• Do not change MCP runtime behavior or tool names in this issue.
• Do not collapse the nested package into the root package; this issue follows the documented separate plexosdb-mcp package strategy.
• Do not publish to PyPI from a local machine; publication must remain in the GitHub release workflow.

Work Plan

Validation

• uv build exits 0 for the root package.
• uv build src/plexosdb-mcp --out-dir dist exits 0 and creates plexosdb_mcp wheel/sdist artifacts in dist/.
• A clean-venv smoke test installs the built plexosdb-mcp wheel and plexosdb dependency, then plexosdb-mcp health exits 0 and prints JSON containing "ok": true.
• uv run sphinx-build docs/source/ docs/_build/ exits 0 after doc updates.
• uv run prek run --show-diff-on-failure --color=always --all-files --hook-stage pre-push exits 0 before handoff.

Documentation

• Update src/plexosdb-mcp/README.md only if the publish/install command changes.
• Update docs/source/howtos/mcp_server.md only if the publish/install command changes.
• Add or configure a nested package changelog path if release-please requires one for src/plexosdb-mcp.

Testing

• Add a release/package smoke step in .github/workflows/release.yaml after building distributions and before upload/publish.
• The smoke test must exercise the console script, not only import the module.

Risks

Breaking-change

Medium. Runtime APIs are unchanged, but release automation touches package publishing. Misconfiguration can block releases or publish incomplete artifacts.

Review-size

Medium. Scope is limited to release config, release workflow, package metadata/lockfiles, and docs/changelog updates.

Implementation notes

Scope

In scope:

• .github/workflows/release.yaml
• .release-please-config.json
• .release-please-manifest.json
• src/plexosdb-mcp/pyproject.toml
• src/plexosdb-mcp/uv.lock
• src/plexosdb-mcp/README.md
• docs/source/howtos/mcp_server.md
• src/plexosdb-mcp/CHANGELOG.md if release-please needs a nested changelog file

Out of scope:

• .github/workflows/CI.yaml — covered by the CI/pre-push issue this packet depends on.
• src/plexosdb-mcp/src/plexosdb_mcp/server.py — no runtime behavior changes.
• Root package source under src/plexosdb/ — no package API changes are needed.

Suggested steps

1. Confirm release-please monorepo configuration for a second Python package under src/plexosdb-mcp.
   • Add a packages["src/plexosdb-mcp"] entry with package-name: "plexosdb-mcp" and the required extra-files/version paths for the nested package.
   • Add src/plexosdb-mcp to .release-please-manifest.json with the current nested version.
2. Update .github/workflows/release.yaml so the build job builds both packages into dist/.
   • Keep uv build for the root package.
   • Add uv build src/plexosdb-mcp --out-dir dist for the nested package.
3. Add a package smoke test before uploading release artifacts.
   • Install the built root and MCP wheels into a clean virtual environment.
   • Run plexosdb-mcp health and assert JSON contains "ok": true.
4. Check TestPyPI/PyPI Trusted Publishing readiness for the plexosdb-mcp project name.
   • If the publishing trust relationship is not configured for plexosdb-mcp, stop and report the exact environment/package setup required.
5. Update docs only if install/run commands change.

Test details

• The smoke test should install from local dist/ artifacts to prove the console script exists in the built wheel.
• Keep root package smoke behavior intact.

Maintenance notes

• Reviewers should inspect artifact names in CI logs and confirm both packages are present before publish jobs run.
• Future nested packages should follow the same release-please package entry pattern rather than being hidden behind the root package release.