@oneentry/mcp-platform-server 0.1.0 → 0.1.1

package/README.md

@@ -3,14 +3,20 @@
 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:
+Nothing is frozen into the package. Both halves are fetched at runtime and cached:
 
-- **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.
+- **Knowledge.** Small markdown files from a public GitHub repository
+  ([ONEENTRY-PLATFORM/oneentry-platform-rules](https://github.com/ONEENTRY-PLATFORM/oneentry-platform-rules)),
+  chunked into searchable sections. Editing a doc there — through the GitHub UI, a PR, whatever — takes effect on the next
+  restart of any server, with no npm release.
+- **Actuation.** Every Admin API operation, built from the stand's own
+  `GET /api/admin/workflows/nodes/admin-api/swagger.json`, with parameter and body schemas, the
+  permission each one requires, and a risk classification — reachable through one generic invoke
+  tool instead of one tool per endpoint. The catalog always describes the API that is actually
+  running, not a snapshot of it.
+
+The one thing still committed here is `data/permissions.json`: `@GrantByPermission` is a decorator
+and never reaches any swagger, so that map has to be recovered from the CMS sources.
 
 Only the Admin API is exposed.
 
@@ -29,7 +35,7 @@ Add to `.mcp.json` in the repo you work from:
   "mcpServers": {
     "oneentry-mcp-platform": {
       "command": "npx",
-      "args": ["-y", "@oneentry/mcp-platform-server", "--back", "../backend-app", "--front", "../frontend-app"],
+      "args": ["-y", "@oneentry/mcp-platform-server"],
       "env": {
         "ONEENTRY_CMS_BASE_URL": "http://localhost:3003/api/admin",
         "ONEENTRY_CMS_LOGIN": "your-admin-login",
@@ -40,8 +46,9 @@ Add to `.mcp.json` in the repo you work from:
 }
 ```
 
-`--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.
+No checkout of the CMS is needed. On first run the knowledge repository is downloaded once and
+cached; later runs re-use the cache and only ask GitHub whether the commit moved, at most once an
+hour.
 
 backend-app must be running with `API_TYPE=/api/admin` (default port 3003).
 
@@ -63,43 +70,6 @@ arguments, so a prompt-injected instruction cannot swap identities:
 
 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 |
@@ -110,7 +80,7 @@ To point an MCP client at the containerised stdio server:
 | `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 |
+| `cms_whoami` | mode, base URL, admin + permissions, knowledge commit, catalog state and warnings |
 
 Plus two MCP resources: `oneentry://knowledge/mcp/operating-rules` and `oneentry://knowledge/index`.
 
@@ -135,42 +105,114 @@ Read-only by default. `--allow` (or `ONEENTRY_MCP_ALLOW`) raises it:
 - 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
+## Where the knowledge comes from
 
-`data/catalog.json` and `data/knowledge.json` are committed build outputs:
+A public GitHub repository of small markdown files. Layout:
+
+```
+knowledge/
+  mcp/operating-rules.md          -> docId "mcp/operating-rules"
+  back/docs/menus-module.md       -> docId "back/docs/menus-module"
+  back/docs/orders-module/index.md      -> docId "back/docs/orders-module"
+  back/docs/orders-module/status-axis.md-> docId "back/docs/orders-module/status-axis"
+```
+
+The docId is the path under `knowledge/` without `.md`; `<name>/index.md` collapses back to
+`<name>`, which is what lets a long document be split into a directory of small files without
+changing the id anything already links to. **No file over 12 KB** — the same cap `cms_docs_read`
+applies to a section, so a section can never come back truncated.
+
+At startup the server asks GitHub for the commit behind `--knowledge-ref` (one cheap request,
+skipped entirely while the cache is younger than `--knowledge-ttl`, default 1 h), and downloads
+`codeload.github.com/<repo>/tar.gz/<sha>` only when that commit has moved — one request for the
+whole corpus, no API rate limit. The tree is unpacked into `--cache-dir` keyed by commit, so a
+restart is instant and the previous commit is pruned.
+
+| situation | what happens |
+|---|---|
+| cache fresh | no network at all |
+| commit unchanged | one API request, no download |
+| commit moved | one API request + one archive download |
+| GitHub unreachable, cache present | the cached commit is used |
+| GitHub unreachable, no cache | falls back to the bundled `operating-rules.md`, and says so in `cms_guide` and `cms_whoami` |
+| `--offline` | cache and bundled rules only, never the network |
+
+Which repository and which commit is a configuration choice, not a constant: `--knowledge-repo`
+(`ONEENTRY_MCP_KNOWLEDGE_REPO`, default `ONEENTRY-PLATFORM/oneentry-platform-rules`) and
+`--knowledge-ref`
+(`ONEENTRY_MCP_KNOWLEDGE_REF`, default `main`) — a ref may be a branch, a tag or a commit sha, so a
+stand can be frozen on a known-good corpus. `ONEENTRY_GITHUB_TOKEN` is optional and only raises the
+API rate limit; the repo is public. `cms_whoami` reports the repo, ref and 12-character commit the
+running server actually loaded.
+
+### Reading the docs from a local folder instead
+
+For testing, or for editing docs without committing, point the server at a directory:
 
 ```bash
-npm run sync:from-cms -- --back ../backend-app --front ../frontend-app
-npm run check:drift                                  # CI: fails if the committed data is stale
+ONEENTRY_MCP_KNOWLEDGE_PATH=../oneentry-platform-rules oneentry-mcp-platform
+# or: oneentry-mcp-platform --knowledge-path ../oneentry-platform-rules
 ```
 
-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.
+Either the clone root or its `knowledge/` directory works — the path is probed for a `knowledge`
+subdirectory and used directly if there is none. While it is set, GitHub is never contacted and the
+cache is not consulted, so edits take effect on the next restart with no commit and no push;
+`cms_whoami` reports `source: "local"`. Leave it unset for the default, which is GitHub.
+
+A path that cannot be read is a **startup error**, not a fallback: unlike GitHub being unreachable,
+a bad path is a configuration mistake, and degrading silently to the bundled operating rules would
+look like an empty corpus.
+
+### Known limitation: retrieval is single-language
+
+Search does not translate. The backend corpus is largely English, so a Russian question will not
+find an English-only document no matter how it is weighted — and the reverse holds too. The fix is
+content, not code: give such a document a short summary section in the other language, or ask in the
+language the document is written in.
 
-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.
+### Publishing CMS docs into it
 
-The catalog is built from two sources, because neither alone is enough:
+The knowledge repo is what the server reads; the CMS repos remain where the docs are written.
+To move them across:
+
+```bash
+npm run publish:knowledge -- --back ../dnk-back --front ../dnk-front --out ../oneentry-platform-rules
+```
+
+It copies `.claude/docs`, `.claude/tests` and `.claude/rules` from both checkouts, splits anything
+over 12 KB at `##` boundaries, and reports files in the target it did not produce. It **does not
+commit or push** — that diff is the moment internal text becomes public, and a human owns it.
+`.claude/fixes` and the CMS `CLAUDE.md` files are deliberately not published.
+
+## Where the catalog comes from
+
+Two sources, because neither alone is enough:
+
+1. `GET {baseUrl}/workflows/nodes/admin-api/swagger.json?langCode=en_US` — paths, operation ids and
+   schemas, straight from the stand you are pointed at. Cached per base URL, so an unreachable
+   stand still yields the last known catalog.
+2. `data/permissions.json` — the `@GrantByPermission` decorators, which never reach swagger.
+   Regenerate it when the CMS changes its permissions:
+
+```bash
+npm run sync:permissions -- --back ../dnk-back
+```
 
-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.
+That pass walks base classes too, 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:
+Inconsistencies are surfaced as catalog `warnings` (visible in `cms_whoami`) rather than swallowed:
+paths outside `/api/admin` (dropped — this server exposes the Admin API only), operations with no
+`operationId`, handlers whose permission is known but which the stand does not expose, and
+permissions required by controllers but absent from `AdminPermissionsEnum` — no admin can hold
+those, so such endpoints answer 403 forever.
 
-- 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.
+If the stand does not serve its swagger at all, the catalog is **empty** and says so loudly. Empty
+is safe — there is nothing to call — but silence would read as "the CMS has no such endpoint".
 
 ### The swagger is not valid JSON Schema
 
-311 `type` values in the source swagger are TypeScript expressions (`Record<string, any>`,
+Many `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