@backstage/plugin-mcp-actions-backend 0.1.5 → 0.1.6-next.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @backstage/plugin-mcp-actions-backend
 
+## 0.1.6-next.0
+
+### Patch Changes
+
+- 79ef471: Clarify error handling in readme and update handleError.ts to include all backstage/errors
+- Updated dependencies
+  - @backstage/backend-defaults@0.14.0-next.0
+  - @backstage/backend-plugin-api@1.5.1-next.0
+  - @backstage/plugin-catalog-node@1.20.1-next.0
+  - @backstage/catalog-client@1.12.1
+  - @backstage/errors@1.2.7
+  - @backstage/types@1.2.2
+
 ## 0.1.5
 
 ### Patch Changes

package/README.md

@@ -71,6 +71,31 @@ export const myPlugin = createBackendPlugin({
 });
 ```
 
+### Error Handling
+
+When errors are thrown from MCP actions, the backend will handle and surface error message for any error from `@backstage/errors`. Unknown errors will be handled by `@modelcontextprotocol/sdk`'s default error handling, which may result in a generic `500 Server Error` being returned. As a result, we recommend using errors from `@backstage/errors` when applicable.
+
+See https://backstage.io/docs/reference/errors/ for a full list of supported errors.
+
+When writing MCP tools, use the appropriate error from `@backstage/errors` when applicable:
+
+```ts
+action: async ({ input }) => {
+  // ... get current user and some resource
+
+  if (!resource) {
+    throw new NotFoundError(`Resource ${input.id} not found`);
+  }
+
+  // Check if the user has permissions to access/use the resource
+  if (!hasPermission(user, resource)) {
+    throw new NotAllowedError(
+      `user does not have sufficient permissions for ${resource}`,
+    );
+  }
+};
+```
+
 ### Authentication Configuration
 
 By default, the Backstage backend requires authentication for all requests.

package/dist/services/handleErrors.cjs.js

@@ -10,7 +10,8 @@ const knownErrors = /* @__PURE__ */ new Set([
   "ConflictError",
   "NotModifiedError",
   "NotImplementedError",
-  "ResponseError"
+  "ResponseError",
+  "ServiceUnavailableError"
 ]);
 function extractCause(err) {
   if ((err.name === "ResponseError" || err instanceof errors.ForwardedError) && errors.isError(err.cause)) {

package/dist/services/handleErrors.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"handleErrors.cjs.js","sources":["../../src/services/handleErrors.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  ErrorLike,\n  ForwardedError,\n  isError,\n  serializeError,\n} from '@backstage/errors';\n\nimport { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';\n\nconst knownErrors = new Set([\n  'InputError',\n  'AuthenticationError',\n  'NotAllowedError',\n  'NotFoundError',\n  'ConflictError',\n  'NotModifiedError',\n  'NotImplementedError',\n  'ResponseError',\n]);\n\n// Extracts the cause error, if the provided error is `ResponseError` or\n// `ForwardedError` with a cause.\nfunction extractCause(err: ErrorLike): ErrorLike {\n  if (\n    (err.name === 'ResponseError' || err instanceof ForwardedError) &&\n    isError(err.cause)\n  ) {\n    return err.cause;\n  }\n  return err;\n}\n\n/**\n * Takes a value expected to be an object, and returns a description of the\n * error to return to the MCP client, if the error is a known Backstage error.\n *\n * Re-throws the original error otherwise\n */\nfunction describeError(err: unknown): string {\n  if (err instanceof Error) {\n    const serialized = serializeError(err);\n\n    const { name, message } = extractCause(serialized);\n\n    if (knownErrors.has(name)) {\n      return `${name}: ${message}`;\n    }\n  }\n\n  throw err;\n}\n\ntype RequestResultType = ReturnType<\n  Parameters<McpServer['setRequestHandler']>[1]\n>;\n/**\n * Wraps a request function with an error handler that turns known Backstage\n * errors into user-friendly messages, instead of failing the request\n * generically with a 500.\n */\nexport async function handleErrors(\n  fn: () => RequestResultType | Promise<RequestResultType>,\n): Promise<RequestResultType> {\n  try {\n    return await fn();\n  } catch (err) {\n    // This will rethrow if the error is not a known Backstage error\n    const description = describeError(err);\n    return {\n      content: [{ type: 'text', text: description }],\n      isError: true,\n    };\n  }\n}\n"],"names":["ForwardedError","isError","serializeError"],"mappings":";;;;AAyBA,MAAM,WAAA,uBAAkB,GAAA,CAAI;AAAA,EAC1B,YAAA;AAAA,EACA,qBAAA;AAAA,EACA,iBAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,kBAAA;AAAA,EACA,qBAAA;AAAA,EACA;AACF,CAAC,CAAA;AAID,SAAS,aAAa,GAAA,EAA2B;AAC/C,EAAA,IAAA,CACG,GAAA,CAAI,SAAS,eAAA,IAAmB,GAAA,YAAeA,0BAChDC,cAAA,CAAQ,GAAA,CAAI,KAAK,CAAA,EACjB;AACA,IAAA,OAAO,GAAA,CAAI,KAAA;AAAA,EACb;AACA,EAAA,OAAO,GAAA;AACT;AAQA,SAAS,cAAc,GAAA,EAAsB;AAC3C,EAAA,IAAI,eAAe,KAAA,EAAO;AACxB,IAAA,MAAM,UAAA,GAAaC,sBAAe,GAAG,CAAA;AAErC,IAAA,MAAM,EAAE,IAAA,EAAM,OAAA,EAAQ,GAAI,aAAa,UAAU,CAAA;AAEjD,IAAA,IAAI,WAAA,CAAY,GAAA,CAAI,IAAI,CAAA,EAAG;AACzB,MAAA,OAAO,CAAA,EAAG,IAAI,CAAA,EAAA,EAAK,OAAO,CAAA,CAAA;AAAA,IAC5B;AAAA,EACF;AAEA,EAAA,MAAM,GAAA;AACR;AAUA,eAAsB,aACpB,EAAA,EAC4B;AAC5B,EAAA,IAAI;AACF,IAAA,OAAO,MAAM,EAAA,EAAG;AAAA,EAClB,SAAS,GAAA,EAAK;AAEZ,IAAA,MAAM,WAAA,GAAc,cAAc,GAAG,CAAA;AACrC,IAAA,OAAO;AAAA,MACL,SAAS,CAAC,EAAE,MAAM,MAAA,EAAQ,IAAA,EAAM,aAAa,CAAA;AAAA,MAC7C,OAAA,EAAS;AAAA,KACX;AAAA,EACF;AACF;;;;"}
+{"version":3,"file":"handleErrors.cjs.js","sources":["../../src/services/handleErrors.ts"],"sourcesContent":["/*\n * Copyright 2025 The Backstage Authors\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  ErrorLike,\n  ForwardedError,\n  isError,\n  serializeError,\n} from '@backstage/errors';\n\nimport { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js';\n\nconst knownErrors = new Set([\n  'InputError',\n  'AuthenticationError',\n  'NotAllowedError',\n  'NotFoundError',\n  'ConflictError',\n  'NotModifiedError',\n  'NotImplementedError',\n  'ResponseError',\n  'ServiceUnavailableError',\n]);\n\n// Extracts the cause error, if the provided error is `ResponseError` or\n// `ForwardedError` with a cause.\nfunction extractCause(err: ErrorLike): ErrorLike {\n  if (\n    (err.name === 'ResponseError' || err instanceof ForwardedError) &&\n    isError(err.cause)\n  ) {\n    return err.cause;\n  }\n  return err;\n}\n\n/**\n * Takes a value expected to be an object, and returns a description of the\n * error to return to the MCP client, if the error is a known Backstage error.\n *\n * Re-throws the original error otherwise\n */\nfunction describeError(err: unknown): string {\n  if (err instanceof Error) {\n    const serialized = serializeError(err);\n\n    const { name, message } = extractCause(serialized);\n\n    if (knownErrors.has(name)) {\n      return `${name}: ${message}`;\n    }\n  }\n\n  throw err;\n}\n\ntype RequestResultType = ReturnType<\n  Parameters<McpServer['setRequestHandler']>[1]\n>;\n/**\n * Wraps a request function with an error handler that turns known Backstage\n * errors into user-friendly messages, instead of failing the request\n * generically with a 500.\n */\nexport async function handleErrors(\n  fn: () => RequestResultType | Promise<RequestResultType>,\n): Promise<RequestResultType> {\n  try {\n    return await fn();\n  } catch (err) {\n    // This will rethrow if the error is not a known Backstage error\n    const description = describeError(err);\n    return {\n      content: [{ type: 'text', text: description }],\n      isError: true,\n    };\n  }\n}\n"],"names":["ForwardedError","isError","serializeError"],"mappings":";;;;AAyBA,MAAM,WAAA,uBAAkB,GAAA,CAAI;AAAA,EAC1B,YAAA;AAAA,EACA,qBAAA;AAAA,EACA,iBAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,kBAAA;AAAA,EACA,qBAAA;AAAA,EACA,eAAA;AAAA,EACA;AACF,CAAC,CAAA;AAID,SAAS,aAAa,GAAA,EAA2B;AAC/C,EAAA,IAAA,CACG,GAAA,CAAI,SAAS,eAAA,IAAmB,GAAA,YAAeA,0BAChDC,cAAA,CAAQ,GAAA,CAAI,KAAK,CAAA,EACjB;AACA,IAAA,OAAO,GAAA,CAAI,KAAA;AAAA,EACb;AACA,EAAA,OAAO,GAAA;AACT;AAQA,SAAS,cAAc,GAAA,EAAsB;AAC3C,EAAA,IAAI,eAAe,KAAA,EAAO;AACxB,IAAA,MAAM,UAAA,GAAaC,sBAAe,GAAG,CAAA;AAErC,IAAA,MAAM,EAAE,IAAA,EAAM,OAAA,EAAQ,GAAI,aAAa,UAAU,CAAA;AAEjD,IAAA,IAAI,WAAA,CAAY,GAAA,CAAI,IAAI,CAAA,EAAG;AACzB,MAAA,OAAO,CAAA,EAAG,IAAI,CAAA,EAAA,EAAK,OAAO,CAAA,CAAA;AAAA,IAC5B;AAAA,EACF;AAEA,EAAA,MAAM,GAAA;AACR;AAUA,eAAsB,aACpB,EAAA,EAC4B;AAC5B,EAAA,IAAI;AACF,IAAA,OAAO,MAAM,EAAA,EAAG;AAAA,EAClB,SAAS,GAAA,EAAK;AAEZ,IAAA,MAAM,WAAA,GAAc,cAAc,GAAG,CAAA;AACrC,IAAA,OAAO;AAAA,MACL,SAAS,CAAC,EAAE,MAAM,MAAA,EAAQ,IAAA,EAAM,aAAa,CAAA;AAAA,MAC7C,OAAA,EAAS;AAAA,KACX;AAAA,EACF;AACF;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-mcp-actions-backend",
-  "version": "0.1.5",
+  "version": "0.1.6-next.0",
   "backstage": {
     "role": "backend-plugin",
     "pluginId": "mcp-actions",
@@ -37,20 +37,20 @@
     "test": "backstage-cli package test"
   },
   "dependencies": {
-    "@backstage/backend-defaults": "^0.13.1",
-    "@backstage/backend-plugin-api": "^1.5.0",
-    "@backstage/catalog-client": "^1.12.1",
-    "@backstage/errors": "^1.2.7",
-    "@backstage/plugin-catalog-node": "^1.20.0",
-    "@backstage/types": "^1.2.2",
+    "@backstage/backend-defaults": "0.14.0-next.0",
+    "@backstage/backend-plugin-api": "1.5.1-next.0",
+    "@backstage/catalog-client": "1.12.1",
+    "@backstage/errors": "1.2.7",
+    "@backstage/plugin-catalog-node": "1.20.1-next.0",
+    "@backstage/types": "1.2.2",
     "@modelcontextprotocol/sdk": "^1.12.3",
     "express": "^4.17.1",
     "express-promise-router": "^4.1.0",
     "zod": "^3.22.4"
   },
   "devDependencies": {
-    "@backstage/backend-test-utils": "^1.10.0",
-    "@backstage/cli": "^0.34.5",
+    "@backstage/backend-test-utils": "1.10.1-next.0",
+    "@backstage/cli": "0.34.6-next.0",
     "@types/express": "^4.17.6"
   },
   "typesVersions": {