@sofianedjerbi/knowledge-tree-mcp/docs/backend/patterns/common-development-patterns-anti-patterns.json

MCP server for hierarchical project knowledge management

{
  "title": "Common Development Patterns and Anti-Patterns",
  "priority": "COMMON",
  "problem": "Developers working on Knowledge Tree MCP need to understand common patterns used throughout the codebase and anti-patterns to avoid for consistency and maintainability.",
  "solution": "## Common Patterns to Follow\n\n### 1. Tool Handler Pattern\n```typescript\nexport const myToolHandler: ToolHandler = async (\n  args: MyToolArgs,\n  context: ServerContext\n): Promise<MCPResponse> => {\n  try {\n    // 1. Validate arguments\n    if (!args.requiredField) {\n      throw new Error('Required field is missing');\n    }\n    \n    // 2. Perform operations with context\n    const result = await performOperation(args, context);\n    \n    // 3. Return formatted MCP response\n    return {\n      content: [{\n        type: \"text\",\n        text: formatResult(result)\n      }]\n    };\n  } catch (error) {\n    // 4. Handle errors consistently\n    throw new Error(`Tool failed: ${error.message}`);\n  }\n};\n```\n\n### 2. File Operations Pattern\n```typescript\n// Always use utility functions\nimport { \n  ensureDirectory, \n  fileExists, \n  readKnowledgeEntry, \n  writeKnowledgeEntry \n} from '../utils/fileSystem.js';\n\n// Check existence before operations\nif (await fileExists(fullPath)) {\n  const existing = await readKnowledgeEntry(fullPath);\n  // Process existing entry\n}\n\n// Ensure directory exists before writing\nawait ensureDirectory(dirname(fullPath));\nawait writeKnowledgeEntry(fullPath, entry);\n```\n\n### 3. Error Handling Pattern\n```typescript\n// Specific error types with context\nthrow new Error(`Failed to parse entry: ${filename} - ${parseError.message}`);\n\n// Catch and re-throw with context\ntry {\n  await riskyOperation();\n} catch (error) {\n  throw new Error(`Operation failed for ${resourceId}: ${error.message}`);\n}\n```\n\n### 4. Path Handling Pattern\n```typescript\nimport { join, dirname, basename } from 'path';\n\n// Always use path.join for cross-platform compatibility\nconst fullPath = join(context.docsPath, relativePath);\n\n// Normalize extensions\nconst jsonPath = ensureJsonExtension(userPath);\n\n// Extract components safely\nconst parentDir = dirname(fullPath);\nconst filename = basename(fullPath, '.json');\n```\n\n## Anti-Patterns to Avoid\n\n### 1. Direct File System Access\n```typescript\n// ❌ BAD - Direct fs usage\nimport { readFileSync } from 'fs';\nconst content = readFileSync('/path/to/file.json', 'utf-8');\n\n// ✅ GOOD - Use utilities\nimport { readKnowledgeEntry } from '../utils/fileSystem.js';\nconst entry = await readKnowledgeEntry(fullPath);\n```\n\n### 2. Inconsistent Error Messages\n```typescript\n// ❌ BAD - Generic errors\nthrow new Error('Something went wrong');\nthrow new Error('Invalid input');\n\n// ✅ GOOD - Specific context\nthrow new Error(`Knowledge entry not found: ${path}`);\nthrow new Error(`Invalid priority level: ${priority}. Must be CRITICAL, REQUIRED, COMMON, or EDGE-CASE`);\n```\n\n### 3. Missing Async/Await\n```typescript\n// ❌ BAD - Promise chains\nreturn fileExists(path)\n  .then(exists => {\n    if (exists) {\n      return readKnowledgeEntry(path);\n    }\n    throw new Error('Not found');\n  });\n\n// ✅ GOOD - Async/await\nconst exists = await fileExists(path);\nif (!exists) {\n  throw new Error(`Entry not found: ${path}`);\n}\nreturn await readKnowledgeEntry(path);\n```\n\n### 4. Hardcoded Paths\n```typescript\n// ❌ BAD - Hardcoded\nconst docsPath = './docs';\nconst configPath = './docs/.knowledge-tree.json';\n\n// ✅ GOOD - Use context\nconst fullPath = join(context.docsPath, relativePath);\nconst configPath = join(context.docsPath, CONFIG_FILENAME);\n```\n\n## TypeScript Patterns\n\n### 1. Proper Type Guards\n```typescript\nfunction isKnowledgeEntry(obj: any): obj is KnowledgeEntry {\n  return obj && \n    typeof obj.priority === 'string' &&\n    typeof obj.problem === 'string' &&\n    typeof obj.solution === 'string';\n}\n```\n\n### 2. Union Types for Enums\n```typescript\n// Define allowed values\ntype Priority = \"CRITICAL\" | \"REQUIRED\" | \"COMMON\" | \"EDGE-CASE\";\ntype RelationshipType = \"related\" | \"supersedes\" | \"superseded_by\" | \"conflicts_with\";\n\n// Use in interfaces\ninterface KnowledgeEntry {\n  priority: Priority;\n  // ...\n}\n```\n\n### 3. Optional Parameters with Defaults\n```typescript\ninterface SearchArgs {\n  query?: string;\n  priority?: Priority[];\n  limit?: number;\n}\n\n// Handle defaults in function\nfunction search(args: SearchArgs = {}) {\n  const {\n    query = '',\n    priority = ['CRITICAL', 'REQUIRED', 'COMMON', 'EDGE-CASE'],\n    limit = 50\n  } = args;\n}\n```",
  "tags": [
    "patterns",
    "anti-patterns",
    "development",
    "best-practices",
    "typescript"
  ],
  "context": "The Knowledge Tree MCP codebase follows specific patterns for tool handlers, error handling, file operations, and TypeScript usage. Following these patterns ensures code consistency and reduces bugs.",
  "examples": [
    {
      "title": "Complete Tool Implementation",
      "code": "interface ValidateArgs {\n  path?: string;\n  fix?: boolean;\n}\n\nexport const validateKnowledgeHandler: ToolHandler = async (\n  args: ValidateArgs,\n  context: ServerContext\n): Promise<MCPResponse> => {\n  const { path, fix = false } = args;\n  \n  try {\n    let results: ValidationResult[];\n    \n    if (path) {\n      // Validate specific entry\n      const fullPath = join(context.docsPath, ensureJsonExtension(path));\n      if (!await fileExists(fullPath)) {\n        throw new Error(`Entry not found: ${path}`);\n      }\n      results = [await validateSingleEntry(fullPath, fix)];\n    } else {\n      // Validate all entries\n      results = await validateAllEntries(context.docsPath, fix);\n    }\n    \n    const summary = summarizeValidation(results);\n    \n    return {\n      content: [{\n        type: \"text\",\n        text: formatValidationResults(summary, results)\n      }]\n    };\n  } catch (error) {\n    throw new Error(`Validation failed: ${error.message}`);\n  }\n};",
      "language": "typescript"
    }
  ],
  "created_at": "2025-08-03T16:54:53.660Z",
  "updated_at": "2025-08-04T11:15:05.796Z",
  "related_to": [
    {
      "path": "backend/patterns/typescript-best-practices-patterns.json",
      "relationship": "related",
      "description": "TypeScript patterns complement the general development patterns for type-safe code"
    }
  ]
}