refactor: improve error handling with centralized error classes and handlers (#109)

## Summary
- Add new centralized error handling system with custom error classes
(`InvalidArgumentError`, `NotFoundError`)
- Replace generic `Error` throws with specific error types for better
categorization
- Centralize error handling logic in `handleToolError` function in
`src/server/errors.ts`
- Replace inappropriate `NeonDbError` usage with proper custom errors
- Improve error messages for better user experience
- Clean up unused imports and improve code organization

## Test plan
- [x] All existing functionality should work as before
- [x] Error messages should be more specific and helpful
- [x] Linting and type checking passes
- [x] No breaking changes to existing API

🤖 Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: Shridhad

src/server/errors.ts

@@ -0,0 +1,78 @@
+import { isAxiosError } from 'axios';
+import { NeonDbError } from '@neondatabase/serverless';
+import { logger } from '../utils/logger.js';
+import { captureException } from '@sentry/node';
+
+export class InvalidArgumentError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidArgumentError';
+  }
+}
+
+export class NotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+
+export function isClientError(
+  error: unknown,
+): error is InvalidArgumentError | NotFoundError {
+  return (
+    error instanceof InvalidArgumentError || error instanceof NotFoundError
+  );
+}
+
+export function errorResponse(error: unknown) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: 'text' as const,
+        text:
+          error instanceof Error
+            ? `${error.name}: ${error.message}`
+            : 'Unknown error',
+      },
+    ],
+  };
+}
+
+export function handleToolError(
+  error: unknown,
+  properties: Record<string, string>,
+) {
+  if (error instanceof NeonDbError || isClientError(error)) {
+    return errorResponse(error);
+  } else if (
+    isAxiosError(error) &&
+    error.response?.status &&
+    error.response?.status < 500
+  ) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text' as const,
+          text: error.response.data.message,
+        },
+        {
+          type: 'text' as const,
+          text: `[${error.response.statusText}] ${error.message}`,
+        },
+      ],
+    };
+  } else {
+    logger.error('Tool call error:', {
+      error:
+        error instanceof Error
+          ? `${error.name}: ${error.message}`
+          : 'Unknown error',
+      properties,
+    });
+    captureException(error, { extra: properties });
+    return errorResponse(error);
+  }
+}

src/server/index.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { isAxiosError } from 'axios';
 import { NEON_RESOURCES } from '../resources.js';
 import {
   NEON_HANDLERS,
@@ -11,12 +10,11 @@ import {
 import { logger } from '../utils/logger.js';
 import { createNeonClient, getPackageJson } from './api.js';
 import { track } from '../analytics/analytics.js';
-import { captureException, setHttpStatus, startSpan } from '@sentry/node';
+import { captureException, startSpan } from '@sentry/node';
 import { ServerContext } from '../types/context.js';
 import { setSentryTags } from '../sentry/utils.js';
 import { ToolHandlerExtraParams } from '../tools/types.js';
-import { handleNeonDbError } from '../tools/utils.js';
-import { NeonDbError } from '@neondatabase/serverless';
+import { handleToolError } from './errors.js';
 
 export const createMcpServer = (context: ServerContext) => {
   const server = new McpServer(
@@ -75,36 +73,7 @@ export const createMcpServer = (context: ServerContext) => {
               span.setStatus({
                 code: 2,
               });
-              if (error instanceof NeonDbError) {
-                return handleNeonDbError(error);
-              } else {
-                if (
-                  isAxiosError(error) &&
-                  error.response?.status &&
-                  error.response?.status < 500
-                ) {
-                  setHttpStatus(span, error.response.status);
-                  return {
-                    isError: true,
-                    content: [
-                      {
-                        type: 'text',
-                        text: error.response?.data.message || error.message,
-                      },
-                    ],
-                  };
-                }
-
-                logger.error('Tool call error:', {
-                  error:
-                    error instanceof Error ? error.message : 'Unknown error',
-                  properties,
-                });
-                captureException(error, {
-                  extra: properties,
-                });
-                throw error;
-              }
+              return handleToolError(error, properties);
             }
           },
         );

src/tools/tools.ts

@@ -6,8 +6,9 @@ import {
   Organization,
   ProjectCreateRequest,
 } from '@neondatabase/api-client';
-import { neon, NeonDbError } from '@neondatabase/serverless';
+import { neon } from '@neondatabase/serverless';
 import crypto from 'crypto';
+import { InvalidArgumentError, NotFoundError } from '../server/errors.js';
 
 import { describeTable, formatTableDescription } from '../describeUtils.js';
 import { handleProvisionNeonAuth } from './handlers/neon-auth.js';
@@ -331,7 +332,9 @@ async function handleGetConnectionString(
         if (projects.length === 1) {
           projectId = projects[0].id;
         } else {
-          throw new Error('No projects found in your account');
+          throw new NotFoundError(
+            'Please provide a project ID or ensure you have only one project in your account.',
+          );
         }
       }
 
@@ -345,7 +348,9 @@ async function handleGetConnectionString(
         if (defaultBranch) {
           branchId = defaultBranch.id;
         } else {
-          throw new Error('No default branch found in your project');
+          throw new NotFoundError(
+            'No default branch found in this project. Please provide a branch ID.',
+          );
         }
       }
 
@@ -655,7 +660,7 @@ async function handleQueryTuning(
     const tableNames = extractTableNamesFromPlan(executionPlan);
 
     if (tableNames.length === 0) {
-      throw new Error(
+      throw new NotFoundError(
         'No tables found in execution plan. Cannot proceed with optimization.',
       );
     }
@@ -1000,7 +1005,7 @@ async function handleListSlowQueries(
   const extensionExists = extensionCheck[0]?.extension_exists;
 
   if (!extensionExists) {
-    throw new NeonDbError(
+    throw new NotFoundError(
       `pg_stat_statements extension is not installed on the database. Please install it using the following command: CREATE EXTENSION pg_stat_statements;`,
     );
   }
@@ -1084,8 +1089,8 @@ async function handleListBranchComputes(
     if (projects.length === 1) {
       projectId = projects[0].id;
     } else {
-      throw new Error(
-        'Please provide a project ID or ensure you have only one project.',
+      throw new InvalidArgumentError(
+        'Please provide a project ID or ensure you have only one project in your account.',
       );
     }
   }

src/tools/utils.ts

@@ -1,7 +1,7 @@
 import { NEON_DEFAULT_DATABASE_NAME } from '../constants.js';
 import { Api, Organization } from '@neondatabase/api-client';
 import { ToolHandlerExtraParams } from './types.js';
-import { NeonDbError } from '@neondatabase/serverless';
+import { NotFoundError } from '../server/errors.js';
 
 export const splitSqlStatements = (sql: string) => {
   return sql.split(';').filter(Boolean);
@@ -125,7 +125,7 @@ export async function getDefaultDatabase(
   );
   const databases = data.databases;
   if (databases.length === 0) {
-    throw new Error('No databases found in your project branch');
+    throw new NotFoundError('No databases found in your project branch');
   }
 
   if (databaseName) {
@@ -177,7 +177,7 @@ export async function getOrgByOrgIdOrDefault(
   );
 
   if (consoleOrganizations.length === 0) {
-    throw new Error('No organizations found for this user');
+    throw new NotFoundError('No organizations found for this user');
   }
 
   if (consoleOrganizations.length === 1) {
@@ -186,7 +186,7 @@ export async function getOrgByOrgIdOrDefault(
     const orgList = consoleOrganizations
       .map((org) => `- ${org.name} (ID: ${org.id})`)
       .join('\n');
-    throw new Error(
+    throw new NotFoundError(
       `Multiple organizations found. Please specify the org_id parameter with one of the following organization IDs:\n${orgList}`,
     );
   }
@@ -206,13 +206,3 @@ export function filterOrganizations(
       org.id.toLowerCase().includes(searchLower),
   );
 }
-
-export function handleNeonDbError(error: NeonDbError) {
-  return Promise.resolve({
-    isError: true,
-    content: [
-      { type: 'text' as const, text: error.message },
-      { type: 'text' as const, text: JSON.stringify(error, null, 2) },
-    ],
-  });
-}