grp-mcp-plugin 0.81.0rc12__tar.gz

grp_mcp_plugin-0.81.0rc12/.env.example

@@ -0,0 +1,49 @@
+# Default Acumatica instance (used when a tool is called without an `instance` arg).
+# For multiple instances, use connections.json instead (see connections.example.json).
+
+GRP_MCP_BASE_URL=https://your-instance.acumatica.com
+GRP_MCP_CLIENT_ID=YOUR_CLIENT_ID@CompanyLogin
+GRP_MCP_CLIENT_SECRET=your_client_secret
+GRP_MCP_USERNAME=admin
+GRP_MCP_PASSWORD=your_password
+
+# Optional. Defaults shown.
+GRP_MCP_ENDPOINT_NAME=Default
+GRP_MCP_ENDPOINT_VERSION=24.200.001
+# Tenant/company login name, used for OData (Generic Inquiry) calls and
+# Customization API cookie login.
+GRP_MCP_TENANT=
+# Optional login branch.
+GRP_MCP_BRANCH=
+# --- write gates (default read-only; opt in) ---
+# Allow record mutations (create/update, load, actions, import-scenario, note, attach).
+GRP_MCP_ALLOW_WRITE=false
+# Allow record deletes (stricter than write).
+GRP_MCP_ALLOW_DELETE=false
+# Gate Customization API writes (publish/import/unpublish). Default off.
+# WARNING: publishing is website-level and affects ALL tenants on the instance.
+GRP_MCP_ALLOW_PUBLISH=false
+# Filesystem sandbox (read_roots / write_roots / max_file_bytes) is configured via
+# connections.json only — see connections.example.json. Empty roots confine
+# filesystem tools to the process working directory; whole-disk access is the
+# explicit `allow_unrestricted_fs: true` opt-in. (This comment said "empty roots =
+# unrestricted" for several releases. It was wrong — config.py is authoritative.)
+
+# --- tool surface (token cost) ---
+# grp-mcp registers 100+ tools. Serving all of them costs roughly 58k tokens of
+# context BEFORE the agent does anything — about 28% of a 200k window
+# (measured 2026-08-17 against the live registry).
+#
+# Set this to 1 and only a small core is LISTED (~10k tokens, an 82% cut). The
+# rest are not removed: they stay classified, gated and preflighted, and the
+# agent reaches them with find_tool("what you want") then call_tool(name, args).
+# Recommended for day-to-day use; leave it off if a client of yours calls a
+# non-core tool by name, since a pruned tool is not directly callable.
+GRP_MCP_CORE_ONLY=0
+
+# Persisting connection-profile changes from inside the agent (add_instance /
+# remove_instance / set_active_instance with persist) additionally requires:
+# GRP_MCP_ALLOW_ADMIN=1
+
+# Path to a JSON file holding multiple named instances (optional).
+# GRP_MCP_CONNECTIONS=C:\Temp\grp-mcp\connections.json

grp_mcp_plugin-0.81.0rc12/.gitattributes

@@ -0,0 +1,6 @@
+# core.hooksPath points at .githooks, so these run as shell scripts. Git on Windows
+# checks text files out as CRLF by default, and /bin/sh refuses a script whose
+# shebang line ends in \r ("bad interpreter: /bin/sh^M"). Pin them to LF so the
+# hooks stay executable on every clone, including this one after a fresh checkout.
+.githooks/** text eol=lf
+scripts/*.py text eol=lf

grp_mcp_plugin-0.81.0rc12/.githooks/pre-commit

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Content-based secret gate. See scripts/check_secrets.py for why this exists
+# rather than relying on .gitignore alone (2026-07-27 leak).
+# Enable once per clone:  git config core.hooksPath .githooks
+python "$(git rev-parse --show-toplevel)/scripts/check_secrets.py" --staged || exit 1

grp_mcp_plugin-0.81.0rc12/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  schedule:
+    # Weekly, for the mcp-latest job below. Nothing else here needs a timer.
+    - cron: "17 6 * * 1"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    # Windows is where this actually runs (the paths, the .exe launchers, the
+    # file-locking failure modes), so it is not an afterthought row here.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, python: "3.10" }
+          - { os: ubuntu-latest, python: "3.13" }
+          - { os: windows-latest, python: "3.13" }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      # The `search` extra is load-bearing for the COUNT: without fastembed,
+      # tests/test_tool_search.py importorskips and the suite silently runs ~21
+      # tests short while still reporting all-green. Those tests build the corpus
+      # from the registry and never download the ONNX model.
+      - run: pip install -e ".[dev,search]"
+      - run: python -m pytest tests/ -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.13", cache: pip }
+      - run: pip install -e ".[dev]"
+      # Narrow by design (E9,F,BLE) — see the [tool.ruff] comment in pyproject.
+      - run: python -m ruff check src/ tests/ scripts/
+
+  package:
+    # The sdist is PUBLIC and permanent. Twice now something private reached a
+    # BUILT artifact while the working tree looked clean: machine-specific
+    # absolute paths (2026-08-17) and a live bearer token in a test (same day,
+    # caught by scanning the artifact, not the tree). Scanning the tree is not
+    # the same check, so this scans what would actually be uploaded.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.13", cache: pip }
+      - run: pip install build
+      - run: python -m build
+      - name: Scan the built sdist for credentials
+        run: python scripts/check_secrets.py --sdist dist/*.tar.gz
+      - name: Scan the built wheel for credentials
+        run: python scripts/check_secrets.py --sdist dist/*.whl
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  mcp-latest:
+    # EARLY WARNING, not a gate. server.py reaches two private MCP-SDK attributes
+    # through the seam (_tool_manager._tools, _lowlevel_server.instructions).
+    # pyproject pins mcp>=2,<3, so a minor release cannot break an install — but
+    # it can break US, silently, at the next unpinned upgrade. This job finds out
+    # first. It is allowed to fail.
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.13", cache: pip }
+      - run: pip install -e ".[dev,search]"
+      - run: pip install --upgrade mcp
+      - run: python -c "import mcp; print('mcp', mcp.__version__ if hasattr(mcp,'__version__') else '?')"
+      # The three seam-degradation tests are the ones that matter here: the seam
+      # returns {} / "" / False rather than raising, so a moved attribute shows up
+      # as a silent no-op unless something asserts otherwise.
+      - run: python -m pytest tests/ -q

grp_mcp_plugin-0.81.0rc12/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+
+# Secrets / local config
+.env
+connections.json
+kb_server.json
+
+# IDE
+.vscode/
+.idea/
+.DS_Store
+
+# Snapshot dumps (business data)
+snapshots/
+
+# Playwright debug screenshots
+playwright/shots/
+
+# Credential files — the bare name was not enough. A connections.json.bak-<date>
+# backup (written by the config editor) slipped past `connections.json` and was
+# committed to a PUBLIC repo on 2026-07-27. Match every variant, not the one name.
+connections.json*
+kb_server.json*
+*.bak
+*.bak-*
+.env
+
+# graphify is no longer used in this repo. The rule stays because the tool writes
+# multi-MB generated graphs into these directories the moment anyone runs it, and
+# `git status` collapses an untracked directory to a single line — which is exactly
+# how a 2.8 MB graph.json gets swept into a `git add -A` unnoticed.
+graphify-out/
+graphify-out-code*/
+
+# generated repowiki from an external tool — huge, and some paths exceed the Windows limit
+.qoder/
+
+# Frozen-build scratch (packaging/BUILD.md). buildenv/ already ignores itself via
+# the .gitignore venv writes, but pybuild/ does not: only pybuild/dist matches the
+# `dist/` rule above, so work/ and the generated .spec were left untracked and a
+# `git add -A` would sweep in ~100MB of PyInstaller intermediates.
+buildenv/
+pybuild/
+extbuild/
+setupbuild/
+ext/
+*.mcpb

grp_mcp_plugin-0.81.0rc12/CLAUDE.md

@@ -0,0 +1,199 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`grp-mcp` — an MCP server (stdio, `mcp.server.MCPServer`) that exposes an **Acumatica ERP** instance as ~120 agent
+tools. Python 3.10+, `src/` layout, published to PyPI as `grp-mcp`. Entry points: `grp_mcp.server:main`
+(the MCP server) and `grp_mcp.ui:main` (a localhost config page).
+
+## Commands
+
+```bash
+pip install -e ".[dev]"
+```
+
+```bash
+./.venv/Scripts/python.exe -m pytest tests/ -q
+```
+
+711 tests, all pure logic — **no live Acumatica instance is needed or used**. The `search` extra is
+required for the full count: without `fastembed`, `tests/test_tool_search.py` collects 0 and the suite
+silently runs 21 tests short. Single test / file:
+
+```bash
+./.venv/Scripts/python.exe -m pytest tests/test_smoke.py::test_delete_gate_is_independent_of_write -q
+```
+
+Retrieval quality of `find_tool` (not part of pytest — these print a score, they don't assert):
+
+```bash
+./.venv/Scripts/python.exe scripts/eval_find_tool.py
+```
+
+One runner, four datasets (`--dataset core|holdout|holdout2|holdout3`, `--list` to see them; all four
+by default). `core` is the calibration set and the hold-outs are the anti-overfit checks written after
+it was already passing — tuning against `core` alone overfits it. `holdout2` also measures the NOISE
+CEILING: off-domain queries that must reach no tool, which is what the WEAK threshold has to clear.
+`eval_find_tool_mined.py` stays separate — it mines intents from local Claude transcripts rather than
+reading a fixed list, and reads machine-private files. `scripts/mutate_*.py` are mutation checks — they break a module on purpose,
+run the matching test file, and report which tests went red (a test nobody has watched fail is a claim,
+not a check). They restore the file in a `finally`.
+
+Lint (narrow by design — `E9,F,BLE`; style rules are deliberately not selected):
+
+```bash
+./.venv/Scripts/python.exe -m ruff check src/ tests/ scripts/
+```
+
+`BLE` is the point of enabling it at all: the package carries 150+ `# noqa: BLE001` suppressions, and
+until 2026-08-17 they were written for a linter that never ran, so a deliberate blind except was
+indistinguishable from an accidental one. Every suppression now carries a reason.
+
+CI (`.github/workflows/ci.yml`) runs the suite on ubuntu 3.10/3.13 and windows 3.13, lints, and builds
+the sdist+wheel and scans **the built artifacts** with `check_secrets.py` — scanning the tree is not the
+same check, and twice something private reached an artifact while the tree looked clean. A
+`continue-on-error` job tracks the latest `mcp` release as early warning for the SDK seam.
+
+Enable the secret gate once per clone (content-based, scans staged diffs — see `scripts/check_secrets.py`
+for the 2026-07-27 leak it exists for):
+
+```bash
+git config core.hooksPath .githooks
+```
+
+Release (maintainers): bump `version` in `pyproject.toml`, `python -m build`, **audit the built sdist AND
+wheel** (`python scripts/check_secrets.py --sdist dist/*.tar.gz`, plus grep for tenant/host names — the
+sdist is public and permanent), then `twine upload dist/grp_mcp-<version>*`. Full checklist in
+KNOWLEDGE.md §10.
+
+## Architecture
+
+### Five client planes
+
+The whole design follows from one fact: **no single Acumatica API can drive every screen.** Each plane
+has capability holes the others cover, so tools are grouped by plane, not by feature.
+
+| Plane | Module | Reaches | Cannot |
+|---|---|---|---|
+| Contract REST (OAuth2) | `acumatica.py` | endpoint entities, bulk CRUD, actions, reports | context/master-detail screens |
+| DAC / GI OData | `acumatica.py` | any table incl. config singletons, mandatory-field CSDL | read-only |
+| Classic screen SOAP | `screen.py` (`ScreenClient`) | context/wizard screens by replaying UI commands | can't address an *existing* grid row by key; some action tags are silent no-ops |
+| Modern UI-JSON | `screen.py` (`ui_*` methods) | grid CRUD, dialogs, enum values, live action state | `/structure` absent on older builds; one container per view name, so classic "ViewName: 2" duplicates are invisible |
+| Classic ASPX callbacks | `aspx.py` | the REAL validation text behind a failed save; actions + confirms on keyed records | not a general write path |
+
+Both classic SOAP and modern UI-JSON live in `screen.py` because they **share one login session**
+(`_SESSION_CACHE`) — logins hold scarce "Web Services API Users" seats (trial = 2), so sessions are
+pooled and logged out at shutdown. Never mix planes inside one session: they hold separate dirty-graph
+state and collide.
+
+KNOWLEDGE.md §1 is the plane routing table; §3 (classic command mechanics) and §4 (modern JSON protocol)
+are the protocol references. Read them before touching `screen.py`.
+
+### Tool registration and the core-only mode
+
+Every tool is a `@mcp.tool()` in `server.py` (12.5k lines — one file by design; `_TOOL_NOTES` holds the
+long prose that would otherwise bloat docstrings/schemas). At import time, after all registrations:
+
+1. `_apply_core_only_gating()` snapshots the full registry into `_ALL_TOOLS`, then — **only if
+   `GRP_MCP_CORE_ONLY=1`** — deletes everything outside `CORE_TOOLS` from the SDK's registry.
+2. `_sync_instruction_tool_count()` rewrites the served MCP `instructions` with the real count and, in
+   core-only mode, the sentence telling the client that the unlisted tail exists.
+
+Pruning the registry (rather than skipping the decorator) keeps **one definition path**: a hidden tool is
+still classified, still gated, still preflighted, and still reachable via `find_tool` (semantic search,
+`tool_search.py`) → `call_tool(tool, args)`, which dispatches to the same function.
+
+Both steps need MCP-SDK internals, so all of it goes through the **SDK seam** at the top of `server.py`
+— `_registry()`, `_instructions()`, `_set_instructions()`. Never reach `mcp._tool_manager` /
+`mcp._lowlevel_server` anywhere else; `test_sdk_private_access_stays_inside_the_seam` fails the build if
+you do. `_registry()` returns the SDK's **live mutable dict, not a copy** — core-only prunes it in place,
+so a copy silently turns pruning into a no-op that still reports a pruned count. The seam degrades (`{}`
+/ `""` / `False`) rather than raising, and three tests plus `scripts/mutate_sdk_seam.py` keep that
+degradation loud.
+
+The seam paid for itself on the `mcp` 2.0 migration (`FastMCP` → `MCPServer`, `mcp.server.fastmcp`
+deleted, low-level Server rebuilt): the whole cost inside `server.py` was the import, the constructor,
+and one attribute name. Two measured facts worth keeping — `instructions` has **no setter in either
+major** (`fset` is `None`), so the private write path is permanent rather than a v1 wart; and 2.0 still
+exposes `_tool_manager._tools` as a dict of tools carrying `.description` and `.parameters`, which is
+why `_registry()` and the `find_tool` corpus needed no change. Neither is promised by anything.
+`pyproject.toml` now pins `mcp>=2,<3`; the sibling **grp-kb** still pins `<2`, which is fine — it runs
+as a separate subprocess with its own environment, so the two majors never share an interpreter.
+
+### Enforcement layer (`enforcement.py`) — the load-bearing invariant
+
+`TOOL_CLASS` maps **every** registered tool to a risk class (`read`/`write`/`delete`/`publish`/`bg_job`/
+`diagnostic_write`/`filesystem`/`admin`). It documents and checks; it does **not** re-route gates — the
+real `_require_write` / `_require_delete` / `_require_publish` / `_require_admin` calls stay inline in
+`server.py` (several are runtime branches — a tool that write-gates normally but delete-gates on a
+destructive action). AST-based tests in `tests/test_smoke.py` cross-check the registry against the source
+so an unguarded mutation cannot ship. Escape hatches are `GATELESS_MUTATION_ALLOW` and `DELEGATED_GATE`
+— keep them tiny and justified.
+
+### Adding or changing a tool — the checklist the tests enforce
+
+1. `@mcp.tool()` in `server.py`.
+2. Add it to `enforcement.TOOL_CLASS` (`test_every_registered_tool_is_classified` fails otherwise, in
+   both directions — a stale entry is also an error).
+3. If it mutates ERP data, call a real `_require_*` gate **lexically in the tool body**
+   (`test_erp_mutation_tools_are_actually_gated` reads the AST, not the runtime).
+4. Wire the KB write-preflight: `@_preflight_write(...)` below `@mcp.tool()`, or inline for the four
+   arteries in `PREFLIGHT_INLINE`. Coverage is tested.
+5. If it's a read whose result should carry the nudge, `@_hint_only`.
+
+### Write honesty
+
+A clean `ok:true` from Acumatica proves nothing — success-shaped no-ops are routine. So:
+
+- `writeback.py` (pure, no I/O) compares a read-back against what was sent. Its rule: **never report
+  `rejected` for something merely uncomparable** — a false "your write failed" sends the caller off to
+  redo work that already succeeded.
+- `enforcement.verify_state()` / `normalize_verification()` collapse the scattered per-plane flags
+  (`save_verified`, `delete_verified`, `grid_rows_readable`, `graph_is_dirty`) into one
+  `verified`/`rejected`/`unverified` verdict, worst-case wins. There is deliberately **no rollback
+  state**: automatic cross-plane undo is unsafe, so a failure is surfaced, never reversed.
+- Any non-verified mutation gets `_DIAGNOSE_ROUTE` stapled on — it names *instruments* (`aspx_screen_action`,
+  `diagnose_save_error`, `SMPerformanceInfoTraceMessages`), never a guessed cause. That wording is
+  deliberate; see the comment above it.
+
+### KB-first policy
+
+Before any write, the server itself consults the KB — it does not trust the agent to have done it.
+`kb_client.py` spawns the sibling **grp-kb** package as a subprocess (launch spec from
+`GRP_MCP_KB_SERVER` / `kb_server.json`) and runs its semantic search; `kb.py` digests the relevant
+section of the **bundled** `KNOWLEDGE.md`. Server-produced evidence is unfakeable; caller-supplied
+references are only an attestation. `preflight.py` applies the level from
+`Instance.effective_enforcement()` — `off` (dev default) / `warn` (production default) / `enforce`
+(blocks the write if grp-kb was unreachable). Preflight never raises: a broken preflight must not break
+a write.
+
+### Safety model (`config.py`)
+
+Per-instance gates, **read-only by default**: `allow_write`, `allow_delete` (strictly stronger, enforced
+across *all* planes), `allow_publish`. Persisting connection-profile changes additionally need
+`GRP_MCP_ALLOW_ADMIN=1`. Every authenticated request is pinned to the profile's origin *and* base-URL
+path prefix (SSRF / token-exfiltration guard, incl. sibling apps on the same host). Filesystem tools
+resolve roots through `Instance.effective_roots()`: configured roots win, empty roots confine to the
+process CWD, and whole-disk access is the explicit `allow_unrestricted_fs=true` opt-in. `config.py` is
+authoritative here — the prose in README.md and Installation-and-Setup-Guide.md described the older
+opt-in-sandbox behaviour for several releases before it was caught.
+
+## Repo conventions
+
+- **KNOWLEDGE.md is the engineering log, not decoration.** Each numbered section records a measured
+  finding (what was tried, what the instrument said, what was wrong). Tools quote it at runtime and the
+  preflight digests it. Headings must match `## N. Title` or `## §N Title` — sections 19+ use the `§`
+  form, and a heading that matches neither becomes invisible to `knowledge()` *and* to the write
+  preflight (this happened for five releases; see §26).
+- Comments here explain **why**, usually with a date and a measurement, and often name the wrong
+  hypothesis that cost time. Match that register; don't strip those comments as noise.
+- Commit subjects are imperative and state the *effect*, not the file touched — "delete_entity now
+  proves the record is gone", "Close a filesystem-sandbox existence oracle (authorize before stat)". A
+  release commit carries a trailing `(vX.Y.Z)` and pairs with a Status entry in README.md plus a
+  KNOWLEDGE.md section.
+- `connections.json`, `kb_server.json`, `.env`, `*.bak*` and `snapshots/` are gitignored and must never
+  be committed or packaged — `pyproject.toml`'s sdist `exclude` list is the second line of defence.
+- `graphify` was evaluated and removed on purpose (2026-07-29). Don't propose reinstating it; the
+  `.gitignore` rules for it stay because the tool writes multi-MB artifacts the moment anyone runs it.

grp_mcp_plugin-0.81.0rc12/Edit-Connections.bat

@@ -0,0 +1,66 @@
+@echo off
+setlocal
+title grp-mcp - launching config UI
+
+rem Always use the connections.json sitting next to THIS script, no matter
+rem what folder the double-click happened from. This is the fix for the
+rem classic "config UI wrote to the wrong file" problem - it removes the
+rem current-working-directory dependency entirely.
+set "GRP_MCP_CONNECTIONS=%~dp0connections.json"
+
+echo ============================================
+echo   grp-mcp Configuration UI
+echo ============================================
+echo   Connections file: %GRP_MCP_CONNECTIONS%
+echo ============================================
+echo.
+
+rem WHICH BUILD IS ABOUT TO RUN? This used to be invisible, and it bit us.
+rem "uvx --from grp-mcp" resolves the PUBLISHED PyPI package, and --refresh
+rem actively re-pulls it - so on a machine that HAS a source clone, this script
+rem happily ignored the local code and served the released UI instead. Symptom:
+rem you edit ui.py, re-run this, and get the old page with an old build number.
+rem So: prefer a local install sitting next to this script, and fall back to
+rem PyPI only when there is not one (the normal end-user case).
+set "LOCAL_UI=%~dp0.venv\Scripts\grp-mcp-ui.exe"
+
+if exist "%LOCAL_UI%" (
+    echo Build: LOCAL - %LOCAL_UI%
+    echo   ^(rename .venv to force the published PyPI build instead^)
+    echo.
+    echo Starting the config server in a new window...
+    start "grp-mcp config UI - close this window when you are done editing" cmd /k "%LOCAL_UI%"
+    goto :opened
+)
+
+where uvx >nul 2>nul
+if errorlevel 1 (
+    echo ERROR: "uvx" was not found on your PATH.
+    echo.
+    echo Install it first, then close ALL terminal windows and re-run this:
+    echo   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 ^| iex"
+    echo.
+    pause
+    exit /b 1
+)
+
+echo Build: PUBLISHED from PyPI ^(no local .venv beside this script^)
+echo.
+echo Starting the config server in a new window...
+rem --refresh forces uvx to pull the LATEST grp-mcp from PyPI instead of a stale
+rem cached wheel. Without it, uvx keeps serving whatever version it first cached,
+rem so shipped UI fixes never reach you (symptom: the page hangs on "loading...").
+start "grp-mcp config UI - close this window when you are done editing" cmd /k uvx --refresh --from grp-mcp grp-mcp-ui
+
+:opened
+echo Waiting for it to start...
+timeout /t 3 /nobreak >nul
+
+echo Opening your browser...
+start "" http://127.0.0.1:8765
+
+echo.
+echo Done - edit your instance^(s^) in the browser tab that just opened.
+echo The page header shows a build number; if it looks stale, hard-refresh with
+echo Ctrl+Shift+R. When finished, close the "grp-mcp config UI" window.
+timeout /t 4 >nul