devduck 0.3.0__tar.gz → 0.4.0__tar.gz

devduck-0.4.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: devduck
+Version: 0.4.0
+Summary: 🦆 Extreme minimalist self-adapting AI agent - one file, self-healing, runtime dependencies
+Author-email: duck <hey@devduck.dev>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cagataycali/devduck
+Project-URL: Repository, https://github.com/cagataycali/devduck.git
+Project-URL: Documentation, https://github.com/cagataycali/devduck#readme
+Project-URL: Bug Tracker, https://github.com/cagataycali/devduck/issues
+Keywords: ai,agent,minimalist,self-healing,ollama,strands-agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: strands-agents
+Requires-Dist: prompt_toolkit
+Requires-Dist: strands-agents[ollama]
+Requires-Dist: strands-agents-tools
+Requires-Dist: strands-agentcore-tools
+Requires-Dist: beautifulsoup4
+Requires-Dist: colorama
+Requires-Dist: websockets
+Requires-Dist: strands-mcp-server
+Provides-Extra: all
+Requires-Dist: strands-agents[openai]; extra == "all"
+Requires-Dist: strands-agents[anthropic]; extra == "all"
+Requires-Dist: strands-fun-tools[audio]; extra == "all"
+Requires-Dist: strands-fun-tools[vision]; extra == "all"
+Requires-Dist: strands-fun-tools[all]; extra == "all"
+Dynamic: license-file
+
+# 🦆 DevDuck
+
+**Self-healing agent. One file. Zero config.**
+
+Minimalist AI that adapts to your environment and fixes itself when things break.
+
+## Install
+
+```bash
+pipx install "devduck[all]"  # Full install (recommended)
+```
+
+Requires: Python 3.10+, Ollama (or set `MODEL_PROVIDER`)
+
+## Quick Start
+
+```bash
+devduck                      # Interactive mode (auto-starts servers)
+devduck "analyze this code"  # CLI mode
+```
+
+```python
+import devduck
+devduck("calculate 2+2")  # Python API
+```
+
+## Core Features
+
+- **🔧 Self-healing** - Auto-fixes dependencies, models, errors
+- **🔥 Hot-reload** - Save `.py` files in `./tools/`, use instantly (no restart)
+- **🧠 RAG memory** - Set `STRANDS_KNOWLEDGE_BASE_ID` for automatic context retrieval/storage
+- **🌍 Multi-protocol** - TCP (9999), WebSocket (8080), MCP (8000), CLI, Python
+- **📚 19+ tools** - shell, editor, calculator, python, GitHub, subagents, and more
+- **🎯 Adaptive** - Auto-selects model by OS (macOS: 1.7b, Linux: 30b)
+
+## Auto-Started Servers
+
+When you run `devduck`, 3 servers start automatically:
+
+| Server | Endpoint | Usage |
+|--------|----------|-------|
+| 🌐 **Web UI** | [cagataycali.github.io/devduck](http://cagataycali.github.io/devduck) | Browser interface |
+| 🔌 **TCP** | `localhost:9999` | `nc localhost 9999` |
+| 🌊 **WebSocket** | `ws://localhost:8080` | Structured JSON messages |
+| 🔗 **MCP** | `http://localhost:8000/mcp` | Model Context Protocol |
+
+**Customize ports:**
+```bash
+devduck --tcp-port 9000 --ws-port 8001 --mcp-port 3000
+devduck --no-tcp --no-ws  # Disable specific servers
+```
+
+## Connect Options
+
+### MCP Client (Claude Desktop)
+
+**Simple stdio mode (recommended):**
+```json
+{
+  "mcpServers": {
+    "devduck": {
+      "command": "uvx",
+      "args": ["devduck", "--mcp"]
+    }
+  }
+}
+```
+
+**Proxy mode (if devduck already running):**
+```json
+{
+  "mcpServers": {
+    "devduck": {
+      "command": "uvx",
+      "args": ["strands-mcp-server", "--upstream-url", "http://localhost:8000/mcp/"]
+    }
+  }
+}
+```
+
+### Terminal (TCP)
+```bash
+nc localhost 9999
+> analyze logs
+```
+
+### Shell Prefix
+```bash
+devduck
+🦆 ! git status  # Run shell commands with !
+```
+
+## Hot-Reload Tool Creation
+
+Create tools instantly—no restart needed:
+
+```python
+# ./tools/tip_calc.py
+from strands import tool
+
+@tool
+def calculate_tip(amount: float, percent: float = 15.0) -> str:
+    """Calculate restaurant tip."""
+    tip = amount * (percent / 100)
+    return f"Tip: ${tip:.2f} | Total: ${amount + tip:.2f}"
+```
+
+Save → Available instantly → Use: `devduck "calculate tip for $42"`
+
+## Built-in Tools (19+)
+
+| Category | Tools |
+|----------|-------|
+| **Development** | shell, editor, python_repl, load_tool, environment |
+| **GitHub** | use_github, create_subagent, gist, add_comment, list_issues |
+| **Network** | tcp, websocket, mcp_server, mcp_client, http_request |
+| **AI** | use_agent, install_tools, retrieve, store_in_kb |
+| **Utilities** | calculator, image_reader, scraper, system_prompt, view_logs |
+
+## Multi-Model Support
+
+Switch models via environment variables:
+
+```bash
+# Bedrock (Claude)
+export MODEL_PROVIDER="bedrock"
+export STRANDS_MODEL_ID="us.anthropic.claude-sonnet-4-5-20250929-v1:0"
+export STRANDS_MAX_TOKENS="64000"
+
+# Anthropic API
+export MODEL_PROVIDER="anthropic"
+export STRANDS_MODEL_ID="claude-sonnet-4-20250514"
+
+# Ollama (default)
+export MODEL_PROVIDER="ollama"
+export OLLAMA_HOST="http://localhost:11434"
+```
+
+## Knowledge Base (RAG)
+
+Enable automatic memory across sessions:
+
+```bash
+export STRANDS_KNOWLEDGE_BASE_ID="your-kb-id"
+devduck  # Auto-retrieves context before queries, stores after responses
+```
+
+Works with AWS Bedrock Knowledge Bases.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MODEL_PROVIDER` | `ollama` | Model provider (bedrock, anthropic, ollama) |
+| `STRANDS_KNOWLEDGE_BASE_ID` | - | Enable auto-RAG with KB ID |
+| `DEVDUCK_TCP_PORT` | `9999` | TCP server port |
+| `DEVDUCK_WS_PORT` | `8080` | WebSocket port |
+| `DEVDUCK_MCP_PORT` | `8000` | MCP server port |
+| `DEVDUCK_ENABLE_TCP` | `true` | Enable TCP server |
+| `DEVDUCK_ENABLE_WS` | `true` | Enable WebSocket |
+| `DEVDUCK_ENABLE_MCP` | `true` | Enable MCP server |
+| `DEVDUCK_LOG_LINE_COUNT` | `50` | Log lines in context |
+| `SYSTEM_PROMPT` | - | Custom system prompt |
+
+## Dynamic Tool Loading
+
+Load tools from any Python package at runtime:
+
+```python
+devduck
+🦆 install_tools(action="install_and_load", 
+              package="strands-fun-tools", 
+              module="strands_fun_tools")
+```
+
+No restart required—tools available immediately.
+
+## System Prompt Management
+
+Modify agent behavior dynamically:
+
+```bash
+devduck
+🦆 system_prompt(action="update", prompt="You are a senior Python expert.")
+🦆 system_prompt(action="view")  # See current prompt
+```
+
+## Logs
+
+```bash
+devduck
+🦆 view_logs(action="view", lines=100)
+🦆 view_logs(action="search", pattern="error")
+🦆 view_logs(action="stats")
+```
+
+Log location: `/tmp/devduck/logs/devduck.log`
+
+## GitHub Actions
+
+Run DevDuck in CI/CD:
+
+```yaml
+- name: DevDuck Analysis
+  uses: cagataycali/devduck@main
+  with:
+    query: "analyze test coverage"
+    model: "us.anthropic.claude-sonnet-4-20250514-v1:0"
+```
+
+---
+
+**One file. 19+ tools. Self-healing. Hot-reload. RAG memory.**
+
+*Built with [Strands Agents SDK](https://github.com/strands-agents/sdk-python)*

devduck-0.4.0/README.md

@@ -0,0 +1,215 @@
+# 🦆 DevDuck
+
+**Self-healing agent. One file. Zero config.**
+
+Minimalist AI that adapts to your environment and fixes itself when things break.
+
+## Install
+
+```bash
+pipx install "devduck[all]"  # Full install (recommended)
+```
+
+Requires: Python 3.10+, Ollama (or set `MODEL_PROVIDER`)
+
+## Quick Start
+
+```bash
+devduck                      # Interactive mode (auto-starts servers)
+devduck "analyze this code"  # CLI mode
+```
+
+```python
+import devduck
+devduck("calculate 2+2")  # Python API
+```
+
+## Core Features
+
+- **🔧 Self-healing** - Auto-fixes dependencies, models, errors
+- **🔥 Hot-reload** - Save `.py` files in `./tools/`, use instantly (no restart)
+- **🧠 RAG memory** - Set `STRANDS_KNOWLEDGE_BASE_ID` for automatic context retrieval/storage
+- **🌍 Multi-protocol** - TCP (9999), WebSocket (8080), MCP (8000), CLI, Python
+- **📚 19+ tools** - shell, editor, calculator, python, GitHub, subagents, and more
+- **🎯 Adaptive** - Auto-selects model by OS (macOS: 1.7b, Linux: 30b)
+
+## Auto-Started Servers
+
+When you run `devduck`, 3 servers start automatically:
+
+| Server | Endpoint | Usage |
+|--------|----------|-------|
+| 🌐 **Web UI** | [cagataycali.github.io/devduck](http://cagataycali.github.io/devduck) | Browser interface |
+| 🔌 **TCP** | `localhost:9999` | `nc localhost 9999` |
+| 🌊 **WebSocket** | `ws://localhost:8080` | Structured JSON messages |
+| 🔗 **MCP** | `http://localhost:8000/mcp` | Model Context Protocol |
+
+**Customize ports:**
+```bash
+devduck --tcp-port 9000 --ws-port 8001 --mcp-port 3000
+devduck --no-tcp --no-ws  # Disable specific servers
+```
+
+## Connect Options
+
+### MCP Client (Claude Desktop)
+
+**Simple stdio mode (recommended):**
+```json
+{
+  "mcpServers": {
+    "devduck": {
+      "command": "uvx",
+      "args": ["devduck", "--mcp"]
+    }
+  }
+}
+```
+
+**Proxy mode (if devduck already running):**
+```json
+{
+  "mcpServers": {
+    "devduck": {
+      "command": "uvx",
+      "args": ["strands-mcp-server", "--upstream-url", "http://localhost:8000/mcp/"]
+    }
+  }
+}
+```
+
+### Terminal (TCP)
+```bash
+nc localhost 9999
+> analyze logs
+```
+
+### Shell Prefix
+```bash
+devduck
+🦆 ! git status  # Run shell commands with !
+```
+
+## Hot-Reload Tool Creation
+
+Create tools instantly—no restart needed:
+
+```python
+# ./tools/tip_calc.py
+from strands import tool
+
+@tool
+def calculate_tip(amount: float, percent: float = 15.0) -> str:
+    """Calculate restaurant tip."""
+    tip = amount * (percent / 100)
+    return f"Tip: ${tip:.2f} | Total: ${amount + tip:.2f}"
+```
+
+Save → Available instantly → Use: `devduck "calculate tip for $42"`
+
+## Built-in Tools (19+)
+
+| Category | Tools |
+|----------|-------|
+| **Development** | shell, editor, python_repl, load_tool, environment |
+| **GitHub** | use_github, create_subagent, gist, add_comment, list_issues |
+| **Network** | tcp, websocket, mcp_server, mcp_client, http_request |
+| **AI** | use_agent, install_tools, retrieve, store_in_kb |
+| **Utilities** | calculator, image_reader, scraper, system_prompt, view_logs |
+
+## Multi-Model Support
+
+Switch models via environment variables:
+
+```bash
+# Bedrock (Claude)
+export MODEL_PROVIDER="bedrock"
+export STRANDS_MODEL_ID="us.anthropic.claude-sonnet-4-5-20250929-v1:0"
+export STRANDS_MAX_TOKENS="64000"
+
+# Anthropic API
+export MODEL_PROVIDER="anthropic"
+export STRANDS_MODEL_ID="claude-sonnet-4-20250514"
+
+# Ollama (default)
+export MODEL_PROVIDER="ollama"
+export OLLAMA_HOST="http://localhost:11434"
+```
+
+## Knowledge Base (RAG)
+
+Enable automatic memory across sessions:
+
+```bash
+export STRANDS_KNOWLEDGE_BASE_ID="your-kb-id"
+devduck  # Auto-retrieves context before queries, stores after responses
+```
+
+Works with AWS Bedrock Knowledge Bases.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MODEL_PROVIDER` | `ollama` | Model provider (bedrock, anthropic, ollama) |
+| `STRANDS_KNOWLEDGE_BASE_ID` | - | Enable auto-RAG with KB ID |
+| `DEVDUCK_TCP_PORT` | `9999` | TCP server port |
+| `DEVDUCK_WS_PORT` | `8080` | WebSocket port |
+| `DEVDUCK_MCP_PORT` | `8000` | MCP server port |
+| `DEVDUCK_ENABLE_TCP` | `true` | Enable TCP server |
+| `DEVDUCK_ENABLE_WS` | `true` | Enable WebSocket |
+| `DEVDUCK_ENABLE_MCP` | `true` | Enable MCP server |
+| `DEVDUCK_LOG_LINE_COUNT` | `50` | Log lines in context |
+| `SYSTEM_PROMPT` | - | Custom system prompt |
+
+## Dynamic Tool Loading
+
+Load tools from any Python package at runtime:
+
+```python
+devduck
+🦆 install_tools(action="install_and_load", 
+              package="strands-fun-tools", 
+              module="strands_fun_tools")
+```
+
+No restart required—tools available immediately.
+
+## System Prompt Management
+
+Modify agent behavior dynamically:
+
+```bash
+devduck
+🦆 system_prompt(action="update", prompt="You are a senior Python expert.")
+🦆 system_prompt(action="view")  # See current prompt
+```
+
+## Logs
+
+```bash
+devduck
+🦆 view_logs(action="view", lines=100)
+🦆 view_logs(action="search", pattern="error")
+🦆 view_logs(action="stats")
+```
+
+Log location: `/tmp/devduck/logs/devduck.log`
+
+## GitHub Actions
+
+Run DevDuck in CI/CD:
+
+```yaml
+- name: DevDuck Analysis
+  uses: cagataycali/devduck@main
+  with:
+    query: "analyze test coverage"
+    model: "us.anthropic.claude-sonnet-4-20250514-v1:0"
+```
+
+---
+
+**One file. 19+ tools. Self-healing. Hot-reload. RAG memory.**
+
+*Built with [Strands Agents SDK](https://github.com/strands-agents/sdk-python)*

{devduck-0.3.0 → devduck-0.4.0}/devduck/__init__.py

@@ -677,29 +677,33 @@ class DevDuck:
             except ImportError as e:
                 logger.warning(f"devduck.tools import failed: {e}")
 
-            try:
-                from strands_fun_tools import (
-                    listen,
-                    cursor,
-                    clipboard,
-                    screen_reader,
-                    yolo_vision,
-                )
+            # Skip fun tools in --mcp mode (they're not needed for MCP server)
+            if "--mcp" not in sys.argv:
+                try:
+                    from strands_fun_tools import (
+                        listen,
+                        cursor,
+                        clipboard,
+                        screen_reader,
+                        yolo_vision,
+                    )
 
-                core_tools.extend(
-                    [listen, cursor, clipboard, screen_reader, yolo_vision]
-                )
-            except ImportError:
-                logger.info(
-                    "strands-fun-tools not installed - vision/audio tools unavailable (install with: pip install devduck[all])"
-                )
+                    core_tools.extend(
+                        [listen, cursor, clipboard, screen_reader, yolo_vision]
+                    )
+                except ImportError:
+                    logger.info(
+                        "strands-fun-tools not installed - vision/audio tools unavailable (install with: pip install devduck[all])"
+                    )
+            else:
+                logger.info("--mcp mode: skipping vision/audio tools")
 
             try:
                 from strands_tools import (
                     shell,
                     editor,
                     calculator,
-                    python_repl,
+                    # python_repl,
                     image_reader,
                     use_agent,
                     load_tool,
@@ -713,7 +717,7 @@ class DevDuck:
                         shell,
                         editor,
                         calculator,
-                        python_repl,
+                        # python_repl,
                         image_reader,
                         use_agent,
                         load_tool,
@@ -1267,7 +1271,13 @@ def weather(action: str, location: str = None) -> Dict[str, Any]:
 
 # 🦆 Auto-initialize when imported
 # Check environment variables to control server configuration
+# Also check if --mcp flag is present to skip auto-starting servers
 _auto_start = os.getenv("DEVDUCK_AUTO_START_SERVERS", "true").lower() == "true"
+
+# Disable auto-start if --mcp flag is present (stdio mode)
+if "--mcp" in sys.argv:
+    _auto_start = False
+
 _tcp_port = int(os.getenv("DEVDUCK_TCP_PORT", "9999"))
 _ws_port = int(os.getenv("DEVDUCK_WS_PORT", "8080"))
 _mcp_port = int(os.getenv("DEVDUCK_MCP_PORT", "8000"))
@@ -1561,15 +1571,33 @@ def cli():
 Examples:
   devduck                          # Start interactive mode
   devduck "your query here"        # One-shot query
+  devduck --mcp                    # MCP stdio mode (for Claude Desktop)
   devduck --tcp-port 9000          # Custom TCP port
   devduck --no-tcp --no-ws         # Disable TCP and WebSocket
   devduck --mcp-port 3000          # Custom MCP port
+
+Claude Desktop Config:
+  {
+    "mcpServers": {
+      "devduck": {
+        "command": "uvx",
+        "args": ["devduck", "--mcp"]
+      }
+    }
+  }
         """,
     )
 
     # Query argument
     parser.add_argument("query", nargs="*", help="Query to send to the agent")
 
+    # MCP stdio mode flag
+    parser.add_argument(
+        "--mcp",
+        action="store_true",
+        help="Start MCP server in stdio mode (for Claude Desktop integration)",
+    )
+
     # Server configuration
     parser.add_argument(
         "--tcp-port", type=int, default=9999, help="TCP server port (default: 9999)"
@@ -1601,6 +1629,30 @@ Examples:
 
     logger.info("CLI mode started")
 
+    # Handle --mcp flag for stdio mode
+    if args.mcp:
+        logger.info("Starting MCP server in stdio mode (blocking, foreground)")
+        print("🦆 Starting MCP stdio server...", file=sys.stderr)
+
+        # Don't auto-start HTTP/TCP/WS servers for stdio mode
+        if devduck.agent:
+            try:
+                # Start MCP server in stdio mode - this BLOCKS until terminated
+                devduck.agent.tool.mcp_server(
+                    action="start",
+                    transport="stdio",
+                    expose_agent=True,
+                    agent=devduck.agent,
+                )
+            except Exception as e:
+                logger.error(f"Failed to start MCP stdio server: {e}")
+                print(f"🦆 Error: {e}", file=sys.stderr)
+                sys.exit(1)
+        else:
+            print("🦆 Agent not available", file=sys.stderr)
+            sys.exit(1)
+        return
+
     if args.query:
         query = " ".join(args.query)
         logger.info(f"CLI query: {query}")

{devduck-0.3.0 → devduck-0.4.0}/devduck/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
 
-__commit_id__ = commit_id = 'g1f44e96e5'
+__commit_id__ = commit_id = 'ga94b2b054'

{devduck-0.3.0 → devduck-0.4.0}/devduck/tools/mcp_server.py

@@ -190,9 +190,11 @@ def _start_mcp_server(
             agent_invoke_tool = types.Tool(
                 name="devduck",
                 description=(
-                    "Invoke the full DevDuck agent with a natural language prompt. "
-                    "Use this for complex queries that require reasoning across multiple tools "
-                    "or when you need a conversational response from the agent."
+                    "Invoke a FULL DevDuck instance with complete capabilities. "
+                    "Each invocation creates a fresh DevDuck agent with self-healing, "
+                    "hot-reload, all tools, knowledge base integration, and system prompt building. "
+                    "Use this for complex queries requiring reasoning, multi-tool orchestration, "
+                    "or when you need the complete DevDuck experience via MCP."
                 ),
                 inputSchema={
                     "type": "object",
@@ -228,7 +230,7 @@ def _start_mcp_server(
             try:
                 logger.debug(f"call_tool: name={name}, arguments={arguments}")
 
-                # Handle agent invocation tool - use the devduck instance directly
+                # Handle agent invocation tool - create a full DevDuck instance
                 if name == "devduck" and expose_agent:
                     prompt = arguments.get("prompt")
                     if not prompt:
@@ -241,8 +243,34 @@ def _start_mcp_server(
 
                     logger.debug(f"Invoking devduck with prompt: {prompt[:100]}...")
 
-                    # Use the devduck agent directly (don't create a new instance)
-                    result = agent(prompt)
+                    # Create a NEW DevDuck instance for this MCP invocation
+                    # This gives full DevDuck power: self-healing, hot-reload, all tools, etc.
+                    try:
+                        from devduck import DevDuck
+
+                        # Create fresh DevDuck instance (no auto-start to avoid recursion)
+                        mcp_devduck = DevDuck(auto_start_servers=False)
+                        mcp_agent = mcp_devduck.agent
+
+                        if not mcp_agent:
+                            return [
+                                types.TextContent(
+                                    type="text",
+                                    text="❌ Error: Failed to create DevDuck instance",
+                                )
+                            ]
+
+                        # Execute with full DevDuck capabilities
+                        result = mcp_agent(prompt)
+
+                    except Exception as e:
+                        logger.error(f"DevDuck creation failed: {e}", exc_info=True)
+                        return [
+                            types.TextContent(
+                                type="text",
+                                text=f"❌ Error creating DevDuck instance: {str(e)}",
+                            )
+                        ]
 
                     # Extract text response from agent result
                     response_text = str(result)