@rockhopper-co/mcp-server 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to this project are documented here. Follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] — 2026-05-12
+
+### Changed
+- **`resources/list` no longer enumerates per-file instances.** The 4
+  per-file resource templates (`enrolled-file`, `file-versions`,
+  `file-comments`, `unattributed-changes`) previously expanded into one
+  concrete resource per enrolled file via their `list:` callbacks,
+  bloating the response to 44+ entries at single-digit file counts and
+  ~400 at 100 files. They now appear in `resources/templates/list`
+  semantics instead — AI clients learn the URI pattern and construct
+  concrete URIs on demand. `resources/list` stays at a small static set
+  regardless of workspace size. Closes KI-078 / ENG-1381.
+
+### Added
+- **`rockhopper://orchestration-guide` resource.** Static markdown
+  resource that documents tool sequencing, identity disambiguation
+  (`fileMsId` vs `versionId` vs `versionInternalId`), the comment and
+  review lifecycles, versioning rules, and cross-cloud (Microsoft vs
+  Google Sheets) differences. AI clients can read it once at session
+  start to avoid common tool-sequencing errors. Backed by
+  `src/resources/orchestration-guide.md`. Closes KI-079 / ENG-1382.
+
+### Internal
+- Build step now copies `src/**/*.md` into `dist/` so non-`.ts` assets
+  ship with the package (`scripts/copy-non-ts-assets.mjs`).
+- Unit and e2e test updates: assert `resources/list` returns exactly 2
+  static entries and `resources/templates/list` returns the 8 URI
+  templates; new test reads the orchestration-guide content.
+- Regenerated Postman collection (16 tools, 10 resources, 4 prompts).
+
+### Breaking changes
+- Behavior change in `resources/list` response shape. Downstream
+  consumers that cached the previous per-file enumeration must refresh
+  their resource lists. No tool, prompt, or resource-read semantics
+  changed — only the `resources/list` response.
+
 ## [0.4.0] — 2026-05-03
 
 ### Added

package/dist/resources/changes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"changes.d.ts","sourceRoot":"","sources":["../../src/resources/changes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CAoCN"}
+{"version":3,"file":"changes.d.ts","sourceRoot":"","sources":["../../src/resources/changes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CA4BN"}

package/dist/resources/changes.js

@@ -1,18 +1,10 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 export function registerChangeResources(server, api) {
+    // KI-078 (ENG-1381): template only, no per-file expansion into resources/list.
+    // Previously this enumerated only files with `hasUncommittedChanges === true` —
+    // a per-call API request that scaled linearly with file count.
     server.registerResource('unattributed-changes', new ResourceTemplate('rockhopper://files/{fileMsId}/changes', {
-        list: async () => {
-            const files = await api.listEnrolledFiles();
-            return {
-                resources: files
-                    .filter((f) => f.hasUncommittedChanges)
-                    .map((f) => ({
-                    uri: `rockhopper://files/${f.platformId}/changes`,
-                    name: `Unattributed changes in ${f.name}`,
-                    mimeType: 'application/json',
-                })),
-            };
-        },
+        list: undefined,
     }), {
         title: 'Unattributed Changes',
         description: 'Pending cell-level changes not yet attributed to a version for a file',

package/dist/resources/changes.js.map

@@ -1 +1 @@
-{"version":3,"file":"changes.js","sourceRoot":"","sources":["../../src/resources/changes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAI3E,MAAM,UAAU,uBAAuB,CACrC,MAAiB,EACjB,GAAc;IAEd,MAAM,CAAC,gBAAgB,CACrB,sBAAsB,EACtB,IAAI,gBAAgB,CAAC,uCAAuC,EAAE;QAC5D,IAAI,EAAE,KAAK,IAAI,EAAE;YACf,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,iBAAiB,EAAE,CAAC;YAC5C,OAAO;gBACL,SAAS,EAAE,KAAK;qBACb,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,qBAAqB,CAAC;qBACtC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACX,GAAG,EAAE,sBAAsB,CAAC,CAAC,UAAU,UAAU;oBACjD,IAAI,EAAE,2BAA2B,CAAC,CAAC,IAAI,EAAE;oBACzC,QAAQ,EAAE,kBAAkB;iBAC7B,CAAC,CAAC;aACN,CAAC;QACJ,CAAC;KACF,CAAC,EACF;QACE,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EACT,uEAAuE;QACzE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1B,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,sBAAsB,CAAC,QAAkB,CAAC,CAAC;QACrE,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;iBACvC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"changes.js","sourceRoot":"","sources":["../../src/resources/changes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAI3E,MAAM,UAAU,uBAAuB,CACrC,MAAiB,EACjB,GAAc;IAEd,+EAA+E;IAC/E,gFAAgF;IAChF,+DAA+D;IAC/D,MAAM,CAAC,gBAAgB,CACrB,sBAAsB,EACtB,IAAI,gBAAgB,CAAC,uCAAuC,EAAE;QAC5D,IAAI,EAAE,SAAS;KAChB,CAAC,EACF;QACE,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EACT,uEAAuE;QACzE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1B,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,sBAAsB,CAAC,QAAkB,CAAC,CAAC;QACrE,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;iBACvC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/resources/comments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/resources/comments.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CAkCN"}
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/resources/comments.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CA0BN"}

package/dist/resources/comments.js

@@ -1,16 +1,8 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 export function registerCommentResources(server, api) {
+    // KI-078 (ENG-1381): template only, no per-file expansion into resources/list.
     server.registerResource('file-comments', new ResourceTemplate('rockhopper://files/{fileMsId}/comments', {
-        list: async () => {
-            const files = await api.listEnrolledFiles();
-            return {
-                resources: files.map((f) => ({
-                    uri: `rockhopper://files/${f.platformId}/comments`,
-                    name: `Comments on ${f.name}`,
-                    mimeType: 'application/json',
-                })),
-            };
-        },
+        list: undefined,
     }), {
         title: 'File Comments',
         description: 'All comments and chat threads on a specific enrolled file',

package/dist/resources/comments.js.map

@@ -1 +1 @@
-{"version":3,"file":"comments.js","sourceRoot":"","sources":["../../src/resources/comments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAI3E,MAAM,UAAU,wBAAwB,CACtC,MAAiB,EACjB,GAAc;IAEd,MAAM,CAAC,gBAAgB,CACrB,eAAe,EACf,IAAI,gBAAgB,CAAC,wCAAwC,EAAE;QAC7D,IAAI,EAAE,KAAK,IAAI,EAAE;YACf,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,iBAAiB,EAAE,CAAC;YAC5C,OAAO;gBACL,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC3B,GAAG,EAAE,sBAAsB,CAAC,CAAC,UAAU,WAAW;oBAClD,IAAI,EAAE,eAAe,CAAC,CAAC,IAAI,EAAE;oBAC7B,QAAQ,EAAE,kBAAkB;iBAC7B,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC;KACF,CAAC,EACF;QACE,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,2DAA2D;QAC7D,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1B,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,QAAkB,CAAC,CAAC;QAC/D,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"comments.js","sourceRoot":"","sources":["../../src/resources/comments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAI3E,MAAM,UAAU,wBAAwB,CACtC,MAAiB,EACjB,GAAc;IAEd,+EAA+E;IAC/E,MAAM,CAAC,gBAAgB,CACrB,eAAe,EACf,IAAI,gBAAgB,CAAC,wCAAwC,EAAE;QAC7D,IAAI,EAAE,SAAS;KAChB,CAAC,EACF;QACE,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,2DAA2D;QAC7D,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1B,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,QAAkB,CAAC,CAAC;QAC/D,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/resources/files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/resources/files.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CAyDN"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/resources/files.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CAmDN"}

package/dist/resources/files.js

@@ -16,18 +16,12 @@ export function registerFileResources(server, api) {
             ],
         };
     });
+    // KI-078 (ENG-1381): the per-file template no longer enumerates `resources/list`.
+    // It is exposed via `resources/templates/list` so AI clients learn the URI pattern;
+    // concrete instances are read by URI on demand (e.g. `rockhopper://files/abc123`).
+    // The workspace-level `rockhopper://files` listing above is the discovery entry point.
     server.registerResource('enrolled-file', new ResourceTemplate('rockhopper://files/{fileMsId}', {
-        list: async () => {
-            const files = await api.listEnrolledFiles();
-            return {
-                resources: files.map((f) => ({
-                    uri: `rockhopper://files/${f.platformId}`,
-                    name: f.name,
-                    description: `${f.name} (${f.fileType})`,
-                    mimeType: 'application/json',
-                })),
-            };
-        },
+        list: undefined,
     }), {
         title: 'Enrolled File Details',
         description: 'Details for a specific enrolled file by its platform ID',

package/dist/resources/files.js.map

@@ -1 +1 @@
-{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/resources/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAI3E,MAAM,UAAU,qBAAqB,CACnC,MAAiB,EACjB,GAAc;IAEd,MAAM,CAAC,gBAAgB,CACrB,gBAAgB,EAChB,oBAAoB,EACpB;QACE,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACT,sEAAsE;QACxE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE;QACZ,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,iBAAiB,EAAE,CAAC;QAC5C,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;iBACrC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,gBAAgB,CACrB,eAAe,EACf,IAAI,gBAAgB,CAAC,+BAA+B,EAAE;QACpD,IAAI,EAAE,KAAK,IAAI,EAAE;YACf,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,iBAAiB,EAAE,CAAC;YAC5C,OAAO;gBACL,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC3B,GAAG,EAAE,sBAAsB,CAAC,CAAC,UAAU,EAAE;oBACzC,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,WAAW,EAAE,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,QAAQ,GAAG;oBACxC,QAAQ,EAAE,kBAAkB;iBAC7B,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC;KACF,CAAC,EACF;QACE,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,yDAAyD;QACtE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,QAAkB,CAAC,CAAC;QAC3D,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;iBACpC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/resources/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAI3E,MAAM,UAAU,qBAAqB,CACnC,MAAiB,EACjB,GAAc;IAEd,MAAM,CAAC,gBAAgB,CACrB,gBAAgB,EAChB,oBAAoB,EACpB;QACE,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACT,sEAAsE;QACxE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE;QACZ,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,iBAAiB,EAAE,CAAC;QAC5C,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;iBACrC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,kFAAkF;IAClF,oFAAoF;IACpF,mFAAmF;IACnF,uFAAuF;IACvF,MAAM,CAAC,gBAAgB,CACrB,eAAe,EACf,IAAI,gBAAgB,CAAC,+BAA+B,EAAE;QACpD,IAAI,EAAE,SAAS;KAChB,CAAC,EACF;QACE,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,yDAAyD;QACtE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,QAAkB,CAAC,CAAC;QAC3D,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;iBACpC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/resources/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAQlD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CAON"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AASlD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CAQN"}

package/dist/resources/index.js

@@ -4,6 +4,7 @@ import { registerCommentResources } from './comments.js';
 import { registerReviewResources } from './reviews.js';
 import { registerTeamResources } from './teams.js';
 import { registerChangeResources } from './changes.js';
+import { registerOrchestrationGuideResource } from './orchestration-guide.js';
 export function registerResources(server, api) {
     registerFileResources(server, api);
     registerVersionResources(server, api);
@@ -11,5 +12,6 @@ export function registerResources(server, api) {
     registerReviewResources(server, api);
     registerTeamResources(server, api);
     registerChangeResources(server, api);
+    registerOrchestrationGuideResource(server);
 }
 //# sourceMappingURL=index.js.map

package/dist/resources/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,UAAU,iBAAiB,CAC/B,MAAiB,EACjB,GAAc;IAEd,qBAAqB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,uBAAuB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrC,qBAAqB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,uBAAuB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/resources/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,kCAAkC,EAAE,MAAM,0BAA0B,CAAC;AAE9E,MAAM,UAAU,iBAAiB,CAC/B,MAAiB,EACjB,GAAc;IAEd,qBAAqB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACtC,uBAAuB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrC,qBAAqB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC,uBAAuB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrC,kCAAkC,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/resources/orchestration-guide.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerOrchestrationGuideResource(server: McpServer): void;
+//# sourceMappingURL=orchestration-guide.d.ts.map

package/dist/resources/orchestration-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration-guide.d.ts","sourceRoot":"","sources":["../../src/resources/orchestration-guide.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAczE,wBAAgB,kCAAkC,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAoB1E"}

package/dist/resources/orchestration-guide.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const ORCHESTRATION_GUIDE_URI = 'rockhopper://orchestration-guide';
+// KI-079 (ENG-1382): static narrative resource that documents tool sequencing,
+// identity disambiguation (`fileMsId` vs `versionId` vs `versionInternalId`),
+// and lifecycle rules. Loaded once at module init from the sibling .md file;
+// the build copies the .md into `dist/resources/` so it ships with the package.
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const guideContent = readFileSync(join(moduleDir, 'orchestration-guide.md'), 'utf8');
+export function registerOrchestrationGuideResource(server) {
+    server.registerResource('orchestration-guide', ORCHESTRATION_GUIDE_URI, {
+        title: 'Orchestration Guide',
+        description: 'Narrative reference for sequencing Rockhopper MCP tools correctly — identity types, workflows, review lifecycle, versioning rules, cross-cloud differences.',
+        mimeType: 'text/markdown',
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: guideContent,
+            },
+        ],
+    }));
+}
+//# sourceMappingURL=orchestration-guide.js.map

package/dist/resources/orchestration-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration-guide.js","sourceRoot":"","sources":["../../src/resources/orchestration-guide.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,uBAAuB,GAAG,kCAAkC,CAAC;AAEnE,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,gFAAgF;AAChF,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,YAAY,GAAG,YAAY,CAC/B,IAAI,CAAC,SAAS,EAAE,wBAAwB,CAAC,EACzC,MAAM,CACP,CAAC;AAEF,MAAM,UAAU,kCAAkC,CAAC,MAAiB;IAClE,MAAM,CAAC,gBAAgB,CACrB,qBAAqB,EACrB,uBAAuB,EACvB;QACE,KAAK,EAAE,qBAAqB;QAC5B,WAAW,EACT,6JAA6J;QAC/J,QAAQ,EAAE,eAAe;KAC1B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QACd,QAAQ,EAAE;YACR;gBACE,GAAG,EAAE,GAAG,CAAC,IAAI;gBACb,QAAQ,EAAE,eAAe;gBACzB,IAAI,EAAE,YAAY;aACnB;SACF;KACF,CAAC,CACH,CAAC;AACJ,CAAC"}

package/dist/resources/orchestration-guide.md

@@ -0,0 +1,120 @@
+# Rockhopper MCP — orchestration guide
+
+This guide explains how to combine Rockhopper's MCP tools and resources correctly. Read it before sequencing multiple tool calls — it documents the prerequisites, identity types, and lifecycle rules that the individual tool descriptions cannot show in isolation.
+
+## 1. Identity and IDs
+
+Rockhopper uses three distinct identifiers. Mixing them is the most common cause of tool-call errors.
+
+| ID | Type | Where it comes from | Where it goes |
+|----|------|---------------------|---------------|
+| `fileMsId` | string | `list_files` response, `rockhopper://files` resource | Tools that act on a file: `get_file_versions`, `get_file_comments`, `add_comment`, `create_version`, `discard_changes`, `get_cell_history`, `get_unattributed_changes`, `update_file_description` |
+| `versionId` | number | `get_file_versions` response (`internalId` field), `create_version` response | Tools that act on a specific version snapshot: `get_reviews`, `create_review_request`, `approve_review`, `cancel_review` |
+| `versionInternalId` | number | `get_file_comments` response (comments scope to a version) | Comment-thread tools: `add_comment`, `reply_to_comment`, `resolve_comment` |
+
+Decision tree:
+
+- **Reading file metadata** → `fileMsId`.
+- **Writing a comment** → `fileMsId` (the server auto-resolves the latest version) OR `versionInternalId` if commenting on a historical version.
+- **Acting on a review** → `versionId`.
+
+If a tool returns an error like "expected versionId but received fileMsId", you used the wrong identifier — check the tool description for which type it accepts.
+
+## 2. Reading workflow
+
+Standard sequence to inspect a file:
+
+1. `list_files` — discover enrolled files. Returns `fileMsId`, `name`, `fileType`, `hasUncommittedChanges`.
+2. `get_file_versions(fileMsId)` — version history. Each entry has `internalId` (this is the `versionId`).
+3. Branch:
+   - File contents at a specific version → `get_cell_history(fileMsId, sheet, cellAddress)`.
+   - Comments → `get_file_comments(fileMsId)`. Filters to the latest live version by default.
+   - Reviews → `get_reviews(versionId)`. Pass a `versionId` from step 2.
+   - Uncommitted changes → `get_unattributed_changes(fileMsId)` (only useful if `hasUncommittedChanges === true`).
+
+## 3. Commenting workflow
+
+Comments are scoped to a version. The default version is the latest **committed** one.
+
+1. `add_comment({ fileMsId, message, cellReference })` — creates a top-level comment on the latest version.
+2. `reply_to_comment({ parentCommentId, message })` — `parentCommentId` is the `internalId` from `get_file_comments`, **not** a substring or message match.
+3. `resolve_comment({ commentId })` — closes a thread. Idempotent — calling on an already-resolved comment is a no-op (returns the existing record).
+
+Comments on historical versions:
+
+- Pass `versionInternalId` explicitly to `add_comment` to comment on a historical version snapshot.
+- `get_file_comments` accepts `versionInternalId` if you want to read historical-version comments rather than the current set.
+
+## 4. Review lifecycle
+
+Reviews follow a strict state machine: **`pending` → `approved`** or **`pending` → `cancelled`**. No other transitions are valid.
+
+1. `create_review_request({ versionId, reviewerEmails, subject, description? })` — creates a `pending` review. Only the file owner / workspace member with edit rights can create.
+2. `approve_review({ reviewId })` — moves `pending` → `approved`. **Only** assigned reviewers can approve.
+3. `cancel_review({ reviewId })` — moves `pending` → `cancelled`. **Only** the requester can cancel.
+
+Calling `approve_review` before `create_review_request` returns a 404 — there is no review to approve. Calling `approve_review` on an already-approved or cancelled review returns a 409 conflict.
+
+## 5. Versioning
+
+`create_version` snapshots the file's current uncommitted state as a new version.
+
+Rules:
+
+- **Requires uncommitted changes.** If `get_unattributed_changes(fileMsId)` returns an empty list, `create_version` will fail with "no changes to commit".
+- **Auto-bumps semver** from the latest committed version. Defaults to patch (`1.0.0` → `1.0.1`). Pass `bumpType: 'minor' | 'major'` to override.
+- **Optional `description`** — a one-line changelog entry. Recommended for any non-trivial version.
+
+`discard_changes(fileMsId)` is the **destructive** alternative: it wipes uncommitted edits without creating a snapshot. Use only when the user explicitly asks to throw away unsaved work — call `get_unattributed_changes(fileMsId)` first and confirm with the user before discarding anything substantive.
+
+## 6. Uncommitted changes vs. committed history
+
+Two distinct concepts. Tools work with one or the other; do not mix.
+
+- **Committed history** — version snapshots created by `create_version`. Surfaced by `get_file_versions`, `get_cell_history`. Immutable.
+- **Uncommitted changes** — cell edits the user has made since the last `create_version`. Surfaced by `get_unattributed_changes`. Mutable; consumed by the next `create_version` or `discard_changes` call.
+
+Common mistake: calling `get_cell_history` to inspect a recent edit before it has been committed. `get_cell_history` only returns committed values — use `get_unattributed_changes` for pending edits.
+
+## 7. Cross-cloud differences
+
+Rockhopper supports both Microsoft Excel files (M365 / OneDrive) and Google Sheets. Tool calls work transparently across both, but the identifiers carry different meanings:
+
+| Field | Microsoft Excel | Google Sheets |
+|-------|------------------|----------------|
+| `fileType` | `microsoft_xlsx` | `google_sheets` |
+| `driveMsId` | OneDrive / SharePoint drive ID | Google Drive file ID (yes, the field name is misleading for the Google case) |
+| `platformId` (= `fileMsId`) | Microsoft graph file ID | Google Drive file ID |
+
+If a tool description references "drive ID" or "platform ID", it works identically across both clouds. If you need to know the platform, inspect `fileType`.
+
+## 8. Error handling
+
+Tool failures return structured responses with `isError: true` and a human-readable message in `content`. Common patterns:
+
+- **404 / "not found"** — usually a wrong-identifier-type error. Re-check the IDs section above.
+- **409 / "conflict"** — state-machine violation (e.g. approving an already-approved review).
+- **403 / "forbidden"** — permission error (e.g. non-reviewer calling `approve_review`).
+- **5xx** — server-side error. Retry once; if it persists, surface the error to the user — don't loop.
+
+When a tool returns `isError: true`, do not silently retry with the same arguments. Either correct the arguments based on the error message or surface the failure.
+
+## 9. Resources
+
+The MCP server exposes two static resources via `resources/list`:
+
+- `rockhopper://files` — workspace-level enrolled files listing. Same data as `list_files` tool.
+- `rockhopper://orchestration-guide` — this document.
+
+Eight URI templates via `resources/templates/list` — read these by constructing a concrete URI from the template pattern:
+
+- `rockhopper://files/{fileMsId}` — file details
+- `rockhopper://files/{fileMsId}/versions` — version history
+- `rockhopper://files/{fileMsId}/comments` — all comments
+- `rockhopper://files/{fileMsId}/changes` — uncommitted changes
+- `rockhopper://versions/{versionId}` — version details
+- `rockhopper://versions/{versionId}/reviews` — reviews on a version
+- `rockhopper://reviews/{reviewId}` — review details
+- `rockhopper://teams/{teamId}` — team details
+
+Resources and tools return the same data for the same identifiers. Tools are preferable when you need argument shaping (filters, search); resources are preferable when you have a known URI and want the canonical representation.

package/dist/resources/versions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/resources/versions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CAyDN"}
+{"version":3,"file":"versions.d.ts","sourceRoot":"","sources":["../../src/resources/versions.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,SAAS,GACb,IAAI,CAiDN"}

package/dist/resources/versions.js

@@ -1,16 +1,8 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 export function registerVersionResources(server, api) {
+    // KI-078 (ENG-1381): template only, no per-file expansion into resources/list.
     server.registerResource('file-versions', new ResourceTemplate('rockhopper://files/{fileMsId}/versions', {
-        list: async () => {
-            const files = await api.listEnrolledFiles();
-            return {
-                resources: files.map((f) => ({
-                    uri: `rockhopper://files/${f.platformId}/versions`,
-                    name: `Versions of ${f.name}`,
-                    mimeType: 'application/json',
-                })),
-            };
-        },
+        list: undefined,
     }), {
         title: 'File Version History',
         description: 'All version snapshots for a specific enrolled file',

package/dist/resources/versions.js.map

@@ -1 +1 @@
-{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/resources/versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAI3E,MAAM,UAAU,wBAAwB,CACtC,MAAiB,EACjB,GAAc;IAEd,MAAM,CAAC,gBAAgB,CACrB,eAAe,EACf,IAAI,gBAAgB,CAAC,wCAAwC,EAAE;QAC7D,IAAI,EAAE,KAAK,IAAI,EAAE;YACf,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,iBAAiB,EAAE,CAAC;YAC5C,OAAO;gBACL,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC3B,GAAG,EAAE,sBAAsB,CAAC,CAAC,UAAU,WAAW;oBAClD,IAAI,EAAE,eAAe,CAAC,CAAC,IAAI,EAAE;oBAC7B,QAAQ,EAAE,kBAAkB;iBAC7B,CAAC,CAAC;aACJ,CAAC;QACJ,CAAC;KACF,CAAC,EACF;QACE,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EAAE,oDAAoD;QACjE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1B,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,QAAkB,CAAC,CAAC;QAC/D,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,gBAAgB,CACrB,cAAc,EACd,IAAI,gBAAgB,CAAC,mCAAmC,EAAE;QACxD,IAAI,EAAE,SAAS;KAChB,CAAC,EACF;QACE,KAAK,EAAE,iBAAiB;QACxB,WAAW,EAAE,oDAAoD;QACjE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;QAC3B,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QAC5D,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;iBACvC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/resources/versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAI3E,MAAM,UAAU,wBAAwB,CACtC,MAAiB,EACjB,GAAc;IAEd,+EAA+E;IAC/E,MAAM,CAAC,gBAAgB,CACrB,eAAe,EACf,IAAI,gBAAgB,CAAC,wCAAwC,EAAE;QAC7D,IAAI,EAAE,SAAS;KAChB,CAAC,EACF;QACE,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EAAE,oDAAoD;QACjE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC1B,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,QAAkB,CAAC,CAAC;QAC/D,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,gBAAgB,CACrB,cAAc,EACd,IAAI,gBAAgB,CAAC,mCAAmC,EAAE;QACxD,IAAI,EAAE,SAAS;KAChB,CAAC,EACF;QACE,KAAK,EAAE,iBAAiB;QACxB,WAAW,EAAE,oDAAoD;QACjE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;QAC3B,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QAC5D,OAAO;YACL,QAAQ,EAAE;gBACR;oBACE,GAAG,EAAE,GAAG,CAAC,IAAI;oBACb,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;iBACvC;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rockhopper-co/mcp-server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Rockhopper MCP server — expose file metadata, versions, reviews, and comments to AI tools",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-non-ts-assets.mjs",
     "start": "node dist/cli.js",
     "dev": "tsx watch src/cli.ts",
     "lint": "eslint src/",