minecode-mcp 0.2.0__tar.gz → 0.2.2__tar.gz

{minecode_mcp-0.2.0 → minecode_mcp-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: minecode-mcp
-Version: 0.2.0
+Version: 0.2.2
 Summary: MCP Server for Minecraft datapack development with wiki, Spyglass, Misode, and Mojira integrations
 Project-URL: Homepage, https://github.com/AnCarsenat/minecode-mcp
 Project-URL: Repository, https://github.com/AnCarsenat/minecode-mcp
@@ -27,18 +27,35 @@ Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: twine>=5.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# 🎮 MineCode MCP
+<!--
+  Absolute raw URLs, not relative paths: this file is also the PyPI long
+  description, and PyPI does not resolve repo-relative image paths.
+  Points at the 256x256 export and displays at 128, so the browser scales
+  DOWN rather than up. GitHub strips style attributes, so image-rendering
+  cannot be set -- downscaling is what keeps the block art from smearing.
+-->
+<div align="center">
 
-**MCP Server for Minecraft Datapack Development**
+<img src="https://github.com/AnCarsenat/minecode-mcp/raw/main/assets/readme/logo_256x256.png" alt="MineCode logo" width="128" height="128">
 
-Written for a hackathon about MCP sponsored by dust, alpic, and others. Please star if you'd like to help out, and open issues for anything broken.
+# MineCode MCP
+
+**Version-accurate Minecraft data for AI assistants**
 
-[![PyPI](https://img.shields.io/pypi/v/minecode-mcp)](https://pypi.org/project/minecode-mcp/)
-[![Python](https://img.shields.io/badge/Python-3.10+-blue)](https://python.org)
+[![PyPI](https://img.shields.io/pypi/v/minecode-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/minecode-mcp/)
+[![Python](https://img.shields.io/badge/Python-3.10+-blue?logo=python&logoColor=white)](https://python.org)
 [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
+[![Tests](https://github.com/AnCarsenat/minecode-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/AnCarsenat/minecode-mcp/actions/workflows/test.yml)
+
+[![MseeP.ai Security Assessment](https://mseep.net/pr/ancarsenat-minecode-mcp-badge.png)](https://mseep.ai/app/ancarsenat-minecode-mcp)
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/5b3391b1-6799-4fd5-8496-308849e8a8c7)
+
+</div>
 
 MineCode is a **local** [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants like **GitHub Copilot** and **Claude** real-time access to version-accurate Minecraft data, documentation, vanilla presets, and your Minecraft logs.
 
+Written for a hackathon about MCP sponsored by dust, alpic, and others. Please star if you'd like to help out, and open issues for anything broken.
+
 ![example](https://github.com/AnCarsenat/minecode-mcp/raw/main/assets/readme/example6.png)
 
 ---
@@ -227,7 +244,8 @@ Configure your client (next section), then restart it. The client spawns the ser
 | Symptom | Cause and fix |
 |---------|---------------|
 | `command not found: minecode` | The script isn't on PATH. Use `python -m minecode.server`, or check `pip show -f minecode-mcp` |
-| `No module named minecode` | Wrong interpreter. Use the same Python you installed into — in a venv, use its absolute path in the client config |
+| `No module named minecode` | Wrong interpreter. The client's `python` isn't the one you installed into — classic with pipx and venv installs. Use `"command": "minecode"` in the client config, or the interpreter's absolute path |
+| `Error while finding module specification for 'minecode'` | `-m minecode` is not a valid entry point. The module form is `-m minecode.server` |
 | `AttributeError: 'Server' object has no attribute 'list_tools'` | You have mcp 2.x. Run `pip install "mcp>=1.25.0,<2"` |
 | Server starts, client shows no tools | Client config points at a different Python or a stale install. Restart the client fully — most only read MCP config at startup |
 | Everything hangs with no output | Expected when run directly, see above. If it happens *inside a client*, check the client's MCP logs |
@@ -260,6 +278,23 @@ Configure your client (next section), then restart it. The client spawns the ser
 
 Add to **User Settings** (`Ctrl+Shift+P` → "MCP: Open User Configuration"), or create `.vscode/mcp.json` in your workspace:
 
+```json
+{
+  "servers": {
+    "minecode": {
+      "type": "stdio",
+      "command": "minecode",
+      "args": []
+    }
+  },
+  "inputs": []
+}
+```
+
+The `minecode` script is installed alongside the package and already points at the right interpreter, so this form works for pipx, venv, and `--user` installs alike.
+
+The module form is equivalent **only if the package is importable from whichever `python` the client resolves**:
+
 ```json
 {
   "servers": {
@@ -273,7 +308,9 @@ Add to **User Settings** (`Ctrl+Shift+P` → "MCP: Open User Configuration"), or
 }
 ```
 
-> On Windows use `"command": "py"`. `py` is the Windows launcher and does not exist on macOS or Linux.
+> ⚠️ VS Code spawns the server with a bare `python` from `PATH` — **not** your selected Python interpreter, and not a pipx or venv environment. With a pipx install this fails with `No module named minecode`, since the package lives in pipx's own venv. Use `"command": "minecode"` above, or the absolute interpreter path from the next section.
+
+> On Windows use `"command": "py"` for the module form. `py` is the Windows launcher and does not exist on macOS or Linux.
 
 ### If `minecode` isn't on PATH
 
@@ -590,25 +627,65 @@ That's it. No token is generated and nothing is pasted into GitHub.
 
 ### Releasing
 
+> **⚠️ Step 1 is bumping the version in `pyproject.toml`. Do not skip it.**
+>
+> A version number on PyPI is **permanent**. Once `0.2.0` is published, that
+> number can never be reused or overwritten — even if you delete the release.
+> A bad publish can only be followed by a *new* version, never a replacement.
+> Re-tagging an already-published version fails at the upload step.
+
+**1. Bump the version.** Edit `version` in `pyproject.toml`:
+
+```toml
+version = "0.2.1"   # was 0.2.0
+```
+
+Which digit to move:
+
+| Change | Bump | Example |
+|--------|------|---------|
+| Bug fix, docs, internals — nothing user-visible breaks | patch | `0.2.0` → `0.2.1` |
+| New tools, new parameters — existing setups keep working | minor | `0.2.0` → `0.3.0` |
+| Tools removed or renamed, parameters removed — existing configs break | major-ish | `0.2.0` → `0.3.0` before 1.0, `1.x` → `2.0` after |
+
+(`0.2.0` was a minor bump because it removed two tools and renamed one.)
+
+**2. Commit, tag, and push.** The tag must be `v` + the exact version:
+
 ```bash
-# 1. Bump the version in pyproject.toml, e.g. 0.1.9 -> 0.2.0
-# 2. Commit, tag, push
 git add pyproject.toml
-git commit -m "Release 0.2.0"
-git tag v0.2.0
+git commit -m "Release 0.2.1"
+git tag v0.2.1
 git push origin main --tags
 ```
 
-The workflow fires on the tag and will:
+**3. Approve the deployment.** The workflow builds, then pauses. Go to the
+**Actions** tab → the running **Publish to PyPI** run → **Review deployments**
+→ tick `pypi` → **Approve and deploy**. GitHub also emails you an approve link.
+
+Publishing takes about 30 seconds after approval.
+
+#### What the workflow checks before it will publish
+
+1. **The tag matches `pyproject.toml`** — this is the safety net for a forgotten bump. Tagging `v0.2.1` while `pyproject.toml` still says `0.2.0` fails the build with `Tag v0.2.1 does not match pyproject.toml version 0.2.0`, and nothing is published
+2. Offline test suite passes
+3. Wheel and sdist build
+4. `twine check` on the metadata
+5. The preprompt, config, and migration table are actually inside the wheel
+
+If any of these fail, the approval button never appears — there is nothing to approve.
 
-1. Verify the tag matches `pyproject.toml` (a mismatch fails the build rather than shipping a mislabelled release)
-2. Run the offline test suite
-3. Build the wheel and sdist
-4. Check the metadata with `twine check`
-5. Verify the preprompt, config, and migration table are actually inside the wheel
-6. Publish to PyPI
+#### If you forgot to bump
+
+The build fails at step 1 and nothing ships. Recover by deleting the tag, bumping properly, and re-tagging:
+
+```bash
+git tag -d v0.2.1
+git push origin :refs/tags/v0.2.1
+# bump pyproject.toml, commit, then tag again
+```
 
-If you enabled required reviewers, approve the run in the **Actions** tab.
+This is safe precisely *because* nothing was published.
 
 ### Optional: TestPyPI first
 

minecode_mcp-0.2.0/readme.md → minecode_mcp-0.2.2/README.md

@@ -1,15 +1,32 @@
-# 🎮 MineCode MCP
+<!--
+  Absolute raw URLs, not relative paths: this file is also the PyPI long
+  description, and PyPI does not resolve repo-relative image paths.
+  Points at the 256x256 export and displays at 128, so the browser scales
+  DOWN rather than up. GitHub strips style attributes, so image-rendering
+  cannot be set -- downscaling is what keeps the block art from smearing.
+-->
+<div align="center">
 
-**MCP Server for Minecraft Datapack Development**
+<img src="https://github.com/AnCarsenat/minecode-mcp/raw/main/assets/readme/logo_256x256.png" alt="MineCode logo" width="128" height="128">
 
-Written for a hackathon about MCP sponsored by dust, alpic, and others. Please star if you'd like to help out, and open issues for anything broken.
+# MineCode MCP
+
+**Version-accurate Minecraft data for AI assistants**
 
-[![PyPI](https://img.shields.io/pypi/v/minecode-mcp)](https://pypi.org/project/minecode-mcp/)
-[![Python](https://img.shields.io/badge/Python-3.10+-blue)](https://python.org)
+[![PyPI](https://img.shields.io/pypi/v/minecode-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/minecode-mcp/)
+[![Python](https://img.shields.io/badge/Python-3.10+-blue?logo=python&logoColor=white)](https://python.org)
 [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
+[![Tests](https://github.com/AnCarsenat/minecode-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/AnCarsenat/minecode-mcp/actions/workflows/test.yml)
+
+[![MseeP.ai Security Assessment](https://mseep.net/pr/ancarsenat-minecode-mcp-badge.png)](https://mseep.ai/app/ancarsenat-minecode-mcp)
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/5b3391b1-6799-4fd5-8496-308849e8a8c7)
+
+</div>
 
 MineCode is a **local** [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants like **GitHub Copilot** and **Claude** real-time access to version-accurate Minecraft data, documentation, vanilla presets, and your Minecraft logs.
 
+Written for a hackathon about MCP sponsored by dust, alpic, and others. Please star if you'd like to help out, and open issues for anything broken.
+
 ![example](https://github.com/AnCarsenat/minecode-mcp/raw/main/assets/readme/example6.png)
 
 ---
@@ -198,7 +215,8 @@ Configure your client (next section), then restart it. The client spawns the ser
 | Symptom | Cause and fix |
 |---------|---------------|
 | `command not found: minecode` | The script isn't on PATH. Use `python -m minecode.server`, or check `pip show -f minecode-mcp` |
-| `No module named minecode` | Wrong interpreter. Use the same Python you installed into — in a venv, use its absolute path in the client config |
+| `No module named minecode` | Wrong interpreter. The client's `python` isn't the one you installed into — classic with pipx and venv installs. Use `"command": "minecode"` in the client config, or the interpreter's absolute path |
+| `Error while finding module specification for 'minecode'` | `-m minecode` is not a valid entry point. The module form is `-m minecode.server` |
 | `AttributeError: 'Server' object has no attribute 'list_tools'` | You have mcp 2.x. Run `pip install "mcp>=1.25.0,<2"` |
 | Server starts, client shows no tools | Client config points at a different Python or a stale install. Restart the client fully — most only read MCP config at startup |
 | Everything hangs with no output | Expected when run directly, see above. If it happens *inside a client*, check the client's MCP logs |
@@ -231,6 +249,23 @@ Configure your client (next section), then restart it. The client spawns the ser
 
 Add to **User Settings** (`Ctrl+Shift+P` → "MCP: Open User Configuration"), or create `.vscode/mcp.json` in your workspace:
 
+```json
+{
+  "servers": {
+    "minecode": {
+      "type": "stdio",
+      "command": "minecode",
+      "args": []
+    }
+  },
+  "inputs": []
+}
+```
+
+The `minecode` script is installed alongside the package and already points at the right interpreter, so this form works for pipx, venv, and `--user` installs alike.
+
+The module form is equivalent **only if the package is importable from whichever `python` the client resolves**:
+
 ```json
 {
   "servers": {
@@ -244,7 +279,9 @@ Add to **User Settings** (`Ctrl+Shift+P` → "MCP: Open User Configuration"), or
 }
 ```
 
-> On Windows use `"command": "py"`. `py` is the Windows launcher and does not exist on macOS or Linux.
+> ⚠️ VS Code spawns the server with a bare `python` from `PATH` — **not** your selected Python interpreter, and not a pipx or venv environment. With a pipx install this fails with `No module named minecode`, since the package lives in pipx's own venv. Use `"command": "minecode"` above, or the absolute interpreter path from the next section.
+
+> On Windows use `"command": "py"` for the module form. `py` is the Windows launcher and does not exist on macOS or Linux.
 
 ### If `minecode` isn't on PATH
 
@@ -561,25 +598,65 @@ That's it. No token is generated and nothing is pasted into GitHub.
 
 ### Releasing
 
+> **⚠️ Step 1 is bumping the version in `pyproject.toml`. Do not skip it.**
+>
+> A version number on PyPI is **permanent**. Once `0.2.0` is published, that
+> number can never be reused or overwritten — even if you delete the release.
+> A bad publish can only be followed by a *new* version, never a replacement.
+> Re-tagging an already-published version fails at the upload step.
+
+**1. Bump the version.** Edit `version` in `pyproject.toml`:
+
+```toml
+version = "0.2.1"   # was 0.2.0
+```
+
+Which digit to move:
+
+| Change | Bump | Example |
+|--------|------|---------|
+| Bug fix, docs, internals — nothing user-visible breaks | patch | `0.2.0` → `0.2.1` |
+| New tools, new parameters — existing setups keep working | minor | `0.2.0` → `0.3.0` |
+| Tools removed or renamed, parameters removed — existing configs break | major-ish | `0.2.0` → `0.3.0` before 1.0, `1.x` → `2.0` after |
+
+(`0.2.0` was a minor bump because it removed two tools and renamed one.)
+
+**2. Commit, tag, and push.** The tag must be `v` + the exact version:
+
 ```bash
-# 1. Bump the version in pyproject.toml, e.g. 0.1.9 -> 0.2.0
-# 2. Commit, tag, push
 git add pyproject.toml
-git commit -m "Release 0.2.0"
-git tag v0.2.0
+git commit -m "Release 0.2.1"
+git tag v0.2.1
 git push origin main --tags
 ```
 
-The workflow fires on the tag and will:
+**3. Approve the deployment.** The workflow builds, then pauses. Go to the
+**Actions** tab → the running **Publish to PyPI** run → **Review deployments**
+→ tick `pypi` → **Approve and deploy**. GitHub also emails you an approve link.
+
+Publishing takes about 30 seconds after approval.
+
+#### What the workflow checks before it will publish
+
+1. **The tag matches `pyproject.toml`** — this is the safety net for a forgotten bump. Tagging `v0.2.1` while `pyproject.toml` still says `0.2.0` fails the build with `Tag v0.2.1 does not match pyproject.toml version 0.2.0`, and nothing is published
+2. Offline test suite passes
+3. Wheel and sdist build
+4. `twine check` on the metadata
+5. The preprompt, config, and migration table are actually inside the wheel
+
+If any of these fail, the approval button never appears — there is nothing to approve.
 
-1. Verify the tag matches `pyproject.toml` (a mismatch fails the build rather than shipping a mislabelled release)
-2. Run the offline test suite
-3. Build the wheel and sdist
-4. Check the metadata with `twine check`
-5. Verify the preprompt, config, and migration table are actually inside the wheel
-6. Publish to PyPI
+#### If you forgot to bump
+
+The build fails at step 1 and nothing ships. Recover by deleting the tag, bumping properly, and re-tagging:
+
+```bash
+git tag -d v0.2.1
+git push origin :refs/tags/v0.2.1
+# bump pyproject.toml, commit, then tag again
+```
 
-If you enabled required reviewers, approve the run in the **Actions** tab.
+This is safe precisely *because* nothing was published.
 
 ### Optional: TestPyPI first
 

{minecode_mcp-0.2.0 → minecode_mcp-0.2.2}/pyproject.toml

@@ -4,9 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "minecode-mcp"
-version = "0.2.0"
+# To release: bump this, commit, then tag with a matching "v" prefix.
+#     version = "0.2.1"  ->  git tag v0.2.1 && git push origin main --tags
+# The publish workflow refuses to build if the tag and this value disagree,
+# so a forgotten bump fails loudly instead of shipping a mislabelled release.
+# PyPI version numbers are permanent -- a published version can never be
+# replaced, only superseded. See "Releasing" in README.md.
+version = "0.2.2"
 description = "MCP Server for Minecraft datapack development with wiki, Spyglass, Misode, and Mojira integrations"
-readme = "readme.md"
+readme = "README.md"
 license = "MIT"
 authors = [
     { name = "AnCarsenat" }
@@ -65,7 +71,7 @@ artifacts = [
 include = [
     "minecode/",
     "tests/",
-    "readme.md",
+    "README.md",
     "LICENSE",
     "example/",
 ]

minecode_mcp-0.2.0/scripts/readme.md

@@ -1,22 +0,0 @@
-
----
-
-**Release**
-- **Script**: `scripts/release.ps1` — full release workflow (clean, bump, build, push, publish).
-- **Token**: `pip_token.txt` or environment variable `PYPI_API_TOKEN` (the script sets `TWINE_USERNAME=__token__` and `TWINE_PASSWORD` from the token).
-- **Behavior**: removes `dist/`, `build/` and any `*.egg-info`, bumps the patch number in `pyproject.toml` (when `-Bump`), commits, tags `vX.Y.Z`, pushes, builds sdist/wheel, and uploads the release.
-- **Python**: prefers `venv\Scripts\python.exe` if present, otherwise uses `python` on PATH.
-- **Examples**:
-
-```powershell
-# Bump, build, push tag, and publish
-.\scripts\release.ps1 -Bump -Publish
-
-# Build and publish without bump
-.\scripts\release.ps1 -Publish
-
-# Just build (no bump, no publish)
-.\scripts\release.ps1
-```
-
-- **Notes**: the older `scripts/bump_version.*` utilities were consolidated into `release.ps1`; keep your PyPI API token in `pip_token.txt` or set `PYPI_API_TOKEN` for CI.