@myspec/mcp-server 1.1.1-next.158 → 1.1.1-next.160

package/README.md

@@ -333,8 +333,8 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 
 | Name | Inputs | Output |
 |---|---|---|
-| `list_projects` | `query?`, `limit?`, `offset?` | Paginated list of projects |
-| `get_project` | `project_id` | Project + active sessions + files + attachments |
+| `list_projects` | `query?`, `limit?`, `offset?` | Paginated list of projects, each with your `viewer_role` (`read`/`write`/`admin`) when the platform reports it |
+| `get_project` | `project_id` | Project (with your `viewer_role` when reported) + active sessions + files + attachments |
 | `get_spec_file` | `file_id`, optional `include_download_url` | File metadata, including `content_version` (see [Concurrent edits](#concurrent-edits-content_version)); with `include_download_url=N` also returns a download URL targeting revision `N` |
 | `read_spec_file` | `file_id`, optional `revision`, optional `offset`, optional `limit` | UTF-8 content paginated by line (`offset` is 1-based, default/cap 2000 lines, 1 MiB per response) with `content`, `start_line`, `end_line`, `read_lines`, `total_lines`, `truncated`, `next_offset`; plus `content_version` when reading the latest revision (errors for binary or files > 8 MiB — use `download_spec_file` for those). Cached on disk under `MYSPEC_DOWNLOAD_ROOT`, so paging through a file downloads it once |
 | `download_spec_file` | `file_id`, optional `destination_path`, optional `revision`, optional `overwrite` | Downloads the file's raw bytes to a local file — by default under `.specs/` in the working directory (see [Download destinations](#download-destinations)). Handles binary files and files up to 50 MiB. Refuses to replace an existing file unless `overwrite=true`. Returns only metadata (`saved_path`, `bytes_written`, `revision_number`, `destination_source`) — **not** the content, so a large file can be saved locally and read in chunks |
@@ -366,6 +366,8 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 
 There is deliberately **no tool to resolve, unresolve or re-anchor a thread**. Those three are human-only: resolving declares a review finished, and re-anchoring is the repair a person makes after the automatic pass has already failed to locate the passage. The platform refuses them for an AI caller with a 403, so a tool would only ever return an error.
 
+**Project roles.** A tool that needs more than your role on the project (`read` is read-only; `write` also edits files, comments, attachments and artifacts and starts AI chat sessions; `admin` also renames, archives and deletes the project) fails with `permission denied — this action needs the <role> role on the project; you have <role>. Ask a project admin for access.` A new token will not help; a project admin has to raise your role.
+
 ### Brownfield sessions: start the bridge first
 
 `start_spec_session` hands MySpec a prompt; it does **not** hand it your files.

package/dist/index.js

@@ -1810,6 +1810,37 @@ function isPlatformQuotaError(err) {
   const code = err.code;
   return typeof code === "string" && code.toLowerCase() === QUOTA_EXCEEDED_CODE;
 }
+var PROJECT_PERMISSION_DENIED_CODE = "project_permission_denied";
+var PlatformPermissionError = class extends PlatformHttpError {
+  code = PROJECT_PERMISSION_DENIED_CODE;
+  /** The capability that was refused, e.g. `file.write`. */
+  capability;
+  /** The role it needs. */
+  requiredRole;
+  /** The role the caller has. */
+  viewerRole;
+  constructor(message, details) {
+    super(message, 403, details);
+    this.name = "PlatformPermissionError";
+    this.capability = stringField(details, "capability");
+    this.requiredRole = stringField(details, "required_role");
+    this.viewerRole = stringField(details, "viewer_role");
+  }
+};
+function isProjectPermissionDeniedError(err) {
+  if (err instanceof PlatformPermissionError) {
+    return true;
+  }
+  if (typeof err !== "object" || err === null) {
+    return false;
+  }
+  const code = err.code;
+  if (typeof code === "string" && code.toLowerCase() === PROJECT_PERMISSION_DENIED_CODE) {
+    return true;
+  }
+  const message = err.message;
+  return typeof message === "string" && message.includes("PROJECT_PERMISSION_DENIED:");
+}
 function isPlatformHttpError(err) {
   return typeof err === "object" && err !== null && err[PLATFORM_ERROR_BRAND] === true;
 }
@@ -1899,6 +1930,9 @@ function createPlatformError(message, status, details, code) {
   if (status === 429 && typeof code === "string" && code.toLowerCase() === QUOTA_EXCEEDED_CODE) {
     return new PlatformQuotaError(message, status, details, code.toLowerCase());
   }
+  if (status === 403 && typeof code === "string" && code.toLowerCase() === PROJECT_PERMISSION_DENIED_CODE) {
+    return new PlatformPermissionError(message, details);
+  }
   return new PlatformHttpError(message, status, details);
 }
 function truncate(text) {
@@ -2149,6 +2183,22 @@ var BaseHttpClient = class {
   }
 };
 
+// ../../packages/platform-client/shared/project-access.types.ts
+var RANK = { none: 0, read: 1, write: 2, admin: 3 };
+function parseProjectRole(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const role = value.trim().toLowerCase();
+  return Object.prototype.hasOwnProperty.call(RANK, role) ? role : void 0;
+}
+function parseViewerRole(value) {
+  if (value === void 0 || value === null || value === "") {
+    return void 0;
+  }
+  return parseProjectRole(value) ?? "read";
+}
+
 // ../../packages/platform-client/project/types/attachment.types.ts
 var MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
 function transformAttachmentResponse(raw) {
@@ -2232,7 +2282,9 @@ function transformProjectResponse(raw) {
     createdAt: new Date(raw.created_at),
     updatedAt: new Date(raw.updated_at),
     deletedAt: raw.deleted_at ? new Date(raw.deleted_at) : void 0,
-    lastActivityAt: raw.last_activity_at ? new Date(raw.last_activity_at) : void 0
+    lastActivityAt: raw.last_activity_at ? new Date(raw.last_activity_at) : void 0,
+    viewerRole: parseViewerRole(raw.viewer_role),
+    viewerCanManageAccess: typeof raw.viewer_can_manage_access === "boolean" ? raw.viewer_can_manage_access : void 0
   };
 }
 
@@ -2254,7 +2306,8 @@ function transformSpecSessionResponse(raw) {
     archivedAt: raw.archived_at ? new Date(raw.archived_at) : void 0,
     createdAt: new Date(raw.created_at),
     updatedAt: new Date(raw.updated_at),
-    deletedAt: raw.deleted_at ? new Date(raw.deleted_at) : void 0
+    deletedAt: raw.deleted_at ? new Date(raw.deleted_at) : void 0,
+    viewerRole: parseViewerRole(raw.viewer_role)
   };
 }
 
@@ -2892,11 +2945,7 @@ var HttpSpecSessionClient = class {
     if (opts?.query) params.set("q", opts.query);
     if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
     if (opts?.offset !== void 0) params.set("offset", String(opts.offset));
-    const response = await this.httpClient.get(
-      `/project/v1/projects/${projectId}/sessions?${params.toString()}`,
-      jwtToken,
-      {}
-    );
+    const response = await this.httpClient.get(`/project/v1/projects/${projectId}/sessions?${params.toString()}`, jwtToken, {});
     return {
       sessions: response.sessions.map(transformSpecSessionResponse),
       total: response.total,
@@ -2904,13 +2953,14 @@ var HttpSpecSessionClient = class {
       offset: response.offset
     };
   }
-  async updateSpecSession(sessionId, updates, jwtToken) {
+  async updateSpecSession(sessionId, updates, jwtToken, options) {
     const body = {};
     if (updates.status !== void 0) body.status = updates.status;
     if (updates.messageCount !== void 0) body.message_count = updates.messageCount;
     if (updates.tokenCount !== void 0) body.token_count = updates.tokenCount;
     if (updates.context !== void 0) body.context = updates.context;
     if (updates.chatHistory !== void 0) body.chat_history = updates.chatHistory;
+    if (options?.originClientId) body.origin_client_id = options.originClientId;
     const raw = await this.httpClient.put(
       `/project/v1/sessions/${sessionId}`,
       body,
@@ -2919,8 +2969,10 @@ var HttpSpecSessionClient = class {
     );
     return transformSpecSessionResponse(raw);
   }
-  async appendSessionMessage(sessionId, message, jwtToken) {
-    const response = await this.httpClient.post(`/project/v1/sessions/${sessionId}/messages`, { message }, jwtToken, {});
+  async appendSessionMessage(sessionId, message, jwtToken, options) {
+    const body = { message };
+    if (options?.originClientId) body.origin_client_id = options.originClientId;
+    const response = await this.httpClient.post(`/project/v1/sessions/${sessionId}/messages`, body, jwtToken, {});
     return { messageCount: response.message_count };
   }
   async archiveSpecSession(sessionId, jwtToken) {
@@ -4095,6 +4147,9 @@ var deleteProjectTool = {
     try {
       await ctx.client.deleteProject(args.project_id);
     } catch (err) {
+      if (isProjectPermissionDeniedError(err)) {
+        throw err;
+      }
       const message = err instanceof Error ? err.message : String(err);
       return errorResult(`Failed to delete project ${args.project_id}: ${message}`);
     }
@@ -4435,7 +4490,8 @@ var getProjectTool = {
         description: project.description,
         status: project.status,
         created_at: project.createdAt,
-        updated_at: project.updatedAt
+        updated_at: project.updatedAt,
+        viewer_role: project.viewerRole
       },
       active_sessions: sessions.sessions.map((s) => ({
         id: s.id,
@@ -4739,7 +4795,9 @@ var listProjectsTool = {
         status: p.status,
         updated_at: p.updatedAt,
         // The list is ordered by this, newest first.
-        last_activity_at: p.lastActivityAt
+        last_activity_at: p.lastActivityAt,
+        // read | write | admin; absent from a platform without project roles.
+        viewer_role: p.viewerRole
       })),
       total: result.total,
       limit: result.limit,
@@ -7183,11 +7241,29 @@ function wrapToolHandler(tool, ctx) {
       if (err instanceof NeedsLoginError) {
         return errorResult(err.message);
       }
+      if (isProjectPermissionDeniedError(err)) {
+        return errorResult(`${tool.name} failed: ${permissionDeniedMessage(err)}`);
+      }
       const message = err instanceof Error ? err.message : String(err);
       return errorResult(`${tool.name} failed: ${message}`);
     }
   };
 }
+function permissionDeniedMessage(err) {
+  let required;
+  let viewer;
+  if (err instanceof PlatformPermissionError) {
+    required = err.requiredRole;
+    viewer = err.viewerRole;
+  } else if (err instanceof Error) {
+    const details = parseHttpErrorDetails(err.message);
+    required = details?.required_role;
+    viewer = details?.viewer_role;
+  }
+  const need = typeof required === "string" ? `the ${required} role` : "a higher role";
+  const have = typeof viewer === "string" ? `; you have ${viewer}` : "";
+  return `permission denied \u2014 this action needs ${need} on the project${have}. Ask a project admin for access.`;
+}
 function registerTool(server, tool, ctx) {
   server.registerTool(
     tool.name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myspec/mcp-server",
-  "version": "1.1.1-next.158",
+  "version": "1.1.1-next.160",
   "description": "MySpec MCP server — exposes MySpec platform projects, files and attachments to MCP-aware clients via OAuth-authenticated access tokens.",
   "type": "module",
   "repository": {