avanza-mcp 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

avanza_mcp/__init__.py

@@ -12,7 +12,7 @@ Provides access to:
 - Real-time market status and trading hours
 """
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 from fastmcp import FastMCP
 

avanza_mcp/prompts/__init__.py

@@ -2,5 +2,6 @@
 
 # Import to register prompts via decorators
 from . import analysis  # noqa: F401
+from . import workflows  # noqa: F401
 
-__all__ = ["analysis"]
+__all__ = ["analysis", "workflows"]

avanza_mcp/prompts/workflows.py

@@ -0,0 +1,488 @@
+"""Workflow prompt templates emphasizing when to provide scripts vs using tools."""
+
+from .. import mcp
+
+
+@mcp.prompt()
+def bulk_data_script_guide(item_count: int, operation_type: str) -> str:
+    """Guide for providing scripts for bulk data operations.
+
+    Use this when user requests data for 50+ items.
+
+    Args:
+        item_count: Number of items to fetch
+        operation_type: Type of operation (e.g., "stock analysis", "ETF screening")
+
+    Returns:
+        Prompt explaining why and how to provide a script
+    """
+    return f"""For {operation_type} involving {item_count} items, I should provide a script instead of using MCP tools.
+
+## Why Not Use MCP Tools?
+
+Making {item_count} MCP tool calls would:
+- Take 5-10 minutes to complete
+- Overload the MCP connection
+- Be inefficient and error-prone
+
+## What to Provide Instead
+
+I'll give you a ready-to-run script that:
+- Fetches all {item_count} items in parallel (30-60 seconds)
+- Saves data to a file for analysis
+- Includes error handling and rate limiting
+
+### Python Script Template (Recommended)
+```python
+import httpx
+import asyncio
+import json
+from datetime import datetime
+
+async def fetch_item(client, item_id):
+    \"\"\"Fetch single item with error handling.\"\"\"
+    try:
+        url = "https://www.avanza.se/_api/..."  # Specific endpoint
+        response = await client.get(url, timeout=30.0)
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        print(f"Error fetching {{item_id}}: {{e}}")
+        return None
+
+async def main():
+    item_ids = [...]  # Your {item_count} IDs
+
+    print(f"Fetching {{len(item_ids)}} items...")
+
+    async with httpx.AsyncClient() as client:
+        tasks = [fetch_item(client, iid) for iid in item_ids]
+        results = await asyncio.gather(*tasks)
+
+    # Filter out errors
+    valid_results = [r for r in results if r is not None]
+
+    # Save to file
+    output_file = f"data_{{datetime.now().strftime('%Y%m%d_%H%M%S')}}.json"
+    with open(output_file, 'w') as f:
+        json.dump(valid_results, f, indent=2)
+
+    print(f"✅ Fetched {{len(valid_results)}}/{{len(item_ids)}} items")
+    print(f"📁 Saved to {{output_file}}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### How to Run
+```bash
+# Install dependencies
+pip install httpx
+
+# Run the script
+python fetch_data.py
+
+# Analyze the results
+# I can help you analyze the JSON file after you run this!
+```
+
+## Next Steps
+
+After you run the script:
+1. Share the output file with me (or key findings)
+2. I can help analyze patterns, create visualizations, etc.
+3. We can drill down into specific interesting items using MCP tools
+"""
+
+
+@mcp.prompt()
+def decide_tool_or_script(user_request: str, estimated_items: int) -> str:
+    """Help decide whether to use tools or provide a script.
+
+    Args:
+        user_request: What the user wants to do
+        estimated_items: Estimated number of items to process
+
+    Returns:
+        Decision prompt
+    """
+    if estimated_items <= 20:
+        approach = "use MCP tools"
+        reason = "small enough for interactive exploration"
+    elif estimated_items <= 50:
+        approach = "ask user preference"
+        reason = "medium size - tools work but script is faster"
+    else:
+        approach = "provide script"
+        reason = "too many for MCP tools - script is much more efficient"
+
+    return f"""Request: "{user_request}"
+Estimated items: {estimated_items}
+
+## Decision: {approach.upper()}
+
+**Reason**: {reason}
+
+**Approach**:
+{"I'll use MCP tools to fetch data interactively." if estimated_items <= 20 else
+ "I'll ask if you prefer tools (interactive) or script (faster)." if estimated_items <= 50 else
+ "I'll provide a Python/bash script for efficient bulk fetching."}
+
+{"" if estimated_items <= 20 else f'''
+## Script Template
+
+For {estimated_items} items, here's what I'll provide:
+
+```python
+# Efficient parallel fetching
+import httpx
+import asyncio
+
+async def fetch_all(ids):
+    async with httpx.AsyncClient() as client:
+        tasks = [client.get(f"https://www.avanza.se/_api/.../{{id}}") for id in ids]
+        responses = await asyncio.gather(*tasks, return_exceptions=True)
+        return [r.json() for r in responses if hasattr(r, 'json')]
+
+# Run and save
+results = asyncio.run(fetch_all(your_{estimated_items}_ids))
+```
+
+This completes in ~30-60 seconds vs {estimated_items * 2}+ seconds with MCP tools.
+'''}
+"""
+
+
+@mcp.prompt()
+def filter_large_dataset(instrument_type: str, criteria: str) -> str:
+    """Guide for filtering large datasets using API endpoints directly.
+
+    Args:
+        instrument_type: Type (certificates, etfs, warrants, etc.)
+        criteria: Filtering criteria
+
+    Returns:
+        Prompt with curl/script for bulk filtering
+    """
+    filter_endpoints = {
+        "certificates": "market-certificate-filter",
+        "etfs": "market-etf-filter",
+        "warrants": "market-warrant-filter",
+    }
+
+    endpoint = filter_endpoints.get(instrument_type.lower(), "market-etf-filter")
+
+    return f"""To screen {instrument_type} with criteria: {criteria}
+
+## Use the Filter API Directly (Don't Loop Through MCP Tools)
+
+Instead of calling MCP tools repeatedly, use the filter endpoint:
+
+### Option 1: curl Command (Quick & Simple)
+
+```bash
+curl 'https://www.avanza.se/_api/{endpoint}/' \\
+  -H 'Content-Type: application/json' \\
+  --data-raw '{{
+    "filter": {{
+      {{"// Add your filters here based on criteria"}}
+    }},
+    "offset": 0,
+    "limit": 100,
+    "sortBy": {{"field": "name", "order": "asc"}}
+  }}' | jq '.' > results.json
+```
+
+### Option 2: Python Script (For Processing)
+
+```python
+import httpx
+import json
+
+def filter_{instrument_type}(filters, limit=100):
+    \"\"\"Filter {instrument_type} directly via API.\"\"\"
+    url = "https://www.avanza.se/_api/{endpoint}/"
+
+    payload = {{
+        "filter": filters,
+        "offset": 0,
+        "limit": limit,
+        "sortBy": {{"field": "name", "order": "asc"}}
+    }}
+
+    response = httpx.post(url, json=payload, timeout=30.0)
+    return response.json()
+
+# Example: Apply your criteria
+filters = {{
+    # Map your criteria to filter parameters
+}}
+
+results = filter_{instrument_type}(filters, limit=100)
+
+# Save
+with open('{instrument_type}_filtered.json', 'w') as f:
+    json.dump(results, f, indent=2)
+
+print(f"Found {{results.get('totalNumberOfOrderbooks', 0)}} matches")
+```
+
+## Available Filter Parameters
+
+**For {instrument_type}**:
+{_get_filter_params(instrument_type)}
+
+## Pagination for Large Results
+
+If results exceed 100:
+
+```bash
+# Get next page
+curl 'https://www.avanza.se/_api/{endpoint}/' \\
+  -H 'Content-Type: application/json' \\
+  --data-raw '{{
+    "filter": {{}},
+    "offset": 100,  # Next page
+    "limit": 100,
+    "sortBy": {{"field": "name", "order": "asc"}}
+  }}'
+```
+
+## After Fetching
+
+Once you have the results:
+1. I can help analyze patterns in the data
+2. Pick interesting items for deep dives using MCP tools
+3. Create comparisons or visualizations
+"""
+
+
+def _get_filter_params(instrument_type: str) -> str:
+    """Get filter parameters for instrument type."""
+    params = {
+        "certificates": """
+- `directions`: ["long", "short"]
+- `leverages`: [1.0, 2.0, 3.0, ...]
+- `issuers`: ["Valour", "WisdomTree", ...]
+- `underlyingInstruments`: [orderbookIds]
+""",
+        "etfs": """
+- `exposures`: ["usa", "europe", "global", ...]
+- `assetCategories`: ["stock", "bond", "commodity", ...]
+- `riskScores`: ["risk_one", "risk_two", ...]
+- `managementFee`: (use sortBy to filter)
+""",
+        "warrants": """
+- `directions`: ["long", "short"]
+- `subTypes`: ["TURBO", "MINI", ...]
+- `issuers`: ["Societe Generale", ...]
+- `underlyingInstruments`: [orderbookIds]
+""",
+    }
+    return params.get(instrument_type.lower(), "Check API documentation")
+
+
+@mcp.prompt()
+def analyze_vs_fetch(operation_description: str, requires_bulk_data: bool) -> str:
+    """Distinguish between analysis (use tools) and fetching (use scripts).
+
+    Args:
+        operation_description: What the user wants to do
+        requires_bulk_data: Whether it needs 50+ items
+
+    Returns:
+        Guidance prompt
+    """
+    if requires_bulk_data:
+        return f"""Operation: "{operation_description}"
+
+## This Requires Bulk Data Fetching
+
+### Two-Step Approach:
+
+**Step 1: Fetch Data (You Do This)**
+I'll provide a script to fetch the data:
+- Runs in 30-60 seconds
+- Saves to JSON/CSV file
+- Handles errors gracefully
+
+**Step 2: Analyze Data (I Help With This)**
+After you have the data:
+- Share the file or key metrics
+- I'll use MCP tools for specific deep dives
+- We can explore patterns together
+
+### Why This Approach?
+
+- **Efficient**: Parallel fetching vs sequential MCP calls
+- **Reliable**: Better error handling, can resume if failed
+- **Flexible**: You own the data for other analyses
+
+### Script I'll Provide
+
+```python
+# Fast parallel data fetcher
+import httpx, asyncio, json
+
+async def fetch_all():
+    ids = [...]  # Your list
+    async with httpx.AsyncClient() as c:
+        tasks = [c.get(f"https://www.avanza.se/_api/.../{{id}}") for id in ids]
+        return await asyncio.gather(*tasks, return_exceptions=True)
+
+results = asyncio.run(fetch_all())
+with open('data.json', 'w') as f:
+    json.dump([r.json() for r in results if hasattr(r, 'json')], f)
+```
+
+### Next: Share Results & Analyze Together
+"""
+    else:
+        return f"""Operation: "{operation_description}"
+
+## This Can Use MCP Tools Directly
+
+I'll use MCP tools interactively because:
+- Small enough dataset (< 20 items)
+- Interactive exploration is valuable
+- Results available immediately
+
+I'll proceed with using the appropriate MCP tools for this analysis.
+"""
+
+
+@mcp.prompt()
+def script_template_selector(
+    task: str, data_source: str, output_format: str = "json"
+) -> str:
+    """Provide appropriate script template based on task.
+
+    Args:
+        task: What to accomplish
+        data_source: Where to get data (endpoint type)
+        output_format: Desired output format
+
+    Returns:
+        Complete script template
+    """
+    return f"""Task: {task}
+Data Source: {data_source}
+Output: {output_format}
+
+## Recommended Script
+
+```python
+#!/usr/bin/env python3
+\"\"\"
+{task}
+
+Fetches data from Avanza's public API and saves to {output_format}.
+No authentication required.
+\"\"\"
+
+import httpx
+import asyncio
+import json
+from pathlib import Path
+from datetime import datetime
+
+# Configuration
+BASE_URL = "https://www.avanza.se/_api"
+OUTPUT_DIR = Path("avanza_data")
+MAX_CONCURRENT = 10  # Limit concurrent requests
+
+async def fetch_item(client, item_id, semaphore):
+    \"\"\"Fetch single item with rate limiting.\"\"\"
+    async with semaphore:
+        try:
+            url = f"{{BASE_URL}}/{data_source}/{{item_id}}"
+            response = await client.get(url, timeout=30.0)
+            response.raise_for_status()
+            return {{"id": item_id, "data": response.json(), "error": None}}
+        except Exception as e:
+            return {{"id": item_id, "data": None, "error": str(e)}}
+
+async def main():
+    # TODO: Replace with your actual IDs
+    item_ids = [
+        # "5247",  # Example: Volvo
+        # "5361",  # Example: Ericsson
+        # Add your IDs here
+    ]
+
+    if not item_ids:
+        print("⚠️  Please add item IDs to the script")
+        return
+
+    print(f"📊 Fetching {{len(item_ids)}} items...")
+
+    # Create output directory
+    OUTPUT_DIR.mkdir(exist_ok=True)
+
+    # Rate limiting semaphore
+    semaphore = asyncio.Semaphore(MAX_CONCURRENT)
+
+    # Fetch all items
+    async with httpx.AsyncClient() as client:
+        tasks = [fetch_item(client, iid, semaphore) for iid in item_ids]
+        results = await asyncio.gather(*tasks)
+
+    # Separate successful and failed
+    successful = [r for r in results if r["error"] is None]
+    failed = [r for r in results if r["error"] is not None]
+
+    # Save results
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    output_file = OUTPUT_DIR / f"results_{{timestamp}}.{output_format}"
+
+    with open(output_file, "w", encoding="utf-8") as f:
+        json.dump(
+            {{
+                "metadata": {{
+                    "timestamp": timestamp,
+                    "total": len(item_ids),
+                    "successful": len(successful),
+                    "failed": len(failed),
+                }},
+                "data": [r["data"] for r in successful],
+                "errors": [{{"id": r["id"], "error": r["error"]}} for r in failed],
+            }},
+            f,
+            indent=2,
+            ensure_ascii=False,
+        )
+
+    # Print summary
+    print(f"\\n✅ Successfully fetched: {{len(successful)}}/{{len(item_ids)}}")
+    if failed:
+        print(f"❌ Failed: {{len(failed)}}")
+        for fail in failed[:5]:  # Show first 5 errors
+            print(f"   - {{fail['id']}}: {{fail['error']}}")
+    print(f"\\n📁 Saved to: {{output_file}}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## How to Use
+
+1. **Save the script**: `save as fetch_data.py`
+2. **Add your IDs**: Edit the `item_ids` list
+3. **Install dependency**: `pip install httpx`
+4. **Run**: `python fetch_data.py`
+
+## What You Get
+
+- JSON file with all results
+- Error tracking for failed requests
+- Timestamp for record keeping
+- Summary of success/failure rates
+
+## After Running
+
+Share the results file and I can help you:
+- Analyze patterns
+- Create visualizations
+- Filter and sort data
+- Deep dive on specific items
+"""

avanza_mcp/resources/__init__.py

@@ -2,5 +2,6 @@
 
 # Import to register resources via decorators
 from . import instruments  # noqa: F401
+from . import usage  # noqa: F401
 
-__all__ = ["instruments"]
+__all__ = ["instruments", "usage"]

avanza_mcp/resources/usage.py

@@ -0,0 +1,503 @@
+"""Usage guide resources for AI callers."""
+
+from .. import mcp
+
+USAGE_GUIDE = """# Avanza MCP Server - Usage Guide for AI Assistants
+
+## 🎯 Critical: When NOT to Use MCP Tools
+
+### MCP Tools Are For Interactive Exploration, NOT Bulk Data Processing
+
+**Use MCP tools for**:
+- ✅ Single instrument lookups (1-5 items)
+- ✅ Small comparisons (2-10 instruments)
+- ✅ Quick searches and exploration
+- ✅ Interactive data analysis
+
+**DO NOT use MCP tools for**:
+- ❌ Fetching data for 50+ instruments
+- ❌ Bulk screening operations
+- ❌ Large-scale data analysis
+- ❌ Building datasets
+
+## 📏 The Threshold Rule
+
+| Number of Items | Action |
+|----------------|---------|
+| 1-20 items | Use MCP tools directly |
+| 20-50 items | Ask user if they want to continue with tools OR get a script |
+| 50+ items | **DO NOT USE MCP TOOLS** - Provide a script instead |
+
+## 🚫 Common Anti-Pattern (DON'T DO THIS)
+
+```
+User: "Analyze the top 100 Swedish stocks"
+
+❌ BAD Response:
+for stock_id in top_100_stocks:
+    get_stock_info(stock_id)  # This will make 100 MCP calls!
+    get_stock_chart(stock_id)  # Another 100 calls!
+```
+
+**Problem**: This creates 200+ MCP tool calls, which is:
+- Slow and inefficient
+- Overloads the MCP connection
+- Not what MCP tools are designed for
+
+## ✅ Correct Approach for Large Data Fetching
+
+### Option 1: Provide a Python Script
+
+```python
+User: "Analyze the top 100 Swedish stocks"
+
+✅ GOOD Response:
+"For analyzing 100 stocks, you should fetch the data directly using a script
+rather than MCP tools. Here's a Python script you can run:
+
+```python
+import httpx
+import asyncio
+import json
+
+async def fetch_stock_info(client, stock_id):
+    url = f"https://www.avanza.se/_api/market-guide/stock/{stock_id}"
+    response = await client.get(url)
+    return response.json()
+
+async def main():
+    stock_ids = ["5247", "5361", ...]  # Your 100 stock IDs
+
+    async with httpx.AsyncClient() as client:
+        tasks = [fetch_stock_info(client, sid) for sid in stock_ids]
+        results = await asyncio.gather(*tasks)
+
+    # Save to file
+    with open('stocks_data.json', 'w') as f:
+        json.dump(results, f, indent=2)
+
+    print(f"Fetched {len(results)} stocks")
+
+asyncio.run(main())
+```
+
+This will efficiently fetch all 100 stocks in parallel and save to a JSON file."
+```
+
+### Option 2: Provide curl Commands
+
+```bash
+User: "Get data for 50 certificates"
+
+✅ GOOD Response:
+"For fetching 50 certificates, use the filter endpoint directly with a script:
+
+```bash
+# Get all certificates at once with pagination
+curl 'https://www.avanza.se/_api/market-certificate-filter/' \\
+  -H 'Content-Type: application/json' \\
+  --data-raw '{
+    "filter": {},
+    "offset": 0,
+    "limit": 50,
+    "sortBy": {"field": "name", "order": "asc"}
+  }' > certificates.json
+
+# For more than 50, fetch next page:
+curl 'https://www.avanza.se/_api/market-certificate-filter/' \\
+  -H 'Content-Type: application/json' \\
+  --data-raw '{
+    "filter": {},
+    "offset": 50,
+    "limit": 50,
+    "sortBy": {"field": "name", "order": "asc"}
+  }' >> certificates.json
+```
+
+This fetches the data directly from Avanza's public API."
+```
+
+### Option 3: Provide a Shell Script for Multiple Items
+
+```bash
+User: "Get stock info for these 100 companies"
+
+✅ GOOD Response:
+"Here's a shell script to fetch data for all 100 stocks:
+
+```bash
+#!/bin/bash
+
+# Array of stock IDs
+stock_ids=(5247 5361 5239 ...)  # All 100 IDs
+
+# Create output directory
+mkdir -p stock_data
+
+# Fetch each stock
+for id in "${stock_ids[@]}"; do
+  echo "Fetching stock $id..."
+  curl -s "https://www.avanza.se/_api/market-guide/stock/$id" \\
+    > "stock_data/stock_$id.json"
+  sleep 0.5  # Be nice to the API
+done
+
+echo "Done! Data saved in stock_data/"
+```
+
+Run with: `chmod +x fetch_stocks.sh && ./fetch_stocks.sh`"
+```
+
+## 📋 API Endpoint Reference (For Script Writing)
+
+When instructing users to write scripts, these are the public endpoints:
+
+### Search & Discovery
+```bash
+# Search instruments
+curl 'https://www.avanza.se/_api/search/filtered-search' \\
+  -H 'Content-Type: application/json' \\
+  --data-raw '{"query": "Tesla", "instrumentTypes": ["STOCK"]}'
+```
+
+### Stock Data
+```bash
+# Stock info
+curl 'https://www.avanza.se/_api/market-guide/stock/{id}'
+
+# Stock quote
+curl 'https://www.avanza.se/_api/market-guide/stock/{id}/quote'
+
+# Stock chart
+curl 'https://www.avanza.se/_api/price-chart/stock/{id}?timePeriod=one_month'
+
+# Order book
+curl 'https://www.avanza.se/_api/market-guide/stock/{id}/orderdepth'
+```
+
+### Filter Endpoints (Bulk Operations)
+```bash
+# Filter certificates (POST request)
+curl 'https://www.avanza.se/_api/market-certificate-filter/' \\
+  -H 'Content-Type: application/json' \\
+  --data-raw '{
+    "filter": {"directions": ["long"]},
+    "offset": 0,
+    "limit": 100,
+    "sortBy": {"field": "name", "order": "asc"}
+  }'
+
+# Filter ETFs (POST request)
+curl 'https://www.avanza.se/_api/market-etf-filter/' \\
+  -H 'Content-Type: application/json' \\
+  --data-raw '{
+    "filter": {"exposures": ["usa"]},
+    "offset": 0,
+    "limit": 100,
+    "sortBy": {"field": "managementFee", "order": "asc"}
+  }'
+
+# Filter warrants (POST request)
+curl 'https://www.avanza.se/_api/market-warrant-filter/' \\
+  -H 'Content-Type: application/json' \\
+  --data-raw '{
+    "filter": {"subTypes": ["TURBO"]},
+    "offset": 0,
+    "limit": 100,
+    "sortBy": {"field": "name", "order": "asc"}
+  }'
+```
+
+### Fund Data
+```bash
+# Fund info
+curl 'https://www.avanza.se/_api/fund-guide/guide/{id}'
+
+# Fund chart
+curl 'https://www.avanza.se/_api/fund-guide/chart/{id}/three_years'
+```
+
+## 🔄 Decision Tree: Tool vs Script
+
+```
+User request → Count number of items needed
+    │
+    ├─ 1-20 items? → Use MCP tools directly
+    │
+    ├─ 20-50 items? → Ask user:
+    │   "This will require ~{count} API calls. Would you like me to:
+    │    1. Proceed with MCP tools (slower, interactive)
+    │    2. Provide a script for you to run (faster, bulk)"
+    │
+    └─ 50+ items? → ALWAYS provide script
+        │
+        ├─ User is technical? → Python script with async
+        ├─ User wants simple? → Bash script with curl
+        └─ User wants data file? → curl command + jq
+```
+
+## 🎓 Examples of Correct Responses
+
+### Example 1: Small Request (Use Tools)
+
+```
+User: "What's the current price of Volvo?"
+
+✅ Response:
+search_instruments(query="Volvo B", instrument_types=["STOCK"])
+get_stock_quote(instrument_id="5247")
+"Volvo B is currently trading at 265.40 SEK, up 1.2%"
+```
+
+### Example 2: Medium Request (Ask User)
+
+```
+User: "Compare these 30 ETFs"
+
+✅ Response:
+"Comparing 30 ETFs will require approximately 60 API calls through MCP tools.
+I have two options for you:
+
+1. **Use MCP Tools** (slower, ~2-3 minutes):
+   I'll fetch each ETF's data interactively. Good if you want to explore
+   the data step-by-step.
+
+2. **Provide a Script** (faster, ~30 seconds):
+   I'll give you a Python script that fetches all 30 ETFs in parallel,
+   saves to JSON, and you can analyze the results.
+
+Which would you prefer?"
+```
+
+### Example 3: Large Request (Provide Script)
+
+```
+User: "Analyze all Swedish stocks with market cap > 1B SEK"
+
+✅ Response:
+"To analyze 100+ stocks efficiently, you should fetch the data directly
+rather than using MCP tools. Here's a Python script:
+
+```python
+import httpx
+import asyncio
+import pandas as pd
+
+async def fetch_stock(client, stock_id):
+    try:
+        response = await client.get(
+            f"https://www.avanza.se/_api/market-guide/stock/{stock_id}"
+        )
+        return response.json()
+    except Exception as e:
+        print(f"Error fetching {stock_id}: {e}")
+        return None
+
+async def main():
+    # First, get Swedish stock IDs (you'd need to search or have a list)
+    stock_ids = [...]  # Your list of stock IDs
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        tasks = [fetch_stock(client, sid) for sid in stock_ids]
+        results = await asyncio.gather(*tasks)
+
+    # Filter for market cap > 1B
+    large_caps = [
+        s for s in results
+        if s and s.get('company', {}).get('marketCapital', 0) > 1_000_000_000
+    ]
+
+    # Convert to DataFrame for analysis
+    df = pd.DataFrame([{
+        'name': s['name'],
+        'price': s['quote']['last'],
+        'market_cap': s['company']['marketCapital'],
+        'pe_ratio': s.get('keyIndicators', {}).get('priceEarningsRatio'),
+    } for s in large_caps])
+
+    df.to_csv('large_cap_stocks.csv', index=False)
+    print(f"Analyzed {len(large_caps)} large-cap stocks")
+    print(df.head())
+
+asyncio.run(main())
+```
+
+Save this as `analyze_stocks.py` and run with:
+```bash
+pip install httpx pandas
+python analyze_stocks.py
+```
+
+After running this, I can help you analyze the results in `large_cap_stocks.csv`."
+```
+
+## 💡 Key Principles
+
+1. **MCP tools = Interactive exploration** (1-20 items)
+2. **Scripts = Bulk data processing** (50+ items)
+3. **Always explain why** you're recommending a script over tools
+4. **Provide working code** that users can run immediately
+5. **Include error handling** in scripts (timeouts, retries)
+6. **Be nice to the API** (rate limiting, delays)
+
+## 🚀 Script Templates You Can Use
+
+### Python: Async Bulk Fetcher
+```python
+import httpx
+import asyncio
+
+async def fetch_data(url):
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url, timeout=30.0)
+        return response.json()
+
+async def bulk_fetch(urls):
+    tasks = [fetch_data(url) for url in urls]
+    return await asyncio.gather(*tasks, return_exceptions=True)
+
+# Usage
+urls = [f"https://www.avanza.se/_api/market-guide/stock/{i}" for i in stock_ids]
+results = asyncio.run(bulk_fetch(urls))
+```
+
+### Bash: Simple Sequential Fetcher
+```bash
+#!/bin/bash
+for id in $(cat stock_ids.txt); do
+  curl -s "https://www.avanza.se/_api/market-guide/stock/$id" \\
+    > "data/stock_$id.json"
+  sleep 0.5
+done
+```
+
+### curl + jq: Filter and Extract
+```bash
+# Fetch and extract just the fields you need
+curl -s 'https://www.avanza.se/_api/market-certificate-filter/' \\
+  -H 'Content-Type: application/json' \\
+  --data-raw '{"filter":{},"offset":0,"limit":100,"sortBy":{"field":"name","order":"asc"}}' \\
+  | jq '.certificates[] | {name, orderbookId, leverage, direction}'
+```
+
+## ⚠️ Important Reminders
+
+- **No authentication required** - All endpoints shown are public
+- **Rate limiting** - Add delays (0.5-1s) between requests in loops
+- **Timeout handling** - Use appropriate timeouts (10-30s)
+- **Error handling** - Check for HTTP errors and null responses
+- **Respect the API** - Don't hammer the servers with concurrent requests
+
+## 📊 Summary
+
+| Scenario | Items | Action |
+|----------|-------|--------|
+| Quick lookup | 1-5 | Use MCP tools |
+| Comparison | 5-20 | Use MCP tools |
+| Small screening | 20-50 | Ask user preference |
+| Bulk screening | 50-200 | Provide script |
+| Large analysis | 200+ | Provide script + pagination guide |
+
+**Golden Rule**: If you're thinking about calling the same tool in a loop more than 20 times, provide a script instead.
+"""
+
+
+@mcp.resource("avanza://docs/usage")
+async def get_usage_guide() -> str:
+    """Get comprehensive usage guide for AI assistants.
+
+    URI: avanza://docs/usage
+
+    This resource provides critical guidance on:
+    - When to use MCP tools (small, interactive queries)
+    - When to provide scripts instead (bulk data fetching)
+    - How to write curl commands and Python scripts for users
+    - API endpoint reference for script writing
+
+    Returns:
+        Markdown-formatted usage guide
+    """
+    return USAGE_GUIDE
+
+
+@mcp.resource("avanza://docs/quick-start")
+async def get_quick_start() -> str:
+    """Get quick start guide focused on tool vs script decision.
+
+    URI: avanza://docs/quick-start
+
+    Returns:
+        Quick reference guide
+    """
+    return """# Avanza MCP - Quick Decision Guide
+
+## 🚦 When to Use What
+
+### Use MCP Tools (✅)
+- Single lookups: "What's Tesla's price?"
+- Small comparisons: "Compare these 5 funds"
+- Quick exploration: "Find ETFs with USA exposure"
+- Interactive analysis: Step-by-step investigation
+
+### Provide Script (📝)
+- Bulk operations: "Analyze 100 stocks"
+- Large screenings: "Get all certificates"
+- Dataset building: "Fetch all Swedish funds"
+- Repeated operations: "Daily price monitoring"
+
+## 📏 The Rule
+
+```
+if items > 50:
+    provide_script()
+elif items > 20:
+    ask_user_preference()
+else:
+    use_mcp_tools()
+```
+
+## 🔧 Quick Script Templates
+
+### Fetch Multiple Stocks (Python)
+```python
+import httpx
+import asyncio
+
+async def main():
+    stock_ids = ["5247", "5361", ...]
+    async with httpx.AsyncClient() as client:
+        for sid in stock_ids:
+            r = await client.get(f"https://www.avanza.se/_api/market-guide/stock/{sid}")
+            print(r.json()['name'], r.json()['quote']['last'])
+
+asyncio.run(main())
+```
+
+### Bulk Filter (curl)
+```bash
+curl 'https://www.avanza.se/_api/market-etf-filter/' \\
+  -H 'Content-Type: application/json' \\
+  --data-raw '{"filter":{},"offset":0,"limit":100,"sortBy":{"field":"name","order":"asc"}}'
+```
+
+## 💭 Example Responses
+
+**User**: "Check Volvo stock"
+**You**: ✅ Use `get_stock_quote("5247")`
+
+**User**: "Compare 10 funds"
+**You**: ✅ Use `get_fund_info()` for each
+
+**User**: "Analyze 80 Swedish stocks"
+**You**: 📝 "Here's a Python script to fetch all 80 stocks..."
+
+**User**: "Screen all ETFs"
+**You**: 📝 "Here's a curl command using filter_etfs endpoint..."
+
+## 🎯 Remember
+
+MCP = Interactive exploration (1-20 items)
+Script = Bulk processing (50+ items)
+
+Read full guide: `avanza://docs/usage`
+"""

{avanza_mcp-1.2.0.dist-info → avanza_mcp-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avanza-mcp
-Version: 1.2.0
+Version: 1.3.0
 Summary: MCP server for Avanza public market data API - Swedish stocks, funds, and more
 License-File: LICENSE.md
 Requires-Python: >=3.12
@@ -95,10 +95,29 @@ The author of this software is not responsible for any indirect damages (foresee
 
 ## 💡 MCP Prompts
 
+### Analysis Prompts
 - `analyze_stock` - Comprehensive stock analysis workflow
 - `compare_funds` - Multi-fund comparison template
 - `screen_dividend_stocks` - Dividend stock screening
 
+### Workflow Prompts (Teach AI Efficient Data Fetching)
+- `search_and_analyze_instrument` - Guide for finding and analyzing instruments efficiently
+- `filter_instruments_efficiently` - Guide for filtering large datasets with pagination
+- `compare_multiple_instruments` - Guide for comparing instruments efficiently
+- `explore_market_segment` - Guide for exploring market segments
+- `get_historical_analysis` - Guide for analyzing historical data
+- `screen_by_criteria` - Guide for screening by custom criteria
+
+## 📚 MCP Resources
+
+### Documentation Resources
+- `avanza://docs/usage` - Comprehensive usage guide for AI assistants
+- `avanza://docs/quick-start` - Quick reference for common tasks
+
+### Instrument Resources
+- `avanza://stock/{instrument_id}` - Get stock information as markdown
+- `avanza://fund/{instrument_id}` - Get fund information as markdown
+
 
 ### Configuration for MCP Clients
 

{avanza_mcp-1.2.0.dist-info → avanza_mcp-1.3.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-avanza_mcp/__init__.py,sha256=2pf3Q75vzuidsLXDpi9E_beR2PvHvJQiGbUyNuiOiT8,1002
+avanza_mcp/__init__.py,sha256=ccShZ9OeQ4V6UgFirUJZI9OV5cD8H93MgIIkfyO-bnw,1002
 avanza_mcp/client/__init__.py,sha256=Yab-cUgQclyZgqdUkl7I15abQjEXVLoTvD3430oxpuY,515
 avanza_mcp/client/base.py,sha256=92WrXDf0oTvE9gLJvEcbNkgbaT3rQkhoCAoGIpbaz0M,12853
 avanza_mcp/client/endpoints.py,sha256=S7LK9Ab2ATHMEZ_680SbPbi5PogzbpGa-2USoMGthjo,2732
@@ -15,10 +15,12 @@ avanza_mcp/models/instrument_data.py,sha256=-5MJTCFy4W8zVU-oVjTBxWo55SzGG62577X3
 avanza_mcp/models/search.py,sha256=HrP3V2T9Y1LBk_wwnNJdqg6XbHaz96AqvVUQ9iwuNyw,2816
 avanza_mcp/models/stock.py,sha256=KR7SxeaiGe-7Me0-mXuqE37xwyhW94FPn8zjOtpyh8I,6420
 avanza_mcp/models/warrant.py,sha256=k8uzeSOeFxPZuV9CE0vZwvOpmDZwlNto9PzPQKtzJ8o,2324
-avanza_mcp/prompts/__init__.py,sha256=P7ClxG1itpYEKXGP9nQzqJ1zo2S0QeiHgOsfgwdf7VQ,140
+avanza_mcp/prompts/__init__.py,sha256=6GOy34A-1ZIhMk7yFyIJ8pHnE8j42aaBRReiuAOVlBE,191
 avanza_mcp/prompts/analysis.py,sha256=uW3P_jdupoNp7QsyjPsjXJjCNlR5646oYyVV9SMwXeM,3694
-avanza_mcp/resources/__init__.py,sha256=jXyXHN_BV7HKkVh-2EfqHui7PzfcPlpEY7GaCWJuDQA,150
+avanza_mcp/prompts/workflows.py,sha256=x56DjSRQZvV-yNHGL5BXwgb8MCCyy-rYXrSsLp0KJzw,13414
+avanza_mcp/resources/__init__.py,sha256=IgzNHfy_fXl-oUfzL10HctB8GC5jOUIY58z3uKeXUg8,193
 avanza_mcp/resources/instruments.py,sha256=1pZbQ19NAWNMD_qmBOcniwf988jpFKUK4QiXrdOyYGw,3948
+avanza_mcp/resources/usage.py,sha256=sGtlR_dF-nHvFYEQYYugmispCgeKnT7OiFd_YfDhvNw,13602
 avanza_mcp/services/__init__.py,sha256=hCCYSVLvFglaGfNo4MXQP8mzsKHmV8yG_iNH0VsIsPs,190
 avanza_mcp/services/market_data_service.py,sha256=EEjF1rwUAZ9ejLeLJJu49cntTaHuZ4opApJ8faEj6so,19212
 avanza_mcp/services/search_service.py,sha256=op2BKokwraqoOSv0SdnLMFBJJODyqCAhOaFiCJ1hc30,1930
@@ -31,8 +33,8 @@ avanza_mcp/tools/instrument_data.py,sha256=EkE4dPSm1d4m1CeofCBdualwQqbPB8UtxCGon
 avanza_mcp/tools/market_data.py,sha256=qqvnrnYpcvPucZlqvLHODh4DsRF5XPC7WmguDmaEzEk,16474
 avanza_mcp/tools/search.py,sha256=srB7K-9VCJhB6Zvs4aLX_jfFekiMUIkYgOAp5IrCApg,3722
 avanza_mcp/tools/warrants.py,sha256=jLaC3FK5X1DQcU_f5oXXP6asjTTTp2GfhDcE47uF94M,4515
-avanza_mcp-1.2.0.dist-info/METADATA,sha256=Xwb4iHc8wqNJ9LiNd7Mj_j304WihW6jvCugOhXjCb-U,5173
-avanza_mcp-1.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-avanza_mcp-1.2.0.dist-info/entry_points.txt,sha256=4MF6-imOIBHK-U5DLdRrufwrV3MXfqGG0OIA_e4Jl_M,47
-avanza_mcp-1.2.0.dist-info/licenses/LICENSE.md,sha256=WVxy2qGCtophbFXxeAHHY0IksvRJLsUIuRgcGNtqH5Q,1065
-avanza_mcp-1.2.0.dist-info/RECORD,,
+avanza_mcp-1.3.0.dist-info/METADATA,sha256=h_5cJ6f4AdJVNUXjYqDzObJQLSquipu5m-5BBSZ5viM,6058
+avanza_mcp-1.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+avanza_mcp-1.3.0.dist-info/entry_points.txt,sha256=4MF6-imOIBHK-U5DLdRrufwrV3MXfqGG0OIA_e4Jl_M,47
+avanza_mcp-1.3.0.dist-info/licenses/LICENSE.md,sha256=WVxy2qGCtophbFXxeAHHY0IksvRJLsUIuRgcGNtqH5Q,1065
+avanza_mcp-1.3.0.dist-info/RECORD,,