mikser-io-mcp 2.0.0 → 11.0.1

package/README.md

@@ -7,7 +7,7 @@ MCP (Model Context Protocol) substrate and tools for [mikser-io](https://github.
 - **The MCP substrate** — `createMcpSubstrate`, per-session McpServer + transport via `mountMcpOnExpress`, the pino-to-MCP log bridge `wireLoggerToMcp`. Other plugins compose against `runtime.options.mcp` to register their own tools and resources.
 - **Built-in resources** — `mikser://config`, `mikser://lifecycle`, `mikser://logs`, `mikser://server`. Read-only introspection any MCP client can use.
 - **Built-in tools**
-  - *Catalog* — `mikser_query_entities`, `mikser_read_entity`, `mikser_update_entity`, `mikser_delete_entity`, `mikser_render`, over the engine's public catalog API.
+  - *Catalog* — `mikser_query_entities`, `mikser_read_entity`, `mikser_edit_entity`, `mikser_update_entity`, `mikser_delete_entity`, `mikser_render`, over the engine's public catalog API.
   - *Finding things* — `mikser_search` locates a string across entity meta, source files, and (with `in: ["output"]`) the BUILT files, reporting occurrences per page — and with `attribute: true`, which source emitted each hit. That is how you find content you can only describe by what it says, and how you size a change to anything shared before making it.
   - *Working backwards* — `mikser_which` takes a built destination and returns the source that produced it: the field path and line/column a value was written at, or the line in file content where it appears — each occurrence flagged by whether the string BEGINS its line, which separates a declaration from a use in any text format without a per-language grammar. Each answer is labelled by how it was reached — `meta-field` and `source-content` are RECORDED (the engine's own `refClosure` says this render consumed that entity, and the position comes from parsing its source), `scan` is not. It reaches values that appear nowhere in a page's own document, which is most of a shared nav or footer.
   - *References* — `mikser_refs_inbound` / `mikser_refs_outbound` / `mikser_refs_broken` / `mikser_refs_rename`, from `runtime.refs`.
@@ -40,8 +40,36 @@ piping into `jq` works; exit status is 0 / 1 (the tool reported an error) /
 
 ## Editing content
 
-`mikser_update_entity` writes the WHOLE file — there is no partial-edit or
-patch mode. Three fields make that safe to do without a shell on the box:
+Two tools write source files, and which one you reach for is the whole point.
+
+`mikser_edit_entity` changes PART of a file: you name the text to replace and
+everything else is left exactly as it is, byte for byte. Use it for any change
+to an existing file.
+
+```js
+await mikser_edit_entity({
+    id: '/documents/pricing.md',
+    find: 'price: 1200',        // must match exactly once
+    replace: 'price: 1400',
+})
+```
+
+`find` must appear exactly once, or the edit is refused and told how many times
+it appeared — extend it with the surrounding lines, or pass `all: true` for a
+rename that really should hit every one. An anchor that appears nowhere is
+refused too: the file is not what you read. And the RESULT must still parse in
+the file's format — a broken YAML block is caught before it lands, which is the
+check a whole-file write has no way to make. None of those come back as
+errors; each is a result carrying what the next attempt needs.
+
+This exists because rewriting a whole file to change one line means re-emitting
+every other line, and a line dropped on the way looks downstream exactly like a
+line someone deleted on purpose. `ifChecksum` catches a stale read; nothing
+catches a lossy write.
+
+`mikser_update_entity` writes the WHOLE file. Use it to CREATE a file, or when
+you are genuinely replacing most of one. Three fields make that safe to do
+without a shell on the box:
 
 ```js
 const page = await mikser_read_entity({ id: '/styles/tokens/buttons.css', include: ['content', 'positions'] })

package/index.js

@@ -50,9 +50,12 @@ import {
     cycleHistory,
     checksum as fileChecksumOf,
     writeEntitySource,
+    editEntitySource,
     withChangeSet,
+    withPrincipal,
     describeAuthority,
     inventory,
+    loadedPlugins,
     actingRole,
     explainRefusal,
     findChangeSet,
@@ -237,7 +240,14 @@ function wrapMutatingHandler(handler) {
                 // more calls can join it, and only it knows when that stops.
                 closeOnReturn: !changeSet,
             },
-            () => handler(toolArgs, ...rest),
+            // The REAL principal, alongside the display string above. Those
+            // are two different things and the difference matters: the string
+            // is for the log, and asking `hasCapability` about it reads
+            // `undefined.capabilities`, takes the not-capability-scoped
+            // branch, and returns true for everything. Establishing the
+            // object is what lets the write primitives refuse.
+            () => withPrincipal(authContext.getStore()?.principal ?? null,
+                () => handler(toolArgs, ...rest)),
         )
         // Report the id back, whatever shape the tool's own result takes.
         //
@@ -751,7 +761,7 @@ function stalePackages(workingFolder) {
     substrate.registerTool(
         'mikser_ping',
         {
-            description: 'Return mikser engine identity, current lifecycle phase, and (if --server is on) where the HTTP server is reachable. Use to confirm the connection is live before issuing other tool calls and to learn the base URL for preview outputs.\n\n`plugins` lists what this mikser is built from — every installed mikser package with its purpose, version and links, and `active: true` on the ones actually running. Read it once to know what the system can do before reasoning about what it should.\n\nCheck `faults` before reading any empty result as a fact about the site: it is absent unless a subsystem has reported that it cannot work, and while it is present a tool may be answering emptily because it is unable to answer rather than because there is nothing to say. Each entry names the condition, when it was first and last seen, and how often — report it and stop rather than working around it.\n\nCheck `stale` before trusting any other tool, and before reporting a bug: it lists mikser packages installed SINCE this process booted, whose code is therefore not the code answering you. A running process never re-reads node_modules, and --watch does not change that — it reloads content, not dependencies. When `stale` is non-empty the fix is a restart, not a bug report.\n\nThe `auth` block names the ROLE this session acts as, what it may write and what it may only read — and `auth.roles` lists EVERY role on this site with the same reach, the acting one marked. That is INFORMATIONAL: report what you cannot do and stop. There is no way to request or change a role and none will be added — the listing names a person to ask, not a privilege to obtain.',
+            description: 'Return mikser engine identity, current lifecycle phase, and (if --server is on) where the HTTP server is reachable. Use to confirm the connection is live before issuing other tool calls and to learn the base URL for preview outputs.\n\n`loaded` is what this runtime is actually RUNNING — recorded as each plugin loads, not worked out afterwards from what it happens to expose. Every loaded plugin is in it. `package` names the one it came from; `package: null` means the plugin is running and did not say what it is, which is NOT the same as not running and must not be read as it. Nothing is ever missing from this list because it could not be detected.\n\n`installed` is a different question: every mikser package on disk with its purpose, version and links — what the site COULD use, including what it is not using. A package in `installed` and absent from `loaded` is not loaded.\n\nRead `loaded` to know what the system does, and `installed` to know what it could do. Earlier versions merged the two into one list with an `active` flag whose absence meant either \'not running\' or \'could not tell\' — it reported git sync and schema validation as off while both were running.\n\nCheck `faults` before reading any empty result as a fact about the site: it is absent unless a subsystem has reported that it cannot work, and while it is present a tool may be answering emptily because it is unable to answer rather than because there is nothing to say. Each entry names the condition, when it was first and last seen, and how often — report it and stop rather than working around it.\n\nCheck `stale` before trusting any other tool, and before reporting a bug: it lists mikser packages installed SINCE this process booted, whose code is therefore not the code answering you. A running process never re-reads node_modules, and --watch does not change that — it reloads content, not dependencies. When `stale` is non-empty the fix is a restart, not a bug report.\n\nThe `auth` block names the ROLE this session acts as, what it may write and what it may only read — and `auth.roles` lists EVERY role on this site with the same reach, the acting one marked. That is INFORMATIONAL: report what you cannot do and stop. There is no way to request or change a role and none will be added — the listing names a person to ask, not a privilege to obtain.',
             inputSchema: {},
         },
         async () => ({
@@ -784,7 +794,8 @@ function stalePackages(workingFolder) {
                     // `active` marks the ones actually running: a package in
                     // node_modules that no config loads explains nothing about
                     // this site's behaviour.
-                    plugins: inventory(),
+                    loaded: loadedPlugins(),
+                    installed: inventory(),
                     server: serverInfo(),
                     // Whether this connection is authenticated and for how
                     // much longer, so a long task can be sequenced rather
@@ -2183,7 +2194,8 @@ export function mcp(options = {}) {
 
         mcp.simpleTool(
             'mikser_update_entity',
-            'Create or update a content file inside a mikser collection. Writes the WHOLE file — there is no partial-edit or patch mode, so send the complete intended contents. The file lands on disk and the next lifecycle cycle picks it up.\n\n'
+            'Create or update a content file inside a mikser collection. Writes the WHOLE file: send the complete intended contents, because anything you leave out is deleted.\n\n'
+            + 'Use this to CREATE a file, or when you are rewriting most of one. To change part of an existing file use mikser_edit_entity instead — it changes only the text you name, so a long file cannot lose a line you did not mean to touch.\n\n'
             + 'Pass `ifChecksum` with the checksum you got from mikser_read_entity to make the write conditional: if the file has changed since you read it the write is REFUSED and the response carries `currentChecksum`, so a blind whole-file rewrite cannot silently discard someone else\'s edit. Without it the write is unconditional.\n\n'
             + 'The response returns the resulting `checksum` (pass it as the next `ifChecksum`), the `cycleId` your write will be picked up by, and `siblingDestinations` when another file could render to the same place (e.g. index.md beside index.yml — whichever renders last wins and the other output is discarded).\n\n'
             + 'Pass `await: true` to block until that cycle finishes and get its build report back, so one call tells you what your edit invalidated instead of writing and guessing.',
@@ -2239,6 +2251,69 @@ export function mcp(options = {}) {
             { mutates: true },
         )
 
+        mcp.simpleTool(
+            'mikser_edit_entity',
+            'Change PART of an existing content file, by naming the text to change. Everything you do not name is '
+            + 'left exactly as it is — byte for byte, including whitespace, line endings and anything further down '
+            + 'the file you never read.\n\n'
+            + 'Prefer this over mikser_update_entity for any change to an existing file. A whole-file write makes you '
+            + 're-emit the entire document to change one line, and a line dropped on the way looks downstream exactly '
+            + 'like a line someone deleted on purpose.\n\n'
+            + '`find` must appear EXACTLY ONCE. If it appears more than once the edit is refused and the response '
+            + 'says how many times: extend `find` with the surrounding lines until it is unique, or pass `all: true` '
+            + 'to change every occurrence. If it appears nowhere the edit is refused too — the file is not what you '
+            + 'read, so re-read it rather than guessing.\n\n'
+            + 'The result must also still PARSE in the file\'s format (YAML frontmatter, a .yml data file, whatever '
+            + 'the site has registered). If it would not, nothing is written and the response carries the parser\'s '
+            + 'complaint. This is the check a whole-file write cannot offer.\n\n'
+            + 'Copy `find` from mikser_read_entity output verbatim, including indentation. An anchor assembled from '
+            + 'memory is the usual reason for a refusal.',
+            {
+                id:           z.string().optional().describe('Catalog id of the entity to edit (e.g. "/blog/launch.md"). Alternative to collection + relativePath.'),
+                collection:   z.string().optional().describe('Collection name (e.g. "documents"). Required unless `id` is given.'),
+                relativePath: z.string().optional().describe('Path relative to the collection folder. Required unless `id` is given.'),
+                find:         z.string().describe('The EXACT text to replace, copied from the file. Must match once (or pass `all`). Include enough surrounding lines to be unique — a bare word usually is not.'),
+                replace:      z.string().optional().describe('The text to put in its place. Omit or pass "" to DELETE the matched text. Match the surrounding indentation; nothing reindents it for you.'),
+                all:          z.boolean().optional().describe('Replace every occurrence instead of refusing an ambiguous one. Use for a rename that really should hit all of them; the response reports `replacements`.'),
+                ifChecksum:   z.string().optional().describe('Precondition: only edit if the file\'s current DISK checksum equals this. Use `diskChecksum` from mikser_read_entity. Optional here — the anchor is itself a check on the file being what you read.'),
+                await:        z.boolean().optional().describe('Block until the cycle that picks up this edit completes, and return its build report as `report`.'),
+                dryRun:       z.boolean().optional().describe('Write NOTHING, but still resolve the anchor: refusals are reported exactly as they would be. Returns `wouldAffect` — every destination that would re-render.'),
+            },
+            async ({ id, collection, relativePath, find, replace = '', all, ifChecksum, await: awaitCycle, dryRun }) => {
+                try {
+                    if (!dryRun) {
+                        const refusal = refuseIfExpiringWithin(
+                            awaitCycle ? 120 : 15,
+                            awaitCycle ? 'an edit that then waits for a build cycle' : 'an edit')
+                        if (refusal) return refusal
+                    }
+
+                    const result = await editEntitySource({
+                        id, collection, relativePath, find, replace, all, ifChecksum, dryRun, awaitCycle,
+                    })
+
+                    // The anchor refusals are NOT errors. Each one carries what
+                    // the next attempt needs — the occurrence count, the
+                    // parser's complaint, the current checksum — and an error
+                    // string is where that goes to die. A caller that gets
+                    // `refused: 'anchor-ambiguous'` with `occurrences: 4` can
+                    // fix its own anchor; one that gets a red failure retries
+                    // the same call or falls back to rewriting the whole file,
+                    // which is the outcome this tool exists to avoid.
+                    const recoverable = ['anchor-not-found', 'anchor-ambiguous',
+                                         'would-not-parse', 'checksum-mismatch']
+                    if (!result.ok && !recoverable.includes(result.refused)) {
+                        return fail(result.error ?? result.refused)
+                    }
+                    return ok(result)
+                } catch (err) {
+                    logger.error('MCP mikser_edit_entity error: %s', err.message)
+                    return fail(err.message)
+                }
+            },
+            { mutates: true },
+        )
+
         mcp.simpleTool(
             'mikser_delete_entity',
             'Remove a content file from a mikser collection. Deletes the source file; the next lifecycle cycle prunes its rendered outputs from the manifest.\n\n'
@@ -2327,6 +2402,6 @@ export function mcp(options = {}) {
         logger.debug('MCP tools registered: mikser_{query_entities,read_entity,update_entity,delete_entity,render} (mcp plugin)')
     })
 
-    return { name: 'mcp' }
+    return { name: 'mcp', module: import.meta.url }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mikser-io-mcp",
-  "version": "2.0.0",
+  "version": "11.0.1",
   "description": "MCP (Model Context Protocol) substrate and tools for mikser-io. Extracted from core to iterate on its own release cadence.",
   "main": "index.js",
   "type": "module",
@@ -42,11 +42,11 @@
     "minimatch": "^10.0.3"
   },
   "peerDependencies": {
-    "mikser-io": "^10.0.0",
+    "mikser-io": "^11.0.1",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "mikser-io": "file:../mikser-io",
+    "mikser-io": "^11.0.1",
     "zod": "^4.0.0"
   }
 }