Portable MCP Toolkit

# AIStack Development Standards ## Project Context You have access to the codebase via MCP protocol with these tools: - **filesystem**: Read/write/search files - **git**: View history and changes - **github**: Check PRs and issues - **sequential-thinking**: Break down complex tasks - **brave-search**: Research best practices ## MCP Usage Guidelines ### When to Use MCP Tools 1. **Understanding Context**: Use filesystem to read related files 2. **Pattern Matching**: Search for similar implementations 3. **Change History**: Use git to understand why code exists 4. **Research**: Use brave-search for best practices 5. **Complex Tasks**: Use sequential-thinking to plan approach ### Token Optimization - Read only necessary files (ask which files before reading) - Use git log with --oneline for quick history - Summarize large files before suggesting changes - Prefer targeted searches over reading entire directories ### MCP Environment Self-Test **Before starting work, verify the MCP environment is properly configured:** ```powershell # Quick self-test of MCP environment python scripts/test_mcp_environment.py # Verbose output with details python scripts/test_mcp_environment.py --verbose # Test specific server only python scripts/test_mcp_environment.py --server aistack-intelligence ``` **What the self-test discovers automatically:** - MCP servers configured in `.cursor/mcp.json` - Service dependencies (Ollama, Qdrant, etc.) from environment variables - Service health checks (HTTP endpoints) - Server configuration validation - Workspace accessibility **The script follows SOLID principles:** - **Single Responsibility**: Each checker handles one concern - **Open/Closed**: Easy to add new service checkers without modifying existing code - **Liskov Substitution**: All checkers implement consistent interface - **Interface Segregation**: Separate concerns (discovery, checking, reporting) - **Dependency Inversion**: Depends on configuration abstraction, not hardcoded values **If self-test fails:** 1. Review failed checks in output 2. Ensure required services are running (docker-compose up) 3. Verify MCP configuration matches actual setup 4. Check Cursor logs: Help > Toggle Developer Tools > Console **The script is self-discovering** - it reads `.cursor/mcp.json` and extracts: - Server names and configurations - Service URLs from `env` variables (pattern: `*_URL`, `*_HOST`) - Workspace paths from server arguments - No hardcoded values - fully maintainable ## Code Standards ### Architecture - Async/await for all I/O operations - Dependency injection via constructor - Interface-based design for testability - SOLID principles throughout ### Error Handling - Use Result<T> pattern for expected failures - Never throw exceptions for control flow - Log errors with structured context - Include correlation IDs for tracing ### Async Patterns - Always async/await (never .Result or .Wait()) - Use ConfigureAwait(false) in library code - Cancel operations with CancellationToken - Handle TimeoutException and OperationCanceledException ### Logging - Structured logging with context objects - Appropriate log levels (Debug/Info/Warning/Error) - Include timing information for operations - Sensitive data excluded from logs ### Testing - Unit tests for business logic (xUnit) - Integration tests for workflows - Mocked dependencies via interfaces - Test both happy path and error cases ## Workflow ### Before Making Changes 1. Use MCP filesystem to read target file 2. Use git to check recent changes 3. Search for similar patterns in codebase 4. Ask me to confirm approach before implementing ### When Suggesting Code 1. Explain what you read via MCP 2. Reference specific files and patterns found 3. Show how your suggestion matches existing style 4. Highlight any deviations from standard patterns ### For Complex Changes 1. Use sequential-thinking to break down task 2. Show me the plan before executing 3. Implement incrementally with tests 4. Use git to verify no unintended changes ## Project Structure - src/Core/ - Domain models and interfaces - src/Orchestration/ - Task coordination - src/Agents/ - AI agent implementations - tests/ - Unit and integration tests ## Dependencies - .NET 8 for C# projects - Python 3.11+ for AI workflows - Docker for containerization ## Environment (Windows) This project runs on **Windows 10/11** with **PowerShell** as the default shell. ### Shell Command Syntax - **DO NOT use `&&`** - PowerShell does not support `&&` as a command separator - **USE semicolons** to chain commands: `cd C:\path; git status` - **USE `-and`** for conditional execution: `(command1) -and (command2)` ```powershell # WRONG - will fail with "token '&&' is not valid" cd C:\AIStack-MCP && git log --oneline -5 # CORRECT - use semicolon cd C:\AIStack-MCP; git log --oneline -5 # CORRECT - single command with full path git -C C:\AIStack-MCP log --oneline -5 ``` ### Path Format - Use backslashes for Windows paths: `C:\AIStack-MCP\scripts` - Or forward slashes (PowerShell accepts both): `C:/AIStack-MCP/scripts` ### Console Output Encoding **Windows console uses cp1252 encoding** - Unicode characters will crash Python scripts! - **DO NOT use Unicode symbols**: `✓`, `✗`, `→`, `•`, `▶`, emojis, etc. - **USE ASCII alternatives**: `[OK]`, `[FAIL]`, `[WARN]`, `->`, `*`, `-`, `>>` ```python # WRONG - will crash with UnicodeEncodeError on Windows print("✓ Connected to Qdrant") print("✗ Connection failed") print("→ Processing...") # CORRECT - ASCII-safe for Windows console print("[OK] Connected to Qdrant") print("[FAIL] Connection failed") print(">> Processing...") ``` **Safe status indicators:** - Success: `[OK]`, `[PASS]`, `[SUCCESS]`, `[+]` - Failure: `[FAIL]`, `[ERROR]`, `[X]`, `[-]` - Warning: `[WARN]`, `[!]`, `[?]` - Info: `[INFO]`, `[*]`, `>>` ## Common Patterns ### Result<T> Error Handling ```csharp public async Task<Result<Data>> GetDataAsync() { try { var data = await _service.FetchAsync(); return Result<Data>.Success(data); } catch (Exception ex) { _logger.LogError(ex, "Failed to fetch data"); return Result<Data>.Failure($"Fetch failed: {ex.Message}"); } } ``` ### Structured Logging ```csharp _logger.LogInformation( "Operation completed", new { OperationId = operationId, Duration = duration.TotalMilliseconds, ItemCount = items.Count } ); ``` ### Async Best Practice ```csharp public async Task<string> ProcessAsync(CancellationToken ct) { var result = await _httpClient .GetStringAsync(url, ct) .ConfigureAwait(false); return result; } ``` ## Git & GitHub Workflow ### Branch Protection is ENABLED **The `main` branch is protected.** Direct pushes are blocked. All changes require PRs. ### NEVER Do This ```powershell # WRONG - will be rejected git push origin main git push -f origin main ``` ### ALWAYS Do This ```powershell # 1. Create feature branch git checkout -b feature/my-change # 2. Make changes and commit git add . git commit -m "feat: description of change" # 3. Push branch git push -u origin feature/my-change # 4. Create PR gh pr create --title "feat: description" --body "Details here" # 5. Wait for CI to pass, then merge gh pr merge --squash --delete-branch ``` ### Branch Naming Conventions | Type | Pattern | Example | |------|---------|---------| | Feature | `feature/description` | `feature/add-retry-logic` | | Bugfix | `fix/description` | `fix/search-timeout` | | Docs | `docs/description` | `docs/update-readme` | | Chore | `chore/description` | `chore/update-deps` | ### Commit Message Format ``` type: short description - feat: New feature - fix: Bug fix - docs: Documentation - chore: Maintenance - test: Tests - refactor: Code refactoring ``` ### Before Creating a PR 1. Pull latest main: `git pull origin main` 2. Rebase if needed: `git rebase main` 3. Run tests: `pytest tests/unit/ -v` 4. Check for conflicts ### Dependabot Automation Dependabot automatically creates PRs for dependency updates: - **Minor/Patch updates**: Auto-merged after CI passes - **Major updates**: Require manual review **When you see Dependabot PRs:** - They will auto-merge if CI passes (minor/patch) - Review major version bumps manually - Use `gh pr merge <number> --squash` if needed ### Checking PR Status ```powershell # List open PRs gh pr list # Check PR status gh pr status # View specific PR gh pr view <number> # Check CI status on PR gh pr checks <number> ``` ### Merging PRs ```powershell # Merge after CI passes (squash recommended) gh pr merge <number> --squash --delete-branch # Or merge with merge commit gh pr merge <number> --merge --delete-branch ``` ### Handling Merge Conflicts ```powershell # Update your branch with latest main git checkout feature/my-branch git fetch origin git rebase origin/main # Resolve conflicts, then git add . git rebase --continue git push --force-with-lease ``` ### Emergency Bypass (Admin Only) If you absolutely must push directly (not recommended): ```powershell # You'll get a warning but can bypass as admin git push origin main # GitHub will warn but allow it ``` ## CI/CD Pipeline ### What Runs on Every PR | Workflow | Purpose | Must Pass | |----------|---------|-----------| | `test.yml` | Unit tests (88 tests) | Yes | | `lint.yml` | Code style | No (warnings only) | | `validate-config.yml` | MCP config | No | ### Checking CI Locally Before PR ```powershell # Run tests pytest tests/unit/ -v # Check linting (optional) flake8 . --count --select=E9,F63,F7,F82 --show-source # Format code black . isort . ``` ## Remember - Use MCP tools to understand context first - Match existing patterns found in codebase - Ask before making significant architectural changes - Test thoroughly before suggesting code - **ALWAYS use PRs** - never push directly to main - **Check for Dependabot PRs** before making related changes - **Run tests locally** before creating PRs