@oneentry/mcp-platform-server 0.1.0 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OneEntry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,16 +1,23 @@
 # @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.
+MCP server that lets an AI agent **operate the OneEntry Admin API** — grounded in published
+operating 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 instance's own API document at
+  `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`: the permission an operation requires
+is declared in platform code and never reaches the API document, so that map has to be recovered
+separately.
 
 Only the Admin API is exposed.
 
@@ -20,7 +27,7 @@ Only the Admin API is exposed.
 npm i -g @oneentry/mcp-platform-server     # or use npx, below
 ```
 
-## Local mode (agent and CMS on the same machine)
+## Local mode (agent and instance on the same machine)
 
 Add to `.mcp.json` in the repo you work from:
 
@@ -29,7 +36,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,20 +47,21 @@ 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.
+Nothing has to be checked out locally. 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).
+The base URL must point at an instance that exposes the Admin API under `/api/admin`.
 
-## Remote mode (hosted, many agents, one stand)
+## Remote mode (hosted, many agents, one instance)
 
 ```bash
 oneentry-mcp-platform --http --port 8931 --audit /var/log/oneentry-mcp-platform-audit.jsonl \
-        --base-url https://stand.example/api/admin \
+        --base-url https://your-instance.example/api/admin \
         --allowed-origins https://agent.example
 ```
 
-Each MCP session carries its own CMS identity, passed as connection headers — never as tool
+Each MCP session carries its own identity, passed as connection headers — never as tool
 arguments, so a prompt-injected instruction cannot swap identities:
 
 | header | meaning |
@@ -63,43 +71,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 |
@@ -108,9 +79,9 @@ To point an MCP client at the containerised stdio server:
 | `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_describe` | params, body schema, required permission, risk, confirm gating |
 | `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`.
 
@@ -130,60 +101,132 @@ Read-only by default. `--allow` (or `ONEENTRY_MCP_ALLOW`) raises it:
   `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.
+- Permissions are checked locally first: if the admin lacks the permission 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
+## Where the knowledge comes from
+
+A public GitHub repository of small markdown files. Layout:
 
-`data/catalog.json` and `data/knowledge.json` are committed build outputs:
+```
+knowledge/
+  mcp/operating-rules.md                -> docId "mcp/operating-rules"
+  mcp/docs/api/orders.md                -> docId "mcp/docs/api/orders"
+  mcp/docs/server/cms-api-call.md       -> docId "mcp/docs/server/cms-api-call"
+  mcp/docs/api/orders/index.md          -> docId "mcp/docs/api/orders"
+```
+
+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 an
+instance 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
 
-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.
+Search does not translate, and the corpus is English. A question asked in another language will not
+find an English-only document no matter how it is weighted. The fix is content, not code.
 
-The catalog is built from two sources, because neither alone is enough:
+### The corpus is hand-authored
 
-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.
+The knowledge repository is written for a public audience, one file at a time. There is no import
+script and one must not be added: bulk-copying internal documentation into it would publish source
+paths, storage identifiers and tracker ids in a single command, and a repository that is public and
+mirrored cannot be un-published. `npm run publish:knowledge` exists only to refuse.
 
-Two classes of inconsistency in dnk-back are surfaced as catalog `warnings` (visible in
-`cms_whoami`) rather than silently swallowed:
+At release time, copy `knowledge/mcp/operating-rules.md` from the rules repository over this
+package's `knowledge/operating-rules.md` — the rules repository is the source, and the bundled seed
+is never hand-edited.
 
-- 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.
+## Where the catalog comes from
 
-### The swagger is not valid JSON Schema
+Two sources, because neither alone is enough:
 
-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.
+1. `GET {baseUrl}/workflows/nodes/admin-api/swagger.json?langCode=en_US` — paths, operation ids and
+   schemas, straight from the instance you are pointed at. Cached per base URL, so an unreachable
+   instance still yields the last known catalog.
+2. `data/permissions.json` — the permission each operation requires, which the API document does not
+   express. Regenerate it when the platform changes its permissions:
+
+```bash
+npm run sync:permissions -- --back <path to a platform checkout>
+```
+
+That pass walks base classes too, since the operation id is derived from the *registered* class
+while the handler often lives in a parent.
+
+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`, operations whose permission is known but which the instance does not expose, and
+permissions that operations require but no admin can hold — such endpoints answer 403 forever.
+
+If the instance does not serve its API document at all, the catalog is **empty** and says so loudly.
+Empty is safe — there is nothing to call — but silence would read as "the platform has no such
+endpoint".
+
+### The API document is not valid JSON Schema
+
+Many `type` values in the source document are expressions in the platform's own type language
+(`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 instance 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
+npm test                 # unit + MCP protocol + remote-mode transport (no instance needed)
+npm run test:integration # against a live instance; 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.
+The integration suite needs `ONEENTRY_CMS_BASE_URL` pointing at an instance that exposes the Admin
+API, 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.
+
+## License
+
+MIT — see [LICENSE](LICENSE).