npm - @hybridlabor-api/aos - Versions diffs - 4.2.0 → 4.4.0 - Mend

@hybridlabor-api/aos 4.2.0 → 4.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1098) hide show

package/mcps/windows-computer-use-mcp/docs/_stale/serena/SERENA_GUIDE.md DELETED Viewed

@@ -1,632 +0,0 @@
-# Serena MCP - Complete Installation & Usage Guide
-**Date:** 2025-10-09
-**Status:** Production-ready FOSS project
-**GitHub:** https://github.com/oraios/serena
-**Stars:** 9.8k+ (very active!)
----
-## 🎯 What is Serena?
-**Serena** is a FREE, open-source MCP server that makes AI assistants (Claude, Cursor, etc.) WAY smarter at coding by giving them **semantic code understanding** - not just text reading.
-### The Problem Serena Solves
-**Without Serena:**
-- AI reads your ENTIRE codebase every time (wastes tokens 💸)
-- AI only sees text, not code structure (like class relationships, function calls)
-- Large projects hit token limits fast
-- AI can't find specific functions/classes efficiently
-**With Serena:**
-- AI reads ONLY what it needs (70% token savings! 🎉)
-- AI understands code semantically (via Language Server Protocol)
-- AI can search by meaning: "find all authentication functions"
-- Creates project "memories" in `.serena/memories/` for context
-- Works like a real IDE with symbol navigation, references, etc.
-### How It Works
-1. **First run (Onboarding):**
-   - Serena scans your project
-   - Creates index of all code symbols (classes, functions, etc.)
-   - Generates "memory" files in `.serena/memories/` with project understanding
-   - Starts language servers (Python, TypeScript, Java, etc.)
-2. **During conversation:**
-   - AI asks Serena specific questions like "find_symbol", "get_references"
-   - Serena uses language servers to get exact answers
-   - Only relevant code is sent to AI (not the whole project)
-   - AI has semantic understanding (not just text search)
-3. **Automatic optimization:**
-   - Serena caches results
-   - Updates indexes when files change
-   - Manages memory files automatically
----
-## 📋 Supported Languages
-**Fully Supported (Auto-configured):**
-- Python (pylsp)
-- JavaScript/TypeScript (typescript-language-server)
-- Rust (rust-analyzer)
-- Go (gopls)
-- Java, C#, C++, and 8+ more
-**Works Best For:**
-- Large projects (10,000+ lines)
-- Multi-file codebases with complex relationships
-- Projects with good structure (not single-file scripts)
----
-## 🔧 Installation Guide
-### Prerequisites
-**Required:**
-- Python 3.10+ (you have 3.13 ✅)
-- `uv` package manager (Python's new fast package tool)
-**Install uv (Windows PowerShell):**
-```powershell
-# Run this command
-powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
-# Verify installation
-uv --version
-```
-**Or via winget:**
-```powershell
-winget install astral-sh.uv
-```
----
-## 🚀 Quick Setup (Recommended Method)
-### Method 1: Direct Run (No Clone Needed) ⭐ EASIEST
-This uses `uvx` to run Serena directly from GitHub:
-**For Claude Desktop:**
-1. Open Claude Desktop config:
-   ```
-   C:\Users\sandr\AppData\Roaming\Claude\claude_desktop_config.json
-   ```
-2. Add Serena entry:
-   ```json
-   {
-     "mcpServers": {
-       "serena": {
-         "command": "uvx",
-         "args": [
-           "--from",
-           "git+https://github.com/oraios/serena",
-           "serena",
-           "start-mcp-server",
-           "--context",
-           "ide-assistant"
-         ],
-         "env": {
-           "PYTHONUNBUFFERED": "1"
-         }
-       }
-     }
-   }
-   ```
-3. Restart Claude Desktop **completely** (quit from system tray!)
-4. Verify: Look for hammer icon 🔨 next to your message box
-**For Cursor:**
-1. Open/create Cursor MCP config:
-   ```
-   C:\Users\sandr\.cursor\mcp.json
-   ```
-2. Add Serena entry:
-   ```json
-   {
-     "mcpServers": {
-       "serena": {
-         "command": "uvx",
-         "args": [
-           "--from",
-           "git+https://github.com/oraios/serena",
-           "serena",
-           "start-mcp-server",
-           "--context",
-           "ide-assistant"
-         ]
-       }
-     }
-   }
-   ```
-3. Restart Cursor
----
-### Method 2: Clone & Run (More Control)
-**For Sandra's setup:**
-```powershell
-# Navigate to repos
-Set-Location "d:\dev\repos"
-# Clone Serena
-git clone https://github.com/oraios/serena
-Set-Location "d:\dev\repos\serena"
-# Test it works
-uv run serena start-mcp-server --help
-```
-**Claude Desktop config:**
-```json
-{
-  "mcpServers": {
-    "serena": {
-      "command": "uv",
-      "args": [
-        "run",
-        "--directory",
-        "d:\\dev\\repos\\serena",
-        "serena",
-        "start-mcp-server",
-        "--context",
-        "ide-assistant"
-      ],
-      "env": {
-        "PYTHONUNBUFFERED": "1"
-      }
-    }
-  }
-}
-```
----
-## 🎮 Using Serena
-### First Time in a Project
-When you start working on a project, Serena needs to "onboard":
-**In Claude/Cursor, say:**
-```
-"Run onboarding for this project"
-```
-Or just start coding naturally:
-```
-"Analyze the authentication flow in this project"
-```
-Serena will:
-1. Scan your project structure
-2. Create `.serena/memories/` folder
-3. Generate memory files (project structure, key components, etc.)
-4. Index all code symbols
-5. Start language servers
-**This takes 30 seconds to 2 minutes** depending on project size.
-### After Onboarding
-Serena is ready! It has deep understanding of your code.
-**What You Can Ask:**
-**Code Navigation:**
-```
-"Find all functions that handle user authentication"
-"Show me where UserService is defined"
-"Find all references to the authenticate() method"
-"List all classes in the auth module"
-```
-**Code Analysis:**
-```
-"Explain the relationship between UserController and UserService"
-"What does the payment processing flow look like?"
-"Find potential security issues in the login code"
-"Analyze code complexity in the database layer"
-```
-**Code Editing:**
-```
-"Add logging to all API endpoints"
-"Refactor the UserService to use dependency injection"
-"Fix all TODO comments in the project"
-"Add error handling to database queries"
-```
-**Project Understanding:**
-```
-"What does this project do?"
-"Where is the main entry point?"
-"How is authentication implemented?"
-"Show me the API structure"
-```
-### Serena's Tools (What It Can Do)
-Serena provides these tools to the AI:
-- `get_symbol_definition` - Get code for a specific symbol
-- `get_symbol_references` - Find all uses of a symbol
-- `search_symbols` - Search for symbols by name/pattern
-- `find_patterns` - Search code by regex pattern
-- `list_memories` - Show available memory files
-- `read_memory` - Read a memory file
-- `read_file` - Read any project file
-- `replace_lines` - Edit code by line ranges
-- `replace_symbol_body` - Replace entire function/class
-- `list_dir` - Browse project structure
-- `onboarding` - Initialize project understanding
-- `prepare_for_new_conversation` - Continue with context
-**You don't call these directly!** The AI decides when to use them.
----
-## 📊 The Dashboard (Very Cool!)
-Serena runs a **local web dashboard** for monitoring:
-**Access:** http://localhost:24282/dashboard/index.html
-**Shows:**
-- All tool calls Serena makes
-- Language server status
-- Project memory files
-- Token usage estimates
-- Real-time logs
-**Auto-opens** when you start Serena (unless disabled)
----
-## ⚙️ Configuration
-### Project Config (.serena/serena_config.yml)
-After first run, edit `.serena/serena_config.yml` in your project:
-```yaml
-# Ignore certain directories (important!)
-ignored_dirs:
-  - node_modules
-  - .venv
-  - venv
-  - __pycache__
-  - dist
-  - build
-  - .git
-# Read-only mode (no editing)
-read_only: false
-# Disable dangerous shell commands
-disabled_tools:
-  - execute_shell_command
-# Language-specific settings
-languages:
-  python:
-    language_server: "pylsp"
-  typescript:
-    language_server: "typescript-language-server"
-```
-### Contexts (Behavior Modes)
-Serena has different "contexts" for different use cases:
-- `desktop-app` - Default for Claude Desktop
-- `ide-assistant` - Best for Cursor/IDEs (recommended)
-- `agent` - For autonomous operation
-- `planning` - Focus on analysis
-- `editing` - Optimize for code changes
-**Set context in config:**
-```json
-"args": [
-  "serena",
-  "start-mcp-server",
-  "--context",
-  "ide-assistant"
-]
-```
----
-## 🛡️ Safety & Best Practices
-### Critical Warnings
-1. **Backup your work!** Serena can edit code.
-   - Use git: `git add -A && git commit -m "before serena"`
-2. **Inspect commands:** When Serena wants to run shell commands, CHECK THEM!
-3. **Use read-only mode** if you only want analysis:
-   ```yaml
-   read_only: true
-   ```
-4. **Ignore large folders:** Add to `ignored_dirs` or it will scan forever:
-   ```yaml
-   ignored_dirs:
-     - node_modules
-     - .venv
-     - data
-     - logs
-   ```
-### Known Issues
-**Serena hangs on startup:**
-- Usually due to large virtual environments
-- **Fix:** Add venv folders to `ignored_dirs`
-- **Fix:** Delete `.serena/` folder and restart
-**Language server not starting:**
-- Check Serena dashboard logs
-- Serena auto-installs servers, but might fail
-- **Fix:** Manually install (e.g., `pip install python-lsp-server`)
-**Token limits hit:**
-- Serena helps but doesn't eliminate limits
-- **Fix:** Use more focused prompts
-- **Fix:** Work on smaller modules at a time
----
-## 📈 Performance Tips
-### Maximize Token Savings
-1. **Good project structure:**
-   - Well-organized folders
-   - Clear naming conventions
-   - Serena navigates better = fewer tokens
-2. **Use memories:**
-   ```
-   "Read the memories for this project first"
-   ```
-   Then ask your question
-3. **Specific prompts:**
-   ```
-   ❌ "Improve this project"
-   ✅ "Refactor the UserService class to use interfaces"
-   ```
-4. **Let Serena prepare:**
-   ```
-   "Run prepare_for_new_conversation"
-   ```
-   Before starting new chat
-### Speed Up Onboarding
-- Configure `ignored_dirs` BEFORE first run
-- Start with smaller modules
-- Use `.gitignore` (Serena respects it)
----
-## 💡 Real-World Examples
-### Example 1: Bug Hunting
-```
-You: "Find all database queries that don't have error handling"
-Serena: *searches symbols, analyzes code*
-Serena: "Found 5 instances in UserRepository, OrderRepository..."
-You: "Add try-catch blocks to all of them"
-Serena: *edits files with replace_symbol_body*
-```
-### Example 2: Refactoring
-```
-You: "The UserService class is too large. Split it into UserAuthService and UserProfileService"
-Serena: *analyzes dependencies, creates new files, updates imports*
-```
-### Example 3: Understanding New Project
-```
-You: "I just inherited this codebase. Explain the architecture"
-Serena: *reads memories, analyzes structure*
-Serena: "This is a 3-tier architecture with..."
-```
----
-## 🎓 Advanced Usage
-### Custom Memory Files
-You can manually add memory files to `.serena/memories/`:
-**Example:** `.serena/memories/deployment.md`
-```markdown
-# Deployment Process
-1. Run tests: npm test
-2. Build: npm run build
-3. Deploy: ./deploy.sh production
-Database migrations run automatically.
-```
-Serena will read this when relevant!
-### Multiple Projects
-Each project gets its own `.serena/` folder with separate:
-- Memory files
-- Index
-- Configuration
-You can copy memory files between projects for consistency.
-### Integration with Claude Code
-**Claude Code CLI** has special Serena integration:
-```bash
-claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)
-```
-This automatically configures Serena for the current directory!
----
-## 🔧 Troubleshooting
-### Serena Not Showing Up
-**Check:**
-1. Config file syntax is valid JSON
-2. You fully restarted the IDE (not just closed window!)
-3. Look for hammer icon 🔨 in chat
-4. Check IDE logs for MCP errors
-**Claude Desktop logs:**
-```
-C:\Users\sandr\AppData\Roaming\Claude\logs\
-```
-**Cursor logs:**
-```
-%APPDATA%\Cursor\logs\
-```
-### Serena Hangs on Startup
-**Common causes:**
-- Scanning large `node_modules` or `venv`
-- Too many files
-**Fixes:**
-1. Add to `.gitignore` (Serena respects it)
-2. Configure `ignored_dirs` in `serena_config.yml`
-3. Delete `.serena/` and restart
-### Commands Not Working
-**Try:**
-```
-"Use the onboarding tool"
-"Use the find_symbol tool to search for UserService"
-```
-Be explicit about tool names!
-### Out of Context Errors
-Even with Serena, you can hit limits on huge files.
-**Solutions:**
-- Work on smaller modules
-- Split large files
-- Use focused prompts
-- Start new conversation with `prepare_for_new_conversation`
----
-## 📝 Summary: Serena Cheat Sheet
-**Installation:**
-```powershell
-# Quick method
-Add to claude_desktop_config.json:
-{
-  "serena": {
-    "command": "uvx",
-    "args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant"]
-  }
-}
-```
-**First Use:**
-```
-"Run onboarding for this project"
-```
-**Common Commands:**
-```
-"Find all functions that..."
-"Show me where X is defined"
-"Refactor X to use Y"
-"Explain the architecture"
-"Add logging to all endpoints"
-```
-**Dashboard:**
-```
-http://localhost:24282/dashboard/index.html
-```
-**Memory Location:**
-```
-<your-project>/.serena/memories/
-```
-**Config:**
-```
-<your-project>/.serena/serena_config.yml
-```
----
-## 🎯 Is Serena Right for You?
-**YES, if:**
-- ✅ Working on medium/large projects (1000+ lines)
-- ✅ Multi-file codebases with structure
-- ✅ Want to save tokens/API costs
-- ✅ Need semantic code understanding
-- ✅ Projects in Python, JS/TS, Java, Rust, Go
-**MAYBE NOT, if:**
-- ❌ Single-file scripts
-- ❌ Very small projects (<100 lines)
-- ❌ Just need basic text editing
-- ❌ Don't want to manage another tool
----
-## 🔗 Resources
-- **GitHub:** https://github.com/oraios/serena
-- **Issues:** https://github.com/oraios/serena/issues
-- **Changelog:** https://github.com/oraios/serena/releases
-- **Roadmap:** Check GitHub discussions
----
-**Built by:** Oraios AI
-**License:** MIT (Free Open Source)
-**Status:** Active development, 9.8k+ stars, production-ready
----
-**Try it!** It's free, open source, and can save you 70% of tokens. What's not to love? 🚀