mcp-adr-analysis-server

Instructions

Implementation Reference

• src/utils/root-manager.ts:103-105 (handler)

  The core handler logic for the list_roots tool. This method returns all configured filesystem roots as Root objects, implementing MCP best practices for file access control.
  listRoots(): Root[] { return Array.from(this.roots.values()); }
• src/tools/tool-catalog.ts:1086-1101 (schema)

  Tool schema and metadata registration in the central TOOL_CATALOG. Defines input schema (no parameters), description, and properties for dynamic tool discovery.
  TOOL_CATALOG.set('list_roots', { name: 'list_roots', shortDescription: 'List root directories', fullDescription: 'Lists configured root directories.', category: 'file-system', complexity: 'simple', tokenCost: { min: 50, max: 200 }, hasCEMCPDirective: true, // Phase 4.3: Simple tool - root listing relatedTools: ['read_directory', 'list_directory'], keywords: ['roots', 'list', 'directories'], requiresAI: false, inputSchema: { type: 'object', properties: {}, }, });
• src/utils/root-manager.ts:41-175 (helper)

  RootManager class that manages the filesystem roots. The list_roots tool uses this class's listRoots() method and roots are predefined in the constructor.
  export class RootManager { private roots: Map<string, Root> = new Map(); /** * Initialize root manager with project and ADR paths * * @param projectPath - Path to the project root directory * @param adrDirectory - Path to the ADR directory */ constructor(projectPath: string, adrDirectory: string) { // Root 1: Project directory (entire codebase) this.roots.set('project', { name: 'project', path: resolve(projectPath), description: 'Project source code, configuration, and documentation', }); // Root 2: ADR directory (may be inside project, but worth explicit access) const resolvedAdrPath = resolve(adrDirectory); this.roots.set('adrs', { name: 'adrs', path: resolvedAdrPath, description: 'Architectural Decision Records', }); } /** * Check if a path is within accessible roots * * @param targetPath - Path to check (can be relative or absolute) * @returns true if path is within any root, false otherwise * * @example * ```typescript * if (!rootManager.isPathAllowed(userPath)) { * throw new Error('Access denied: Path is outside accessible roots'); * } * ``` */ isPathAllowed(targetPath: string): boolean { const resolved = resolve(targetPath); for (const root of this.roots.values()) { if (resolved.startsWith(root.path)) { return true; } } return false; } /** * List all accessible roots * * @returns Array of root definitions * * @example * ```typescript * const roots = rootManager.listRoots(); * roots.forEach(root => { * console.log(`${root.name}: ${root.path}`); * }); * ``` */ listRoots(): Root[] { return Array.from(this.roots.values()); } /** * Get which root a path belongs to * * @param targetPath - Path to check * @returns Root that contains this path, or null if outside all roots * * @example * ```typescript * const root = rootManager.getRootForPath('/path/to/project/src/index.ts'); * if (root) { * console.log(`File is in ${root.name} root`); * } * ``` */ getRootForPath(targetPath: string): Root | null { const resolved = resolve(targetPath); for (const root of this.roots.values()) { if (resolved.startsWith(root.path)) { return root; } } return null; } /** * Get the relative path from root * * @param targetPath - Path to get relative path for * @returns Relative path from root, or null if outside all roots * * @example * ```typescript * const relPath = rootManager.getRelativePathFromRoot('/path/to/project/src/index.ts'); * // Returns: 'src/index.ts' * ``` */ getRelativePathFromRoot(targetPath: string): string | null { const root = this.getRootForPath(targetPath); if (!root) { return null; } return relative(root.path, resolve(targetPath)); } /** * Add a custom root (useful for testing or dynamic root management) * * @param name - Unique identifier for the root * @param path - Absolute path to the root directory * @param description - Human-readable description */ addRoot(name: string, path: string, description: string): void { this.roots.set(name, { name, path: resolve(path), description, }); } /** * Remove a root by name * * @param name - Name of the root to remove * @returns true if root was removed, false if not found */ removeRoot(name: string): boolean { return this.roots.delete(name); } }
• src/utils/server-context-generator.ts:309-313 (registration)

  Tool listed in server context generator for LLM awareness of available tools.
  { name: 'list_roots', description: 'List available filesystem roots for operations' }, { name: 'read_directory', description: 'Read directory contents and metadata' }, { name: 'read_file', description: 'Read file contents from filesystem' }, { name: 'write_file', description: 'Write content to filesystem' }, { name: 'list_directory', description: 'List directory contents with filtering' },
• src/utils/server-context-generator.ts:439-439 (schema)

  Categorization logic includes 'list_roots' in File System Operations category.
  name.includes('list_roots') ||