fix: refactor MCP tools to use class-based initialization [DX-579] (#263)

* Refactor MCP tools to use ContentfulMcpTools for initialization and environment configuration. Removed dotenv and related environment validation from config files. Updated tool registration to utilize new client configuration methods. Enhanced error handling across various tools for better reliability.

* chore: update package lock

* chore: update env file local mcp

* chore: refactor tests

* chore: fix linter

Author: chasepoirier

package-lock.json

@@ -44,7 +44,8 @@
   },
   "dependencies": {
     "@contentful/mcp-tools": "0.1.1",
-    "@modelcontextprotocol/sdk": "^1.17.0"
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "dotenv": "^17.2.3"
   },
   "devDependencies": {
     "@types/node": "^22.16.5",

packages/mcp-server/package.json

@@ -1,5 +1,5 @@
-import dotenv from 'dotenv';
 import { z } from 'zod';
+import dotenv from 'dotenv';
 dotenv.config();
 
 const EnvSchema = z.object({
@@ -11,7 +11,6 @@ const EnvSchema = z.object({
     .optional()
     .default('api.contentful.com')
     .describe('Contentful API host'),
-
   APP_ID: z.string().optional().describe('Contentful App ID'),
   SPACE_ID: z.string().optional().describe('Contentful Space ID'),
   ENVIRONMENT_ID: z

packages/mcp-tools/src/config/env.ts renamed to packages/mcp-server/src/config/env.ts

@@ -1,21 +1,23 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { registerAllTools } from './register.js';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import {
-  aiActionTools,
-  assetTools,
-  contentTypeTools,
-  contextTools,
-  editorInterfaceTools,
-  entryTools,
-  environmentTools,
-  jobTools,
-  localeTools,
-  orgTools,
-  spaceTools,
-  tagTools,
-  taxonomyTools,
-} from '@contentful/mcp-tools';
+import { ContentfulMcpTools } from '@contentful/mcp-tools';
+import { env } from '../config/env.js';
+
+// Mock the env module
+vi.mock('../config/env.js', () => ({
+  env: {
+    success: true,
+    data: {
+      CONTENTFUL_MANAGEMENT_ACCESS_TOKEN: 'test-token',
+      CONTENTFUL_HOST: 'api.contentful.com',
+      SPACE_ID: 'test-space-id',
+      ENVIRONMENT_ID: 'master',
+      ORGANIZATION_ID: 'test-org-id',
+      APP_ID: 'test-app-id',
+    },
+  },
+}));
 
 describe('registerAllTools', () => {
   let mockServer: McpServer;
@@ -38,20 +40,30 @@ describe('registerAllTools', () => {
   it('should register all standard tool collections', () => {
     registerAllTools(mockServer);
 
+    // Create a ContentfulMcpTools instance to count tools
+    const mcpTools = new ContentfulMcpTools({
+      accessToken: env.data!.CONTENTFUL_MANAGEMENT_ACCESS_TOKEN,
+      host: env.data!.CONTENTFUL_HOST,
+      spaceId: env.data!.SPACE_ID,
+      environmentId: env.data!.ENVIRONMENT_ID,
+      organizationId: env.data!.ORGANIZATION_ID,
+      appId: env.data!.APP_ID,
+    });
+
     // Count expected tool registrations from standard collections
     const standardToolCollections = [
-      aiActionTools,
-      assetTools,
-      contentTypeTools,
-      contextTools,
-      editorInterfaceTools,
-      entryTools,
-      environmentTools,
-      localeTools,
-      orgTools,
-      spaceTools,
-      tagTools,
-      taxonomyTools,
+      mcpTools.getAiActionTools(),
+      mcpTools.getAssetTools(),
+      mcpTools.getContentTypeTools(),
+      mcpTools.getContextTools(),
+      mcpTools.getEditorInterfaceTools(),
+      mcpTools.getEntryTools(),
+      mcpTools.getEnvironmentTools(),
+      mcpTools.getLocaleTools(),
+      mcpTools.getOrgTools(),
+      mcpTools.getSpaceTools(),
+      mcpTools.getTagTools(),
+      mcpTools.getTaxonomyTools(),
     ];
 
     const expectedStandardToolCount = standardToolCollections.reduce(
@@ -90,7 +102,15 @@ describe('registerAllTools', () => {
   it('should register spaceToSpaceMigrationHandler with workflow tools', () => {
     registerAllTools(mockServer);
 
-    const handlerConfig = jobTools.spaceToSpaceMigrationHandler;
+    const mcpTools = new ContentfulMcpTools({
+      accessToken: env.data!.CONTENTFUL_MANAGEMENT_ACCESS_TOKEN,
+      host: env.data!.CONTENTFUL_HOST,
+      spaceId: env.data!.SPACE_ID,
+      environmentId: env.data!.ENVIRONMENT_ID,
+      organizationId: env.data!.ORGANIZATION_ID,
+      appId: env.data!.APP_ID,
+    });
+    const handlerConfig = mcpTools.getJobTools().spaceToSpaceMigrationHandler;
 
     // Find the call for the migration handler
     const handlerCall = registerToolSpy.mock.calls.find(

packages/mcp-server/src/tools/register.test.ts

@@ -1,19 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import {
-  aiActionTools,
-  assetTools,
-  contentTypeTools,
-  contextTools,
-  editorInterfaceTools,
-  entryTools,
-  environmentTools,
-  jobTools,
-  localeTools,
-  orgTools,
-  spaceTools,
-  tagTools,
-  taxonomyTools,
-} from '@contentful/mcp-tools';
+import { ContentfulMcpTools } from '@contentful/mcp-tools';
+import { env } from '../config/env.js';
 
 /**
  * Registers all Contentful MCP tools with the server.
@@ -24,6 +11,34 @@ import {
  * - The migration handler controls their enable/disable state
  */
 export function registerAllTools(server: McpServer): void {
+  if (!env.success || !env.data) {
+    throw new Error('Environment variables are not properly configured');
+  }
+
+  // Initialize tools with configuration from environment variables
+  const tools = new ContentfulMcpTools({
+    accessToken: env.data.CONTENTFUL_MANAGEMENT_ACCESS_TOKEN,
+    host: env.data.CONTENTFUL_HOST,
+    spaceId: env.data.SPACE_ID,
+    environmentId: env.data.ENVIRONMENT_ID,
+    organizationId: env.data.ORGANIZATION_ID,
+    appId: env.data.APP_ID,
+  });
+
+  // Get tool collections
+  const aiActionTools = tools.getAiActionTools();
+  const assetTools = tools.getAssetTools();
+  const contentTypeTools = tools.getContentTypeTools();
+  const contextTools = tools.getContextTools();
+  const editorInterfaceTools = tools.getEditorInterfaceTools();
+  const entryTools = tools.getEntryTools();
+  const environmentTools = tools.getEnvironmentTools();
+  const localeTools = tools.getLocaleTools();
+  const orgTools = tools.getOrgTools();
+  const spaceTools = tools.getSpaceTools();
+  const tagTools = tools.getTagTools();
+  const taxonomyTools = tools.getTaxonomyTools();
+
   // Combine standard tool collections
   const allToolCollections = [
     aiActionTools,
@@ -54,9 +69,7 @@ export function registerAllTools(server: McpServer): void {
       );
     });
   });
-
-  // Handle migration tools specially
-  // These tools should be disabled by default and controlled by the handler
+  const jobTools = tools.getJobTools();
   const workflowToolsToDisable = [
     'spaceToSpaceParamCollection',
     'exportSpace',

packages/mcp-server/src/tools/register.ts

@@ -44,7 +44,6 @@
     "contentful-export": "^7.21.78",
     "contentful-import": "^9.4.111",
     "contentful-management": "^11.54.3",
-    "dotenv": "^16.4.7",
     "fast-xml-parser": "^5.2.5",
     "outdent": "^0.8.0",
     "@contentful/rich-text-types": "^16.8.5",

packages/mcp-tools/package.json

@@ -0,0 +1,135 @@
+import type { ContentfulConfig } from './config/types.js';
+import { createAiActionTools } from './tools/ai-actions/register.js';
+import { createAssetTools } from './tools/assets/register.js';
+import { createContentTypeTools } from './tools/content-types/register.js';
+import { createContextTools } from './tools/context/register.js';
+import { createEditorInterfaceTools } from './tools/editor-interfaces/register.js';
+import { createEntryTools } from './tools/entries/register.js';
+import { createEnvironmentTools } from './tools/environments/register.js';
+import { createLocaleTools } from './tools/locales/register.js';
+import { createOrgTools } from './tools/orgs/register.js';
+import { createSpaceTools } from './tools/spaces/register.js';
+import { createTagTools } from './tools/tags/register.js';
+import { createTaxonomyTools } from './tools/taxonomies/register.js';
+import { createJobTools } from './tools/jobs/space-to-space-migration/register.js';
+
+/**
+ * Main class for Contentful MCP Tools
+ * 
+ * This class encapsulates all Contentful MCP tools and provides methods
+ * to access tool collections. Configuration is passed to the constructor
+ * and can be updated at runtime.
+ */
+export class ContentfulMcpTools {
+  private config: ContentfulConfig;
+
+  constructor(config: ContentfulConfig) {
+    // Set defaults
+    this.config = {
+      ...config,
+      host: config.host ?? 'api.contentful.com',
+      environmentId: config.environmentId ?? 'master',
+    };
+  }
+
+  /**
+   * Update the configuration after initialization
+   * 
+   * @param updates - Partial configuration to merge with existing config
+   */
+  updateConfig(updates: Partial<ContentfulConfig>): void {
+    this.config = { ...this.config, ...updates };
+  }
+
+  /**
+   * Get AI action tools
+   */
+  getAiActionTools() {
+    return createAiActionTools(this.config);
+  }
+
+  /**
+   * Get asset tools
+   */
+  getAssetTools() {
+    return createAssetTools(this.config);
+  }
+
+  /**
+   * Get content type tools
+   */
+  getContentTypeTools() {
+    return createContentTypeTools(this.config);
+  }
+
+  /**
+   * Get context tools
+   */
+  getContextTools() {
+    return createContextTools(this.config);
+  }
+
+  /**
+   * Get editor interface tools
+   */
+  getEditorInterfaceTools() {
+    return createEditorInterfaceTools(this.config);
+  }
+
+  /**
+   * Get entry tools
+   */
+  getEntryTools() {
+    return createEntryTools(this.config);
+  }
+
+  /**
+   * Get environment tools
+   */
+  getEnvironmentTools() {
+    return createEnvironmentTools(this.config);
+  }
+
+  /**
+   * Get locale tools
+   */
+  getLocaleTools() {
+    return createLocaleTools(this.config);
+  }
+
+  /**
+   * Get organization tools
+   */
+  getOrgTools() {
+    return createOrgTools(this.config);
+  }
+
+  /**
+   * Get space tools
+   */
+  getSpaceTools() {
+    return createSpaceTools(this.config);
+  }
+
+  /**
+   * Get tag tools
+   */
+  getTagTools() {
+    return createTagTools(this.config);
+  }
+
+  /**
+   * Get taxonomy tools
+   */
+  getTaxonomyTools() {
+    return createTaxonomyTools(this.config);
+  }
+
+  /**
+   * Get job tools (space-to-space migration)
+   */
+  getJobTools() {
+    return createJobTools(this.config);
+  }
+}
+

packages/mcp-tools/src/ContentfulMcpTools.ts

@@ -0,0 +1,17 @@
+/**
+ * Configuration for Contentful MCP Tools
+ */
+export interface ContentfulConfig {
+  /** Contentful CMA (Content Management API) access token */
+  accessToken: string;
+  /** Contentful API host (default: 'api.contentful.com') */
+  host?: string;
+  /** Contentful Space ID */
+  spaceId?: string;
+  /** Contentful Environment ID (default: 'master') */
+  environmentId?: string;
+  /** Contentful Organization ID */
+  organizationId?: string;
+  /** Contentful App ID */
+  appId?: string;
+}