Commit b01c13a

@@ -17,6 +17,36 @@ This is a **production-ready** Go-based MCP (Model Context Protocol) server impl
 
 ## Architecture
 
+### Code Structure
+```
+pkg/
+├── mcp/           # Core MCP protocol implementation (JSON-RPC 2.0)
+├── git/           # Git server with repository operations  
+├── filesystem/    # Filesystem server with access controls
+├── memory/        # Knowledge graph with persistent storage
+├── fetch/         # Web content fetching with HTML processing
+├── time/          # Time/timezone utilities
+├── thinking/      # Sequential thinking with session management
+└── maildir/       # Email analysis for Maildir format
+
+cmd/               # Server entry points (main.go files)
+test/integration/  # E2E integration test suite
+```
+
+### MCP Server Architecture Pattern
+All servers follow this pattern:
+1. **Server struct** in `pkg/<name>/server.go` implements the MCP protocol
+2. **Tool handlers** registered via `RegisterTool(name, handler)`
+3. **Base MCP server** (`pkg/mcp/server.go`) handles JSON-RPC 2.0 protocol
+4. **Thread-safe operations** with sync.RWMutex for concurrent access
+5. **Lazy loading** - resources discovered on-demand, not at startup
+
+### Key Components
+- **pkg/mcp/server.go**: Core MCP protocol implementation with JSON-RPC 2.0
+- **pkg/mcp/types.go**: MCP protocol types and structures
+- **Makefile**: Build system with individual server targets
+- **test/integration_test.go**: Comprehensive test suite for all servers
+
 ### Available MCP Servers
 Each server is a standalone binary in `/usr/local/bin/`:
 
@@ -36,19 +66,36 @@ Each server is a standalone binary in `/usr/local/bin/`:
 
 ## Development Commands
 
-### Build All Servers
+### Essential Build Commands
 ```bash
-make clean build
+make build                    # Build all MCP servers
+make clean build             # Clean and rebuild all servers
+make install                 # Install binaries to /usr/local/bin (requires sudo)
+make <server-name>           # Build individual server (e.g., make git, make memory)
 ```
 
-### Install System-wide
+### Testing and Quality
 ```bash
-sudo make install
+go test ./...                # Run all unit tests
+make test                    # Run all tests via Makefile
+make test-coverage           # Run tests with coverage reporting
+make e2e                     # Run integration tests in test/integration/
+make verify                  # Run tests + linting
+make benchmark               # Run performance benchmarks
 ```
 
-### Run Tests
+### Development Workflow
 ```bash
-go test ./...
+make dev-setup               # Initialize development environment
+make lint                    # Format code and run go vet
+make fmt                     # Format Go source code only
+go test ./pkg/<server>/...   # Test specific server package
+```
+
+### Single Test Execution
+```bash
+go test -v ./pkg/memory/... -run TestSpecificFunction
+go test -timeout=30s ./test/integration/... -run TestGitServer
 ```
 
 ### Individual Server Usage
@@ -173,15 +220,37 @@ echo '{"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "se
 
 ## Integration Notes for Claude Code
 
-When working with this codebase:
+### Development Patterns
+1. **Adding New Tools**: Register via `server.RegisterTool(name, handler)` in `pkg/<server>/server.go`
+2. **Tool Handler Pattern**: Implement `func(req mcp.CallToolRequest) (mcp.CallToolResult, error)`
+3. **Thread Safety**: Use `server.mu.Lock()` / `server.mu.RLock()` for concurrent access
+4. **Error Handling**: Return `mcp.NewToolError(msg)` for tool errors
+5. **JSON Storage**: Use `json.MarshalIndent()` for human-readable persistence files
+
+### Testing Strategy
+1. **Unit Tests**: Test individual tool handlers in `pkg/<server>/` 
+2. **Integration Tests**: Use `test/integration_test.go` pattern for full server testing
+3. **MCP Protocol Testing**: Use JSON-RPC messages via stdin/stdout
+4. **Performance Testing**: Critical - ensure <100ms startup, <5MB memory usage
+
+### Server Implementation Guidelines
+1. **Lazy Loading Required**: Never load resources at startup (use on-demand discovery)
+2. **Resource Limits**: Implement limits (e.g., 500 files) to prevent memory bloat
+3. **Persistence Pattern**: Optional file-based storage with graceful degradation
+4. **Command-line Flags**: Use `flag` package for server configuration
+5. **Help Integration**: Implement `--help` flag for AI agent discoverability
+
+### Critical Performance Requirements
+- **Startup Time**: Must be <100ms (enforced by integration tests)
+- **Memory Usage**: Must be <5MB per server (monitored in testing)
+- **Resource Discovery**: On-demand only, sub-20ms response time
+- **Thread Safety**: All servers must handle concurrent requests safely
 
-1. **The servers are fully functional** - all Phase 1-4 enhancements are complete and tested
-2. **Use the installed binaries** in `/usr/local/bin/` for testing integrations
-3. **Check PLAN.md** for detailed implementation history and test results
-4. **All MCP protocol features work**: tools, prompts, resources, roots discovery
-5. **Command-line flags are properly implemented** (--repository, --allowed-directory, --memory-file)
-
-This implementation provides a powerful foundation for AI-assisted development workflows with comprehensive MCP protocol support.
+When working with this codebase:
+1. **All servers are production-ready** with comprehensive MCP protocol support
+2. **Use integration tests** in `test/integration/` to verify changes
+3. **Follow lazy loading pattern** - discovered critical performance issues with eager loading
+4. **Test with installed binaries** in `/usr/local/bin/` for realistic integration testing
 
 ## 🚀 Latest Conversation Memory (Session: 2024-12-23)