Add security audit tool (MCP + CLI)

.gitignore

@@ -10,4 +10,9 @@ wheels/
 .venv
 
 # SGraph files
-*.xml
+*.xml
+
+# MkDocs local build output and cache
+site/
+.cache/
+docs/LOCAL_*

.mcp.json.example

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "sgraph": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "http://localhost:8008/sse"]
+    }
+  }
+}

.vscode/settings.json

@@ -1,4 +1,6 @@
 {
   "python.analysis.typeCheckingMode": "basic",
-  "python.analysis.autoImportCompletions": true
+  "python.analysis.autoImportCompletions": true,
+  "cursorpyright.analysis.autoImportCompletions": true,
+  "cursorpyright.analysis.typeCheckingMode": "basic"
 }

ARCHITECTURE.md

@@ -0,0 +1,249 @@
+# SGraph-MCP-Server Architecture
+
+## Overview
+
+The sgraph-mcp-server has been designed with a modular architecture that separates concerns, improves testability, and enhances maintainability. This document describes the current architectural patterns and design decisions.
+
+## Architecture Principles
+
+### 1. **Single Responsibility Principle**
+Each module has one clear purpose:
+- **Core**: Fundamental components (model management, data conversion)
+- **Services**: Business logic (search, dependency analysis, overview generation)
+- **Tools**: MCP tool definitions and request/response handling
+- **Utils**: Cross-cutting concerns (logging, validation)
+
+### 2. **Dependency Inversion**
+- Services depend on abstractions, not concrete implementations
+- Tools depend on services, not directly on data structures
+- Clear separation between business logic and presentation layer
+
+### 3. **Testability by Design**
+- Each layer can be tested independently
+- Service logic is separated from MCP protocol concerns
+- Minimal external dependencies in core business logic
+
+## Directory Structure
+
+```
+src/
+├── core/                   # Core components
+│   ├── model_manager.py    # Model loading and caching
+│   └── element_converter.py # Element-to-dict conversions
+├── services/               # Business logic layer
+│   ├── search_service.py   # Search algorithms
+│   ├── dependency_service.py # Dependency analysis
+│   └── overview_service.py # Model structure analysis
+├── tools/                  # MCP tool definitions
+│   ├── model_tools.py      # Model management tools
+│   ├── search_tools.py     # Search-related tools
+│   ├── analysis_tools.py   # Dependency analysis tools
+│   └── navigation_tools.py # Element navigation tools
+└── utils/                  # Utilities
+    ├── logging.py          # Centralized logging
+    └── validators.py       # Input validation
+
+tests/
+├── unit/                   # Unit tests
+├── integration/            # Integration tests
+└── performance/            # Performance tests
+
+throwaway-ai-code/          # Temporary AI debugging code
+```
+
+## Component Responsibilities
+
+### Core Layer (`src/core/`)
+
+**ModelManager** (`model_manager.py`)
+- Loads sgraph models from files
+- Manages model caching in memory
+- Handles model lifecycle (load, get, remove, clear)
+- Provides comprehensive logging and error handling
+
+**ElementConverter** (`element_converter.py`)
+- Converts SElement objects to dictionary representations
+- Handles batch conversions
+- Manages association serialization
+
+### Service Layer (`src/services/`)
+
+**SearchService** (`search_service.py`)
+- Implements search algorithms (by name, type, attributes)
+- Uses iterative traversal for performance
+- Handles regex and glob pattern matching
+- Supports scoped searches
+
+**DependencyService** (`dependency_service.py`)
+- Analyzes dependency chains and subtrees
+- Provides transitive dependency analysis
+- Supports multiple element retrieval
+- Handles both incoming and outgoing dependencies
+
+**OverviewService** (`overview_service.py`)
+- Generates hierarchical model overviews
+- Provides statistics and type distribution
+- Supports configurable depth analysis
+- Optimized for quick structural understanding
+
+### Tools Layer (`src/tools/`)
+
+**Model Tools** (`model_tools.py`)
+- `sgraph_load_model`: Load models with validation
+- `sgraph_get_model_overview`: Hierarchical structure overview
+
+**Search Tools** (`search_tools.py`)
+- `sgraph_search_elements_by_name`: Pattern-based search
+- `sgraph_get_elements_by_type`: Type-based filtering
+- `sgraph_search_elements_by_attributes`: Attribute-based search
+
+**Analysis Tools** (`analysis_tools.py`)
+- `sgraph_get_subtree_dependencies`: Subtree dependency analysis
+- `sgraph_get_dependency_chain`: Transitive dependency chains
+- `sgraph_get_multiple_elements`: Bulk element retrieval
+
+**Navigation Tools** (`navigation_tools.py`)
+- `sgraph_get_root_element`: Root element access
+- `sgraph_get_element`: Single element retrieval
+- `sgraph_get_element_*_associations`: Association navigation
+
+### Utils Layer (`src/utils/`)
+
+**Logging** (`logging.py`)
+- Centralized logging configuration
+- Service-specific logger management
+- Consistent log formatting
+
+**Validators** (`validators.py`)
+- Model ID validation
+- Path validation and security checks
+- Pattern validation for search operations
+- Element type validation
+
+## Data Flow
+
+```
+MCP Client Request
+       ↓
+[Tools Layer] - Validates input, calls services
+       ↓
+[Services Layer] - Implements business logic
+       ↓
+[Core Layer] - Manages models and data conversion
+       ↓
+SGraph Library - Actual graph operations
+```
+
+## Performance Characteristics
+
+### Optimizations Implemented
+
+1. **Iterative Traversal**: All tree/graph traversals use iterative approaches instead of recursion
+2. **Model Caching**: Models are loaded once and cached in memory
+3. **Lazy Loading**: Only requested data is processed and converted
+4. **Bulk Operations**: Multiple element operations are batched for efficiency
+
+### Performance Targets
+
+- **Model Loading**: < 60 seconds (with timeout)
+- **Search Operations**: < 100ms for typical queries
+- **Overview Generation**: < 150ms for depth ≤ 5
+- **Dependency Analysis**: < 200ms for moderate subtrees
+
+## Error Handling Strategy
+
+### 1. **Layered Error Handling**
+- **Tools Layer**: Catches all exceptions, returns error objects
+- **Services Layer**: Logs business logic errors, raises specific exceptions
+- **Core Layer**: Handles system-level errors (file I/O, timeouts)
+
+### 2. **Error Response Format**
+```json
+{
+  "error": "Human-readable error message",
+  "details": "Optional technical details"
+}
+```
+
+### 3. **Logging Strategy**
+- **DEBUG**: Detailed operation traces
+- **INFO**: Important state changes and metrics
+- **WARNING**: Recoverable issues
+- **ERROR**: Failures that prevent operation completion
+
+## Testing Strategy
+
+### 1. **Unit Tests** (`tests/unit/`)
+- Test individual components in isolation
+- Mock external dependencies
+- Focus on business logic correctness
+
+### 2. **Integration Tests** (`tests/integration/`)
+- Test component interactions
+- End-to-end workflows
+- Real model loading and analysis
+
+### 3. **Performance Tests** (`tests/performance/`)
+- Validate performance targets
+- Regression testing for optimizations
+- Real-world scenario simulation
+
+## Extension Points
+
+### Adding New Tools
+1. Create tool class in appropriate `tools/` module
+2. Use `@mcp.tool()` decorator
+3. Implement validation and error handling
+4. Add corresponding service method if needed
+
+### Adding New Services
+1. Create service class in `services/`
+2. Implement static methods for operations
+3. Add comprehensive logging
+4. Create unit tests
+
+### Adding New Validators
+1. Add validation function to `utils/validators.py`
+2. Use in tool layer for input validation
+3. Add unit tests for edge cases
+
+## Migration Notes
+
+### From Monolithic to Modular
+
+The original `server.py` (350+ lines) has been refactored into:
+- **Tools**: 4 focused modules (~100 lines each)
+- **Services**: 3 business logic modules (~150 lines each)
+- **Core**: 2 fundamental modules (~100 lines each)
+- **Utils**: 2 utility modules (~50 lines each)
+
+### Benefits Achieved
+
+1. **Maintainability**: Clear boundaries, easier to modify
+2. **Testability**: Each component can be tested independently
+3. **Extensibility**: New features don't require touching core logic
+4. **Performance**: Services can be optimized individually
+5. **Reusability**: Core services work outside MCP context
+
+## Future Architectural Considerations
+
+### 1. **Plugin Architecture**
+Consider implementing a plugin system for:
+- Custom search algorithms
+- Additional analysis tools
+- External data source integrations
+
+### 2. **Caching Enhancements**
+- Persistent model caching
+- Query result caching
+- Cache invalidation strategies
+
+### 3. **Parallel Processing**
+- Async service operations
+- Parallel dependency analysis
+- Concurrent model loading
+
+### 4. **Configuration Management**
+- External configuration files
+- Environment-specific settings
+- Runtime configuration updates

CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+SGraph MCP Server is a Python 3.13+ MCP (Model Context Protocol) server that provides AI agents with fast access to software structure and dependency information through cached sgraph models. It reduces query time from seconds to milliseconds by pre-loading hierarchical graph models into memory.
+
+## Development Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Run the MCP server (port 8008) - default legacy profile
+uv run python -m src.server
+
+# Run with specific profile
+uv run python -m src.server --profile claude-code  # 8 optimized tools
+uv run python -m src.server --profile legacy       # 14 tools (default)
+
+# Run security audit CLI
+uv run python -m src.tools.security_report_cli /path/to/model.xml.zip
+uv run python -m src.tools.security_report_cli /path/to/model.xml.zip -o report.md --top-n 20
+
+# Run all tests
+uv run python tests/run_all_tests.py
+
+# Run specific test categories
+uv run python tests/run_all_tests.py unit
+uv run python tests/run_all_tests.py integration
+uv run python tests/run_all_tests.py performance
+
+# Run a single test file
+uv run python -m pytest tests/unit/test_model_manager.py -v
+
+# Lint with ruff
+uv run ruff check src/
+```
+
+## Architecture
+
+The project uses a layered modular architecture:
+
+```
+MCP Client Request
+       ↓
+[Tools Layer] src/tools/        → MCP tool definitions, input validation
+       ↓
+[Services Layer] src/services/  → Business logic (search, dependencies, overview, security audit)
+       ↓
+[Core Layer] src/core/          → Model management, data conversion
+       ↓
+[SGraph Library]                → Graph operations
+```
+
+### Key Components
+
+**Core** (`src/core/`):
+- `ModelManager` - Async model loading with 60s timeout, in-memory caching, nanoid-based model IDs
+- `ElementConverter` - SElement to dictionary conversion
+
+**Services** (`src/services/`): Static methods for testability
+- `SearchService` - Pattern matching (regex/glob), type filtering, scoped searches
+- `DependencyService` - Transitive dependency chains, subtree analysis, bulk retrieval
+- `OverviewService` - Hierarchical structure generation with configurable depth
+
+**Tools** (`src/tools/`): MCP tool implementations
+- `model_tools.py` - Load model, get overview
+- `search_tools.py` - Search by name/type/attributes
+- `analysis_tools.py` - Dependency analysis tools
+- `navigation_tools.py` - Element navigation
+
+**Utils** (`src/utils/`):
+- `validators.py` - Path security checks (blocks `..`), model ID validation (24-char nanoid)
+- `logging.py` - Centralized logging config
+
+### SGraph Data Model
+
+Elements form a hierarchy: `/Project/<directory>/<file>/<code_element>`
+- Associations are directed dependencies between elements
+- External dependencies live under `/ProjectName/External`
+
+## Testing
+
+- **Unit tests** (`tests/unit/`) - Component isolation with mocks
+- **Integration tests** (`tests/integration/`) - End-to-end workflows with real models
+- **Performance tests** (`tests/performance/`) - Validates targets: <100ms searches, <150ms overviews
+
+Test models are in `sgraph-example-models/` (e.g., `langchain.xml.zip`).
+
+## Profiles
+
+The server supports multiple profiles in `src/profiles/`:
+
+| Profile | Tools | Description |
+|---------|-------|-------------|
+| `legacy` | 14 | Full original tool set (default, backwards compatible) |
+| `claude-code` | 6 | Optimized for Claude Code - consolidated tools, TOON output format |
+
+**Claude Code profile tools** (see `SGRAPH_FOR_CLAUDE_CODE.md`):
+- `sgraph_search_elements` - Find symbols by pattern
+- `sgraph_get_element_dependencies` - THE KEY TOOL with `result_level` abstraction
+- `sgraph_get_element_structure` - Explore hierarchy without reading source
+- `sgraph_analyze_change_impact` - Impact analysis with cycle/hub warnings
+- `sgraph_audit` - Architectural health checks (cycles, hubs) for occasional reviews
+
+## Development Notes
+
+- Uses `uv` as package manager
+- Ruff for linting (line length 100, Python 3.13 target)
+- A model for this project exists at `/opt/softagram/output/projects/sgraph-and-mcp/latest.xml.zip` - use it via the MCP tools for faster architectural exploration
+
+## AI Experience Tracking
+
+When experiencing notably good or bad moments with MCP tools, log them to `AI-EXPERIENCES.md` with format: MCP-server, tool name, rating (+/++/+++/-/--/---), short story.