@sofianedjerbi/knowledge-tree-mcp/docs/backend/troubleshooting/knowledge-tree-mcp-edge-cases.json

MCP server for hierarchical project knowledge management

{
  "title": "Knowledge Tree MCP Edge Cases and Error Scenarios",
  "priority": "COMMON",
  "problem": "Knowledge Tree MCP can encounter various edge cases and error scenarios that developers need to handle gracefully to ensure system reliability and good user experience.",
  "solution": "## File System Edge Cases\n\n### Non-Existent Directory Paths\n```typescript\n// Edge case: User provides path to non-existent directory\nconst userPath = \"non-existent/deep/nested/path/entry.json\";\n\n// Handling:\ntry {\n  await ensureDirectory(dirname(fullPath));\n  await writeKnowledgeEntry(fullPath, entry);\n} catch (error) {\n  if (error.code === 'EACCES') {\n    throw new Error(`Permission denied creating directory: ${dirname(fullPath)}`);\n  }\n  throw new Error(`Failed to create entry: ${error.message}`);\n}\n```\n\n### Corrupted JSON Files\n```typescript\n// Edge case: JSON file exists but is corrupted\ntry {\n  const content = await readFile(filePath, 'utf-8');\n  const entry = JSON.parse(content);\n  return entry;\n} catch (error) {\n  if (error instanceof SyntaxError) {\n    throw new Error(`Corrupted knowledge entry: ${filePath} - ${error.message}`);\n  }\n  throw error;\n}\n```\n\n### Permission Issues\n```typescript\ntry {\n  await writeFile(filePath, JSON.stringify(entry, null, 2));\n} catch (error) {\n  if (error.code === 'EACCES') {\n    throw new Error(`Permission denied writing to: ${filePath}`);\n  }\n  if (error.code === 'ENOSPC') {\n    throw new Error(`Insufficient disk space for: ${filePath}`);\n  }\n  throw error;\n}\n```\n\n## Data Validation Edge Cases\n\n### Missing Required Fields\n```typescript\nfunction validateKnowledgeEntry(entry: any): KnowledgeEntry {\n  const required = ['priority', 'problem', 'solution'];\n  const missing = required.filter(field => !(field in entry) || !entry[field]?.trim());\n  \n  if (missing.length > 0) {\n    throw new Error(`Missing required fields: ${missing.join(', ')}`);\n  }\n  \n  return entry as KnowledgeEntry;\n}\n```\n\n### Invalid Priority Values\n```typescript\nconst validPriorities = ['CRITICAL', 'REQUIRED', 'COMMON', 'EDGE-CASE'];\nif (!validPriorities.includes(entry.priority)) {\n  throw new Error(\n    `Invalid priority: ${entry.priority}. Must be one of: ${validPriorities.join(', ')}`\n  );\n}\n```\n\n## Search Edge Cases\n\n### Special Characters in Queries\n```typescript\nfunction sanitizeSearchQuery(query: string): string {\n  return query.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n```\n\n### Empty Search Results\n```typescript\nconst results = await searchKnowledge(query);\nif (results.length === 0) {\n  return {\n    content: [{\n      type: \"text\",\n      text: `No entries found matching \"${query}\". Try broader search terms.`\n    }]\n  };\n}\n```\n\n## Path Generation Edge Cases\n\n### Long Titles\n```typescript\nfunction normalizeLongTitle(title: string): string {\n  const MAX_LENGTH = 100;\n  if (title.length <= MAX_LENGTH) return title;\n  \n  const truncated = title.substring(0, MAX_LENGTH);\n  const lastSpace = truncated.lastIndexOf(' ');\n  return lastSpace > 50 ? truncated.substring(0, lastSpace) : truncated;\n}\n```\n\n### Special Characters in Titles\n```typescript\nfunction generateSafeFilename(title: string): string {\n  const normalized = title\n    .toLowerCase()\n    .replace(/[^a-z0-9\\s-]/g, '')\n    .replace(/\\s+/g, '-')\n    .replace(/-+/g, '-')\n    .replace(/^-|-$/g, '');\n    \n  return normalized || 'untitled';\n}\n```\n\n## WebSocket Edge Cases\n\n### Connection Drops\n```typescript\nfunction sendWebSocketMessage(ws: WebSocket, message: any): void {\n  if (ws.readyState === WebSocket.OPEN) {\n    ws.send(JSON.stringify(message));\n  } else {\n    console.warn('WebSocket not ready, message dropped:', message.type);\n  }\n}\n```\n\n### Malformed Messages\n```typescript\nws.on('message', (data) => {\n  try {\n    const message = JSON.parse(data.toString());\n    handleMessage(message);\n  } catch (error) {\n    console.error('Invalid WebSocket message:', data.toString());\n    // Don't crash the server for bad messages\n  }\n});\n```",
  "tags": [
    "edge-cases",
    "error-handling",
    "debugging",
    "troubleshooting",
    "mcp"
  ],
  "context": "Edge cases often occur at system boundaries, with invalid input, file system issues, or unexpected data formats. Proper handling of these scenarios prevents crashes and provides helpful error messages.",
  "created_at": "2025-08-03T17:41:53.415Z",
  "updated_at": "2025-08-04T11:15:15.326Z",
  "related_to": []
}