npm - @hybridlabor-api/aos - Versions diffs - 4.3.0 → 4.4.1 - Mend

@hybridlabor-api/aos 4.3.0 → 4.4.1

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 (1052) hide show

package/mcps/windows-computer-use-mcp/docs/_stale/development/archive/PYTHON_SNIPPETS_USAGE_GUIDE.md DELETED Viewed

@@ -1,717 +0,0 @@
-> **Archived fleet import** — From **notepadpp-mcp** / generic fleet dev notes. **Not** pywinauto-mcp source of truth. See [DEVELOPMENT.md](../../DEVELOPMENT.md) and [TESTING.md](../../TESTING.md).
-# 🐍 Python Snippets Usage Guide
-**Complete Practical Guide: How to Use Python Snippets from Documentation**
-**Real-World Examples, Common Issues, and Step-by-Step Instructions**
----
-## 🎯 **Overview**
-This guide explains **exactly how to use** the Python snippets shown in the MCP server documentation. You'll learn:
-- ✅ **How to create Python files** from snippets
-- ✅ **What imports are needed** for each snippet type
-- ✅ **How to install dependencies** and run code
-- ✅ **How to test and debug** your MCP servers
-- ✅ **Common mistakes to avoid** and how to fix them
----
-## 🚀 **Quick Start: Copy-Paste-Run**
-### **Step 1: Create Your Python File**
-**Method 1: VS Code/Cursor**
-1. **File** → **New File**
-2. **Save As**: `my_mcp_server.py`
-3. **Copy snippet** from documentation into the file
-**Method 2: Command Line**
-```bash
-# Create new file
-touch my_mcp_server.py
-# Edit with any editor
-code my_mcp_server.py  # VS Code
-notepad my_mcp_server.py  # Notepad
-```
-### **Step 2: Install Dependencies**
-```bash
-# Install FastMCP and required packages
-pip install fastmcp pydantic
-# For async support (if using async tools)
-pip install aiohttp
-# For logging (recommended)
-pip install structlog
-# For monitoring (optional)
-pip install prometheus-client
-```
-### **Step 3: Copy & Modify Snippets**
-#### **Basic Server Example**
-```python
-#!/usr/bin/env python3
-"""
-My First MCP Server
-"""
-from fastmcp import FastMCP
-# Create your server
-app = FastMCP("my-server")
-@app.tool()
-def hello_world() -> str:
-    """A simple hello world tool."""
-    return "Hello from my MCP server!"
-if __name__ == "__main__":
-    print("Starting MCP server...")
-    app.run()
-```
-#### **Server with Parameters**
-```python
-#!/usr/bin/env python3
-"""
-MCP Server with Parameters
-"""
-from fastmcp import FastMCP
-from pydantic import BaseModel
-from typing import Annotated
-class ToolParams(BaseModel):
-    name: Annotated[str, {"description": "Name to greet"}]
-    age: Annotated[int, {"description": "Age of person"}] = None
-app = FastMCP("my-server")
-@app.tool()
-def greet_person(params: ToolParams) -> str:
-    """Greet a person with optional age."""
-    if params.age:
-        return f"Hello {params.name}! You are {params.age} years old."
-    else:
-        return f"Hello {params.name}!"
-if __name__ == "__main__":
-    app.run()
-```
-#### **Async Tool Example**
-```python
-#!/usr/bin/env python3
-"""
-Async MCP Server Example
-"""
-import asyncio
-from fastmcp import FastMCP
-app = FastMCP("async-server")
-@app.tool()
-async def async_operation(task_name: str) -> str:
-    """An async tool that simulates I/O operations."""
-    print(f"Starting async task: {task_name}")
-    await asyncio.sleep(1)  # Simulate async work
-    print(f"Completed async task: {task_name}")
-    return f"Async task '{task_name}' completed successfully!"
-if __name__ == "__main__":
-    app.run()
-```
-### **Step 4: Run Your Server**
-**Simple Run:**
-```bash
-python my_mcp_server.py
-```
-**With Environment Variables:**
-```bash
-# Windows
-set LOG_LEVEL=debug
-python my_mcp_server.py
-# Linux/Mac
-export LOG_LEVEL=debug
-python my_mcp_server.py
-```
-### **Step 5: Test Your Server**
-**Method 1: MCPJam (Recommended)**
-```bash
-# Install MCPJam globally
-npm install -g mcpjam
-# Test your server
-mcpjam test --server "python my_mcp_server.py"
-# Interactive testing
-mcpjam interactive --server "python my_mcp_server.py"
-```
-**Method 2: HTTP API Test**
-```bash
-# List tools
-curl -X POST http://localhost:8000/tools \
-     -H "Content-Type: application/json" \
-     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
-# Call tool
-curl -X POST http://localhost:8000/tools \
-     -H "Content-Type: application/json" \
-     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "hello_world"}}'
-```
----
-## 📦 **Complete Working Example**
-**Create file**: `complete_example.py`
-```python
-#!/usr/bin/env python3
-"""
-Complete MCP Server Example
-Copy and modify this for your own server
-"""
-from fastmcp import FastMCP
-from pydantic import BaseModel
-from typing import Optional
-import logging
-# Configure logging
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-# Create server
-app = FastMCP("complete-example")
-# Simple tool
-@app.tool()
-def health_check() -> dict:
-    """Check server health."""
-    return {
-        "status": "healthy",
-        "server": "complete-example",
-        "version": "1.0.0"
-    }
-# Tool with parameters
-class MathParams(BaseModel):
-    operation: str  # "add", "subtract", "multiply", "divide"
-    a: float
-    b: float
-@app.tool()
-def calculate(params: MathParams) -> float:
-    """Perform mathematical calculations."""
-    logger.info(f"Calculating: {params.a} {params.operation} {params.b}")
-    if params.operation == "add":
-        return params.a + params.b
-    elif params.operation == "subtract":
-        return params.a - params.b
-    elif params.operation == "multiply":
-        return params.a * params.b
-    elif params.operation == "divide":
-        if params.b == 0:
-            raise ValueError("Cannot divide by zero")
-        return params.a / params.b
-    else:
-        raise ValueError(f"Unknown operation: {params.operation}")
-# Async tool example
-import asyncio
-@app.tool()
-async def async_task(task_name: str) -> str:
-    """Simulate an async task."""
-    logger.info(f"Starting async task: {task_name}")
-    await asyncio.sleep(1)  # Simulate work
-    logger.info(f"Completed async task: {task_name}")
-    return f"Task '{task_name}' completed successfully!"
-if __name__ == "__main__":
-    print("🚀 Complete MCP Server Example")
-    print("Available tools:")
-    print("- health_check() -> dict")
-    print("- calculate(operation: MathParams) -> float")
-    print("- async_task(task_name: str) -> str")
-    print()
-    print("Run with: python complete_example.py")
-    print("Test with: mcpjam test --server 'python complete_example.py'")
-    app.run()
-```
-**Run this example:**
-```bash
-python complete_example.py
-```
----
-## 🔧 **Common Imports Reference**
-### **Basic Imports**
-```python
-# Basic FastMCP
-from fastmcp import FastMCP
-# Pydantic models
-from pydantic import BaseModel, field_validator
-from typing import Annotated
-# Logging
-import logging
-import sys
-# Standard library
-from datetime import datetime
-from typing import Dict, Any, List, Optional
-```
-### **Advanced Imports**
-```python
-# Async support
-import asyncio
-import aiohttp
-# HTTP server for testing
-from fastmcp.server import FastMCPServer
-# Monitoring
-from prometheus_client import Counter, Histogram, Gauge, start_http_server
-# File operations
-import os
-import json
-# Error handling
-from functools import wraps
-```
-### **Environment & Configuration**
-```python
-# Environment variables
-import os
-from dotenv import load_dotenv
-load_dotenv()
-# Configuration from env
-SERVER_NAME = os.getenv("SERVER_NAME", "my-server")
-LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO")
-PORT = int(os.getenv("PORT", "8000"))
-```
----
-## 🐛 **Common Issues & Solutions**
-### **Issue 1: "Module not found"**
-```bash
-# ❌ Error: ImportError: No module named 'fastmcp'
-# ✅ Solution: Install dependencies
-pip install fastmcp pydantic
-# Check Python path
-python -c "import sys; print(sys.path)"
-# Verify installation
-python -c "import fastmcp; print('FastMCP installed successfully')"
-```
-### **Issue 2: "Port already in use"**
-```python
-# ❌ Error: Address already in use
-# ✅ Solution: Change port
-app = FastMCP("my-server", host="127.0.0.1", port=8001)
-# Or use dynamic port allocation
-import socket
-def find_free_port(start=8000, end=9000):
-    for port in range(start, end):
-        try:
-            with socket.socket() as s:
-                s.bind(("", port))
-                return port
-        except OSError:
-            continue
-    raise RuntimeError("No free ports")
-PORT = find_free_port()
-app = FastMCP("my-server", port=PORT)
-```
-### **Issue 3: "Import errors with FastMCP 2.12"**
-```python
-# ❌ Wrong imports (FastMCP 1.x)
-from fastmcp import Tool, Client
-# ✅ Correct imports (FastMCP 2.12)
-from fastmcp import FastMCP
-app = FastMCP("my-server")
-@app.tool()
-def my_function():
-    return "Hello World"
-```
-### **Issue 4: "Server starts but disconnects"**
-```python
-# ❌ Wrong: Using stdout for logging
-print("Server started")  # Breaks stdio protocol
-# ✅ Correct: Use logging or stderr
-import logging
-logger = logging.getLogger(__name__)
-logger.info("Server started")
-# OR use stderr for debugging
-import sys
-print("Debug info", file=sys.stderr)
-```
-### **Issue 5: "Pydantic validation errors"**
-```python
-# ❌ Wrong: Pydantic V1 syntax
-from pydantic import BaseModel, validator
-class User(BaseModel):
-    email: str
-    @validator('email')
-    def validate_email(cls, v):
-        return v.lower()
-# ✅ Correct: Pydantic V2 syntax
-from pydantic import BaseModel, field_validator
-class User(BaseModel):
-    email: str
-    @field_validator('email')
-    @classmethod
-    def validate_email(cls, v):
-        return v.lower()
-```
----
-## 🧪 **Testing Your MCP Server**
-### **Method 1: MCPJam Testing**
-```bash
-# Install MCPJam
-npm install -g mcpjam
-# Basic test
-mcpjam test --server "python my_mcp_server.py"
-# Interactive testing
-mcpjam interactive --server "python my_mcp_server.py"
-# Load testing
-mcpjam load --server "python my_mcp_server.py" --requests 100
-# Performance profiling
-mcpjam profile --server "python my_mcp_server.py"
-```
-### **Method 2: Python Unit Tests**
-```python
-# test_my_server.py
-import pytest
-from my_mcp_server import app
-def test_health_check():
-    result = app.call_tool("health_check", {})
-    assert result["status"] == "healthy"
-def test_calculate_add():
-    result = app.call_tool("calculate", {
-        "operation": "add",
-        "a": 5,
-        "b": 3
-    })
-    assert result == 8
-if __name__ == "__main__":
-    test_health_check()
-    test_calculate_add()
-    print("✅ All tests passed!")
-```
-### **Method 3: HTTP API Testing**
-```bash
-# Test tool listing
-curl -X POST http://localhost:8000/tools \
-     -H "Content-Type: application/json" \
-     -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' \
-     | python -m json.tool
-# Test tool execution
-curl -X POST http://localhost:8000/tools \
-     -H "Content-Type: application/json" \
-     -d '{
-         "jsonrpc": "2.0",
-         "id": 2,
-         "method": "tools/call",
-         "params": {
-             "name": "calculate",
-             "arguments": {
-                 "operation": "add",
-                 "a": 10,
-                 "b": 5
-             }
-         }
-     }' | python -m json.tool
-```
----
-## 📊 **Debugging Workflow**
-### **Step 1: Test Imports First**
-```bash
-# Test if all imports work
-python -c "
-try:
-    from fastmcp import FastMCP
-    from pydantic import BaseModel
-    print('✅ All imports successful')
-except ImportError as e:
-    print(f'❌ Import error: {e}')
-"
-```
-### **Step 2: Test Individual Functions**
-```python
-# Test tool functions before MCP integration
-def test_my_function():
-    # Test your tool logic
-    result = my_tool_function("test_input")
-    print(f"Function result: {result}")
-    return result
-# Run test
-test_my_function()
-```
-### **Step 3: Test Server Startup**
-```bash
-# Start server in test mode
-python -c "
-from my_mcp_server import app
-print('✅ Server imports work')
-# Test individual tools
-try:
-    result = app.call_tool('hello_world', {})
-    print(f'✅ Tool call successful: {result}')
-except Exception as e:
-    print(f'❌ Tool call failed: {e}')
-"
-```
-### **Step 4: Full Server Test**
-```bash
-# Run full server
-python my_mcp_server.py
-# In another terminal, test with MCPJam
-mcpjam test --server "python my_mcp_server.py"
-```
----
-## 🚨 **Common Mistakes to Avoid**
-### **❌ DON'T: Use print() to stdout**
-```python
-# ❌ WRONG - Breaks stdio protocol
-print("Server started")
-print(f"Error: {error}")
-# ✅ CORRECT - Use logging
-logger.info("Server started")
-logger.error(f"Error: {error}")
-# ✅ ACCEPTABLE - Debug info to stderr
-print("Debug: Processing request...", file=sys.stderr)
-```
-### **❌ DON'T: Mix sync/async incorrectly**
-```python
-# ❌ WRONG - Async/sync mismatch
-@app.tool()
-def mixed_tool():
-    return asyncio.run(async_function())  # Wrong!
-# ✅ CORRECT - Proper async patterns
-@app.tool()
-async def async_tool():
-    return await async_function()  # Correct!
-```
-### **❌ DON'T: Ignore error handling**
-```python
-# ❌ WRONG - No error handling
-@app.tool()
-def risky_tool(param: str):
-    return 1 / int(param)  # Will crash on "0"
-# ✅ CORRECT - Comprehensive error handling
-@app.tool()
-def safe_tool(param: str):
-    try:
-        result = 1 / int(param)
-        return f"Result: {result}"
-    except ValueError:
-        return "Invalid number"
-    except ZeroDivisionError:
-        return "Cannot divide by zero"
-    except Exception as e:
-        logger.error(f"Unexpected error: {e}")
-        return f"Error: {str(e)}"
-```
-### **❌ DON'T: Use Pydantic V1 syntax**
-```python
-# ❌ WRONG - Pydantic V1
-from pydantic import BaseModel, validator
-class User(BaseModel):
-    email: str
-    @validator('email')
-    def validate_email(cls, v):
-        return v.lower()
-# ✅ CORRECT - Pydantic V2
-from pydantic import BaseModel, field_validator
-class User(BaseModel):
-    email: str
-    @field_validator('email')
-    @classmethod
-    def validate_email(cls, v):
-        return v.lower()
-```
----
-## 🎯 **Best Practices Summary**
-### **✅ DO: Follow These Patterns**
-1. **Use proper logging** instead of print statements
-2. **Handle all errors** gracefully in tool functions
-3. **Test incrementally** - each change should be tested
-4. **Use type hints** for better IDE support
-5. **Document your tools** with clear descriptions
-6. **Validate inputs** using Pydantic models
-7. **Use async properly** for I/O operations
-8. **Test with MCPJam** before production use
-### **✅ DO: Structure Your Code**
-```python
-# Good structure
-from fastmcp import FastMCP
-import logging
-# Configure logging
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-# Create server
-app = FastMCP("my-server")
-@app.tool()
-def my_tool(param: str) -> str:
-    """Clear description of what this tool does."""
-    try:
-        # Your logic here
-        result = process_param(param)
-        logger.info(f"Processed: {result}")
-        return result
-    except Exception as e:
-        logger.error(f"Error: {e}")
-        return f"Error processing request: {str(e)}"
-if __name__ == "__main__":
-    app.run()
-```
----
-## 📈 **Success Metrics**
-### **You Are Successful If:**
-- ✅ **Server starts** without import errors
-- ✅ **Tools appear** in Claude Desktop/MCPJam
-- ✅ **Tools execute** and return correct results
-- ✅ **Error handling** works properly
-- ✅ **Logging** provides useful debugging info
-- ✅ **No stdio errors** (no stdout print statements)
-### **You Need Help If:**
-- ❌ **Import errors** on startup
-- ❌ **Tools don't appear** in interface
-- ❌ **Server disconnects** immediately
-- ❌ **Stdio transport errors** in logs
-- ❌ **Pydantic validation errors** for tool parameters
----
-## 🚀 **Next Steps**
-1. **Copy any snippet** from the documentation
-2. **Create a new .py file** with the snippet
-3. **Install dependencies** with pip
-4. **Test with MCPJam** or HTTP calls
-5. **Debug any issues** using the troubleshooting section
-6. **Add your own logic** to customize the tools
----
-## 🎉 **Ready to Build MCP Servers!**
-**You now have everything needed to:**
-- ✅ **Create MCP servers** from documentation snippets
-- ✅ **Test and debug** your servers properly
-- ✅ **Avoid common mistakes** that break functionality
-- ✅ **Deploy production-ready** MCP servers
-- ✅ **Integrate with Claude Desktop** seamlessly
-**Start by copying the "Complete Working Example" above into a new file and running it!**
-**What type of MCP server would you like to create?** 🐍🔧✨
----
-**This guide is maintained in basic-memory for easy reference:**
-- **Search**: `search_notes("python snippets", project="claude-depot-consolidated")`
-- **Read**: `read_note("PYTHON_SNIPPETS_USAGE_GUIDE", project="claude-depot-consolidated")`
-**Happy coding!** 🚀🐍