Release v0.8.0

Signed-off-by: Phillip Sitbon <[email protected]>

Author: sitbon

.github/workflows/docker-publish.yml

@@ -4,8 +4,20 @@ on:
   push:
     branches: [ main, beta ]
     tags: [ 'v*.*.*' ]
+    paths:
+      - 'magg/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'magg.dockerfile'
+      - 'compose.yaml'
   pull_request:
     branches: [ main, beta ]
+    paths:
+      - 'magg/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'magg.dockerfile'
+      - 'compose.yaml'
   workflow_dispatch:
 
 env:

.github/workflows/test.yml

@@ -3,8 +3,18 @@ name: Tests
 on:
   push:
     branches: ['*']
+    paths:
+      - 'magg/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
   pull_request:
     branches: ['*']
+    paths:
+      - 'magg/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
 
 jobs:
   test:

docs/index.md

@@ -842,6 +842,86 @@ Check logs for:
 - Tool delegation errors
 - Configuration problems
 
+### Tool Naming and Prefix System
+
+#### Understanding Tool Names
+
+Magg organizes tools from multiple servers using a prefix system. Every tool name follows this pattern:
+
+```
+{prefix}{separator}{tool_name}
+```
+
+Where:
+- `prefix` is the namespace for a server (configurable per server)
+- `separator` is configurable via `prefix_sep` field or `MAGG_PREFIX_SEP` env var (default: `_`)
+- `tool_name` is the original tool name from the server
+
+Examples:
+- `calc_add` - "add" tool from server with "calc" prefix
+- `pw_screenshot` - "screenshot" tool from server with "pw" prefix  
+- `magg_list_servers` - "list_servers" tool from Magg itself
+- `read_file` - "read_file" tool from server with no prefix
+
+#### Configuring Server Prefixes
+
+When adding a server, specify the `prefix` field:
+
+```json
+{
+  "name": "calculator",
+  "source": "...",
+  "prefix": "calc"      // All tools will be calc_*
+}
+```
+
+Special cases:
+- `"prefix": ""` or `"prefix": null` - No prefix, tools keep original names
+- Omitting prefix field - Server name is used as default prefix
+- Multiple servers can share the same prefix (tools are merged)
+
+#### Configuring Magg's Prefix
+
+Magg's own tools use the prefix from `MAGG_SELF_PREFIX`:
+
+```bash
+# Default: magg_list_servers, magg_add_server, etc.
+export MAGG_SELF_PREFIX=magg
+
+# Custom: myapp_list_servers, myapp_add_server, etc.
+export MAGG_SELF_PREFIX=myapp
+
+# No prefix: list_servers, add_server, etc.
+export MAGG_SELF_PREFIX=""
+```
+
+#### Configuring the Separator
+
+You can change the separator between prefix and tool name:
+
+```bash
+# Default underscore separator: calc_add, magg_list_servers
+export MAGG_PREFIX_SEP="_"
+
+# Dash separator: calc-add, magg-list-servers  
+export MAGG_PREFIX_SEP="-"
+
+# Dot separator: calc.add, magg.list.servers
+export MAGG_PREFIX_SEP="."
+
+# No separator: calcadd, magglistservers
+export MAGG_PREFIX_SEP=""
+```
+
+#### Prefix Validation Rules
+
+- Must be valid Python identifiers (alphanumeric, not starting with digit)
+- Cannot contain the separator character (default: underscore, but configurable)
+- Case-sensitive
+- Empty string allowed (results in no prefix)
+
+Note: While the separator is configurable, server prefixes currently still cannot contain underscores due to Python identifier constraints.
+
 ### Performance Optimization
 
 1. **Disable unused servers** to reduce memory usage

docs/proxy.md

@@ -40,15 +40,45 @@ The proxy tool accepts the following parameters:
   - For resources: typically not used (URI is in path)
   - For prompts: prompt-specific arguments
 
+- **limit** (optional): integer (1-1000)
+  - Maximum number of items to return
+  - Only allowed for `list` action
+  - Default: 100
+
+- **offset** (optional): integer (≥0)
+  - Number of items to skip
+  - Only allowed for `list` action
+  - Default: 0
+
+- **filter_server** (optional): string
+  - Filter results by server name prefix
+  - Only allowed for `list` action
+  - Example: `"serena_"` to show only tools from the serena server
+
 ### Examples
 
 ```json
-// List all tools
+// List all tools (with default pagination: limit=100, offset=0)
 {
   "action": "list",
   "type": "tool"
 }
 
+// List tools with pagination
+{
+  "action": "list",
+  "type": "tool",
+  "limit": 50,
+  "offset": 50
+}
+
+// List tools from a specific server only
+{
+  "action": "list",
+  "type": "tool",
+  "filter_server": "serena_"
+}
+
 // Get info about a specific tool
 {
   "action": "info", 
@@ -101,7 +131,10 @@ Example list response structure:
             proxyAction="list",
             proxyType="tool",
             pythonType="Tool",  # Or "Resource | ResourceTemplate", "Prompt"
-            many=True  # For list actions
+            many=True,  # For list actions
+            totalCount=250,  # Total number of items available
+            offset=0,        # Current offset
+            limit=100        # Current limit
         )
     )
 ]
@@ -333,7 +366,8 @@ Proxy errors are returned as standard MCP errors:
 
 - Self-client connection is reused across calls
 - Use targeted queries when possible
-- Consider implementing pagination for large result sets
+- Pagination is implemented with `limit`, `offset`, and `filter_server` parameters
+- Default limit is 100 items to prevent token limit issues
 - Transparent mode adds minimal overhead (one extra tool call)
 
 ## Future Extensions

examples/messaging.py

@@ -11,24 +11,24 @@
 
 class CustomMessageHandler(MaggMessageHandler):
     """Custom message handler that logs all notifications."""
-    
+
     def __init__(self):
         super().__init__()
         self.notification_count = 0
-    
+
     async def on_message(self, message):
         """Called for all messages."""
         self.notification_count += 1
         print(f"📥 Received message #{self.notification_count}: {type(message).__name__}")
-    
+
     async def on_tool_list_changed(self, notification: mcp.types.ToolListChangedNotification):
         """Called when tool list changes."""
         print("🔧 Tool list changed! Available tools may have been updated.")
-    
+
     async def on_resource_list_changed(self, notification: mcp.types.ResourceListChangedNotification):
         """Called when resource list changes."""
         print("📁 Resource list changed! Available resources may have been updated.")
-    
+
     async def on_progress(self, notification: mcp.types.ProgressNotification):
         """Called for progress updates."""
         if notification.params:
@@ -39,7 +39,7 @@ async def on_progress(self, notification: mcp.types.ProgressNotification):
                 print(f"⏳ Progress: {progress}/{total} ({percentage:.1f}%)")
             else:
                 print(f"⏳ Progress: {progress}")
-    
+
     async def on_logging_message(self, notification: mcp.types.LoggingMessageNotification):
         """Called for log messages from servers."""
         if notification.params:
@@ -51,38 +51,38 @@ async def on_logging_message(self, notification: mcp.types.LoggingMessageNotific
 async def callback_example():
     """Example using callback-based message handler."""
     print("🚀 Starting callback-based message handler example...")
-    
+
     def on_tool_change(notification):
         print("🔧 [Callback] Tools changed!")
-    
+
     def on_progress(notification):
         if notification.params and notification.params.progress is not None:
             print(f"⏳ [Callback] Progress: {notification.params.progress}")
-    
+
     # Create handler with callbacks
     handler = MaggMessageHandler(
         on_tool_list_changed=on_tool_change,
         on_progress=on_progress
     )
-    
+
     # Create client with message handler
     client = MaggClient(
         "http://localhost:8000/mcp/",  # MCP endpoint with trailing slash
         message_handler=handler
     )
-    
+
     try:
         async with client:
             print("✅ Connected to Magg server with message handling")
-            
+
             # List tools to see what's available
             tools = await client.list_tools()
             print(f"📋 Found {len(tools)} tools available")
-            
+
             # Keep connection open to receive notifications
             print("👂 Listening for notifications... (press Ctrl+C to stop)")
             await asyncio.sleep(30)  # Listen for 30 seconds
-            
+
     except KeyboardInterrupt:
         print("\n🛑 Stopped listening for notifications")
     except Exception as e:
@@ -92,36 +92,36 @@ def on_progress(notification):
 async def class_example():
     """Example using class-based message handler."""
     print("🚀 Starting class-based message handler example...")
-    
+
     # Create custom handler
     handler = CustomMessageHandler()
-    
+
     # Create client with message handler
     client = MaggClient(
         "http://localhost:8000/mcp/",  # MCP endpoint with trailing slash
         message_handler=handler
     )
-    
+
     try:
         async with client:
             print("✅ Connected to Magg server with custom message handler")
-            
+
             # List available capabilities
             tools = await client.list_tools()
             resources = await client.list_resources()
             prompts = await client.list_prompts()
-            
+
             print(f"📋 Available capabilities:")
             print(f"  🔧 Tools: {len(tools)}")
             print(f"  📁 Resources: {len(resources)}")
             print(f"  💬 Prompts: {len(prompts)}")
-            
+
             # Keep connection open to receive notifications
             print("👂 Listening for notifications... (press Ctrl+C to stop)")
             await asyncio.sleep(30)  # Listen for 30 seconds
-            
+
             print(f"📊 Total notifications received: {handler.notification_count}")
-            
+
     except KeyboardInterrupt:
         print("\n🛑 Stopped listening for notifications")
     except Exception as e:
@@ -136,17 +136,17 @@ async def main():
     print("This example demonstrates Magg's real-time messaging capabilities.")
     print("Make sure you have a Magg server running at http://localhost:8000")
     print()
-    
+
     # Run callback example
     await callback_example()
     print()
-    
+
     # Wait a bit between examples
     await asyncio.sleep(2)
-    
+
     # Run class example
     await class_example()
-    
+
     print()
     print("✨ Examples completed!")
     print()
@@ -157,4 +157,4 @@ async def main():
 
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    asyncio.run(main())

magg/__init__.py

@@ -17,7 +17,7 @@
 
 __all__ = [
     "MaggClient",
-    "MaggMessageHandler", 
+    "MaggMessageHandler",
     "MessageRouter",
     "ServerMessageCoordinator",
 ]