@oneentry/mcp-platform-server 0.1.0

package/README.md

@@ -0,0 +1,189 @@
+# @oneentry/mcp-platform-server
+
+MCP server that lets an AI agent **operate the OneEntry Admin API** — grounded in the project's own
+rules rather than in guesswork.
+
+Two things are bundled:
+
+- **Knowledge.** ~1 MB of reference docs from `backend-app/.claude/**` and `frontend-app/.claude/**`,
+  split into ~1700 searchable sections, plus a hand-written `operating-rules.md` distilling the
+  payload rules that actually break calls.
+- **Actuation.** All **478 Admin API operations** as a searchable catalog with parameter and body
+  schemas, the permission each one requires, and a risk classification — reachable through one
+  generic invoke tool instead of 478 separate ones.
+
+Only the Admin API is exposed.
+
+## Install
+
+```bash
+npm i -g @oneentry/mcp-platform-server     # or use npx, below
+```
+
+## Local mode (agent and CMS on the same machine)
+
+Add to `.mcp.json` in the repo you work from:
+
+```json
+{
+  "mcpServers": {
+    "oneentry-mcp-platform": {
+      "command": "npx",
+      "args": ["-y", "@oneentry/mcp-platform-server", "--back", "../backend-app", "--front", "../frontend-app"],
+      "env": {
+        "ONEENTRY_CMS_BASE_URL": "http://localhost:3003/api/admin",
+        "ONEENTRY_CMS_LOGIN": "your-admin-login",
+        "ONEENTRY_CMS_PASSWORD": "your-admin-password"
+      }
+    }
+  }
+}
+```
+
+`--back`/`--front` are optional: with them the knowledge is read live from the checkouts, so edits
+to `.claude/docs` take effect immediately; without them the bundled snapshot is used.
+
+backend-app must be running with `API_TYPE=/api/admin` (default port 3003).
+
+## Remote mode (hosted, many agents, one stand)
+
+```bash
+oneentry-mcp-platform --http --port 8931 --audit /var/log/oneentry-mcp-platform-audit.jsonl \
+        --base-url https://stand.example/api/admin \
+        --allowed-origins https://agent.example
+```
+
+Each MCP session carries its own CMS identity, passed as connection headers — never as tool
+arguments, so a prompt-injected instruction cannot swap identities:
+
+| header | meaning |
+|---|---|
+| `x-cms-token` | pre-issued Admin API access token (preferred) |
+| `x-cms-login` + `x-cms-password` | credentials to log in with |
+
+Sessions never share tokens or confirm tokens. `GET /health` reports liveness and session count.
+
+## Docker
+
+```bash
+cp .env.example .env                      # fill in ONEENTRY_CMS_LOGIN / ONEENTRY_CMS_PASSWORD
+docker compose up --build mcp             # remote mode on :8931
+curl -s http://127.0.0.1:8931/health      # {"ok":true,"mode":"remote","sessions":0}
+```
+
+| service | profile | mode |
+|---|---|---|
+| `mcp` | — | remote (Streamable HTTP) on `:8931` |
+| `mcp-live` | `live` | remote, knowledge read live from the mounted checkouts |
+| `stdio` | `stdio` | local stdio — usable directly as an MCP client command |
+
+```bash
+docker compose --profile live up --build mcp-live
+docker compose --profile stdio run --rm -T stdio
+```
+
+A stand running on the host is reachable as `host.docker.internal` (wired via `host-gateway`), so
+the default base URL inside the container is `http://host.docker.internal:3003/api/admin`. The audit
+log is bind-mounted to `./.audit`. Details and gotchas: [.claude/docs/docker.md](.claude/docs/docker.md).
+
+To point an MCP client at the containerised stdio server:
+
+```json
+{
+  "mcpServers": {
+    "oneentry-mcp-platform": {
+      "command": "docker",
+      "args": ["compose", "-f", "/abs/path/to/docker-compose.yml", "--profile", "stdio",
+               "run", "--rm", "-T", "stdio"]
+    }
+  }
+}
+```
+
+## The seven tools
+
+| tool | what it does |
+|---|---|
+| `cms_guide` | read first: mode, policy, API map, the order to use the other tools |
+| `cms_docs_search` | search the knowledge base, returns sections with snippets |
+| `cms_docs_read` | read one section, with its sibling sections listed for paging |
+| `cms_api_search` | find operations by keyword / tag / method / mutating |
+| `cms_api_describe` | params, body schema, required permission, risk, linked docs |
+| `cms_api_call` | execute one operation; `dryRun` and confirm-gating for mutations |
+| `cms_whoami` | mode, base URL, admin + permissions, catalog/knowledge versions and warnings |
+
+Plus two MCP resources: `oneentry://knowledge/mcp/operating-rules` and `oneentry://knowledge/index`.
+
+## Write safety
+
+Read-only by default. `--allow` (or `ONEENTRY_MCP_ALLOW`) raises it:
+
+| level | GET | POST/PUT/PATCH | DELETE |
+|---|---|---|---|
+| `read` (default) | ✅ | ❌ | ❌ |
+| `write` | ✅ | ✅ | ❌ |
+| `destructive` | ✅ | ✅ | ✅ confirm-gated |
+
+- A refusal by level happens **before authentication** — no HTTP request is made at all.
+- Deletes, and every path in the permanently gated list (`immutable-settings`, `admins`, `backups`,
+  `modules`, `payments/webhook`, `settings-general`, `system/captcha-keys`,
+  `auth/logout/all-users`), require a **confirm token**: the first call returns the token *and the
+  current state of the target*, fetched via the sibling GET, so a human can see what is about to
+  change. The token is bound to `hash(opId + arguments)`, single-use, valid 5 minutes.
+- Permissions are checked locally first: if the admin lacks the `AdminPermissionsEnum` value the
+  operation declares, the call is refused without being sent.
+- Every non-GET call is appended to a JSONL audit log (arguments are hashed, not stored). Required
+  in remote mode.
+
+## Keeping the bundled data in sync
+
+`data/catalog.json` and `data/knowledge.json` are committed build outputs:
+
+```bash
+npm run sync:from-cms -- --back ../backend-app --front ../frontend-app
+npm run check:drift                                  # CI: fails if the committed data is stale
+```
+
+Both commands fall back to sibling checkouts (`../dnk-back`, `../dnk-front`) when the flags are
+omitted, so the bare form works in the usual layout. `check:drift` runs automatically as
+`prestart`, i.e. before `npm start` — it compares content only, and **skips** (exit 0) when no
+checkout is next to the repo, so a deployment without the CMS sources still starts. It does not
+run before `npm run dev`: the ts-morph pass over every controller takes ~20 s, which is too slow
+for a restart loop.
+
+Refreshing `swagger.json` itself is dnk-back's job — boot it once with `API_TYPE=/api/admin` and it
+rewrites `local-static/swagger.json` on startup.
+
+The catalog is built from two sources, because neither alone is enough:
+
+1. `backend-app/local-static/swagger.json` — paths, operation ids and schemas.
+2. `backend-app/src/**/*.controller.ts` via ts-morph — the `@GrantByPermission` decorators, which
+   never reach swagger. Base classes are walked, since Nest derives the operation id from the
+   registered controller while the handler often lives in a parent.
+
+Two classes of inconsistency in dnk-back are surfaced as catalog `warnings` (visible in
+`cms_whoami`) rather than silently swallowed:
+
+- handlers that declare a permission but are missing from `swagger.json` — a stale swagger snapshot;
+- permissions required by controllers but absent from `AdminPermissionsEnum` (`users.export`,
+  `orders.export`, `payments.export`) — no admin can hold these, so those endpoints always 403.
+
+### The swagger is not valid JSON Schema
+
+311 `type` values in the source swagger are TypeScript expressions (`Record<string, any>`,
+`CommonLocalizeInfos`, `AttributesSets`, `image`, `date`). The build normalizes what it can and
+marks the rest `"x-loose": true` with the original under `x-source-type`. For loose fields the
+`example` is the contract, and client-side body validation is deliberately advisory — the server
+is the real validator, so a call is never blocked because a loose field could not be checked.
+
+## Tests
+
+```bash
+npm test                 # unit + MCP protocol + remote-mode transport (no stand needed)
+npm run test:integration # against a live dnk-back; skips cleanly if unreachable
+```
+
+The integration suite needs backend-app on `:3003` with `API_TYPE=/api/admin` plus
+`ONEENTRY_CMS_LOGIN`/`ONEENTRY_CMS_PASSWORD`. It walks search → describe → call, asserts a read-only refusal
+sends nothing, and runs a full create → confirm-gated delete cycle on a throwaway template while
+checking the audit log.