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') ||