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/development/archive/mcp-prompt-templates-vs-docstrings.md DELETED Viewed

@@ -1,657 +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).
-# MCP Prompt Templates vs Docstrings
-## Managing Duplication in MCPB Packages
-**Problem**: When you package an MCP server with `mcpb pack`, you can include prompt templates that duplicate your docstrings, creating maintenance burden.
-**Solution**: Strategic approach to minimize duplication while maximizing Claude's success rate.
----
-## The Duplication Challenge
-### What You Have to Maintain
-1. **Python Docstring** (in your code)
-   ```python
-   def search_bookmarks(query: str, profile_path: Optional[str] = None):
-       """Search Firefox bookmarks by title/URL (requires Firefox closed).
-       Args:
-           query (str, REQUIRED): Search term...
-           profile_path (str, OPTIONAL): Full path...
-       ...
-       """
-   ```
-2. **Prompt Template** (in mcpb package)
-   ```
-   # prompts/search_bookmarks.md
-   When using the search_bookmarks tool:
-   - Always close Firefox first
-   - Use get_firefox_profiles() to find the path
-   - Examples: search_bookmarks(query="plex", limit=20)
-   ```
-**Duplication Risk**: Change docstring but forget prompt template = inconsistent behavior
----
-## Three Approaches to This Problem
-### Approach 1: Docstring Only (Minimal Duplication)
-**When to use**: Simple tools, low token budget, minimal confusion risk
-**Strategy**:
-- Write comprehensive docstrings (following the standard)
-- No separate prompt template
-- MCP framework shows docstring to Claude
-**Pros**:
-- ✅ Single source of truth
-- ✅ No sync issues
-- ✅ Less maintenance
-**Cons**:
-- ❌ Docstrings optimized for humans, not LLMs
-- ❌ May include dev-specific details Claude doesn't need
-- ❌ Can't optimize token usage
-**Example Package Structure**:
-```
-my-mcp-server/
-├── src/
-│   └── tools.py  # Comprehensive docstrings
-├── mcp.json      # No prompt templates
-└── README.md
-```
----
-### Approach 2: Prompt Template + Minimal Docstring (LLM-First)
-**When to use**: Complex tools, high token budget, Claude is primary consumer
-**Strategy**:
-- Minimal docstring (for IDE/developers)
-- Comprehensive prompt template (for Claude)
-- Prompt template is the primary documentation
-**Pros**:
-- ✅ Optimized for LLM consumption
-- ✅ Can be more conversational
-- ✅ Token-optimized
-- ✅ Can include LLM-specific guidance
-**Cons**:
-- ❌ Developers get less help in IDE
-- ❌ Prompt template not visible in code
-- ❌ Still duplication (but reversed priority)
-**Example Package Structure**:
-```
-my-mcp-server/
-├── src/
-│   └── tools.py        # Minimal docstrings
-├── prompts/
-│   ├── search_bookmarks.md
-│   └── list_bookmarks.md
-├── mcp.json            # References prompts/
-└── README.md
-```
----
-### Approach 3: Hybrid with Generation (Best of Both Worlds)
-**When to use**: Professional MCP servers, automation-friendly workflow
-**Strategy**:
-- Write ONE comprehensive source (markdown or JSON)
-- Auto-generate BOTH docstring and prompt template
-- Build script keeps them in sync
-**Pros**:
-- ✅ Single source of truth
-- ✅ Optimized for both humans and LLMs
-- ✅ No sync issues
-- ✅ Can optimize each output format
-**Cons**:
-- ❌ Requires build tooling
-- ❌ More complex workflow
-- ❌ Initial setup overhead
-**Example Package Structure**:
-```
-my-mcp-server/
-├── docs/
-│   └── tools.yaml           # Single source of truth
-├── src/
-│   └── tools.py             # GENERATED docstrings
-├── prompts/
-│   └── search_bookmarks.md  # GENERATED from docs/
-├── scripts/
-│   └── generate_docs.py     # Generation script
-├── mcp.json
-└── README.md
-```
----
-## Recommended: Approach 3 with YAML Source
-### Single Source of Truth Format
-```yaml
-# docs/tools/search_bookmarks.yaml
-name: search_bookmarks
-category: firefox
-summary: Search Firefox bookmarks by title/URL (requires Firefox closed)
-prerequisites:
-  - Firefox must be completely closed
-  - Profile must exist with places.sqlite
-  - Read permissions on profile directory
-parameters:
-  - name: query
-    type: string
-    required: true
-    description: Search term to find in titles/URLs
-    format: Case-insensitive partial match
-    examples:
-      - "plex"
-      - "github.com"
-      - "machine learning"
-  - name: profile_path
-    type: string
-    required: false
-    default: Auto-detect from profiles.ini
-    description: Full path to Firefox profile directory
-    format: "C:\\Users\\{user}\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\{profile}"
-    examples:
-      - "C:\\Users\\sandr\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\airiswdq.default-release"
-    get_value_from: get_firefox_profiles()
-  - name: limit
-    type: integer
-    required: false
-    default: 50
-    range: [1, 100]
-    description: Maximum results to return
-returns:
-  success:
-    status: success
-    query: str
-    count: int
-    results:
-      - id: int
-        title: str
-        url: str
-        dateAdded: int
-        parent: int
-  error:
-    status: error
-    error: str
-    suggestion: str
-errors:
-  - condition: "Database is locked"
-    cause: Firefox is running
-    fix: Close Firefox completely (check Task Manager)
-    workaround: Use export_bookmarks() instead
-  - condition: "Profile not found"
-    cause: Invalid path or doesn't exist
-    fix: Use get_firefox_profiles() to find path
-    check: Verify places.sqlite exists
-examples:
-  - name: Basic search (most common)
-    when: Single profile, Firefox closed
-    code: |
-      search_bookmarks(query="plex")
-    returns: Up to 50 bookmarks matching "plex"
-  - name: Specific profile
-    when: Multiple profiles or auto-detect fails
-    code: |
-      search_bookmarks(
-          query="immich",
-          profile_path="C:\\Users\\sandr\\AppData\\Roaming\\Mozilla\\Firefox\\Profiles\\airiswdq.default-release",
-          limit=20
-      )
-    returns: Up to 20 bookmarks from specified profile
-platforms:
-  windows:
-    location: "%APPDATA%\\Mozilla\\Firefox\\Profiles\\"
-    format: Double backslashes "C:\\Users\\..."
-    check_process: Task Manager → firefox.exe
-  linux:
-    location: "~/.mozilla/firefox/"
-    format: Forward slashes "/home/user/..."
-    check_process: ps aux | grep firefox
-  macos:
-    location: "~/Library/Application Support/Firefox/Profiles/"
-    format: Forward slashes (with spaces)
-    check_process: Activity Monitor
-see_also:
-  - get_firefox_profiles: Find available profiles (use first)
-  - list_bookmarks: Browse all bookmarks
-  - export_bookmarks: Export while Firefox open
-```
----
-### Generation Script
-```python
-# scripts/generate_docs.py
-import yaml
-from pathlib import Path
-from jinja2 import Template
-def generate_docstring(tool_spec):
-    """Generate Python docstring from YAML spec"""
-    template = Template('''"""{{ summary }}
-    {{ description }}
-    Prerequisites:
-    {% for prereq in prerequisites %}    - {{ prereq }}
-    {% endfor %}
-    Args:
-    {% for param in parameters %}    {{ param.name }} ({{ param.type }}, {{ 'REQUIRED' if param.required else 'OPTIONAL' }}):
-            {{ param.description }}
-            {% if param.format %}Format: {{ param.format }}{% endif %}
-            {% if param.examples %}Examples: {{ param.examples|join(', ') }}{% endif %}
-            {% if not param.required %}Default: {{ param.default }}{% endif %}
-            {% if param.get_value_from %}Get value: {{ param.get_value_from }}{% endif %}
-    {% endfor %}
-    Returns:
-        dict: {{ returns.success.status }}
-        Structure (Success):
-        {{ returns.success|format_structure }}
-        Structure (Error):
-        {{ returns.error|format_structure }}
-    Common Issues:
-    {% for error in errors %}    {{ loop.index }}. "{{ error.condition }}"
-           CAUSE: {{ error.cause }}
-           FIX: {{ error.fix }}
-           {% if error.workaround %}WORKAROUND: {{ error.workaround }}{% endif %}
-    {% endfor %}
-    Examples:
-    {% for example in examples %}    # {{ example.name }}
-        # Use when: {{ example.when }}
-        {{ example.code }}
-        # Returns: {{ example.returns }}
-    {% endfor %}
-    Platform Notes:
-    {% for platform, details in platforms.items %}    {{ platform.upper() }}:
-            - Location: {{ details.location }}
-            - Format: {{ details.format }}
-            - Check: {{ details.check_process }}
-    {% endfor %}
-    See Also:
-    {% for tool, desc in see_also.items %}    - {{ tool }}(): {{ desc }}
-    {% endfor %}"""''')
-    return template.render(**tool_spec)
-def generate_prompt_template(tool_spec):
-    """Generate Claude prompt template from YAML spec"""
-    template = Template('''# {{ name }} Tool Guide
-## Quick Summary
-{{ summary }}
-**CRITICAL**: {% for prereq in prerequisites %}{{ prereq }}{% if not loop.last %}, {% endif %}{% endfor %}
-## How to Use
-### Parameters
-{% for param in parameters %}
-**{{ param.name }}** ({{ 'REQUIRED' if param.required else 'OPTIONAL' }})
-- What: {{ param.description }}
-- {% if param.examples %}Example: `{{ param.examples[0] }}`{% endif %}
-- {% if not param.required %}Default: {{ param.default }}{% endif %}
-{% if param.get_value_from %}- Get from: {{ param.get_value_from }}{% endif %}
-{% endfor %}
-### Common Patterns
-{% for example in examples %}
-**{{ example.name }}**
-```python
-{{ example.code }}
-```
-Use when: {{ example.when }}
-{% endfor %}
-### When Things Go Wrong
-{% for error in errors %}
-**Problem**: {{ error.condition }}
-- Why: {{ error.cause }}
-- Fix: {{ error.fix }}
-{% if error.workaround %}- Alternative: {{ error.workaround }}{% endif %}
-{% endfor %}
-### Platform Differences
-{% for platform, details in platforms.items %}
-**{{ platform.title() }}**: {{ details.location }}
-- Check if closed: {{ details.check_process }}
-{% endfor %}
-### Related Tools
-{% for tool, desc in see_also.items %}
-- `{{ tool }}()` - {{ desc }}
-{% endfor %}
-''')
-    return template.render(**tool_spec)
-def generate_all():
-    """Generate all documentation from YAML sources"""
-    docs_dir = Path("docs/tools")
-    for yaml_file in docs_dir.glob("*.yaml"):
-        with open(yaml_file) as f:
-            spec = yaml.safe_load(f)
-        # Generate docstring (for insertion into Python code)
-        docstring = generate_docstring(spec)
-        output_file = Path("generated/docstrings") / f"{spec['name']}.txt"
-        output_file.parent.mkdir(exist_ok=True)
-        output_file.write_text(docstring)
-        # Generate prompt template (for mcpb package)
-        prompt = generate_prompt_template(spec)
-        prompt_file = Path("prompts") / f"{spec['name']}.md"
-        prompt_file.parent.mkdir(exist_ok=True)
-        prompt_file.write_text(prompt)
-        print(f"✅ Generated docs for {spec['name']}")
-if __name__ == "__main__":
-    generate_all()
-```
----
-### Workflow Integration
-```toml
-# pyproject.toml
-[tool.mcp]
-generate_docs = "scripts/generate_docs.py"
-[tool.mcp.build]
-pre_build = ["python scripts/generate_docs.py"]
-```
-```bash
-# Build workflow
-python scripts/generate_docs.py  # Generate docstrings + prompt templates
-mcpb validate                     # Validate package
-mcpb pack                        # Package with generated prompts
-```
----
-## Prompt Template Best Practices
-### What to Include in Prompt Templates (That Docstrings Don't Need)
-1. **Conversational Tone**
-   ```markdown
-   # search_bookmarks Tool
-   This tool helps you find bookmarks in Firefox. Before using it,
-   **make sure Firefox is completely closed** - otherwise the database
-   will be locked and the search will fail.
-   ```
-2. **Common User Mistakes**
-   ```markdown
-   ## Common Mistakes to Avoid
-   ❌ Don't use this while Firefox is running
-   ❌ Don't use relative paths for profile_path
-   ❌ Don't forget to call get_firefox_profiles() first
-   ✅ Close Firefox completely
-   ✅ Use full absolute paths
-   ✅ Get profile path from get_firefox_profiles()
-   ```
-3. **Decision Trees**
-   ```markdown
-   ## When to Use This Tool
-   Use search_bookmarks() when:
-   - You know what you're looking for (have search term)
-   - Firefox is closed
-   - You want fast, targeted results
-   Use list_bookmarks() instead when:
-   - You want to browse all bookmarks
-   - You don't know what you're searching for
-   - You want folder structure
-   ```
-4. **LLM-Specific Guidance**
-   ```markdown
-   ## For AI Assistants
-   Before calling this tool:
-   1. Check if Firefox is mentioned as running in conversation
-   2. If user has multiple profiles, call get_firefox_profiles() first
-   3. If this fails with "locked", suggest export_bookmarks() alternative
-   After calling:
-   - If count is 0, suggest broader search terms
-   - If count is high, offer to filter results
-   - Always show at least title and URL for each result
-   ```
----
-## Token Optimization
-### Docstring vs Prompt Template Token Usage
-**Full Docstring** (comprehensive): ~500-1000 tokens per tool
-**Prompt Template** (optimized): ~200-400 tokens per tool
-### Optimization Strategies
-1. **Use References Instead of Repetition**
-   ```markdown
-   # Instead of repeating full structure:
-   Returns the same structure as list_bookmarks() but filtered by query.
-   See list_bookmarks documentation for full return structure.
-   ```
-2. **Common Errors Document**
-   ```markdown
-   # Create shared errors.md
-   All Firefox tools may encounter these errors: [see errors.md]
-   Tool-specific errors:
-   - "No results found" → Try broader search terms
-   ```
-3. **Platform Notes Once**
-   ```markdown
-   # Share platform.md across all Firefox tools
-   Firefox Profile Locations: [see platform.md]
-   ```
-4. **Conditional Inclusion**
-   ```json
-   // mcp.json
-   {
-     "prompts": {
-       "search_bookmarks": {
-         "file": "prompts/search_bookmarks.md",
-         "include_shared": ["firefox_common", "platform_notes"]
-       }
-     }
-   }
-   ```
----
-## Recommended Structure for MCP Packages
-```
-my-firefox-mcp/
-├── src/
-│   └── tools.py                # Minimal docstrings
-├── docs/
-│   ├── tools/
-│   │   ├── search_bookmarks.yaml
-│   │   ├── list_bookmarks.yaml
-│   │   └── get_firefox_profiles.yaml
-│   └── shared/
-│       ├── firefox_common.md   # Shared concepts
-│       ├── platform.md         # Platform differences
-│       └── errors.md           # Common errors
-├── prompts/                    # GENERATED
-│   ├── search_bookmarks.md
-│   └── list_bookmarks.md
-├── generated/                  # GENERATED
-│   └── docstrings/
-│       └── search_bookmarks.txt
-├── scripts/
-│   └── generate_docs.py
-├── mcp.json
-└── README.md
-```
----
-## Practical Example: Your dbops Server
-### Current State (Duplication Hell)
-```python
-# In Python code
-def search_bookmarks(query, profile_path=None, limit=50):
-    """Search bookmarks by title or URL."""  # ❌ Inadequate
-```
-```markdown
-# In prompts/search_bookmarks.md (if it existed)
-When searching Firefox bookmarks:
-- Close Firefox first
-- Use get_firefox_profiles() to find path
-- Example: search_bookmarks(query="plex")
-```
-**Problem**: Two places to update, easily get out of sync
----
-### Recommended Approach
-```yaml
-# docs/tools/search_bookmarks.yaml (SINGLE SOURCE)
-name: search_bookmarks
-category: firefox
-summary: Search Firefox bookmarks (requires Firefox closed)
-# ... full spec as shown above
-```
-```python
-# scripts/generate_docs.py
-# Generates both:
-# - src/tools.py docstring
-# - prompts/search_bookmarks.md
-```
-```bash
-# Build command
-python scripts/generate_docs.py && mcpb pack
-```
-**Benefit**: Change YAML once, both outputs updated automatically
----
-## Migration Path
-### Step 1: Audit Current State (5 min)
-```bash
-# Count your duplication
-grep -r "def.*(" src/ | wc -l        # Python functions
-find prompts/ -name "*.md" | wc -l   # Prompt templates
-# If prompt_count > 0: You have duplication
-```
-### Step 2: Choose Approach (5 min)
-- Simple server (<10 tools): Approach 1 (docstring only)
-- Medium server (10-30 tools): Approach 2 (prompt template primary)
-- Complex server (>30 tools): Approach 3 (generated)
-### Step 3: Implement (varies)
-- Approach 1: Enhance docstrings, remove prompt templates
-- Approach 2: Write comprehensive prompt templates, minimal docstrings
-- Approach 3: Create YAML specs, write generation script
-### Step 4: Automate (1 hour)
-```python
-# Add pre-commit hook
-# .git/hooks/pre-commit
-#!/bin/bash
-python scripts/generate_docs.py
-git add generated/ prompts/
-```
----
-## Conclusion
-**The Duplication Dilemma**: Docstrings vs prompt templates
-**The Solution**:
-- Small servers: Comprehensive docstrings only
-- Large servers: Single source YAML → generate both
-- All servers: Never manually maintain both!
-**The Tools**:
-- YAML for canonical source
-- Jinja2 for generation
-- Pre-commit hooks for automation
-- mcpb for packaging
-**The Result**: Claude succeeds on first try, developers get great IDE support, no sync issues.
----
-## References
-- **MCPB Documentation**: https://github.com/anthropics/mcpb
-- **MCP Prompt Templates**: [Link to official docs]
-- **FastMCP Guide**: https://github.com/jlowin/fastmcp
-- **This Document**: Part of MCP Tool Documentation Standards v1.0