docs: update project docs (#82)

* docs: update project docs and README

Author: lirantal

README.md

@@ -28,6 +28,7 @@
 - **📁 Directory Bubbling**: Intelligent discovery of project-scoped MCP configs from nested directories
 - **🔄 Process Detection**: Real-time status of running MCP servers
 - **🔒 Credential Analysis**: Security analysis of environment variables and API keys
+- **🌐 URL Hostname Extraction**: Clean display of hostnames for URL-based MCP servers
 - **🌍 Cross-Platform**: Support for Windows and macOS (Linux support coming soon)
 - **⚡ High Performance**: Fast discovery with intelligent caching and optimization
 
@@ -51,6 +52,20 @@ cd ~/projects/my-project/backend/services/api
 npx ls-mcp  # Automatically finds .vscode/mcp.json from project root
 ```
 
+### URL Hostname Extraction
+
+The tool now displays clean hostnames for URL-based MCP servers instead of full URLs:
+
+```bash
+# Before: Full URLs cluttered the SOURCE column
+SOURCE                    | STATUS | NAME           | TRANSPORT
+http://localhost:3000/mcp | ❌     | local-server  | http
+
+# After: Clean hostnames for better readability
+SOURCE      | STATUS | NAME           | TRANSPORT
+localhost   | ❌     | local-server  | http
+```
+
 ### Debug Mode
 
 To enable verbose debugging output, set the `NODE_DEBUG` environment variable:
@@ -63,6 +78,17 @@ NODE_DEBUG=ls-mcp npx ls-mcp
 NODE_DEBUG=* npx ls-mcp
 ```
 
+## Documentation
+
+For detailed information about the project architecture and features:
+
+- **[Project Overview](./docs/project.md)**: Comprehensive project analysis and architecture
+- **[Design Documentation](./docs/design.md)**: Technical design decisions and implementation details
+- **[Requirements](./docs/requirements.md)**: Functional and non-functional requirements
+- **[Directory Bubbling](./docs/directory-bubbling.md)**: Intelligent directory traversal feature
+- **[URL Hostname Extraction](./docs/url-hostname-extraction.md)**: Clean display of hostnames for URL-based servers
+- **[Credential Detection](./docs/credential-detection.md)**: Security analysis features
+
 ## Contributing
 
 Please consult [CONTRIBUTING](./.github/CONTRIBUTING.md) for guidelines on contributing to this project.

docs/design.md

@@ -333,6 +333,7 @@ When MCP server configurations don't explicitly specify a `type` field, the syst
     "web-server": {
       "url": "https://example.com/mcp"
       // No type field → automatically inferred as "http"
+      // Hostname "example.com" will be displayed in SOURCE column
     }
   }
 }
@@ -387,6 +388,58 @@ When MCP server configurations don't explicitly specify a `type` field, the syst
 - **Intelligent Defaults**: Reasonable assumptions based on configuration patterns
 - **Comprehensive Coverage**: Handles all common MCP server configuration scenarios
 
+## URL Hostname Extraction
+
+### Overview
+The URL hostname extraction feature (Feature #80) improves the readability of MCP server configurations by displaying only the hostname portion for URL-based servers in the SOURCE column.
+
+### Implementation Details
+
+#### 1. Hostname Extraction Logic
+```typescript
+export function extractHostname(urlString: string): string {
+  try {
+    // Handle URLs without protocol by adding a default one
+    let urlToParse = urlString
+    if (!urlToParse.includes('://')) {
+      urlToParse = `http://${urlToParse}`
+    }
+    const url = new URL(urlToParse)
+    return url.hostname
+  } catch (error) {
+    // If URL parsing fails, return the original string
+    return urlString
+  }
+}
+```
+
+#### 2. Service Integration
+- **MCPConfigService**: Extracts hostname during server configuration conversion
+- **MCPServerManagerService**: Sets source field to hostname when URL is available
+- **Fallback Handling**: Returns original string if URL parsing fails
+
+#### 3. URL Format Support
+- **HTTP/HTTPS**: Standard web protocols
+- **Custom Protocols**: Any protocol supported by Node.js URL constructor
+- **Protocol-less URLs**: Automatically adds `http://` for parsing
+- **IP Addresses**: Handles both IPv4 and IPv6 addresses
+- **Port Numbers**: Port information is stripped from display
+- **Query Parameters**: Query strings are ignored in hostname extraction
+
+#### 4. Benefits
+- **Cleaner Output**: SOURCE column is more readable and concise
+- **Better UX**: Users can quickly identify server location without URL clutter
+- **Consistent Display**: All URL-based servers show consistent hostname format
+- **Robust Parsing**: Handles various URL formats gracefully with fallback
+
+#### 5. Example Transformations
+```
+Before: "http://localhost:3000/mcp" → After: "localhost"
+Before: "https://api.example.com/v1/mcp" → After: "api.example.com"
+Before: "192.168.1.100:8080" → After: "192.168.1.100"
+Before: "invalid-url" → After: "invalid-url" (fallback)
+```
+
 ## Error Handling Strategy
 
 ### 1. Graceful Degradation

docs/directory-bubbling.md

@@ -206,6 +206,28 @@ constructor () {
 - **Integration Tests**: Comprehensive testing of MCPConfigService integration
 - **Edge Cases**: Boundary conditions, error scenarios, symlink handling
 
+### Test Architecture Improvements
+The directory bubbling tests have been significantly improved to address performance and reliability issues:
+
+#### Before (Problematic Tests)
+- **Global Mocking**: Tests were mocking `fs.access` globally, causing conflicts
+- **Heavy Operations**: Tests called `getMCPFileGroups()` which performed real filesystem operations
+- **Hanging Tests**: Tests would hang indefinitely due to infinite loops and filesystem access
+- **Poor Isolation**: Tests were not properly isolated from system dependencies
+
+#### After (Improved Tests)
+- **Direct Service Mocking**: Tests now mock `DirectoryBubbleService.prototype.findLocalConfigInParentDirectories` directly
+- **Lightweight Testing**: Tests focus on service configuration and integration rather than heavy filesystem operations
+- **Fast Execution**: Tests complete in ~5 seconds instead of hanging
+- **Proper Isolation**: Each test is properly isolated and tests specific functionality
+
+#### Test Strategy
+- **Service Configuration Tests**: Verify that `enableDirectoryBubbling` is set correctly
+- **Service Creation Tests**: Ensure services can be instantiated with different options
+- **Integration Tests**: Verify proper wiring between MCPConfigService and DirectoryBubbleService
+- **Error Handling Tests**: Test resilience when directory bubbling fails
+- **Mock Validation**: Verify that mocks are called appropriately based on configuration
+
 ### Test Scenarios
 - ✅ Config file in current directory
 - ✅ Config file in parent directory

docs/project.md

@@ -16,7 +16,7 @@ The tool works by scanning for known MCP configuration files associated with var
 
 3.  **Process Detection:** For each configured MCP server, the tool checks if it is currently running. It does this by executing system commands (`ps` on macOS and `powershell` on Windows) to get a list of all active processes. It then compares the command from the MCP configuration with the running processes to determine the server's status. The tool includes specific logic to handle common ways of running MCP servers, such as using `uvx` or `npx`.
 
-4.  **Output Rendering:** Finally, all the gathered information is displayed in a formatted table in the console. The table shows the server's status (running or stopped), name, source (the command used to start it), and transport protocol.
+4.  **Output Rendering:** Finally, all the gathered information is displayed in a formatted table in the console. The table shows the server's status (running or stopped), name, source (the command used to start it or hostname for URL-based servers), and transport protocol.
 
 ## Project Structure
 
@@ -67,6 +67,7 @@ This architecture ensures maintainability and clear separation of concerns betwe
 - **Transport Handling**: Fixed transport counting by properly mapping `type` field to `transport` field at the data layer
 - **Extended Transport Support**: Added support for `streamable-http` type, treating it as synonym for `http`
 - **Transport Inference**: Implemented intelligent automatic detection of transport types when not explicitly specified
+- **URL Hostname Extraction**: Implemented feature #80 to display only hostnames for URL-based MCP servers in the SOURCE column, improving readability
 - **Directory Bubbling**: Implemented intelligent directory traversal for local MCP config files, providing better DX when running from nested project subdirectories
 - **Test Isolation**: Fixed critical issue where tests were accessing real files outside the project directory
 - **Type Safety**: Created comprehensive TypeScript types for all services
@@ -86,6 +87,45 @@ This architecture ensures maintainability and clear separation of concerns betwe
 - **Linux Support**: Architecture supports adding Linux support in future iterations
 - **Plugin System**: Extensible design for custom AI application definitions
 
+## URL Hostname Extraction Feature
+
+### Overview
+The URL hostname extraction feature improves the readability of MCP server configurations by displaying only the hostname for URL-based servers instead of the full URL in the SOURCE column.
+
+### How It Works
+1. **URL Detection**: When an MCP server configuration contains a `url` field, the system automatically extracts the hostname portion
+2. **Hostname Extraction**: Uses Node.js built-in `URL` constructor to parse URLs and extract the hostname
+3. **Fallback Handling**: If URL parsing fails, the original string is displayed as a fallback
+4. **Protocol Handling**: Automatically adds `http://` protocol if none is specified for proper parsing
+
+### Example Scenarios
+
+#### Before (Full URL Display)
+```
+SOURCE                    | STATUS | NAME           | TRANSPORT
+http://localhost:3000/mcp | ❌     | local-server  | http
+https://api.example.com  | ❌     | api-server    | http
+```
+
+#### After (Hostname Display)
+```
+SOURCE      | STATUS | NAME           | TRANSPORT
+localhost   | ❌     | local-server  | http
+api.example.com | ❌     | api-server    | http
+```
+
+### Benefits
+- **Cleaner Output**: SOURCE column is more readable and concise
+- **Better UX**: Users can quickly identify the server location without URL clutter
+- **Consistent Display**: All URL-based servers show consistent hostname format
+- **Robust Parsing**: Handles various URL formats including those without protocols
+
+### Implementation Details
+- **Utility Function**: `extractHostname()` in `src/utils/url-utils.ts`
+- **Service Integration**: Integrated into both `MCPConfigService` and `MCPServerManagerService`
+- **Error Handling**: Graceful fallback to original string if parsing fails
+- **Protocol Support**: Handles HTTP, HTTPS, and custom protocols
+
 ## Directory Bubbling Feature
 
 ### Overview

docs/requirements.md

@@ -54,6 +54,7 @@ The following AI applications are currently supported:
 - **Must** maintain clean separation between external config format and internal data model
 - **Must** automatically infer transport types when `type` field is not explicitly set:
   - **Must** infer `http` transport when `url` property is present
+- **Must** extract and display only hostname for URL-based MCP servers in the SOURCE column (Feature #80)
   - **Must** infer transport from `args` array keywords (`stdio`, `http`, `sse`)
   - **Must** default to `stdio` transport when `command` is present but no other indicators found