From c55ffdb59b3d3d70c1f471516a9faf9c88a0b2b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Claude4=CE=9Elope?= <xilope@esus.name>
Date: Sat, 28 Jun 2025 12:52:48 +0200
Subject: [PATCH] Add enhanced onboarding examples and Xilope production guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

**Onboarding Enhancements**:
- Added explicit server discovery examples
- Included Claude Code server usage patterns
- Added read_file tool call examples with proper namespacing

**Xilope Production Guide**:
- Complete production environment documentation
- Memory storage integration details (/mnt/data/claude/claude/.mcp-memory/)
- cmem wrapper integration (~/bin/cmem → /usr/local/bin/cmem)
- Bidirectional sync workflows and best practices

**Server Updates**:
- Enhanced onboarding server to serve predefined markdown files
- Priority: predefined files → default.md → fallback instructions

This provides comprehensive guidance for both general MCP Browser usage
and Xilope's specific production environment with cmem integration.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 mcp_servers/onboarding/default.md           |  47 ++++-
 mcp_servers/onboarding/onboarding_server.py |  16 +-
 mcp_servers/onboarding/xilope_production.md | 223 ++++++++++++++++++++
 3 files changed, 277 insertions(+), 9 deletions(-)
 create mode 100644 mcp_servers/onboarding/xilope_production.md

diff --git a/mcp_servers/onboarding/default.md b/mcp_servers/onboarding/default.md
index f94611d..c469725 100644
--- a/mcp_servers/onboarding/default.md
+++ b/mcp_servers/onboarding/default.md
@@ -46,6 +46,17 @@ mcp_call(method="tools/call", params={"name": "brave_web_search", "arguments": {
 
 ## Discovery Examples
 
+### Listing Available Servers
+```python
+# First, discover what MCP servers are available
+mcp_discover(jsonpath="$.servers[*].name")
+# Returns: ["builtin", "claude-code", "filesystem", etc.]
+
+# Get detailed info about servers
+mcp_discover(jsonpath="$.servers[*]")
+```
+
+### Basic Tool Discovery
 ```python
 # Discover all available tools (built-in + external servers)
 mcp_discover(jsonpath="$.tools[*].name")
@@ -53,13 +64,20 @@ mcp_discover(jsonpath="$.tools[*].name")
 # Get tools from specific server
 mcp_discover(jsonpath="$.servers.brave-search.tools[*].name")
 
-# Get all configured servers
-mcp_discover(jsonpath="$.servers[*].name")
-
 # Get tool details
 mcp_discover(jsonpath="$.tools[?(@.name=='brave_web_search')]")
 ```
 
+### Server-Specific Tool Discovery
+```python
+# Example: Get all Claude Code tools
+mcp_discover(jsonpath="$.servers['claude-code'].tools[*].name")
+# Returns: ["read_file", "write_file", "list_directory", etc.]
+
+# Get details of a specific tool from claude-code server
+mcp_discover(jsonpath="$.servers['claude-code'].tools[?(@.name=='read_file')]")
+```
+
 ## Using External Server Tools
 
 Once discovered, call any tool through `mcp_call`:
@@ -82,6 +100,29 @@ mcp_call(
         "arguments": {"query": "mcp-browser"}
     }
 )
+
+# Example: Using Claude Code server to read a file
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "claude-code::read_file",
+        "arguments": {
+            "path": "/path/to/file.py",
+            "start_line": 1,
+            "end_line": 50
+        }
+    }
+)
+
+# Alternative syntax for server-namespaced tools
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "read_file",
+        "arguments": {"path": "/path/to/file.py"},
+        "server": "claude-code"
+    }
+)
 ```
 
 ## Runtime Configuration
diff --git a/mcp_servers/onboarding/onboarding_server.py b/mcp_servers/onboarding/onboarding_server.py
index 37202b9..8ae00b7 100755
--- a/mcp_servers/onboarding/onboarding_server.py
+++ b/mcp_servers/onboarding/onboarding_server.py
@@ -125,17 +125,21 @@ class OnboardingServer(BaseMCPServer):
                 content = self._format_onboarding(identity, data)
                 return self.content_text(content)
             else:
+                # Try to load predefined markdown files first
+                predefined_file = Path(__file__).parent / f"{identity}.md"
+                if predefined_file.exists():
+                    with open(predefined_file) as f:
+                        predefined_content = f.read()
+                    
+                    return self.content_text(predefined_content)
+                
                 # Try to load default onboarding
-                default_file = self.onboarding_dir / "default.md"
+                default_file = Path(__file__).parent / "default.md"
                 if default_file.exists():
                     with open(default_file) as f:
                         default_content = f.read()
                     
-                    return self.content_text(
-                        f"# Onboarding for {identity}\n\n"
-                        f"No specific onboarding found. Using default:\n\n"
-                        f"{default_content}"
-                    )
+                    return self.content_text(default_content)
                 else:
                     return self.content_text(
                         f"# Onboarding for {identity}\n\n"
diff --git a/mcp_servers/onboarding/xilope_production.md b/mcp_servers/onboarding/xilope_production.md
new file mode 100644
index 0000000..30709bb
--- /dev/null
+++ b/mcp_servers/onboarding/xilope_production.md
@@ -0,0 +1,223 @@
+# Xilope Production Environment - MCP Browser Guide
+
+Welcome to Xilope's production MCP Browser setup! This environment provides integrated access to both MCP tools and the Claude Memory (cmem) system.
+
+## Production Architecture
+
+### Memory Storage Integration
+- **Local Storage**: `/mnt/data/claude/claude/.mcp-memory/`
+- **cmem Integration**: Bidirectional sync via `/mnt/data/claude/claude/bin/cmem`
+- **Identity-Based**: Each project gets separate memory space
+- **Persistent**: Memory survives across AI assistant sessions
+
+### Built-in Servers Available
+1. **Memory Server** (`builtin:memory::`):
+   - `task_add`, `task_list`, `task_update` - Task management with cmem sync
+   - `decision_add` - Decision tracking with reasoning
+   - `pattern_add`, `pattern_resolve` - Learning pattern management
+   - `knowledge_add`, `knowledge_get` - Fact storage and retrieval
+   - `project_switch` - Switch between project contexts
+   - `memory_summary` - Get overview of stored information
+
+2. **Screen Server** (`builtin:screen::`):
+   - `create_session`, `execute`, `peek` - GNU screen management
+   - `list_sessions`, `kill_session` - Session lifecycle
+   - `enable_multiuser`, `attach_multiuser`, `add_user` - Collaboration
+
+3. **Pattern Server** (`builtin:patterns::`):
+   - `add_pattern`, `list_patterns` - Auto-response pattern management
+   - `test_pattern`, `execute_pattern` - Pattern execution
+
+4. **Onboarding Server** (`builtin:onboarding::`):
+   - `onboarding` - Identity-aware instructions
+   - `onboarding_list`, `onboarding_delete`, `onboarding_export` - Management
+
+## Production Workflows
+
+### Starting a Session
+```python
+# Check what servers are available
+mcp_discover(jsonpath="$.servers[*].name")
+
+# List all memory tools for task management
+mcp_discover(jsonpath="$.tools[?(@.name =~ /memory|task/)]")
+
+# Check current project context
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "builtin:memory::memory_summary",
+        "arguments": {}
+    }
+)
+```
+
+### Task Management with cmem Sync
+```python
+# Add a new task (automatically syncs to cmem)
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "builtin:memory::task_add",
+        "arguments": {
+            "content": "Implement feature X",
+            "priority": "high",
+            "assignee": "next-ai"
+        }
+    }
+)
+
+# List active tasks
+mcp_call(
+    method="tools/call", 
+    params={
+        "name": "builtin:memory::task_list",
+        "arguments": {"status": "pending"}
+    }
+)
+
+# Update task status (syncs completion to cmem)
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "builtin:memory::task_update", 
+        "arguments": {
+            "task_id": "abc123",
+            "status": "completed"
+        }
+    }
+)
+```
+
+### Decision and Pattern Management
+```python
+# Record important decisions (synced to cmem)
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "builtin:memory::decision_add",
+        "arguments": {
+            "choice": "Use Docker for deployment",
+            "reasoning": "Simplifies environment management",
+            "alternatives": ["Native install", "VM deployment"]
+        }
+    }
+)
+
+# Add learning patterns (synced to cmem)
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "builtin:memory::pattern_add",
+        "arguments": {
+            "pattern": "Always test before commit",
+            "description": "Run full test suite before any git commit",
+            "priority": "high"
+        }
+    }
+)
+```
+
+### Screen Session Management
+```python
+# Create a development session
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "builtin:screen::create_session", 
+        "arguments": {
+            "session_name": "development",
+            "working_directory": "/mnt/data/claude/claude"
+        }
+    }
+)
+
+# Execute commands in session
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "builtin:screen::execute",
+        "arguments": {
+            "session_name": "development",
+            "command": "git status"
+        }
+    }
+)
+
+# Peek at session output
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "builtin:screen::peek",
+        "arguments": {"session_name": "development"}
+    }
+)
+```
+
+### Project Context Switching
+```python
+# Switch to different project memory space
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "builtin:memory::project_switch",
+        "arguments": {"project_name": "mcp-browser"}
+    }
+)
+
+# Use onboarding for project-specific instructions
+mcp_call(
+    method="tools/call",
+    params={
+        "name": "builtin:onboarding::onboarding",
+        "arguments": {
+            "identity": "mcp-browser",
+            "instructions": "Focus on context optimization and AI-first development"
+        }
+    }
+)
+```
+
+## cmem Integration Details
+
+### Memory Storage Structure
+```
+/mnt/data/claude/claude/.mcp-memory/
+├── default/                    # Default project space
+│   ├── tasks.json             # Task storage
+│   ├── decisions.json         # Decision history  
+│   ├── patterns.json          # Learning patterns
+│   └── knowledge.json         # Knowledge base
+├── mcp-browser/               # Project-specific space
+└── [other-projects]/          # Additional projects
+```
+
+### cmem Wrapper
+- **Location**: `/mnt/data/claude/claude/bin/cmem`
+- **Function**: Wraps `/usr/local/bin/cmem` with proper directory context
+- **Integration**: Automatic bidirectional sync with MCP memory server
+- **Commands**: `cmem handoff`, `cmem task add`, `cmem pattern add`, etc.
+
+### Sync Behavior
+- **Automatic**: All memory operations sync to cmem in background
+- **Graceful**: If cmem unavailable, operations continue locally
+- **Identity-Aware**: Each project gets separate cmem context
+- **Bidirectional**: Changes in either system propagate to the other
+
+## Production Best Practices
+
+1. **Always check memory summary** at start of session
+2. **Use task management** to track work across AI sessions  
+3. **Record decisions** with reasoning for future reference
+4. **Create patterns** to capture effective approaches
+5. **Switch project contexts** when working on different codebases
+6. **Use screen sessions** for persistent development environments
+
+## Error Handling
+
+If cmem sync fails:
+- Operations continue with local storage
+- Sync retries automatically when cmem becomes available
+- No data loss occurs during temporary cmem unavailability
+
+This production setup ensures seamless AI assistant transitions while maintaining full project context and memory across sessions.
\ No newline at end of file
